Im Smart Home Bereich ist MQTT ein unverzichtbares Protokoll. Mit dem Mosquitto Broker als Home Assistant Add-On bekommst du eine stabile und performante MQTT-Broker-Lösung an die Hand, die ideal in deine Automatisierungen integriert werden kann. In diesem Tutorial führe ich dich Schritt für Schritt durch die Installation, Konfiguration und den sicheren Betrieb des Mosquitto Brokers unter Home Assistant. Dabei gehe ich speziell auf die ausführliche Einrichtung ein, damit du die volle Kontrolle über deinen MQTT-Broker hast.

Dieses Tutorial richtet sich an Nutzer, die bereits mit Home Assistant vertraut sind und keine Scheu vor Konfigurationsdateien (YAML) haben. So kannst du dein Smart Home mit zuverlässigem Messaging versorgen, was die Basis für nahezu alle Automatisierungen bildet.

Inhaltsverzeichnis

1. Voraussetzungen und Systemübersicht1.1 Technische Voraussetzungen
1.2 MQTT und Mosquitto – Kurze Einführung
2. Installation des Mosquitto Add-ons in Home Assistant2.1 Add-on Repository hinzufügen
2.2 Mosquitto Add-on installieren
2.3 Add-on starten und aktivieren
2.4 Erster Funktionstest
3. Konfiguration des Mosquitto Add-ons3.1 Standard-Konfigurationsdatei verstehen
3.2 Eigene Konfiguration erstellen3.2.1 Authentifizierung einrichten
3.2.2 Access Control Lists (ACL) konfigurieren
3.2.3 TLS-Verschlüsselung einbinden (optional)
3.2.4 Beispiel vollständige mosquitto.conf
3.3 Konfigurationsdateien in Home Assistant ablegen
4. Integration mit Home Assistant4.1 MQTT Broker Verbindung konfigurieren
4.2 Automatisierung und Sensoren per MQTT erstellen
5. Sicherheit und Wartung5.1 Regelmäßige Updates
5.2 Backups der Konfigurationsdateien
5.3 Monitoring
5.4 Firewall & Netzwerksegmentierung
6. Fazit
7. FAQ7.1 Wie verhindere ich, dass anonyme Clients sich verbinden?
7.2 Kann ich das Add-on auch auf einem separaten Server betreiben?
7.3 Wie aktiviere ich TLS im Mosquitto Add-on?
7.4 Werden MQTT-Nachrichten im Mosquitto Broker gespeichert?
7.5 Wie finde ich Fehler im Mosquitto Add-on?

1. Voraussetzungen und Systemübersicht

Bevor du mit der Installation startest, ist es wichtig, die Systemanforderungen und Voraussetzungen klar zu definieren. Hier erfährst du, was du brauchst und wie der Mosquitto Broker in deine bestehende Home Assistant Umgebung eingebunden wird.

1.1 Technische Voraussetzungen

- Home Assistant Installation: Du solltest eine funktionierende Home Assistant Installation mit Supervisor haben (z.B. Home Assistant OS oder Supervised).

- Add-on Store Zugriff: Der Zugriff auf den Add-on Store ist notwendig. Dieser steht standardmäßig bei Supervisor-Installationen zur Verfügung.

- Port 1883 (MQTT) und 8883 (MQTTS): Diese Ports müssen in deinem Netzwerk und ggf. der Firewall geöffnet sein.

- Grundkenntnisse in YAML: Da die Konfiguration über YAML-Dateien erfolgt, solltest Du sicher im Umgang mit YAML sein.

1.2 MQTT und Mosquitto – Kurze Einführung

Mosquitto ist ein Open-Source MQTT Broker, der als Add-on in Home Assistant läuft. MQTT (Message Queuing Telemetry Transport) ist ein leichtgewichtiges Publish-Subscribe-Protokoll für Machine-to-Machine-Kommunikation, perfekt für IoT und Smart Home Anwendungen.

Das Mosquitto Add-on stellt sicher, dass dein Home Assistant und andere Geräte MQTT Nachrichten zuverlässig austauschen können.

2. Installation des Mosquitto Add-ons in Home Assistant

Die Installation des Mosquitto MQTT Brokers erfolgt einfach und schnell über den Home Assistant Add-on Store. Hier zeige ich dir die nötigen Schritte.

2.1 Add-on Repository hinzufügen

Falls das Mosquitto Add-on nicht in deinem Add-on Store auftaucht, füge zuerst das offizielle Home Assistant Add-on Repository hinzu:

- Öffne dazu Home Assistant und gehe zu Supervisor > Add-on Store.

- Klicke auf die drei Punkte oben rechts und wähle Repositories.

- Füge die Adresse https://github.com/home-assistant/addons hinzu und bestätige.

2.2 Mosquitto Add-on installieren

- Suche im Add-on Store nach „Mosquitto“.

- Wähle das Add-on „Mosquitto broker“ aus.

- Klicke auf Installieren und warte, bis die Installation abgeschlossen ist.

2.3 Add-on starten und aktivieren

- Nach der Installation klicke auf Start.

- Aktiviere am besten auch den Autostart, damit der Broker automatisch mit Home Assistant startet.

2.4 Erster Funktionstest

Teste, ob der Broker läuft, indem du dich z.B. mit einem MQTT Client (z.B. MQTT Explorer) verbindest und eine Testnachricht an den Broker sendest.

3. Konfiguration des Mosquitto Add-ons

Die Standardkonfiguration ist minimal gehalten. Für den produktiven Einsatz solltest du den Broker an deine Anforderungen anpassen.

3.1 Standard-Konfigurationsdatei verstehen

Das Mosquitto Add-on verwendet typischerweise die Datei mosquitto.conf. Diese setzt sich aus drei Abschnitten zusammen:

