Ein MQTT-Broker ist das Herzstück jedes lokalen Smart-Home-Stacks: Zigbee-Gateways wie Phoscon/deCONZ, Sensoren, Aktoren und Plattformen wie Home Assistant, Node-RED oder ioBroker kommunizieren alle über diesen zentralen Nachrichten-Verteiler. Eclipse Mosquitto ist der de-facto-Standard – leichtgewichtig, bewährt und komplett selbst gehostet. Auf dem Synology NAS läuft er als Docker-Container im Container Manager und liefert dir einen dauerhaft erreichbaren Broker ohne Abo, ohne Cloud und ohne versteckte Abhängigkeiten. Diese Anleitung richtet Mosquitto 2.1.2 als Compose-Projekt ein, erklärt warum anonymer Zugriff ausbleibt, zeigt wie du Passwort-Datei und ACLs anlegst und verifiziert jeden Schritt, bevor du weitermachst.

Voraussetzungen

Synology NAS mit DSM 7.2 oder höher und installiertem Container Manager
SSH-Zugriff auf das NAS für chmod-Befehle und mosquitto_passwd (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 existieren, bevor der Container startet – das Volume-Mount erzeugt nur das Verzeichnis, nicht die Konfigurationsdatei. Lege die Ordner über die File Station an oder per SSH. Den Basis-Weg und die PUID/PGID-Ermittlung erklärt die Anleitung Docker-Ordner und Berechtigungen auf dem Synology NAS.

Verbinde dich per SSH und erstelle die Verzeichnisse:

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

Mosquitto läuft im Container als Benutzer mosquitto mit UID 1883. Setze die Schreibrechte auf data und log entsprechend – die config-Verzeichnis enthält die passwd-Datei und braucht ebenfalls eingeschränkte Rechte:

chmod 700 /volume1/docker/mosquitto/config
chmod 777 /volume1/docker/mosquitto/data
chmod 777 /volume1/docker/mosquitto/log

Verifizieren: Führe ls -la /volume1/docker/mosquitto/ aus. Du solltest drei Unterverzeichnisse sehen: config, data und log. Alle drei müssen existieren, bevor du fortfährst.

Schritt 2: mosquitto.conf erstellen

Die Konfigurationsdatei ist das kritischste Element. 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. Erstelle die Datei direkt per SSH:

cat > /volume1/docker/mosquitto/config/mosquitto.conf << '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

Warum allow_anonymous false? Seit Mosquitto 2.0 ist dies der Standard – und er ist sinnvoll: Ohne Authentifizierung kann jedes Gerät im Netzwerk beliebige Topics lesen und beschreiben, also z. B. Schalter auslösen oder Sensor-Daten fälschen. Anonymer Zugriff bleibt deshalb dauerhaft deaktiviert.

Erstelle außerdem eine leere ACL-Datei als Platzhalter (sie wird in Schritt 4 befüllt):

touch /volume1/docker/mosquitto/config/acl
touch /volume1/docker/mosquitto/config/passwd

Verifizieren: Prüfe mit 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 du ein neues Compose-Projekt im Container Manager anlegst, zeigt die Grund-Anleitung Container Manager: Docker-Compose-Projekt anlegen, starten und aktualisieren. Benenne das Projekt mosquitto und verwende 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 Alpine-Variant (2.1.2-alpine) ist ca. 9,5 MB groß und für Synology-Produktion empfohlen. Das spezifische Tag verhindert, dass ein docker compose pull unbemerkt auf eine neue Hauptversion wechselt. Alternativ kannst du eclipse-mosquitto:2 verwenden, wenn du immer automatisch auf die neueste 2.x-Version aktualisieren möchtest – dann aber Changelogs vor dem Update prüfen.

Starte das Projekt über den Container Manager. Der Container sollte innerhalb weniger Sekunden den Status „Wird ausgeführt" erreichen.

Verifizieren: Im Container Manager unter „Container" siehst du mosquitto mit grünem Status. Klicke auf „Protokoll" – dort 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 siehst du eine Fehlermeldung zu mosquitto.conf, prüfe Schritt 2.

Schritt 4: Passwort-Datei und ACLs einrichten

Mosquitto liefert keinerlei Standard-Credentials mit – alle Benutzer werden mit dem Tool mosquitto_passwd direkt im laufenden Container angelegt. Öffne ein SSH-Terminal und führe aus:

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

# Weiteren Benutzer fuer Home Assistant hinzufuegen (-b = nicht-interaktiv)
docker exec -it mosquitto mosquitto_passwd /mosquitto/config/passwd homeassistant

Du wirst nach dem Passwort gefragt (oder gibst es mit -b Benutzer Passwort direkt an). Das Flag -c erzeugt eine neue Datei – verwende es nur beim allerersten Benutzer, sonst wird die Datei überschrieben.

Jetzt befüllst du die ACL-Datei. ACLs steuern, welcher Benutzer welche MQTT-Topics lesen und beschreiben darf. Für ein typisches Smart-Home-Setup:

# 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/#

Schreibe die Datei per SSH:

cat > /volume1/docker/mosquitto/config/acl << 'EOF'
user admin
topic readwrite #

user homeassistant
topic readwrite #
EOF

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

docker restart mosquitto

Verifizieren: Im Container Manager > Protokoll erscheint nach dem Neustart erneut die Startmeldung. Prüfe außerdem:

docker exec mosquitto mosquitto_passwd -v /mosquitto/config/passwd

Die Ausgabe listet den angelegten Benutzer auf. Fehlt er, ist etwas beim Anlegen schiefgelaufen.

Schritt 5: Verbindung testen mit mosquitto_sub und mosquitto_pub

Das Alpine-Image enthält mosquitto_sub und mosquitto_pub – du brauchst keine externen Tools zu installieren. Öffne zwei SSH-Sitzungen oder nutze den Terminal-Tab im Container Manager.

Im ersten Terminal: Abonniere ein Test-Topic (läuft im Vordergrund und wartet auf Nachrichten):

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

Im zweiten Terminal: Sende eine Nachricht:

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

Verifizieren: Im ersten Terminal erscheint sofort:

test/hello Mosquitto läuft!

Erscheint stattdessen Connection error: Connection Refused: not authorised, prüfe Benutzername, Passwort und ob der Container nach der passwd-Änderung neu gestartet wurde. 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 Home-Assistant-Anbindung öffne in Home Assistant: Einstellungen > Geräte & Dienste > Integration hinzufügen > MQTT. Trage ein:

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

Alternativ in der configuration.yaml:

mqtt:
  broker: 192.168.1.100
  port: 1883
  username: homeassistant
  password: DeinPasswort

Wichtig: Wenn Home Assistant selbst als Docker-Container auf demselben NAS läuft, verwende trotzdem die NAS-IP, nicht localhost – Container mit unterschiedlichen Netzwerken kommunizieren nicht über loopback. Die vollständige 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 (docker exec mosquitto cat /mosquitto/log/mosquitto.log) siehst du 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": Entweder wurde kein Benutzer mit mosquitto_passwd angelegt, der Pfad /mosquitto/config/passwd in der mosquitto.conf stimmt nicht mit dem Volume-Mount überein, oder der Container wurde nach dem Anlegen des Benutzers nicht neu gestartet. Passwort-Datei und Pfad prüfen, dann docker restart mosquitto.
Container startet, mosquitto.conf wird nicht gefunden: Die Datei wurde nicht vor dem ersten Start angelegt. Das Volume-Mount erzeugt nur das Verzeichnis, nicht die Datei. mosquitto.conf manuell in /volume1/docker/mosquitto/config/ erstellen, dann Container neu starten.
„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: docker restart mosquitto oder 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 – und das solltest du unbedingt vermeiden. allow_anonymous false ist der sichere Standard in Mosquitto 2.x. Lege stattdessen mit mosquitto_passwd Benutzer an und referenziere die password_file in der mosquitto.conf. Anonymer Zugriff erlaubt jedem Gerät im Netzwerk ohne Authentifizierung, beliebige Topics zu lesen und zu schreiben – das ist in einem Smart-Home-Stack, der Schalter und Sensoren steuert, ein ernstes Sicherheitsrisiko.

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 gepinnten Tag behältst du die Kontrolle über Updates.

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

Verwende die NAS-IP-Adresse als Broker-Adresse – nicht localhost. Zwei Container mit unterschiedlichen Netzwerken kommunizieren nicht über den Loopback-Adapter. In Home Assistant: Einstellungen > Geräte & Dienste > MQTT. Broker: NAS-IP, Port: 1883, Benutzername und Passwort für den homeassistant-Account eintragen.

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 docker pull eclipse-mosquitto:2.x.x-alpine ausführen und das Projekt wieder starten. 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. Für TLS-Unterstützung mit OpenSSL benötigst du das Tag eclipse-mosquitto:2.0.22-openssl – das Alpine-Variant nutzt standardmäßig LibreSSL, was für lokale Nutzung ausreicht.

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

Nutze mosquitto_sub und mosquitto_pub direkt im Container – sie sind im Alpine-Image enthalten. Im Container Manager unter „Terminal" oder per SSH: mosquitto_sub -h 127.0.0.1 -t '#' -u admin -P Passwort -v & im Hintergrund starten, dann mosquitto_pub -h 127.0.0.1 -t test/hello -m 'Welt' -u admin -P Passwort. Die Nachricht muss im Subscriber erscheinen.

Fazit

Mosquitto 2.1.2 auf dem Synology NAS ist mit einem Compose-Projekt, einer sauber aufgesetzten mosquitto.conf und einer eigenen ACL-Datei in etwa 25 Minuten produktionsreif. Die drei Kernpunkte, die beim Setup am häufigsten für Probleme sorgen, sind bekannt: die listener-Direktive muss explizit gesetzt sein, die Passwort-Datei muss mit mosquitto_passwd im Container erzeugt werden und Datei-Berechtigungen auf den Volumes müssen auf UID 1883 passen. Wer diese drei Punkte beachtet, hat einen zuverlässigen, passwortgeschützten MQTT-Broker als solides Fundament für den gesamten Smart-Home-Stack – von Phoscon über Home Assistant bis 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).