Mosquitto is an open source MQTT message broker provided by the Eclipse foundation.
emerge --ask app-misc/mosquitto
Libraries/ integration, e.g. Eclipse Paho.
/etc/mosquitto/mosquitto.conf - Global (system wide) configuration file.
~/.config/mosquitto_sub - per user defaults for command mosquitto_sub
~/.config/mosquitto_pub - per user defaults for command mosquitto_pub
Force drop of root user and privileges by configuring user mosquitto in mosquitto.conf. Leaving this unconfigured runs the process as root.
Do not enable PID file in mosquitto.conf as it conflicts with PID file of init script. Using user directive in combination with init-script's PID file crashes the service immediately. PID file created by init script is owned by root which mosquitto can not write.
Secure the broker by either using a (self signed) X509 certificate for TLS or pre shared key TLS. Without TLS communication is unencrypted. Credentials are transferred as plain text. Also setup access control for topics and at least one authorization schema:
user/ password with mosquitto_passwd, set permission on the file so that only user mosquitto can read it: chmod 400
mutual TLS, listener forces all clients to provide a certificate
dynamic security plugin
have at least a single listener so remote connections are possible
specify the network interface with bind_interface to if only one out of many is allowed
configure multiple listeners with enabled per-listener-configuration to separate contexts or shard traffic
memory_limit to avoid resource exhaustion
message_size_limit so the broker rejects payloads being too large
persistent_client_expiration to allow cleaning stale clients
log_dest, preferrably /var/log/mosquitto.log, in conjunction with log_type and optionally connection_messages
This section illustrates basic steps:
create a private key
create a certificate signing request (CSR) for the private key
signing the CSR as your own CA to yield a server certificate
First create a directory tls under Mosquitto's configuration and create a broker key. Shown here an elliptic curve key with non-NIST algorithm:
openssl genpkey -algorithm ED25519 >broker.key
chown mosquitto:mosquitto broker.key
Certificates have limited validity and need to be re-created. It is much easier to do this with a configuration file (no alternative names/ certificate for the MQTT broker only):
distinguished_name = yourserver_mosquitto
req_extensions = v3_req
prompt = no
C = DE
CN = mqtt.yourserver.net
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
Create the CSR:
openssl req -new -out mosquitto_yourserver.csr -key broker.key -config openssl-25519.conf
With your own root/ intermediate CA issue a certificate valid for 365 days:
openssl x509 -req -in mosquitto_yourserver.csr -days 365 -out broker-yourserver.crt -CA root.cer -CAkey root.key -sha256 -CAcreateserial
Finally store broker-yourserver.crt in /etc/mosquitto/tls and configure mosquitto.conf accordingly:
#A listener on default TLS port
# Broker runs as this user
Finally secure all files by revoking permissions/ limiting access to user mosquitto only:
chown -R mosquitto:mosquitto /etc/mosquitto/tls
chmod 400 /etc/mosquitto/tls/*
broker key with password, requires unlocking upon start/ restart
monitoring of certificate expiration, e.g. Icinga2
use key management, e.g. an external device or partition that is only available when starting the service
systemctl start mosquitto
The package provides the broker and tools to directly interact with it. The following command subscribes to a topic announce/info on a given host with port 8883 – assuming the broker was configured with a TLS listener (process runs until stopped):
mosquitto_sub -h mqtt.example.com -p 8883 -u mqtt-consumer-12 -P secret -t announce/info
To publish the message This broker is up and running to the same topic on the same host with a different user:
mosquitto_pub -h mqtt.example.com -p 8883 -u mqtt-publisher -P othersecret -t announce/info -m 'This broker is up and running'
This message now shows up in the output of the first command.
emerge --ask --depclean --verbose app-misc/mosquitto