Eclipse Mosquitto auf dem Synology NAS installieren: MQTT-Broker für das Smart Home

Ein MQTT-Broker ist der zentrale Nachrichtenverteiler eines lokalen Smart Homes: Zigbee-Gateways wie Phoscon/deCONZ, Sensoren, Aktoren und Plattformen wie Home Assistant, Node-RED oder ioBroker tauschen darüber Nachrichten aus. Eclipse Mosquitto ist der verbreitetste Open-Source-Broker. Auf dem Synology NAS läuft er als Container im Container Manager, dauerhaft erreichbar und ohne Cloud. Diese Anleitung richtet Mosquitto 2.1.2 als Compose-Projekt ein, legt Passwort-Datei und ACLs an und prüft jeden Schritt.

Voraussetzungen

• Synology NAS mit DSM 7.2 oder höher und installiertem Container Manager
• SSH-Zugriff auf das NAS für Berechtigungen und mosquitto_passwd; Docker-Befehle führen Sie dort mit sudo aus (Anleitung: SSH auf dem Synology NAS aktivieren und verbinden)
• Mindestens 256 MB freier RAM; Mosquitto selbst benötigt im Betrieb unter 10 MB
• Mindestens 100 MB freier Speicherplatz auf Volume 1 (Image ca. 9,5 MB)
• Statische IP-Adresse für das NAS (empfohlen, damit MQTT-Clients immer dieselbe Broker-Adresse nutzen)
• Geplante MQTT-Zugangsdaten: mindestens ein Admin-Benutzer, sowie Benutzernamen für Home Assistant und weitere Clients

Schritt 1: Ordnerstruktur anlegen und Berechtigungen setzen

Alle drei Verzeichnisse müssen vor dem ersten Start existieren; der Volume-Mount erzeugt nur Verzeichnisse, keine Konfigurationsdatei. Legen Sie die Ordner in der File Station oder per SSH an. Den Basis-Weg und die PUID/PGID-Ermittlung erklärt die Anleitung Docker-Ordner und Berechtigungen auf dem Synology NAS.

Per SSH:

mkdir -p /volume1/docker/mosquitto/config
mkdir -p /volume1/docker/mosquitto/data
mkdir -p /volume1/docker/mosquitto/log

Mosquitto liest die Konfiguration als root und wechselt danach zum Benutzer mosquitto (UID 1883). Passwort- und ACL-Datei liest der Broker bereits als UID 1883. Das Verzeichnis config muss deshalb UID 1883 gehören, sonst sperrt chmod 700 den Broker aus:

sudo chown 1883:1883 /volume1/docker/mosquitto/config
sudo chmod 700 /volume1/docker/mosquitto/config
chmod 777 /volume1/docker/mosquitto/data
chmod 777 /volume1/docker/mosquitto/log

Verifizieren: sudo ls -ln /volume1/docker/mosquitto/ zeigt die drei Unterverzeichnisse config (Besitzer 1883), data und log.

Schritt 2: mosquitto.conf erstellen

Ohne eine gültige mosquitto.conf mit expliziter listener-Direktive bindet Mosquitto 2.x nur an 127.0.0.1 – kein externer Client kann sich verbinden. Erstellen Sie die Datei per SSH:

sudo tee /volume1/docker/mosquitto/config/mosquitto.conf > /dev/null << 'EOF'
# Listener fuer MQTT TCP
listener 1883

# Listener fuer MQTT WebSocket (optional, nur oeffnen wenn benoetigt)
listener 9001
protocol websockets

# Authentifizierung: kein anonymer Zugriff
allow_anonymous false
password_file /mosquitto/config/passwd
acl_file /mosquitto/config/acl

# Persistenz: Retained Messages und QoS-Queue ueberleben Neustarts
persistence true
persistence_location /mosquitto/data/

# Logging: in Datei und auf stdout (sichtbar im Container Manager > Log-Tab)
log_dest file /mosquitto/log/mosquitto.log
log_dest stdout
log_type error
log_type warning
log_type notice
log_type information
EOF

allow_anonymous false ist seit Mosquitto 2.0 Standard. Ohne Authentifizierung könnte jedes Gerät im Netz beliebige Topics lesen und schreiben, also Schalter auslösen oder Sensordaten fälschen.

Legen Sie außerdem leere ACL- und Passwort-Dateien als Platzhalter an (Befüllung in Schritt 4):

