Mosquitto ist ein freier MQTT-Broker der Eclipse Foundation. Er braucht wenig Rechenleistung und läuft auf einem kleinen Linux-Server, einem Raspberry Pi oder einem NAS. Dieser Teil richtet ihn mit Docker ein, sichert ihn ab und bindet ein Python-Programm an. Die Grundlagen erklären Teil 1 und Teil 2.

Alle Befehle und das Programm sind mit Mosquitto 2.1.4 und der Python-Bibliothek paho-mqtt 2.2.0 getestet, Stand: November 2026.

Den Broker starten

Vorausgesetzt sind eine Docker-Installation und etwas Übung mit der Kommandozeile, für das Programm weiter unten außerdem Python 3. Legen Sie die Ordner mosquitto/config und mosquitto/data an und darin die Datei mosquitto/config/mosquitto.conf mit diesem Inhalt:

listener 1883
allow_anonymous true

Die zweite Zeile erlaubt Verbindungen ohne Anmeldung. Das ist nur für den ersten Test gedacht. Gestartet wird der Broker aus dem Ordner, der mosquitto enthält:

docker run -d --name mosquitto --restart unless-stopped \
  -p 127.0.0.1:1883:1883 \
  -v "$PWD/mosquitto/config:/mosquitto/config" \
  -v "$PWD/mosquitto/data:/mosquitto/data" \
  eclipse-mosquitto:2

Die Angabe 127.0.0.1 sorgt dafür, dass nur Programme auf demselben Rechner den Broker erreichen. Für Geräte im Netz wird der Port erst nach der Absicherung freigegeben.

Vorsicht mit der mitgelieferten Konfiguration

Startet man das Docker-Image ohne eigene Konfiguration, gilt die mitgelieferte. Sie erlaubt in der aktuellen Version Verbindungen ohne Anmeldung auf Port 1883. Ein Server, der so mit -p 1883:1883 im Internet erreichbar ist, betreibt einen offenen Broker, den jeder lesen und beschreiben kann. Mosquitto selbst ist strenger: Ganz ohne Konfigurationsdatei nimmt es nur Verbindungen vom eigenen Rechner an.

Der erste Test

Die Werkzeuge mosquitto_sub zum Abonnieren und mosquitto_pub zum Senden sind im Container enthalten. Auf dem eigenen Rechner gibt es sie unter Debian und Ubuntu im Paket mosquitto-clients, auf dem Mac über Homebrew im Paket mosquitto. Ein Terminal abonniert alles unterhalb von haus:

docker exec -it mosquitto mosquitto_sub -t 'haus/#' -v

Ein zweites Terminal sendet einen Messwert und einen Sollwert, den Sollwert mit Retain-Flag:

docker exec mosquitto mosquitto_pub -t haus/wohnzimmer/thermostat/temperatur -m 21.5
docker exec mosquitto mosquitto_pub -t haus/wohnzimmer/thermostat/soll -m 21 -r

Im ersten Terminal erscheinen beide Topics mit ihren Werten, die Option -v zeigt das Topic mit an. Beendet man den Abonnenten mit Strg+C und startet ihn neu, ist nur der Sollwert sofort wieder da, denn nur er wurde als Retained Message gespeichert. Eine leere Nachricht mit den Optionen -r -n löscht ihn.

Absichern: Anmeldung und Zugriffsrechte

Für den Dauerbetrieb braucht der Broker drei Dinge: eine Anmeldung, Zugriffsrechte und eine verschlüsselte Verbindung. Die ersten beiden folgen jetzt, die Verschlüsselung weiter unten. Jedes Gerät und jedes Programm bekommt eigene Zugangsdaten. Wird ein Gerät ausgetauscht oder gestohlen, sperren Sie nur dessen Zugang.

Zugriffsrechte festlegen

Eine Zugriffsliste, kurz ACL für Access Control List, legt fest, wer welche Topics lesen und beschreiben darf. Sie kommt in die Datei mosquitto/config/acl:

# Dashboard: liest alles im Haus, setzt Sollwerte
user dashboard
topic read haus/#
topic write haus/+/thermostat/soll/set
# Thermostat: nur der eigene Bereich
user thermostat-wohnzimmer
topic write haus/wohnzimmer/thermostat/#
topic read haus/wohnzimmer/thermostat/soll/set

