unifios-utilities/mosquitto/README.md

Eclipse Mosquitto™ on Ubiquiti Unifi Dream Machine (Pro)

Run the MQTT message broker Eclipse Mosquitto™ on your Unifi Dream Machine (Pro).

Prerequisities

• Working on_boot.d setup (check unifi-utilities/unifios-utilities#on-boot-script for instructions)
• A VLAN network (you can use one you are already using)

Recommended

• Use container-common to prevent growing disk usage from accumulating logs

Optional

• Port forwarding, ie. WAN -> [MOSQUITTO_IP] (TCP/1883) if needed

Note
Throughout this guide I'm using VLAN 20 with gateway 10.0.20.1/24 as an example; Mosquitto's IP will be 10.0.20.4.
Adjust according to your setup.

Setup

1. First, lets create the folder structure we'll be working with.

   $ mkdir -p /mnt/data/mosquitto/config /mnt/data/mosquitto/data

   This is where Mosquitto's configuration file and data ("persistence database"; if enabled) will live.
   If you're unsure on how to configure mosquitto, use the provided barebone config config/mosquitto.conf to get it initially running.

2. Optional: Customize on_boot.d/45-mosquitto.sh to your setup and copy to /mnt/data/on_boot.d/. Most likely you'll need to mark the script as executable, this will do the trick:

   $ chmod a+x /mnt/data/on_boot.d/45-mosquitto.sh

3. Then take a loot at cni/45-mosquitto.conflist and make sure it matches your previously defined configuration; then place it in /mnt/data/podman/cni/

4. Run boot script (to create the mosquitto network set it's ip routes)

   $ sh /mnt/data/on_boot.d/45-mosquitto.sh

   It fail when trying to run the container, but thats okay, its just for setting op needed configuration before initial image run.
   The script will also create a minimal configuration for Mosquitto in /mnt/data/mosquitto/config/, only if it doesn't already exist.

   Note: You can use this config to get everything started, but I highly recommend securing your instance with authentication (links to the offical documentation & other resources are at the bottom)

5. Register the container with podman:

   $ podman run -d --network mosquitto \
       --restart always \
       --security-opt=no-new-privileges \
       --name mosquitto \
       --hostname mosquitto.local \
       -e "TZ=Europe/Berlin" \
       -v /mnt/data/mosquitto/config/:/mosquitto/config \
       -v /mnt/data/mosquitto/data/:/mosquitto/data \
       eclipse-mosquitto:latest
   

6. Run boot script again and we are done!

   $ sh /mnt/data/on_boot.d/45-mosquitto.sh

You should now be able to connect with any MQTT client to Mosquitto, in my case mqtt://10.0.20.4:1883

Commands

Updates
To update container image to its latest version, first delete the current container ($ podman stop mosquitto && podman rm mosquitto) and follow through setup steps 5. & 6.

Logs
If you want to know what mosquitto is doing, run $ podman logs -f mosquitto to follow the logs.

Relevant Links

• Eclipse Mosquitto Homepage
• mosquitto.conf man page
• Setting up Authentication in Mosquitto MQTT Broker
• eclipse-mosquitto on Docker-Hub

Credits

Huge thanks to @boostchicken for his incredible work on unifios-utilities and all contributors of this repo!