From Gentoo Wiki
Jump to:navigation Jump to:search
This article is a stub. Please help out by expanding it - how to get started.

Mosquitto is an open source MQTT message broker provided by the Eclipse foundation.



root #emerge --ask app-misc/mosquitto

Additional software

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
Without any means of authorization and or access control anybody can publish to any topic. This affects the entire host if for example high message volume exhausts host resources.


  • 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

TLS (X509)

This section illustrates basic steps:

  1. create a private key
  2. create a certificate signing request (CSR) for the private key
  3. signing the CSR as your own CA to yield a server certificate

For other options and how to let the system trust your own CA see Certificates and Certificates/Become your own CA.

First create a directory tls under Mosquitto's configuration and create a broker key. Shown here an elliptic curve key with non-NIST algorithm:

root #cd /etc/mosquitto
root #mkdir tls
root #cd tls
root #openssl genpkey -algorithm ED25519 >broker.key
root #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):

FILE /etc/mosquitto/tls/openssl-25519.conf
distinguished_name = yourserver_mosquitto
req_extensions = v3_req
prompt = no
C = DE
CN =
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth

Create the CSR:

root #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:

user $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:

FILE /etc/mosquitto/mosquitto.conf
#A listener on default TLS port
# Broker runs as this user

listener 8883



Finally secure all files by revoking permissions/ limiting access to user mosquitto only:

root #chown -R mosquitto:mosquitto /etc/mosquitto/tls
root #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



root #/etc/init.d/mosquitto start


root #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):

user $mosquitto_sub -h -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:

user $mosquitto_pub -h -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.



root #emerge --ask --depclean --verbose app-misc/mosquitto