Mit read darf ein Benutzer Nachrichten der genannten Topics empfangen, mit write dorthin senden, mit readwrite oder ganz ohne Angabe beides. Was nicht in der Liste steht, ist verboten. Ein gekapertes Thermostat kann so weder andere Räume steuern noch Nachrichten anderer Geräte mitlesen.

Konfiguration umstellen

Die Datei mosquitto.conf bekommt diesen Inhalt:

listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd
acl_file /mosquitto/config/acl
persistence true
persistence_location /mosquitto/data/

Die letzten beiden Zeilen schalten die Persistenz ein. Retained Messages und Sessions überstehen dann einen Neustart, im Test blieb der gespeicherte Status erhalten. Mosquitto schreibt die Daten beim ordentlichen Beenden auf die Festplatte und zwischendurch in festen Abständen. Wer den Container hart mit docker rm -f entfernt, verliert deshalb die Änderungen seit der letzten Sicherung.

Benutzer anlegen und neu starten

docker exec mosquitto chown -R mosquitto:mosquitto /mosquitto/config
docker exec mosquitto chmod 0700 /mosquitto/config/acl
docker exec -it -u mosquitto mosquitto mosquitto_passwd -c /mosquitto/config/passwd dashboard
docker exec -it -u mosquitto mosquitto mosquitto_passwd /mosquitto/config/passwd thermostat-wohnzimmer
docker restart mosquitto

Mosquitto läuft im Container als eigener Benutzer namens mosquitto. Ihm müssen Passwortdatei und Zugriffsliste gehören. Kann er die Passwortdatei nicht lesen, etwa weil sie root gehört, startet der Broker nicht und meldet im Protokoll „Unable to open pwfile“. Das Protokoll zeigt docker logs mosquitto. Deshalb gehen die ersten beiden Befehle voraus, und mosquitto_passwd läuft dank der Docker-Option -u ebenfalls als mosquitto. Es fragt jeweils nach einem Passwort. Die Option -c legt die Datei neu an und gehört nur zum ersten Benutzer, beim zweiten würde sie den ersten überschreiben.

Die Passwörter selbst stehen nicht in der Datei. mosquitto_passwd speichert nur gesalzene Hashwerte nach dem Verfahren PBKDF2 mit SHA-512, aus denen sich das Passwort nicht zurückrechnen lässt. Die Datei legt es so an, dass nur ihr Besitzer sie lesen kann. Wählen Sie trotzdem lange Zufallspasswörter, etwa aus einem Passwortmanager: Wer die Datei erbeutet, kann kurze Passwörter durch Ausprobieren finden.

Weitere Benutzer legen Sie später mit demselben Befehl ohne -c an, mit -D statt -c löschen Sie einen. Danach liest docker kill -s HUP mosquitto die Passwörter neu ein, ohne den Broker neu zu starten. Einen gelöschten Benutzer trennte der Broker im Test dabei sofort und ließ ihn nicht wieder herein. Auf einem Linux-Server brauchen Sie zum Bearbeiten der Dateien von nun an sudo, denn sie gehören jetzt dem Benutzer des Containers. Und mosquitto_sub und mosquitto_pub brauchen ab jetzt die Optionen -u für den Benutzer und -P für das Passwort.

Ein Python-Programm anbinden

Für Python gibt es die Bibliothek paho-mqtt. Das Programm braucht Version 2.0 oder neuer, ältere Versionen kennen CallbackAPIVersion nicht und rufen die Funktionen anders auf. Am besten installieren Sie die Bibliothek in einer eigenen virtuellen Umgebung, hier im Ordner mqtt-umgebung:

python3 -m venv mqtt-umgebung
mqtt-umgebung/bin/pip install paho-mqtt

Ein einfaches pip install paho-mqtt lehnen aktuelle Versionen von Debian, Ubuntu und Raspberry Pi OS mit der Meldung „externally-managed-environment“ ab. Bricht python3 -m venv mit einem Hinweis auf ensurepip ab, fehlt das Paket python3-venv, installiert mit sudo apt install python3-venv. Das Paket python3-paho-mqtt aus dem Paketmanager ist erst ab Debian 13 und Ubuntu 26.04 neu genug, ältere Versionen liefern 1.6.1.

Das folgende Programm spielt ein Thermostat. Es meldet sich als online, hinterlegt dafür einen Last Will und übernimmt neue Sollwerte.

