Skip to main content
Version: Mosquitto 3.0

Docker Setup

Prerequisites​

Ensure you have the following files ready before configuring Mosquitto:

  • Server Certificate (server.crt): The public server certificate.
  • Private Key (server.key): The private key associated with the server certificate.

Configuring Pro Mosquitto Broker with a Server Certificate​

Pro Mosquitto TLS termination​

Open your mosquitto.conf file to add a certificate to a certain port. Add or modify the following settings to configure the Pro Mosquitto broker to use the server certificate:

# Enable a listener on port 8883 for SSL/TLS connections
listener 8883
protocol mqtt

# SSL/TLS certificate paths
certfile /path/to/server.crt
keyfile /path/to/server.key
  • listener 8883: Sets the port for SSL/TLS communication. Port 8883 is the standard MQTT SSL/TLS port.
  • certfile: Specifies the path to the server's public certificate file.
  • keyfile: Specifies the path to the server's private key file.

HA Proxy TLS termination​

In a cluster setup an HA Proxy is used for TLS termination. This is the default config of the frontend haproxy.jsonfile:

frontend mqtt_frontend
    bind *:1883
    mode tcp
    default_backend mqtt_backend
    timeout client 10m

In order to enable TLS termination here add the following behind the bind *:<port> parameter: ssl crt /path/to/certs/server.pem This will do the TLS termination at the frontend stage before routing the traffic further to the set backend (here mqtt_backend ).

Client connections​

Use an MQTT client to connect to the broker using the secure port (e.g., 8883) to verify that the server certificate is being used:

mosquitto_sub -h <broker-ip> -p 8883 -t test/topic --cafile /path/to/ca.crt

In this example, a --cafile parameter is added to the test because, depending on the device and the server certificate, your underlying system may not have the required CA in place to validate the server certificate you set.

Certificate access​

It is important that the files from the specified path are available to Pro Mosquitto. Ensure that the private key file is securely accessible to the Mosquitto service:

sudo chmod 640 /path/to/server.key
sudo chown mosquitto:mosquitto /path/to/server.key

This ensures that only the Mosquitto service has access to the private key, enhancing security.

To apply the changes, restart Pro Mosquitto. Check the Mosquitto logs for troubleshooting if needed.

Configuring Cedalo Platform with a Server Certificate​

You can achieve https:// access either via a reverse proxy of your choice or by adding the server certificates directly to the platform via environment variables.

Environment Variables​

To conifgure the server certificates use the following Environment Variables:

  • BASE_URL: URL the platform will be reachable at (should have the same IP/hostname as specified in the certificate)
  • NEXTAUTH_URL: URL the platform will be reachable at (should have the same IP/hostname as specified in the certificate)
  • MOSQUITTO_PLATFORM_HTTPS_KEY_PATH: Path to server's private key file (required)
  • MOSQUITTO_PLATFORM_HTTPS_CERT_PATH: Path to server's certificate (required)
  • MOSQUITTO_PLATFORM_HTTPS_CA_PATH: path to CA certificate (optional)

Example configuration​

            BASE_URL: https://192.168.178.27:3000
            NEXTAUTH_URL: https://192.168.178.27:3000
            MOSQUITTO_PLATFORM_HTTPS_KEY_PATH: /certs/cert.key
            MOSQUITTO_PLATFORM_HTTPS_CERT_PATH: /certs/cert.crt

Docker compose​

In docker based deployments make sure, that the linked certificates are reachable. A mount to the local directory allows you to store the used certs in the setup folders:

        volumes:
            ...
            - ./certs:/certs

Kubernetes/Openshift Setup

Configuring Pro Mosquitto Broker with a Server Certificate on Kubernetes/Openshift​

This document outlines the two available methods for configuring a broker runnning on a Kubernetes or Openshift setup with a server certificate: using a proxy for TLS termination or configuring TLS directly on the broker. In cluster environments, the use of HAProxy, as provided in the default setup, is recommended for managing TLS termination.

Prerequisites (For Single Node)​

Ensure you have the following files ready before configuring Mosquitto:

  • Server Certificate (server.crt): The public server certificate.
  • Private Key (server.key): The private key associated with the server certificate.