sudo touch /volume1/docker/mosquitto/config/acl /volume1/docker/mosquitto/config/passwd
sudo chown 1883:1883 /volume1/docker/mosquitto/config/*
sudo chmod 600 /volume1/docker/mosquitto/config/acl /volume1/docker/mosquitto/config/passwd

Verifizieren: Prüfen Sie mit sudo cat /volume1/docker/mosquitto/config/mosquitto.conf, ob die Datei alle Direktiven enthält, insbesondere listener 1883 und allow_anonymous false. Beide Zeilen sind Pflicht.

Schritt 3: Compose-Projekt im Container Manager anlegen

Wie Sie ein Compose-Projekt im Container Manager anlegen, zeigt die Grundanleitung Container Manager: Docker-Compose-Projekt anlegen, starten und aktualisieren. Benennen Sie das Projekt mosquitto und verwenden Sie folgende compose.yaml:

services:
  mosquitto:
    image: eclipse-mosquitto:2.1.2-alpine
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "1883:1883"
      - "9001:9001"
    volumes:
      - /volume1/docker/mosquitto/config:/mosquitto/config
      - /volume1/docker/mosquitto/data:/mosquitto/data
      - /volume1/docker/mosquitto/log:/mosquitto/log

Das festgelegte Tag 2.1.2-alpine (ca. 9,5 MB) verhindert, dass ein Pull unbemerkt eine neue Version einspielt. eclipse-mosquitto:2 folgt automatisch der neuesten 2.x-Version; lesen Sie dann vor jedem Update das ChangeLog. Port 9001 brauchen Sie nur für WebSocket-Clients, sonst streichen Sie die Zeile.

Starten Sie das Projekt im Container Manager. Nach wenigen Sekunden steht der Container auf „Wird ausgeführt“.

Verifizieren: Unter „Container“ steht mosquitto mit grünem Status. Unter „Protokoll“ erscheinen Zeilen wie:

mosquitto version 2.1.2 starting
Config loaded from /mosquitto/config/mosquitto.conf.
Opening ipv4 listen socket on port 1883.
Opening ipv4 listen socket on port 9001.

Fehlt die Zeile mit Port 1883 oder erscheint eine Fehlermeldung zu mosquitto.conf, prüfen Sie Schritt 2.

Schritt 4: Passwort-Datei und ACLs einrichten

Mosquitto bringt keine Standard-Zugangsdaten mit. Legen Sie alle Benutzer mit mosquitto_passwd im laufenden Container an:

# Admin-Benutzer anlegen (-c erstellt neue Datei, NUR beim ersten Benutzer verwenden!)
sudo docker exec -it mosquitto mosquitto_passwd -c /mosquitto/config/passwd admin

# Weiteren Benutzer fuer Home Assistant hinzufuegen (ohne -c)
sudo docker exec -it mosquitto mosquitto_passwd /mosquitto/config/passwd homeassistant

# Besitz wieder auf den Broker-Benutzer setzen (docker exec laeuft als root)
sudo docker exec mosquitto chown mosquitto:mosquitto /mosquitto/config/passwd /mosquitto/config/acl

Das Tool fragt das Passwort interaktiv ab. -c erzeugt eine neue Datei und überschreibt eine vorhandene; verwenden Sie es nur beim ersten Benutzer.

ACLs (Access Control Lists) legen fest, welcher Benutzer welche MQTT-Topics lesen und schreiben darf. Für ein typisches Smart Home:

# Admin: voller Zugriff auf alle Topics
user admin
topic readwrite #

# Home Assistant: voller Zugriff (benoetigt alle Topics fuer Automatisierungen)
user homeassistant
topic readwrite #

# Beispiel fuer eingeschraenkte Geraete (z.B. Sensor nur auf eigenen Namespace)
# user sensor_kueche
# topic readwrite home/kueche/#

Schreiben Sie die Datei per SSH:

sudo tee /volume1/docker/mosquitto/config/acl > /dev/null << 'EOF'
user admin
topic readwrite #

user homeassistant
topic readwrite #
EOF

Starten Sie den Container danach neu, damit Mosquitto die neue Passwort-Datei und die ACLs lädt:

sudo docker restart mosquitto

Verifizieren: Im Protokoll erscheint nach dem Neustart erneut die Startmeldung ohne Warnung zu passwd oder acl. Die Benutzerliste zeigt:

sudo docker exec mosquitto cut -d: -f1 /mosquitto/config/passwd

Die Ausgabe nennt admin und homeassistant. Fehlt ein Name, legen Sie ihn erneut ohne -c an.

Schritt 5: Verbindung testen mit mosquitto_sub und mosquitto_pub

Das Image enthält mosquitto_sub und mosquitto_pub. Öffnen Sie zwei SSH-Sitzungen.

Im ersten Terminal abonnieren Sie ein Test-Topic (wartet im Vordergrund auf Nachrichten):

sudo docker exec -it mosquitto mosquitto_sub -h 127.0.0.1 -t "test/hello" -u admin -P IhrPasswort -v

Im zweiten Terminal senden Sie eine Nachricht:

sudo docker exec mosquitto mosquitto_pub -h 127.0.0.1 -t "test/hello" -m "Mosquitto läuft!" -u admin -P IhrPasswort

Verifizieren: Im ersten Terminal erscheint sofort:

test/hello Mosquitto läuft!

Erscheint stattdessen Connection error: Connection Refused: not authorised, prüfen Sie Benutzername, Passwort und den Neustart nach der passwd-Änderung. Erscheint Error: Address not available, fehlt die listener 1883-Zeile in der mosquitto.conf.

Schritt 6: Firewall freigeben und Home Assistant anbinden

Damit MQTT-Clients von anderen Geräten im Heimnetz (oder aus anderen Docker-Containern) den Broker erreichen, muss Port 1883 in der DSM-Firewall freigegeben sein. Die genaue Vorgehensweise beschreibt DSM-Firewall auf dem Synology NAS: Ports für Docker-Container freigeben.

Für die Anbindung öffnen Sie in Home Assistant Einstellungen > Geräte & Dienste > Integration hinzufügen > MQTT und tragen Sie ein:

Feld	Wert
Broker	IP-Adresse des NAS (z. B. 192.168.1.100) – nicht localhost
Port	1883
Benutzername	homeassistant
Passwort	Ihr gewähltes Passwort

Die Broker-Verbindung richten Sie ausschließlich über diese Oberfläche ein. Die früher übliche Angabe broker: in der configuration.yaml hat Home Assistant entfernt; sie führt zu „Invalid config for 'mqtt'“.

Läuft Home Assistant als Container auf demselben NAS, verwenden Sie trotzdem die NAS-IP statt localhost: Container in unterschiedlichen Netzwerken erreichen sich nicht über Loopback. Anleitung dazu: Home Assistant mit Docker: die lokale Smart-Home-Zentrale.

Verifizieren: In Home Assistant erscheint unter Einstellungen > Geräte & Dienste die MQTT-Integration mit Status „Verbunden“. Im Mosquitto-Log (sudo docker exec mosquitto tail /mosquitto/log/mosquitto.log) steht eine neue Verbindung mit dem Benutzer homeassistant.

Eckdaten des Docker-Images

Eigenschaft	Wert
Image	eclipse-mosquitto:2.1.2-alpine
Aktuelle Version	2.1.2 (erschienen 9. Februar 2026)
Image-Größe	ca. 9,5 MB
Architekturen	amd64, arm64v8, arm32v6, i386 (gesamte Synology-Palette)
MQTT-Port	1883 (TCP, Pflicht)
WebSocket-Port	9001 (optional)
Config-Volume	/volume1/docker/mosquitto/config:/mosquitto/config
Data-Volume	/volume1/docker/mosquitto/data:/mosquitto/data
Log-Volume	/volume1/docker/mosquitto/log:/mosquitto/log
Pflicht-Umgebungsvariablen	Keine – Konfiguration ausschließlich über mosquitto.conf

Troubleshooting / Typische Fehler

• „Error: Address not available“ oder Broker nur auf localhost erreichbar: Die listener 1883-Zeile fehlt in der mosquitto.conf. Seit Mosquitto 2.0 bindet der Broker ohne expliziten Listener ausschließlich an 127.0.0.1. Direktive eintragen, Container neu starten.
• „Connection Refused: not authorised“: Kein Benutzer angelegt, falscher Pfad zu /mosquitto/config/passwd oder kein Neustart nach dem Anlegen. Passwort-Datei und Pfad prüfen, dann sudo docker restart mosquitto.
• Container startet, mosquitto.conf wird nicht gefunden: Der Volume-Mount erzeugt nur das Verzeichnis. Datei laut Schritt 2 anlegen, Container neu starten.
• Warnung oder „Permission denied“ zu passwd/acl: Die Dateien gehören nicht UID 1883, etwa nach mosquitto_passwd per docker exec. Lösung: sudo docker exec mosquitto chown mosquitto:mosquitto /mosquitto/config/passwd /mosquitto/config/acl, dann Neustart.
• „Permission denied“ beim Schreiben in /mosquitto/data oder /mosquitto/log: Der Container läuft als Benutzer mosquitto (UID 1883), hat aber keine Schreibrechte auf die gemounteten Host-Verzeichnisse. Lösung: chmod 777 /volume1/docker/mosquitto/data /volume1/docker/mosquitto/log per SSH ausführen.
• Retained Messages gehen nach Neustart verloren: persistence true und persistence_location /mosquitto/data/ fehlen in der mosquitto.conf. Ohne diese Einträge schreibt Mosquitto keine .db-Datei ins Data-Volume.
• Home Assistant meldet „Unable to connect to MQTT broker“: Entweder ist Port 1883 in der DSM-Firewall nicht freigegeben, oder die ACL-Datei erlaubt dem HA-Benutzer keinen Zugriff. Firewall-Regel prüfen und ACL um topic readwrite # für den HA-Benutzer ergänzen.
• Neue Credentials werden nicht akzeptiert: Mosquitto lädt die passwd-Datei nicht automatisch neu. Nach jeder Änderung: sudo docker restart mosquitto oder sudo docker kill --signal=SIGHUP mosquitto.
• WebSocket-Verbindungen auf Port 9001 schlagen fehl: In der mosquitto.conf fehlt protocol websockets direkt nach dem listener 9001-Eintrag. Ohne diese Zeile behandelt Mosquitto den Port als normalen MQTT-TCP-Listener.

Häufige Fragen

Muss ich allow_anonymous true setzen, damit der Broker funktioniert?

Nein, vermeiden Sie das. allow_anonymous false ist der sichere Standard in Mosquitto 2.x. Legen Sie Benutzer mit mosquitto_passwd an und verweisen Sie mit password_file darauf. Anonymer Zugriff erlaubt jedem Gerät im Netz, Schalter und Sensoren über beliebige Topics zu steuern.

Was ist der Unterschied zwischen eclipse-mosquitto:latest und eclipse-mosquitto:2.1.2-alpine?

latest und 2.1.2-alpine zeigen aktuell auf dasselbe Image. Für den Produktivbetrieb auf dem NAS ist das spezifische Tag empfohlen: latest kann sich beim nächsten docker compose pull auf eine neue Hauptversion ändern, die möglicherweise Breaking Changes enthält. Mit dem festgelegten Tag behalten Sie die Kontrolle über Updates.

Wie verbinde ich Home Assistant (als Docker-Container auf demselben NAS) mit Mosquitto?

Mit der NAS-IP als Broker-Adresse, nicht localhost (siehe Schritt 6): Broker NAS-IP, Port 1883, Benutzer homeassistant mit Passwort.

Wie aktualisiere ich Mosquitto auf eine neue Version?

In der compose.yaml den Tag anpassen (z. B. von 2.1.2-alpine auf 2.x.x-alpine), dann im Container Manager das Projekt stoppen, per SSH sudo docker pull eclipse-mosquitto:2.x.x-alpine ausführen und das Projekt wieder starten. Lesen Sie vorher das ChangeLog: 2.1 kündigt etwa an, password_file und acl_file in 3.0 durch Plugins zu ersetzen. Konfiguration und Daten in den Volumes bleiben erhalten.

Brauche ich TLS/SSL für Mosquitto auf dem heimischen NAS?

Für ein rein lokales Netzwerk, in dem alle Clients im Heimnetz erreichbar sind, ist TLS optional. Sobald der MQTT-Broker über das Internet erreichbar sein soll, ist TLS Pflicht. TLS konfigurieren Sie im Image 2.1.2-alpine direkt in der mosquitto.conf (certfile, keyfile, Port 8883). Die -openssl-Tags gehören zur älteren 2.0-Linie und sind nur für TLS-PSK gedacht.

Wie teste ich ohne externe Tools, ob der Broker korrekt läuft?

Mit mosquitto_sub und mosquitto_pub im Container, wie in Schritt 5 beschrieben. Erscheint die Nachricht im Subscriber, arbeitet der Broker korrekt.

Fazit

Mosquitto 2.1.2 läuft auf dem Synology NAS mit Compose-Projekt, mosquitto.conf und ACL-Datei in etwa 25 Minuten. Die häufigsten Fehlerquellen: fehlende listener-Direktive, Passwort-Datei nicht mit mosquitto_passwd erzeugt und Dateirechte, die nicht zu UID 1883 passen. Mit diesen drei Punkten steht ein passwortgeschützter Broker für Phoscon, Home Assistant und Node-RED.

Weiterführende Anleitungen und Quellen

• Home Assistant mit Docker: die lokale Smart-Home-Zentrale – Mosquitto als MQTT-Broker für HA einrichten
• Phoscon einrichten: Zigbee-Server mit deCONZ in Docker installieren – Zigbee-Gateway, das Mosquitto als MQTT-Backend nutzt
• Node-RED auf dem Synology NAS installieren: Automatisierung per Flow-Editor – MQTT-Flows mit Mosquitto als Datenquelle
• ioBroker auf dem Synology NAS installieren: Smart-Home-Zentrale – weitere Automatisierungsplattform mit Mosquitto-Anbindung

Quellen: Eclipse Mosquitto Docker Hub (hub.docker.com/_/eclipse-mosquitto), offizielle mosquitto.conf-Dokumentation (mosquitto.org/man/mosquitto-conf-5.html), Mosquitto 2.0 Migrationsleitfaden (mosquitto.org/documentation/migrating-to-2-0/), Mosquitto ChangeLog (mosquitto.org/ChangeLog.txt).