import os
import paho.mqtt.client as mqtt
BASIS = "haus/wohnzimmer/thermostat"
def on_connect(client, userdata, flags, reason_code, properties):
    if reason_code.is_failure:
        print("Verbindung abgelehnt:", reason_code)
        return
    # Nach jeder (Wieder-)Verbindung: Status melden, Befehle abonnieren
    client.publish(f"{BASIS}/status", "online", qos=1, retain=True)
    client.subscribe(f"{BASIS}/soll/set", qos=1)
def on_message(client, userdata, msg):
    try:
        soll = float(msg.payload)
    except ValueError:
        return  # keine Zahl: ignorieren
    if not 5 <= soll <= 30:
        return  # außerhalb des erlaubten Bereichs
    print("Neuer Sollwert:", soll)
    client.publish(f"{BASIS}/soll", soll, qos=1, retain=True)
client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="thermostat-wohnzimmer")
client.username_pw_set("thermostat-wohnzimmer", os.environ["MQTT_PASSWORT"])
client.will_set(f"{BASIS}/status", "offline", qos=1, retain=True)
client.on_connect = on_connect
client.on_message = on_message
client.connect_async("localhost", 1883, keepalive=30)
client.loop_forever(retry_first_connection=True)

Speichern Sie das Programm als thermostat.py und starten Sie es mit dem Python der virtuellen Umgebung. Das Passwort des Thermostats bekommt es über die Umgebungsvariable MQTT_PASSWORT, statt Passwort setzen Sie das echte ein:

export MQTT_PASSWORT='Passwort'
mqtt-umgebung/bin/python thermostat.py

Einen neuen Sollwert schickt das Dashboard, hier wieder mit mosquitto_pub und dem Passwort des Benutzers dashboard:

docker exec mosquitto mosquitto_pub -u dashboard -P 'Passwort' -t haus/wohnzimmer/thermostat/soll/set -m 22.5

Das Programm gibt den Wert aus und meldet ihn unter haus/wohnzimmer/thermostat/soll zurück. Einige Stellen verdienen einen zweiten Blick:

  • Status und Abonnement stehen in on_connect. Nach einem Verbindungsabbruch verbindet sich paho-mqtt selbst neu und ruft on_connect erneut auf. Im Test war das Programm nach einem Neustart des Brokers nach wenigen Sekunden wieder online.
  • loop_forever() blockiert das Programm und kümmert sich um Empfang, Lebenszeichen und Wiederverbinden. Zusammen mit connect_async und retry_first_connection=True gilt das schon für die erste Verbindung: Läuft der Broker beim Start noch nicht, etwa nach einem Stromausfall, wartet das Programm, statt mit ConnectionRefusedError abzubrechen. Im Test war es wenige Sekunden nach dem Start des Brokers online. Soll das Programm daneben etwas anderes tun, etwa regelmäßig messen, startet loop_start() dieselbe Arbeit in einem eigenen Thread.
  • Werte, die keine Zahl sind oder außerhalb von 5 bis 30 Grad liegen, werden übergangen, statt das Programm zu beenden.
  • Das Passwort steht nicht im Code, sondern kommt aus der Umgebungsvariablen.

Das Programm meldet sich nie ordentlich ab. Wird es beendet oder bricht die Verbindung ab, veröffentlicht der Broker deshalb den Last Will, und unter …/status steht „offline“.

Verschlüsseln mit TLS

Ohne Verschlüsselung gehen Benutzernamen, Passwörter und Nachrichten im Klartext durchs Netz. Wer den Datenverkehr mitliest, sieht alles. TLS, dasselbe Verfahren wie bei HTTPS, verhindert das. Der Broker braucht dafür ein Zertifikat und den passenden Schlüssel. Für einen Broker mit öffentlichem Namen eignet sich ein Zertifikat von Let's Encrypt. Im eigenen Netz genügt eine eigene kleine Zertifizierungsstelle, kurz CA.

Eigene Zertifizierungsstelle anlegen

Der Broker heißt im Beispiel mqtt.home.arpa. Die Endung home.arpa ist für Namen im Heimnetz vorgesehen. Der Name muss im Netz auf den Rechner des Brokers zeigen, etwa über einen Eintrag im Router. Diese vier Befehle erzeugen die CA und das Zertifikat des Brokers:

openssl req -x509 -newkey rsa:2048 -nodes -days 3650 -subj "/CN=Heimnetz-CA" \
  -addext "basicConstraints=critical,CA:TRUE" \
  -addext "keyUsage=critical,keyCertSign,cRLSign" \
  -addext "subjectKeyIdentifier=hash" -keyout ca.key -out ca.crt