- Listener: Definiert die Ports und Netzwerkschnittstellen.

- Authentication und ACLs: Regeln für Zugang und Themenberechtigungen.

- Persistence und Logging: Speichereinstellungen und Log-Level.

3.2 Eigene Konfiguration erstellen

3.2.1 Authentifizierung einrichten

Für eine sichere Kommunikation ist eine Benutzer-Authentifizierung verpflichtend.

- Erstelle eine Passwortdatei, z.B. mosquitto.passwd.

- Nutze das Mosquitto-Tool auf Deinem System oder innerhalb des Containers:

mosquitto_passwd -c /config/mosquitto.passwd deinbenutzer

- Ergänze die mosquitto.conf:

allow_anonymous false
password_file /config/mosquitto.passwd

3.2.2 Access Control Lists (ACL) konfigurieren

ACLs bestimmen, welche Topics wer lesen/schreiben darf.

Beispiel aclfile.acl:

user deinbenutzer
topic readwrite #

Füge folgende Zeile hinzu:

acl_file /config/aclfile.acl

3.2.3 TLS-Verschlüsselung einbinden (optional)

Für verschlüsselte MQTT-Kommunikation kannst Du TLS-Zertifikate hinterlegen:

listener 8883
cafile /ssl/ca.crt
certfile /ssl/server.crt
keyfile /ssl/server.key
require_certificate false

3.2.4 Beispiel vollständige mosquitto.conf

listener 1883
allow_anonymous false
password_file /config/mosquitto.passwd
acl_file /config/aclfile.acl

listener 8883
cafile /ssl/ca.crt
certfile /ssl/server.crt
keyfile /ssl/server.key
require_certificate false

persistence true
log_dest file /config/mosquitto.log

3.3 Konfigurationsdateien in Home Assistant ablegen

Lege die Konfigurationsdateien im config/mosquitto-Verzeichnis ab (je nach Einrichtung kann der Pfad variieren).

Passe das Add-on so an, dass es die Dateien aus diesem Pfad liest.

4. Integration mit Home Assistant

Damit Home Assistant die MQTT-Kommunikation via Mosquitto nutzen kann, musst du die MQTT-Integration korrekt einrichten.

4.1 MQTT Broker Verbindung konfigurieren

Gehe zu Einstellungen > Geräte & Dienste > Integration hinzufügen und wähle MQTT aus.

- Broker: localhost oder IP-Adresse des Brokers

- Port: 1883 (unverschlüsselt) oder 8883 (TLS)

- Benutzername / Passwort: Deine eingerichteten Credentials

4.2 Automatisierung und Sensoren per MQTT erstellen

Jetzt kannst du MQTT-Sensoren, Schalter und Automatisierungen anlegen, die Nachrichten über deinen Mosquitto Broker senden und empfangen.

Beispiel Home Assistant Sensor via MQTT:

sensor:
- platform: mqtt
name: "Temperatur Wohnzimmer"
state_topic: "home/wohnzimmer/temperatur"
unit_of_measurement: "°C"

5. Sicherheit und Wartung

Ein stabiler MQTT Broker benötigt Pflege und besondere Sicherheitsmaßnahmen.

5.1 Regelmäßige Updates

Halte das Mosquitto Add-on immer auf dem neuesten Stand, um von Sicherheitsfixes zu profitieren.

5.2 Backups der Konfigurationsdateien

Sichere regelmäßig die Konfiguration, insbesondere Passwort- und ACL-Dateien.

5.3 Monitoring

Überwache die Logs auf Fehler und Angriffsversuche:

tail -f /config/mosquitto.log

Optional kannst du Home Assistant mit einem eigenen MQTT-Sensor für den Broker-Status versehen.

5.4 Firewall & Netzwerksegmentierung

Stelle sicher, dass nur autorisierte Geräte Zugriff auf den MQTT-Broker haben. Segmentiere das Netzwerk ggf. mit VLANs oder Firewallregeln.

6. Fazit

Mit dem Mosquitto Broker als Home Assistant Add-On hast du eine robuste und flexible MQTT Broker-Lösung. Die Installation ist einfach, die Anpassbarkeit groß, von der einfachen Authentifizierung bis zu TLS und individuellen ACL-Regeln. Dieses Tutorial hat dir gezeigt, wie du den Broker aufsetzt, konfigurierst und sicher betreibst.

So legst du die wichtige Grundlage für Smart Home Automatisierungen mit stabiler, sicherer Kommunikation im Netzwerk.

7. FAQ

7.1 Wie verhindere ich, dass anonyme Clients sich verbinden?

In der mosquitto.conf muss allow_anonymous false gesetzt und eine Passwortdatei definiert werden.

7.2 Kann ich das Add-on auch auf einem separaten Server betreiben?

Ja, allerdings muss die IP-Adresse und evtl. Firewall-Regeln entsprechend configuriert werden. Home Assistant muss den Broker erreichen können.

7.3 Wie aktiviere ich TLS im Mosquitto Add-on?

Lege Zertifikate im ssl-Verzeichnis ab und passe die mosquitto.conf gemäß Abschnitt 3.2.3 an.

7.4 Werden MQTT-Nachrichten im Mosquitto Broker gespeichert?

Standardmäßig speichert Mosquitto keine Nachrichten, außer persistence true ist aktiviert. Dann bleiben MQTT-Nachrichten bei einem Broker-Neustart erhalten.

7.5 Wie finde ich Fehler im Mosquitto Add-on?

Über die Logdatei /config/mosquitto.log oder direkt über die Add-on Logs in Home Assistant.

Dieses Tutorial basiert auf der folgenden Webseite: https://github.com/home-assistant/addons/blob/master/mosquitto/DOCS.md https://smarthome-assistant.info/home-assistant-add-on-mosquitto-broker/