MQTT is a messaging protocol intended for smaller applications (in "footprint", not necessarily scale) which is available since 1999 but is currently receiving a lot of attention since the rise of the internet of things and the need to send small messages as simply as possible. In this tutorial I will show how to install a mosquitto server on Debian/Ubuntu based systems. The server will require authentication and TLS (using Let's Encrypt).
The following things are needed for all of this to work:
- A publicly accessible server
- Debian/Ubuntu based system
- A DNS
Arecord pointing to the server
Important things to note for this section:
- All commands need to be run as root unless noted otherwise!
- Remember to modify paths and domain names where necessary!
If it's not already there, install certbot:
# apt update # apt install certbot
Then get the certificate for your domain (you should stop any running web server or use another challenge if you get errors):
certbot certonly --standalone --standalone-supported-challenges http-01 -d mqtt.example.com
Since we're using Debian/Ubuntu, the installation is almost as easy as always:
# apt update # apt install mosquitto mosquitto-clients # systemctl stop mosquitto
The service was stopped immediately after installation because it's on a public server and it needs to be configured first. On Debian this can be done the hacky way (by editing
/etc/mosquitto/mosquitto.conf) or the clean way. I will use the latter.
By default, the
/etc/mosquitto/mosquitto.conf file includes the following line:
This makes it load all the files with a name matching
*.conf in the specified directory, so the configuration file can be any way you want.
Let's first remove all sample files in the config directory and then create a new config:
# rm /etc/mosquitto/conf.d/* # vi /etc/mosquitto/conf.d/custom.conf
allow_anonymous false password_file /etc/mosquitto/pwfile listener 1883 localhost listener 8883 certfile /etc/letsencrypt/live/mqtt.example.com/cert.pem cafile /etc/letsencrypt/live/mqtt.example.com/chain.pem keyfile /etc/letsencrypt/live/mqtt.example.com/privkey.pem
See the official configuration docs if you need more options (or don't understand some I used above).
You might have noticed the
password_file parameter in the example configuration. This contains the usernames and passwords that are allowed to connect to the server. Let's create it.
# vi /etc/mosquitto/pwfile
The format of the password file is one username and password per line, separated by a colon (
Now let's use
mosquitto_passwd to encrypt the password file:
# mosquitto_passwd -U /etc/mosquitto/pwfile
If you look into the file after running the command above, you'll notice that the passwords have been encrypted.
If you use
ufw (you should), you'll have to run the following command to enable Mosquitto to receive connections:
# ufw allow 8883
Now it's time to start the service and test it:
# systemctl start mosquitto # systemctl status mosquitto
After the service is running proplerly, the easiest way to test it is using a remote GUI tool like MQTT.fx, mqtt-spy or one of the other ones available. By using this method (opposed to locahost only) you make sure that the firewall and ssl config is working correctly.
Here are some things you might come across when running a MQTT broker.
You can add additional users to the password file by using the following command:
# mosquitto_passwd -b /path/to/passwordfile user password
You can remove a user from the password file by using the following command:
# mosquitto_passwd -D /path/to/passwordfile user
Editing a user
- Delete user
- Create user
Reloading configuration changes
After editing the password file, the changes are not immediately applied on the server. To apply any configuration changes, use the following command:
# systemctl restart mosquitto
You should now have a running MQTT broker at the domain name you have configured. If you have any problems or questions, don't hesitate to contact me or to use a search engine of your choice.
Have a nice day.