Pro Mosquitto TLS termination​

Open your mosquitto.conf file that is part of your helm chart under files section to add a certificate to a certain port. Add or modify the following settings to configure the Pro Mosquitto broker to use the server certificate:

# Enable a listener on port 8883 for SSL/TLS connections
listener 8883
protocol mqtt

# SSL/TLS certificate paths
certfile /path/to/server.crt
keyfile /path/to/server.key

The helm chart contains some default setting you can use the same unless you want your own custom changes. The mosquitto.conf that comes along with helm chart has the following preconfigured commented out setup. In order to enable TLS, please follow the following steps:

Uncomment the configurations in relevant files:​

mosquitto.conf​

# Enable a listener on port 8883 for SSL/TLS connections
listener 8883
protocol mqtt

certfile /mosquitto/certs/server.crt
keyfile /mosquitto/certs/server.key

If you notice, server.key and server.crt defaults to path /mosquitto/certs/. This is the same path that is part of other manifests file like statefulset.yaml of the Helm Charts. If you wish to change it make sure you change it in statefulset.yaml as well.

  • listener 8883: Sets the port for SSL/TLS communication. Port 8883 is the standard MQTT SSL/TLS port.
  • certfile: Specifies the path to the server's public certificate file.
  • keyfile: Specifies the path to the server's private key file.

statefulset.yaml​

The two relevant sections to be uncommented are related to the mosquitto-tls-volume:

volumeMounts:
    - name: mosquitto-tls-volume
    mountPath: /mosquitto/certs
    readOnly: true
volumes:
    - name: mosquitto-tls-volume
        secret:
            secretName: mosquitto-server-tls # Refers to the server TLS Secret
            items:
                - key: server.crt
                path: server.crt
                mode: 0644 # Read-only for everyone
                - key: server.key
                path: server.key
                mode: 0640 # Owner read/write, no access for others (most secure for private key)
  • Note: If you have changed the /mosquitto/certs path in the previous step, make sure you change it here as well.

server-certs.yaml​

Paste the base64 converted version of server.key and server.crt in server-certs.yaml.

data:
  server.crt: ""
    # Paste your base64 version of server.crt here
  server.key: ""
    # Paste your base64 version of server.key here

service-mosquitto.yaml​

- name: mqtt-secure
    port: {{ .Values.mosquitto.ports.secureListener }}
    targetPort: {{ .Values.mosquitto.ports.secureListenerTarget }}
    protocol: TCP

Deploy the helm chart after making changes and now you connect with TLS enabled conection.

Prerequisites (For HA using HAproxy)​

For HA cluster, tls termination happens at the haproxy. Therefore, the server certificates needs to be present at HAproxy instance.

Ensure you have the following files ready before configuring Mosquitto:

  • Server Certificate (haproxy_combined.pem): Server Certificate

In order to enable that make sure you enable TLS you uncomment or add relevant details based on the following steps:

values.yaml​

Place the contents of your haproxy_combined.pem under pemContent in values.yaml.

deployment-haproxy-openshift.yaml/deployment-haproxy.yaml​

volumeMounts:

- name: tls-certs
    mountPath: {{ .Values.haproxy.haproxyCombinedPemFilePath }} # Directory where certs will be available
    readOnly: true # Certificates should be read-only
volumes:
    - name: tls-certs
        secret:
            secretName: haproxy-tls-certs
            items:
               - key: haproxy_combined.pem # Key in the Secret
                 path: haproxy_combined.pem # Filename in the container

service-haproxy-loadbalancer.yaml​


- name: haproxy-secure
      port: {{ .Values.haproxy.ports.secureListener }}
      targetPort: {{ .Values.haproxy.ports.secureListenerTarget }}
      protocol: TCP

haproxy-config.yaml​


For Secure connection
    frontend mqtt_frontend_secure
        bind *:{{ .Values.haproxy.ports.secureListener }} ssl crt {{ .Values.haproxy.haproxyCombinedPemFilePath }}/haproxy_combined.pem
        mode tcp
        maxconn 10000
        default_backend mqtt_backend
        timeout client 10m

Deploy the helm chart after making changes and now you connect with TLS enabled conection.