How to install an MQTT Broker - Mosquitto Install/Config on Debian/Ubuntu/Mint/Fedora/Raspbian

If you’ve worked with any IoT (Raspberry Pi, Arduino, ESP, Zigbee, Z-wave etc) devices, or any popular home automation software (Home Assistant, OpenHAB, Domoticz) chances are you have heard of MQTT as a means of communicating between devices.

Today we are going to install and configure an MQTT broker to allow devices to communicate with each other over the network in one of the simplest ways possible.

Many of our guides use MQTT, so we thought we would provide a guide for how to install it!

What is it and how does it work?

Message Queuing Telemetry Transport or MQTT is a super lightweight and efficient messaging protocol, designed for very low bandwidth devices such as Arduinos or esp8266/32 development boards.

MQTT works by clients publishing and subscribing to topics. The advantage of this is it allows multiple receiving devices to receive the same information at the same time, without the sending device having to re-transmit the same data to each receiving device one at a time.

That might seem a little confusing, one way to look at it is like a group chat on your favourite messenger. When you send a message in a group chat, everyone else’s phones receive that message instantly at the exact same time. As opposed to having to send that same message one at a time to each of your contacts. Hopefully that analogy makes sense.

MQTT uses a server or broker in order to achieve the above. Simply put, the job of the broker is to receive incoming messages and route them to the appropriate clients.

One use-case for MQTT could be to send data from a remote sensor to a central server such as a temperature sensor. Another use-case could be to command and control a remote Arduino, such as toggling a relay on and off.

Install an MQTT Broker – Mosquitto

Mosquitto is a very popular MQTT broker available for pretty much every platform. It is super simple to install an MQTT broker and it requires almost zero management and is very easy to configure.

We are going to take a look at installing Mosquitto on Linux since its probably the most popular method at the moment. Let us know if there is any other platforms you want to see!

First open a terminal and we are going to use our package manager to install:

# Ubuntu/Debian/Raspbian/Mint:
sudo apt update && sudo install -y mosquitto mosquitto-clients

#Fedora
sudo dnf install -y mosquitto

This install the mosquitto broker package, along with the mosquitto-clients package which has tools in it to allow us to test the install by publishing and subscribing to topics. Fedora has these tools built into the main mosquitto package.

Next lets start the service and enable it on boot:

systemctl restart mosquitto
systemctl enable mosquitto

As of this moment, our MQTT broker is up and running. We can test this by opening two terminals and issuing the following commands:

# Terminal 1:
mosquitto_sub -h localhost -t /this/is/a/topic

we used the mosquitto_sub tool to subscribe to a topic named “/this/is/a/topic”. The options for this are:

• -h – specifies the host where the broker is running, in this case it is localhost at the moment.
• -t – specifies the topic to subscribe to.

Next in terminal 2:

# Terminal 2:
mosquitto_pub -h localhost -t /this/is/a/topic -m "This is a message"

Where the options are the same as above with the addition of:

• -m – specifies the message you want to send

Hit enter and back in terminal one you will see:

This is a message

We just successfully published a message to a topic, and received it on a client subscribed to that topic.

Simple right?

One question you may have is around the somewhat lax security, of which there is none. Let’s fix that!

Back in your terminal, we are going to generate a password file using the built in tools:

mosquitto_passwd -c /etc/mosquitto/passwd your_username

Where:

• -c – the location you want the new generated file to be stored
• your_username – the username you want to use for any client to connect

You will be prompted for a password at this point, make sure to note it down.

Next create a config file in /etc/mosquitto/conf.d/default:

# Ubuntu/Debian/Raspbian/Mint:

nano /etc/mosquitto/conf.d/default.conf

# enter the following:

allow_anonymous false
password_file /etc/mosquitto/passwd

# Fedora:
mkdir /etc/mosquitto/conf.d
nano /etc/mosquitto/mosquitto.conf

#Go to the very bottom of the file and find the include_dir line (very last line) and change it from:
#include_dir

#to:
include_dir /etc/mosquitto/conf.d/

#Press CTRL + x to exit, press Y to save, then:

nano /etc/mosquitto/conf.d/default.conf

#enter the following

allow_anonymous false
password_file /etc/mosquitto/passwd

systemctl restart mosquitto

Nice, let’s give it a test using the same as above, except this time we need to specify a username and password:

# Terminal 1
mosquitto_sub -h localhost -t /this/is/a/topic -u your_username -P your_password

# Terminal 2
mosquitto_pub -h localhost -t /this/is/a/topic -u your_username -P your_password -m "this is a message"

And again you should receive a message on the first terminal.

That’s all there is to the install of an MQTT broker, there are a few other options you can play with, like QoS which specifies different levels of message delivery, a good article for those explained is here.

Troubleshooting

If you want to troubleshoot connections, you can use the following command to bring up and follow the logs:

journalctl --unit=mosquitto -f

Which will show you all the connection attempts from clients like so:

mosquitto[5630]: 1582282818: Config loaded from /etc/mosquitto/mosquitto.conf.
mosquitto[5630]: 1582282818: Opening ipv4 listen socket on port 1883.
mosquitto[5630]: 1582282818: Opening ipv6 listen socket on port 1883.
systemd[1]: Started Mosquitto MQTT v3.1/v3.1.1 Broker.
mosquitto[5630]: 1582282861: New connection from ::1 on port 1883.
mosquitto[5630]: 1582282861: New client connected from ::1 as mosq-aCsyKXU9C7Fe4WkTME (p2, c1, k60, u'lewis').
mosquitto[5630]: 1582282893: New connection from ::1 on port 1883.
mosquitto[5630]: 1582282893: New client connected from ::1 as mosq-LdwA0uPR56jq4VK1gY (p2, c1, k60, u'lewis').
mosquitto[5630]: 1582282893: Client mosq-LdwA0uPR56jq4VK1gY disconnected.
mosquitto[5630]: 1582283273: Client mosq-aCsyKXU9C7Fe4WkTME disconnected.
mosquitto[5630]: 1582283289: New connection from ::1 on port 1883.
mosquitto[5630]: 1582283289: New client connected from ::1 as mosq-Pttx4IynNeKqv9CcCv (p2, c1, k60, u'lewis').
mosquitto[5630]: 1582283289: Client mosq-Pttx4IynNeKqv9CcCv disconnected.