RPM Pro Mosquitto

RPM Package for Pro 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 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 configurations.

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.

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

where plugin_opt_disconnected_clients_ttl 300 is the time 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.

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

listener 1883 <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

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

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

listener 8883
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

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.

The listener at port 1883/8883 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.

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. Which node will be elected leader cannot be predetermined, so it is suggested that a single node is started then the contents of /var/opt/cedalo/mosquitto/ha/ duplicated to other nodes in order to have a deterministic password once the cluster is created. Alternatively, the environment variable MOSQUITTO_DYNSEC_PASSWORD can be set prior to running the broker manually and the contents of this variable will be used as the initial password if no other credentials exist.

Example HA network configuration

This section describes how a network could be configured for use with the HA feature. It uses an instance of HAProxy to direct the incoming clients to the currently active leader node, with all Mosquitto instances on the private network only. For the best availability we would recommend multiple HAProxy instances.

For HAProxy you need to combine the server cert and the server key into a single PEM file. e.g. using the command line tool cat:

sudo cat /etc/opt/cedalo/mosquitto/certs/server.crt /etc/lib/cedalo/mosquitto/certs/server.key \
| sudo tee /etc/opt/cedalo/mosquitto/certs/server.pem

In this example, the IP address range 192.0.2.0/24 is a private network, and 203.0.113.0/24 is a publically accessible network.

Mosquitto node 1:

• Listener 1883, bound to private IP address 192.0.2.1 - active when node is a leader
• Listener 2883, bound to private IP address 192.0.2.1 - always active, for Cedalo MQTT Platform only
• Listener 7001, bound to private IP address 192.0.2.1 - internal cluster comms

Mosquitto node 2:

• Listener 1883, bound to private IP address 192.0.2.2 - active when node is a leader
• Listener 2883, bound to private IP address 192.0.2.2 - always active, for Cedalo MQTT Platform only
• Listener 7001, bound to private IP address 192.0.2.2 - internal cluster comms

Mosquitto node 3:

• Listener 1883, bound to private IP address 192.0.2.3 - active when node is a leader
• Listener 2883, bound to private IP address 192.0.2.3 - always active, for Cedalo MQTT Platform only
• Listener 7001, bound to private IP address 192.0.2.3 - internal cluster comms

HAProxy instance:

• Frontend 8883, bound to public address 203.0.113.1 with TLS termination
• Backend to connect to 192.0.2.1:1883
• Backend to connect to 192.0.2.2:1883
• Backend to connect to 192.0.2.3:1883

Cedalo MQTT Platform:

• Frontend 443, bound to public address 203.0.113.2
• Connection to 192.0.2.1:2883
• Connection to 192.0.2.2:2883
• Connection to 192.0.2.3:2883

For this configuration, the connections are added to the Cedalo Platform as shown above.

Setting up a cluster

The following link contains information Mosquitto cluster:

Mosquitto High Availability Cluster