openssl req -newkey rsa:2048 -nodes -subj "/CN=mqtt.home.arpa" \
  -keyout server.key -out server.csr
cat > server.ext <<ENDE
subjectAltName=DNS:mqtt.home.arpa
keyUsage=critical,digitalSignature,keyEncipherment
extendedKeyUsage=serverAuth
authorityKeyIdentifier=keyid,issuer
ENDE
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -days 825 -extfile server.ext -out server.crt

Der erste Befehl erzeugt die CA, gültig für zehn Jahre. Die übrigen erzeugen den Schlüssel des Brokers und ein Zertifikat für seinen Namen, unterschrieben von der CA und 825 Tage gültig. Apple-Geräte akzeptieren Serverzertifikate nur bis zu dieser Laufzeit. Die Zusatzangaben in den Befehlen braucht neuere Software, die streng prüft, Python zum Beispiel ab Version 3.13. Ohne sie wurde die CA im Test mit „CA cert does not include key usage extension“ abgelehnt. Die Datei ca.key ist das wichtigste Geheimnis: Wer sie hat, kann Zertifikate ausstellen, denen alle Clients vertrauen. Sie gehört nicht auf den Broker, sondern sicher verwahrt.

Den Broker umstellen

Die Dateien server.crt und server.key kommen in den Ordner mosquitto/config. Die Konfiguration bekommt einen zweiten Listener auf dem üblichen Port 8883:

listener 8883
certfile /mosquitto/config/server.crt
keyfile /mosquitto/config/server.key

Auch Zertifikat und Schlüssel müssen dem Benutzer mosquitto gehören, sonst bricht der Start mit „Permission denied“ ab:

docker exec mosquitto chown -R mosquitto:mosquitto /mosquitto/config
docker exec mosquitto chmod 0600 /mosquitto/config/server.key

Für den neuen Port legen Sie den Container einmal neu an: docker stop mosquitto, dann docker rm mosquitto und docker run wie oben, zusätzlich mit -p 8883:8883. Durch das ordentliche Anhalten sichert Mosquitto vorher seine Daten, sie liegen in den eingebundenen Ordnern und bleiben erhalten. Port 1883 bleibt so nur auf dem Rechner des Brokers erreichbar, alle anderen Geräte verbinden sich verschlüsselt.

Die Clients bekommen die Datei ca.crt und prüfen damit das Zertifikat des Brokers. mosquitto_sub und mosquitto_pub erhalten dafür die Optionen -h mqtt.home.arpa -p 8883 --cafile ca.crt. Im Python-Programm kommt vor connect_async die Zeile client.tls_set(ca_certs="ca.crt") hinzu, und connect_async nutzt mqtt.home.arpa und Port 8883. Bei einem Zertifikat von Let's Encrypt genügt client.tls_set() ohne Angabe. Im Test bestand das Zertifikat auch die strenge Prüfung von Python 3.13.

Der Name im Zertifikat muss zu der Adresse passen, unter der die Clients den Broker ansprechen. Im Test lehnte der Client eine Verbindung über die IP-Adresse ab, weil das Zertifikat nur für den Namen ausgestellt war. Genau diese Prüfung schützt davor, dass sich ein fremder Rechner als Broker ausgibt. Schalten Sie sie nie ab, auch wenn Bibliotheken das anbieten. Den Broker selbst stellen Sie am besten nicht direkt ins Internet. Für den Zugriff von unterwegs ist ein VPN sicherer als ein offener Port.

Geräte mit eigenem Zertifikat

Noch strenger ist es, auch von jedem Gerät ein Zertifikat zu verlangen. Man nennt das mutual TLS. Ein gestohlenes Passwort reicht dann nicht mehr, ein Angreifer bräuchte auch die Schlüsseldatei des Geräts. Drei Zeilen unter listener 8883 schalten das ein, dazu kommt die Datei ca.crt in den Ordner mosquitto/config:

cafile /mosquitto/config/ca.crt
require_certificate true
use_identity_as_username true

Das Zertifikat eines Geräts entsteht mit derselben CA, mit dem Benutzernamen als Namen und dem Verwendungszweck Client:

openssl req -newkey rsa:2048 -nodes -subj "/CN=thermostat-wohnzimmer" \
  -keyout thermostat.key -out thermostat.csr
cat > geraet.ext <<ENDE
keyUsage=critical,digitalSignature,keyEncipherment
extendedKeyUsage=clientAuth
authorityKeyIdentifier=keyid,issuer
ENDE
openssl x509 -req -in thermostat.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -days 825 -extfile geraet.ext -out thermostat.crt

