Author: Francis Ndungu
Last Updated: Fri, Oct 15, 2021Mosquitto is an open-source message broker that uses the Message Queuing Telemetry Transport (MQTT) Protocol. MQTT runs on top of the TCP/IP model and is the standard messaging platform for the Internet of Things (IoT).
Since the MQQT protocol is extremely lightweight, its small code footprint allows you to create applications for devices with minimal resources such as short battery life, limited network bandwidth, and unreliable internet connections.
The Mosquitto application supports the publisher/subscriber topology. In this model, clients connect to the Mosquitto server, which acts as a broker to distribute information to other clients subscribed or sending messages to a channel.
In this guide, you'll install and configure the Mosquitto application and learn how the event-driven MQQT protocol works with IoT applications.
To follow along with this guide, you need:
You'll pull the mosquitto
package from Ubuntu's software repository by executing the following steps.
SSH to your server and update the package information index.
$ sudo apt update
Install the mosquitto
package.
$ sudo apt install -y mosquitto
The mosquitto
package should now load on your server. Confirm the status of the mosquitto
service.
$ sudo systemctl status mosquitto
Ensure the package is loaded
and active
.
â mosquitto.service - Mosquitto MQTT v3.1/v3.1.1 Broker
Loaded: loaded (/lib/systemd/system/mosquitto.service; enabled; vendor pr>
Active: active (running) since Fri 2021-10-08 06:29:25 UTC; 12s ago
Docs: man:mosquitto.conf(5)
man:mosquitto(8)
...
Once running, you can manage the mosquitto
services by executing the following commands.
Stop the mosquitto
service:
$ sudo systemctl stop mosquitto
Start the mosquitto
service:
$ sudo systemctl start mosquitto
Restart the mosquitto
service:
$ sudo systemctl restart mosquitto
When using an MQTT client, you connect to the Mosquitto broker to send and receive messages on different topics depending on the application's use case. A client can either be a publisher, a subscriber, or both.
The Mosquitto package ships with a command-line client that allows you to test the server functionalities. Install the client.
$ sudo apt install -y mosquitto-clients
Next, you'll subscribe to a topic. In the MQQT protocol, a topic is a string that the server/broker uses to filter messages for the connected clients. For instance, here are some sample topics that you can use when using the Mosquitto broker in a home automation application.
home/lights/sitting_room
home/lights/kitchen
home/lights/master_bedroom
home/lights/kids_bedroom
To subscribe to a topic, execute the mosquitto_sub -t
command followed by the name of the topic that you want to subscribe to. For example, to subscribe to the home/lights/sitting_room
topic, execute.
$ mosquitto_sub -t "home/lights/sitting_room"
Please note that the above command has a blocking function and will put your shell terminal in a listening state.
Open a second terminal window and don't close the first one. This time around, publish an "ON" message to the topic home/lights/sitting_room
topic using the mosquitto_pub -m
command.
$ mosquitto_pub -m "ON" -t "home/lights/sitting_room"
You should now receive the ON
payload in the first window.
ON
Next, publish an OFF
message still on the same home/lights/sitting_room
topic on your second terminal.
$ mosquitto_pub -m "OFF" -t "home/lights/sitting_room"
Your broker should display the new message as well.
ON
OFF
In this guide, you're manually subscribing and publishing messages using the Mosquitto Clients for demonstration purposes. In real-life applications, you should program small microchip devices that support the TCP/IP layer like the ESP8266 to push a message to a broker to control or even monitor devices. Here are some common use-cases where the Mosquitto package is used in real life.
Monitoring patients' heartbeats and sending them to a central server for monitoring by doctors. This avoids heavy transport costs that the patients could incur by traveling to the hospital.
In the gas and the oil industry, MQQT devices monitor different parameters and send the data to a central broker. Usually, this involves thousands of sensors in remote locations that collect and send data through satellite links that are billed per data usage. Luckily, the MQQT topology keeps the transmission minimal and only pushes data to the server when necessary.
In the transport industry, MQQT devices monitor the location of trains in real-time and send data to the companies' headquarters in order to provide better insights to customers who want to travel without any delays.
Also, the Mosquitto broker can be used as a middle layer in a chat application to refresh the online status of users and pass messages between end-users.
Another common scenario where the Mosquitto server can be a good fit is in decoupled systems. Clients can send data to the broker, which then sends the data to a database for permanent storage.
In addition to the above use-cases, there are dozens of libraries that you can use to connect to the Mosquitto server using your favorite programming language, including PHP, Python, Golang, and more.
By default, the Mosquitto server is not secured. However, you can make some configuration settings to secure it with usernames and passwords.
Mosquitto reads configuration information from the following location.
/etc/mosquitto/conf.d
Create a default.conf
under the directory.
$ sudo nano /etc/mosquitto/conf.d/default.conf
Paste the information below to disable anonymous
connections and allow Mosquitto to read valid credentials from the /etc/mosquitto/passwd
file.
allow_anonymous false
password_file /etc/mosquitto/passwd
Save and close the file.
Open the /etc/mosquitto/passwd
file with nano
.
$ sudo nano /etc/mosquitto/passwd
Then, populate the file with the account details for the users that you want to connect to the Mosquitto server. Replace EXAMPLE_PASSWORD
and EXAMPLE_PASSWORD_2
with strong values.
john_doe:EXAMPLE_PASSWORD
mary_smith:EXAMPLE_PASSWORD_2
Save and close the file.
Next, use the mosquitto_passwd
utility to encrypt the passwords.
$ sudo mosquitto_passwd -U /etc/mosquitto/passwd
Your passwords are now encrypted in a format that only the Mosquitto server can decrypt. Use the Linux cat
command to confirm the encryption process.
$ sudo cat /etc/mosquitto/passwd
Output.
john_doe:$6$TSzNycsj...5Qyvgd4g==
mary_smith:$6$DtlKf1lG.../rLHIL0Q==
Restart the mosquitto
service to load the new changes.
$ sudo systemctl restart mosquitto
From this point forward, you should execute any pub/sub command using the syntax below. Remember to replace john_doe
and EXAMPLE_PASSWORD
with the credentials that you defined in the password file.
$ mosquitto_sub -u john_doe -P EXAMPLE_PASSWORD -t "home/lights/sitting_room"
$ mosquitto_pub -u john_doe -P EXAMPLE_PASSWORD -t "home/lights/sitting_room" -m "ON"
Unauthenticated commands or connections with incorrect credentials should now fail.
$ mosquitto_pub -m "ON" -t "home/lights/sitting_room"
$ mosquitto_sub -t "home/lights/sitting_room"
$ mosquitto_sub -u john_doe -P WRONG_PASSWORD -t "home/lights/sitting_room"
$ mosquitto_pub -u john_doe -P WRONG_PASSWORD -t "home/lights/sitting_room" -m "ON"
Output.
...
Connection error: Connection Refused: not authorised.
In this tutorial, you've installed and configured the Mosquitto server on your Ubuntu 20.04 server. You've also used the command-line interface to subscribe and publish messages to a sample topic. Consider using the Mosquitto server next time when deploying an IoT application.