EMQX und MQTT auf Proxmox installieren: Broker, Benutzer und erster Funktionstest

MQTT ist die gemeinsame Sprache vieler Smart-Home-Dienste. Ein Broker nimmt Nachrichten von Sensoren und Anwendungen entgegen und verteilt sie an interessierte Empfänger. In meinem Homelab übernimmt das EMQX in einem eigenen Proxmox-LXC. Diese Anleitung zeigt die Installation, die erste sichere Konfiguration und einen echten Publish/Subscribe-Test. Sie gilt für eine neue Instanz; eine bestehende produktive EMQX-Installation wird damit nicht überschrieben.

Vorbereitung: Was du brauchst

• Proxmox VE mit funktionierendem LXC-Storage und Netzwerk,
• eine freie interne IP oder DHCP-Reservierung,
• für das Beispiel etwa zwei CPU-Kerne, 1 GB RAM und mindestens 6 GB Speicher,
• ein Proxmox-Backup-Ziel, bevor produktive Geräte umziehen.

Im Beispiel heißen Broker und DNS-Name mqtt.example.lan. Ersetze sie durch deine Werte. Interne Adressen, Logins und Tokens meines Homelabs werden hier nicht veröffentlicht.

Schritt 1: LXC installieren

Am bequemsten geht es über die EMQX-Seite der Proxmox-Community-Skripte. Lies den Script-Quelltext vor dem Ausführen; ein fremdes Shell-Skript läuft auf dem Proxmox-Host mit hohen Rechten. Der aktuelle Installationsbefehl lautet:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/emqx.sh)"

Wähle im Dialog eine freie Gast-ID, Hostname, IP beziehungsweise DHCP und das gewünschte Backup-Storage. Nach Abschluss notiere die tatsächlich zugewiesene Container-ID als <CTID>.

pct list
pct status <CTID>
pct exec <CTID> -- systemctl is-active emqx
pct exec <CTID> -- ss -lnt

Erwartet werden active und Listener für MQTT auf Port 1883 sowie das Administrations-Dashboard auf 18083. Port 8883 ist für MQTT über TLS vorgesehen, wenn du Zertifikate eingerichtet hast. Ist der Dienst nicht aktiv, helfen pct exec <CTID> -- journalctl -u emqx -n 100 --no-pager und pct exec <CTID> -- emqx ctl status.

Schritt 2: Admin-Zugang und MQTT-Authentifizierung

Öffne nur im Heimnetz http://mqtt.example.lan:18083. Melde dich mit den auf der Script-Seite dokumentierten Erstzugangsdaten an und ändere das Admin-Passwort sofort. Ein Dashboard-Admin ist nicht automatisch ein MQTT-Benutzer.

Lege unter Access Control → Authentication einen Password-Based-Authenticator mit eingebauter Datenbank an. Füge anschließend unter Users einen eigenen Benutzer für Home Assistant und – besser noch – separate Benutzer für weitere Anwendungen hinzu. Anonyme Zugriffe sollten für ein dauerhaftes Setup nicht erlaubt bleiben. Die genauen Dialogbezeichnungen können sich zwischen EMQX-Versionen ändern; die EMQX-Dokumentation ist für die installierte Version maßgeblich.

Schritt 3: Publish und Subscribe testen

Auf einem Linux-Rechner im selben Netz kannst du die Mosquitto-Clients installieren:

sudo apt update
sudo apt install mosquitto-clients

Terminal 1 wartet auf Nachrichten:

mosquitto_sub -h mqtt.example.lan -p 1883 \
  -u test-leser -P 'DEIN_TESTPASSWORT' -t 'homelab/test' -v

Terminal 2 sendet eine Nachricht:

mosquitto_pub -h mqtt.example.lan -p 1883 \
  -u test-sender -P 'DEIN_TESTPASSWORT' -t 'homelab/test' -m 'Hallo MQTT'

Terminal 1 muss homelab/test Hallo MQTT anzeigen. Die Passwort-Option -P kann in Shell-Historie oder Prozessliste sichtbar sein: Für echte Zugangsdaten besser geschützte Client-Konfiguration oder interaktive Umgebungen verwenden und den Testnutzer danach entfernen. Bei not authorised zuerst Authenticator, Benutzer und Topic-Rechte prüfen; bei connection refused Listener, IP und Firewall.

Schritt 4: Home Assistant anbinden

In Home Assistant unter Einstellungen → Geräte & Dienste → Integration hinzufügen → MQTT den Broker-Host, Port 1883 und den eigens angelegten MQTT-Benutzer eintragen. Für Verbindungen über unsichere Netze stattdessen TLS auf 8883 mit gültigem Zertifikat verwenden. Den Broker niemals ungefiltert samt Admin-Dashboard ins Internet öffnen.

Nach der Einrichtung prüfe ich in EMQX die Client-Liste und in Home Assistant den Status der MQTT-Integration. Erst danach verbinde ich einzelne Geräte und vergebe eingeschränkte Topic-Rechte.

Backup, Updates und typische Fehler

Sichere den kompletten LXC über Proxmox Backup Server und dokumentiere zusätzlich EMQX-Konfiguration, Benutzer- und Authentifizierungsverfahren. Vor einem Update: Backup erstellen, emqx ctl status dokumentieren, Release Notes lesen, dann erst aktualisieren. Ein Reboot des Brokers unterbricht sämtliche MQTT-Clients kurzzeitig.

• Client verbindet nicht: DNS/IP und Listener-Port testen, dann Auth-Fehler im EMQX-Dashboard ansehen.
• Verbunden, aber keine Werte: Topic-Schreibweise und ACL prüfen; MQTT unterscheidet Groß- und Kleinschreibung.
• Telegraf empfängt nichts: Broker-Adresse darf im getrennten Gast nicht 127.0.0.1 sein.
• Nach Neustart fehlen Nachrichten: QoS, Retain und persistente Sessions bewusst konfigurieren; nicht jede Nachricht wird automatisch historisch gespeichert.

Weiter: MQTT-Daten mit Telegraf nach InfluxDB schreiben · offizielle EMQX-Dokumentation.