Nach docker restart mosquitto übernimmt der Broker auf diesem Port den Namen aus dem Zertifikat als Benutzernamen. Die Zugriffsliste gilt unverändert, ein Passwort prüft er hier nicht mehr. Im Python-Programm bekommt tls_set zusätzlich certfile="thermostat.crt" und keyfile="thermostat.key". mosquitto_sub und mosquitto_pub erhalten dafür die Optionen --cert thermostat.crt --key thermostat.key. Im Test kam ein Client ohne Gerätezertifikat nicht herein, auch nicht mit richtigem Passwort. Mit Zertifikat durfte das Thermostat wie zuvor nur in seinem eigenen Bereich senden. Bedenken Sie: Über Port 8883 braucht dann jeder Client ein Zertifikat, auch das Dashboard.

Ein gestohlenes Gerät sperren Sie hier nicht über die Passwortdatei, denn die spielt auf diesem Port keine Rolle. Im Test durfte ein Gerät mit gültigem Zertifikat senden, obwohl es dort gar nicht eingetragen war. Löschen Sie stattdessen seinen Abschnitt aus der Zugriffsliste und lesen Sie sie mit docker kill -s HUP mosquitto neu ein. Im Test erhielt das Gerät danach auch über die bestehende Verbindung keine Nachrichten mehr, und seine eigenen verwarf der Broker. Verbinden kann es sich allerdings weiterhin. Ganz aussperren lässt es sich mit einer Sperrliste für Zertifikate, die Mosquitto über die Einstellung crlfile einliest.

Häufige Fehler

Zwei Geräte mit derselben Client-ID
Folge: Sie werfen sich gegenseitig aus der Verbindung, im Protokoll steht „session taken over“.
Abhilfe: jedem Gerät eine eigene ID geben, etwa aus der Seriennummer.
Befehl mit Retain-Flag gesendet
Folge: Er wird bei jedem Neuverbinden erneut ausgeführt.
Abhilfe: Retain nur für Zustände verwenden.
Abonnement außerhalb von on_connect
Folge: Nach einem Verbindungsabbruch kommen keine Nachrichten mehr.
Abhilfe: in on_connect abonnieren.
Fehlende Schreibrechte bei MQTT 3.1.1
Folge: Der Broker verwirft die Nachricht ohne jede Meldung.
Abhilfe: Zugriffsliste prüfen oder MQTT 5 nutzen, das die Ablehnung meldet.
Zu breites Abonnement, etwa haus/# für ein Thermostat
Folge: Mosquitto bestätigt es, liefert aber nur erlaubte Nachrichten. Der Fehler fällt spät auf.
Abhilfe: nur die nötigen Topics abonnieren.
Broker ohne Persistenz oder hart beendet
Folge: Retained Messages und Sessions sind nach einem Neustart weg.
Abhilfe: persistence true setzen und den Container mit docker stop anhalten.
TLS-Prüfung abgeschaltet
Folge: Ein fremder Rechner kann sich als Broker ausgeben.
Abhilfe: CA angeben und die Prüfung eingeschaltet lassen.

MQTT im Smart Home

Home Assistant und openHAB sprechen MQTT von Haus aus, Home Assistant bietet Mosquitto sogar als fertige Erweiterung an. Zigbee2MQTT macht Zigbee-Geräte über MQTT erreichbar, und viele WLAN-Geräte, etwa mit der freien Firmware Tasmota, senden direkt per MQTT. Ein eigener Broker wird so zur zentralen Drehscheibe: Geräte verschiedener Hersteller tauschen ihre Daten aus, ohne Umweg über die Cloud eines Herstellers. Gerade weil dann alle Geräte des Hauses an einem Broker hängen, lohnt sich die Absicherung aus diesem Artikel.

Fazit der Reihe

MQTT verbindet Geräte und Programme über einen Broker, und Topics sind ihre Adressen. Darum ging es in Teil 1. QoS, Retained Messages, Last Will und Sessions machen den Austausch verlässlich, wie Teil 2 gezeigt hat. Ein Broker wie Mosquitto ist in wenigen Minuten eingerichtet. Ebenso schnell steht er allerdings offen im Netz, wenn Anmeldung, Zugriffsrechte und Verschlüsselung fehlen. Mit den Schritten aus diesem Teil ist er für den Dauerbetrieb vorbereitet.

Zum Weiterlesen