Add guide on how to integrate MQTT Broker demonstrated on Eclipse Mosquitto (#369)

* Guide for Eclipse Mosquitto completed

* Add reference to Mosquitto guide to README

README.md

@@ -126,6 +126,12 @@ Update your cloudflare domains from your UDM with podman.
 This is a docker container that implements <https://github.com/alsmith/multicast-relay> to provide mDNS and SSDP on a unifi dream machine.
 It will likely work on any multi homed host.
 
+### mqtt-mosquitto
+
+<https://hub.docker.com/_/eclipse-mosquitto>
+
+Eclipse Mosquitto is an open source message broker which implements MQTT version 5, 3.1.1 and 3.1.
+
 ### ntopng
 
 <https://github.com/tusc/ntopng-udm>

mqtt-mosquitto/README.md

@@ -0,0 +1,79 @@
+# [Eclipse Mosquitto™](https://mosquitto.org) 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 [boostchicken/udm-utilities#on-boot-script](https://github.com/boostchicken-dev/udm-utilities/tree/master/on-boot-script) for instructions)
+- A VLAN network (you can use one you're already using)
+
+#### Optional:
+
+- Port forwarding, ie. WAN -> 10.0.20.4 (TCP/1883) if needed
+
+> **Note:** Throughout this guide I'm using `VLAN 20` with gateway `10.0.20.1/24`, 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/data /mnt/data/mosquitto/config`
+
+2. Customize [`on_boot.d/45-mosquitto.sh`](on_boot.d/45-mosquitto.sh) to your needs 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. Also edit [`cni/45-mosquitto.conflist`](cni/45-mosquitto.conflist) according your configuration and copy to `/mnt/data/podman/cni/`.
+
+4. Run boot script (to create update network and create CNI configuration for container)
+
+    `$ 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 [bare-metal configuration](config/mosquitto.conf) for Mosquitto in `/mnt/data/mosquitto/config/`.  
+
+    > **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:
+
+    ```shell
+    $ 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, simple do `$ podman stop mosquitto && podman rm mosquitto` and run boot script again.
+
+#### Logs
+
+If you want to know what Mosquitto is doing, run `$ podman logs -f mosquitto` to follow the logs.
+
+## References
+
+- [Eclipse Mosquitto Homepage](https://mosquitto.org)
+- [mosquitto.conf man page](https://mosquitto.org/man/mosquitto-conf-5.html)
+- [Setting up Authentication in Mosquitto MQTT Broker](https://medium.com/@eranda/setting-up-authentication-on-mosquitto-mqtt-broker-de5df2e29afc)
+
+## Credits
+
+Huge thanks to @boostchicken and his incredible work on [udm-utilities](https://github.com/boostchicken/udm-utilities)!  
+
+Guide based upon the incredible contributors of [boostchicken/udm-utilities](https://github.com/boostchicken/udm-utilities)!

mqtt-mosquitto/cni/45-mqtt.conflist

@@ -0,0 +1,32 @@
+{
+  "cniVersion": "0.4.0",
+  "name": "mosquitto",
+  "plugins": [
+      {
+         "type": "bridge",
+         "bridge": "br20",
+         "ipam": {
+            "type": "host-local",
+            "ranges": [
+                [
+                    {
+                        "subnet": "10.0.20.0/24",
+                        "rangeStart": "10.0.20.4",
+                        "rangeEnd": "10.0.20.4",
+                        "gateway": "10.0.20.1" 
+                    }
+                ]
+            ],
+            "routes": [
+                {"dst": "0.0.0.0/0"}
+            ]
+         }
+      },
+      {
+         "type": "tuning",
+         "capabilities": {
+            "mac": true
+         }
+      }
+  ]
+}

mqtt-mosquitto/config/mosquitto.conf

@@ -0,0 +1,14 @@
+listener 1883
+connection_messages true
+
+allow_anonymous true
+allow_zero_length_clientid true
+
+persistence true
+persistence_file mosquitto.db
+persistence_location /mosquitto/data/
+persistent_client_expiration 7d
+
+log_dest stdout
+log_type debug
+log_timestamp true

mqtt-mosquitto/on_boot.d/45-mosquitto.sh

@@ -0,0 +1,70 @@
+#!/bin/sh
+
+## network configuration
+VLAN_ID=20
+IPV4_IP_CONTAINER="10.0.20.4"
+IPV4_IP_GATEWAY="10.0.20.1"
+CONTAINER_NAME="mosquitto"
+CONTAINER_CNI_PATH="/mnt/data/podman/cni/45-mosquitto.conflist"
+
+# make sure cni plugs are installed
+if ! test -f /opt/cni/bin/macvlan; then
+    echo "Error: CNI plugins not found. You can install it with the following command:" >&2
+    echo "       curl -fsSLo /mnt/data/on_boot.d/05-install-cni-plugins.sh https://raw.githubusercontent.com/boostchicken-dev/udm-utilities/master/cni-plugins/05-install-cni-plugins.sh && /bin/sh /mnt/data/on_boot.d/05-install-cni-plugins.sh" >&2
+    exit 1
+fi
+
+## network configuration and startup
+if ! test -f $CONTAINER_CNI_PATH; then
+  logger -s -t podman-mosquitto -p ERROR Container network configuration for $CONTAINER_NAME not found, make sure $CONTAINER_CNI_PATH exists
+  exit 1
+fi
+
+# link the conflist into live directory
+ln -fs "$CONTAINER_CNI_PATH" "/etc/cni/net.d/$(basename "$CONTAINER_CNI_PATH")"
+
+# set VLAN_ID bridge promiscuous
+ip link set br${VLAN_ID} promisc on
+
+# create macvlan bridge and add IPv4 IP
+ip link add br${VLAN_ID}.mac link br${VLAN_ID} type macvlan mode bridge
+ip addr add ${IPV4_IP_GATEWAY}/24 dev br${VLAN_ID}.mac noprefixroute
+
+# set macvlan bridge promiscuous and bring it up
+ip link set br${VLAN_ID}.mac promisc on
+ip link set br${VLAN_ID}.mac up
+
+# add IPv4 route to container
+ip route add ${IPV4_IP_CONTAINER}/32 dev br${VLAN_ID}.mac
+
+# create basic config if not exist
+if ! test -f /mnt/data/mosquitto/config/mosquitto.conf; then
+  mkdir -p /mnt/data/mosquitto/data /mnt/data/mosquitto/config
+  cat > /mnt/data/mosquitto/mosquitto.conf<< EOF
+listener 1883
+allow_anonymous true
+
+allow_zero_length_clientid true
+
+persistence false
+persistence_file mosquitto.db
+persistence_location /mosquitto/data/
+persistent_client_expiration 7d
+
+log_dest stdout
+log_type debug
+log_timestamp true
+
+connection_messages true
+
+allow_anonymous true
+EOF
+fi
+
+
+if podman container exists ${CONTAINER_NAME}; then
+  podman start ${CONTAINER_NAME}
+else
+  logger -s -t podman-mosquitto -p ERROR Container $CONTAINER_NAME not found, make sure you set the proper name, you can ignore this error if it is your first time setting it up
+fi
+