Mosquitto per Docker mit Passwortschutz einrichten

Veröffentlicht am 27. Juli 2026 · Geschätzte Lesezeit: 3 Minuten

Eclipse Mosquitto ist ein schlanker MQTT-Broker: Smart-Home-Geräte und Dienste tauschen darüber kurze Nachrichten aus. Diese Anleitung startet Mosquitto per Docker, verbietet anonyme Verbindungen und legt einen Benutzer mit Passwort an. Plane etwa 15 Minuten ein. Die Einstellungen folgen der offiziellen Mosquitto-Dokumentation und dem offiziellen Docker-Image (Stand: 27. Juli 2026).

Voraussetzungen

• Ein Linux-Server mit Docker und Docker Compose
• Ein Benutzerkonto mit Berechtigung für Docker
• Port 1883 im Heimnetz frei
• Ein MQTT-Programm zum späteren Funktionstest

1. Ordnerstruktur anlegen

Führe diese Befehle auf deinem Docker-Server aus. Sie erstellen getrennte Ordner für Konfiguration, dauerhafte Daten und optionale Protokolldateien:

mkdir -p ~/mosquitto/config ~/mosquitto/data ~/mosquitto/log

cd ~/mosquitto

2. Mosquitto konfigurieren

Lege im Ordner ~/mosquitto/config die Datei mosquitto.conf mit folgendem Inhalt an. Mosquitto lauscht im Heimnetz auf Port 1883, weist anonyme Clients ab und speichert dauerhafte MQTT-Daten im Datenordner:

listener 1883
allow_anonymous false
password_file /mosquitto/config/passwordfile

persistence true
persistence_location /mosquitto/data/

log_dest stdout

Nur für ein vertrauenswürdiges Heimnetz

MQTT auf Port 1883 ist nicht verschlüsselt. Benutzername, Passwort und Nachrichten können in einem unsicheren Netz mitgelesen werden. Öffne den Port niemals direkt zum Internet. Für Zugriffe von außen verwendest du ein VPN oder richtest MQTT mit TLS ein.

3. Compose-Datei anlegen

Lege im Ordner ~/mosquitto eine Datei namens compose.yaml an. Das Image bleibt bewusst auf der Hauptversion 2, damit ein späteres Upgrade auf eine neue Hauptversion nicht unbemerkt erfolgt:

services:
  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "1883:1883"
    volumes:
      - ./config:/mosquitto/config
      - ./data:/mosquitto/data
      - ./log:/mosquitto/log

Prüfe die Datei auf Tippfehler:

docker compose config

4. MQTT-Benutzer erstellen

Ersetze <mqtt-benutzer> durch den gewünschten Benutzernamen. Der Befehl wird im Ordner ~/mosquitto ausgeführt und fragt das Passwort zweimal verdeckt ab. Es steht dadurch weder im Befehl noch im Shell-Verlauf:

docker compose run --rm --entrypoint mosquitto_passwd mosquitto -c /mosquitto/config/passwordfile <mqtt-benutzer>

Prüfe nur, ob die Passwortdatei vorhanden ist. Gib ihren Inhalt nicht weiter:

ls -l config/passwordfile

Keine Passwörter in Compose-Dateien

Trage das MQTT-Passwort nicht direkt in compose.yaml, Skripte oder Screenshots ein. Speichere es im Passwortmanager und hinterlege es bei Clients über deren geschützte Einstellungsoberfläche oder Secret-Verwaltung.

5. Broker starten

Starte Mosquitto im Hintergrund:

docker compose up -d

Prüfe, ob der Container läuft:

docker compose ps

Die letzten Startmeldungen zeigen, ob Konfiguration und Passwortdatei gelesen wurden:

docker compose logs --tail=100 mosquitto

6. Schutz und Verbindung testen

Dieser Test versucht absichtlich eine Verbindung ohne Zugangsdaten. Mosquitto muss sie mit Not authorized ablehnen. Beende den Befehl bei Bedarf mit Strg+C:

docker compose exec mosquitto mosquitto_sub -h localhost -t test/status

Richte danach in deinem MQTT-Programm folgende Werte ein:

• Server: <server-ip> – die feste IP-Adresse des Docker-Servers
• Port: 1883
• Benutzer: <mqtt-benutzer>
• Passwort: das zuvor vergebene Passwort
• Test-Thema: test/status

Abonniere test/status und veröffentliche dort eine kurze Testnachricht. Erscheint sie beim Abonnenten, funktionieren Broker und Anmeldung.

Typische Fehler

Address already in use bedeutet, dass Port 1883 schon belegt ist. Bei Permission denied prüfst du die Rechte der Ordner config und data. Meldet Mosquitto eine fehlende Passwortdatei, führe Schritt 4 erneut im Ordner ~/mosquitto aus.

7. Backup und Rückweg

Stoppe den Broker kurz, damit die dauerhaften Daten konsistent bleiben:

docker compose down

Wechsle in den übergeordneten Ordner:

cd ~

Sichere Konfiguration, Passwort-Hashes und MQTT-Daten in einem Archiv:

tar -czf mosquitto-backup.tar.gz mosquitto

Das Archiv enthält die Passwortdatei und muss geschützt aufbewahrt werden. Starte den Broker danach wieder:

cd ~/mosquitto

docker compose up -d

Für den Rückweg stoppst du Mosquitto mit docker compose down. Die Ordner bleiben erhalten. Ein vorhandenes Backup kannst du nach dem Stoppen zurückkopieren und den Container anschließend neu starten.

Fertig

Mosquitto nimmt nun im Heimnetz nur noch angemeldete MQTT-Clients an. Eine Verbindung ohne Zugangsdaten wird abgewiesen; mit deinem Benutzer kannst du unter test/status eine Nachricht senden und wieder empfangen.