RPM Pro Edition for Eclipse Mosquitto

RPM Package for Pro Edition for Eclipse Mosquitto for RHEL/CentOS

This document assumes that you have downloaded the necessary .rpm file. You can access it via our Cedalo MQTT Platform with a valid subscription or an On-Premises Enterprise Trial.

Pro Edition for Eclipse Mosquitto general installation and set up

To install: yum install mosquitto-premium-x.x.x-y.el8.x86_64.rpm

The binary installation directory is /opt/cedalo/mosquitto

Place your license file at /etc/opt/cedalo/mosquitto/license.lic Place your configuration file at /etc/opt/cedalo/mosquitto/mosquitto.conf Application data should be configured to be saved in /var/opt/cedalo/mosquitto

See the sections below for different configuration examples. Make sure to have the correct configurations set up before starting the broker.

Default Credentials

If credentials are not explicitly declared, the broker will automatically generate random default credentials upon the first startup. These are stored in a .pw file within the following directories:mosquitto/ or mosquitto/ha/ if the cluster plugin is configured. When setting up a cluster, it is highly recommended to avoid using random credentials. For the cluster to communicate effectively, you should use identical credentials for all nodes across the environment.

Manual Credential Setup

To define specific credentials and override the random generation, add the necessary environment variable (MOSQUITTO_DYNSEC_PASSWORD) to the systemd service file:

Path: /usr/lib/systemd/system/mosquitto.service

...
Environment=CEDALO_LICENSE_FILE=/etc/opt/cedalo/mosquitto/license.lic
Environment=MOSQUITTO_DYNSEC_PASSWORD=<put your 12+character password here !>
...

[!TIP] After editing the service file, remember to run systemctl daemon-reload and systemctl restart mosquitto to apply the changes.

Start Mosquitto

To configure mosquitto to start on boot:

systemctl enable mosquitto

And to start mosquitto:

systemctl start mosquitto

info

Mosquitto will run as the mosquitto user by default. All files must have permissions that are accessible to this user.

Connect Mosquitto in the Platform UI

In the UI, you can add a Single Node or a Cluster to a project. Use the following details for the connection:

• Credentials: Use the default credentials.
• Port: Use the declared admin port as specified in your configuration file.

Single Node Configuration

This section assumes you wish to configure a single Mosquitto node using TLS encryption and running the dynamic security plugin for authentication.

Place your TLS certificate and private key at e.g. /etc/opt/cedalo/mosquitto/certs/server.crt and /etc/opt/cedalo/mosquitto/certs/server.key, and set them to be owned by the mosquitto user.

Edit your config file as follows:

listener 8883
certfile /etc/opt/cedalo/mosquitto/certs/server.crt
keyfile /etc/opt/cedalo/mosquitto/certs/server.key
plugin /opt/cedalo/mosquitto/lib/mosquitto_dynamic_security.so
plugin_opt_config_file /var/opt/cedalo/mosquitto/dynamic-security.json

plugin /opt/cedalo/mosquitto/lib/cedalo_inspect.so
plugin_opt_disconnected_clients_ttl 300
enable_control_api true

listener 2883 
admin_listener true

where plugin_opt_disconnected_clients_ttl 300 is the time to live of the disconnected clients in seconds.

Using this configuration, an initial dynamic security configuration will be created and the initial admin credentials stored at /var/opt/cedalo/mosquitto/dynamic-security.json.pw - this file should be removed after the credentials are recorded elsewhere. The admin password should be provided to the Cedalo MQTT Platform.

After enabling and starting the broker in systemd, clients can connect to port 8883 using the admin credentials, which can be used in the Platform to create further users.

Note that if you want to use streams plugin you should add the following lines to the config file:

plugin /opt/cedalo/mosquitto/lib/cedalo_stream_processing.so
plugin_opt_data_dir /mosquitto/data/stream

but don't forget to create /mosquitto/date/stream directory or ensure that it was created before.

HA Cluster Configuration

This section assumes you wish to configure three Mosquitto nodes to be configured as a High Availability cluster. We strongly recommend that for this setup all Mosquitto nodes are placed on a private network and that a reverse proxy is placed in front of the three nodes, to direct the incoming clients to the current cluster leader. In any case, the internal cluster communication must be on a private network or secured through a VPN.

Proxy

This proxy configuration is an example for HAProxy, but any proxy capable of TCP (Layer 4) routing (such as NGINX, Envoy, or Traefik) can achieve this. This is an example where no TLS termination is done in the proxy.

Configuration Snippet

global
    daemon
    maxconn 4096

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

backend mqtt_backend
    mode tcp
    timeout connect 5000
    timeout server 10m
    option redispatch
    
    # send-proxy-v2: Passes the real Client IP to the broker.
    server mqtt01 <Broker1IP>:1888 check send-proxy-v2 on-marked-down shutdown-sessions
    server mqtt02 <Broker2IP>:1888 check send-proxy-v2 backup on-marked-down shutdown-sessions
    server mqtt03 <Broker3IP>:1888 check send-proxy-v2 backup on-marked-down shutdown-sessions

    # config connects incoming 1883 traffic to the 1888 port of the cluster leader.

Mosquitto Configuration

If you are using a reverse proxy and carrying out TLS termination on the proxy, then use the following configuration file:

listener 1888 <private network address>
global_plugin /opt/cedalo/mosquitto/lib/cedalo_mosquitto_ha.so
persistence_location /var/opt/cedalo/mosquitto

plugin /opt/cedalo/mosquitto/lib/cedalo_inspect.so
plugin_opt_disconnected_clients_ttl 300
enable_control_api true

listener 2883 <private network address>
admin_listener true

plugin /opt/cedalo/mosquitto/lib/cedalo_inspect.so
plugin /opt/cedalo/mosquitto/lib/cedalo_client_control.so
plugin /opt/cedalo/mosquitto/lib/cedalo_certificate_management.so
plugin /opt/cedalo/mosquitto/lib/cedalo_topic_tree.so

If you are not carrying out TLS termination on the proxy, then use the following configuration file:

listener 1888
certfile /etc/opt/cedalo/mosquitto/certs/server.crt
keyfile /etc/opt/cedalo/mosquitto/certs/server.key
global_plugin /opt/cedalo/mosquitto/lib/cedalo_mosquitto_ha.so
persistence_location /var/opt/cedalo/mosquitto

plugin /opt/cedalo/mosquitto/lib/cedalo_inspect.so
plugin_opt_disconnected_clients_ttl 300
enable_control_api true

listener 2883 <private network address>
admin_listener true

plugin /opt/cedalo/mosquitto/lib/cedalo_inspect.so
plugin /opt/cedalo/mosquitto/lib/cedalo_client_control.so
plugin /opt/cedalo/mosquitto/lib/cedalo_certificate_management.so
plugin /opt/cedalo/mosquitto/lib/cedalo_topic_tree.so

Using these configurations, an initial dynamic security configuration will be created and the initial admin credentials stored at /var/opt/cedalo/mosquitto/ha/dynamic-security.json.pw - this file should be removed after the credentials are recorded elsewhere. The admin password should be provided to the Cedalo MQTT Platform. As suggested above this password should be set via environment variable and not be random. The initial password created on each node will be different. When the cluster is created via the Cedalo Platform, the first node to be elected leader will duplicate its authentication settings to the follower nodes, which means their credentials will change.

The listener at port 1888 will only be active on the current cluster leader. The listener on port 2883 will always be available, but must only be used with the Platform for cluster management and monitoring.