How to install an MQTT broker (Mosquitto) on Unraid

This article will guide you through the installation of the Mosquitto MQTT broker on Unraid.

Disclosure: This post contains affiliate links. If you click through and make a purchase, I’ll earn a commission, at no additional cost to you. Read my full disclosure here.

This guide will show you how to install an MQTT broker, namely Mosquitto, on your Unraid server. MQTT (Message Queuing Telemetry Transport) is the perfect network protocol for connecting remote devices, such as those used on the Internet of Things (IoT). It has a small code footprint and uses minimal network bandwidth. No wonder then, that applications such as Zigbee2MQTT rely on MQTT for communication. MQTT is an open OASIS and ISO standard (ISO/IEC 20922), making it relatively future-proof.

Mosquitto is possibly the most popular message broker that implements the MQTT protocol versions 5.0, 3.1.1 and 3.1. An MQTT broker, such as Mosquitto, acts as a post office. When sending a message, MQTT doesn’t use the address for the intended recipient. For example, you don’t need to enter any IP when trying to get Zigbee2MQTT to communicate with the home automation software Home Assistant. Instead, MQTT uses topics.

Anyone who wants to receive a copy of a certain message has to subscribe to that topic. To take our previous example: When you want Home Assistant to receive messages from Zigbee2MQTT you would have it subscribed to all topics beginning with zigbee2mqtt. That way, multiple clients can receive a message from a single broker, which is also described as the one to many capability.

Installing the Mosquitto MQTT broker on Unraid

As with most popular applications, the Mosquitto MQTT broker can be found in the Community Applications. Simply search for the title and a template provided by cmccambridge should show up. Click on the installation icon and continue with the app’s configuration.

There are only a few settings to adjust, so I will go through them one by one. The configuration directory should be placed in your appdata folder, along with all other persistent Docker directories. You might also want to add folders for persistent data and logs, though these are not required.

It’s best to leave the host’s port set to 1883, as this is MQTT’s standard port. Any clients you connect to the Mosquitto MQTT broker, will be looking for it on port 1883 by default. Finally, you can select whether you want to password-protect your MQTT broker or not. I highly suggest using a password as it doesn’t make the setup much more complicated, but you broker’s security will benefit from it.

The Mosquitto MQTT broker settings
My Mosquitto Docker settings

Enabling password-based authentication

To create a user and password, you will have to execute a few commands within the Docker container. To do so, head over to your Docker overview in the Unraid dashboard and search for Mosquitto. Once found, click on its icon and select the option Console.

The console for the Mosquitto Docker container on Unraid

First you will need to create a file to store the passwords as it most likely doesn’t exist yet. To do so, you can use the touch command:

touch /mosquitto/config/passwd

With the file created you can create your first user. Most likely you will never need more than a single user, but if you ever were to need more than one, you can simply execute the same command one more time. After hitting Enter you will be prompted to set a password:

mosquitto_passwd /mosquitto/config/passwd <MQTT_USER_NAME>

Just like that you have created your user. For the settings to be applied you will need to restart the Docker container. You can now start connecting other services to your Mosquitto MQTT broker running on Unraid.

About Liam Alexander Colman

I first heard of Unraid through the same medium as many of us did: The Linus Tech Tips channel on YouTube. At the time, I was running TrueNAS (or FreeNAS as it was called back then) on my DIY NAS built using a dual-core Intel Pentium G4400 at its heart. I was convinced, I had chosen the better operating system. After all, it was free and open-source and had a large community behind it. One day, after once again facing the need to buy another three hard drives, I seriously started researching Unraid and its features. I bit the bullet and gave it a go, transferring my data on to external hard drives that I later shucked and added to the Unraid array. Since that day, I have not looked back once, and I am now an enthusiastic and experienced user of Unraid. You can find out more about Unraid Guides right here.

Leave a comment