Mosquitto-MQTT-Broker installieren (Ubuntu, Debian, Windows, macOS)

Eclipse Mosquitto ist der am weitesten verbreitete Open-Source-MQTT-Broker: klein, schnell und für praktisch jedes Betriebssystem verfügbar. Dieses Tutorial zeigt dir, wie du Mosquitto unter Ubuntu, Debian, Windows und macOS installierst, ihn als Hintergrunddienst laufen lässt, mit den Kommandozeilen-Clients prüfst und die häufigste Falle von Mosquitto 2.x umgehst – den Broker, der Remote-Verbindungen stillschweigend ablehnt.

Neu bei MQTT? Lies zuerst Was ist MQTT?; wenn du lieber nichts auf dem Host installieren willst, sieh dir Mosquitto in Docker betreiben an.

Mosquitto unter Ubuntu und Debian installieren

Mosquitto ist in den Standard-Repositorys von Ubuntu und Debian enthalten. Broker und CLI-Clients sind getrennte Pakete, installiere also beide:

sudo apt update
sudo apt install -y mosquitto mosquitto-clients

Distributionspakete hinken den Upstream-Releases oft hinterher. Wenn du unter Ubuntu die neueste Version brauchst, stellt das Mosquitto-Projekt ein PPA bereit:

sudo apt-add-repository ppa:mosquitto-dev/mosquitto-ppa
sudo apt update
sudo apt install -y mosquitto mosquitto-clients

Prüfe, was du bekommen hast:

mosquitto -h | head -n 1

Mosquitto als systemd-Dienst betreiben

Das Debian-Paket registriert eine systemd-Unit mosquitto und startet sie meist sofort. Verwalte sie mit den üblichen Befehlen:

sudo systemctl enable --now mosquitto   # start now and at boot
sudo systemctl status mosquitto         # is it running?
sudo systemctl restart mosquitto        # after editing the config
journalctl -u mosquitto -f              # follow the logs

Die Hauptkonfigurationsdatei ist /etc/mosquitto/mosquitto.conf. Sie bindet jede *.conf-Datei in /etc/mosquitto/conf.d/ ein – der sauberste Ort für deine eigenen Einstellungen.

Mosquitto unter Windows installieren

1. Lade den Windows-Installer (64-Bit-.exe) von der offiziellen Download-Seite unter mosquitto.org/download herunter.
2. Führe ihn aus. Lass die Komponente Service ausgewählt, wenn Mosquitto als Windows-Dienst laufen soll. Der Standard-Installationspfad ist C:\Program Files\mosquitto.
3. Füge diesen Ordner zu deinem PATH hinzu, damit mosquitto_pub und mosquitto_sub in jedem Terminal funktionieren.

Starte den Dienst aus einer PowerShell oder Eingabeaufforderung mit Administratorrechten:

net start mosquitto
# or run in the foreground with verbose logging:
cd "C:\Program Files\mosquitto"
.\mosquitto.exe -c mosquitto.conf -v

Mosquitto unter macOS installieren

Mit Homebrew ist es ein Einzeiler, und der Service-Manager von Homebrew hält ihn im Hintergrund am Laufen:

brew install mosquitto
brew services start mosquitto     # run as a background service
brew services info mosquitto      # check status

Die Konfigurationsdatei liegt unter dem Homebrew-Präfix: /opt/homebrew/etc/mosquitto/mosquitto.conf auf Apple Silicon bzw. /usr/local/etc/mosquitto/mosquitto.conf auf Intel-Macs. Die Clients sind in derselben Formula enthalten.

Die Installation mit mosquitto_sub und mosquitto_pub prüfen

Öffne zwei Terminals auf dem Rechner, auf dem der Broker läuft. Subscribe im ersten:

mosquitto_sub -h localhost -t 'test/#' -v

Publishe aus dem zweiten:

mosquitto_pub -h localhost -t 'test/hello' -m 'Mosquitto works'

Terminal 1 sollte test/hello Mosquitto works ausgeben. Für alle Flags halte unser Cheat Sheet zu mosquitto_pub und mosquitto_sub griffbereit.

Die Falle „Local only mode“ in Mosquitto 2.x

Der Test auf localhost klappt, aber ein Client auf einem anderen Rechner bekommt connection refused. Das ist Absicht. Seit Version 2.0 bindet sich Mosquitto nur an das Loopback-Interface, wenn mosquitto.conf keinen Listener definiert, und loggt etwa:

Starting in local only mode. Connections will only be possible from clients running on this machine.
Create a configuration file which defines a listener to allow remote access.

Außerdem setzt Mosquitto 2.x standardmäßig allow_anonymous false, sobald du einen Listener definierst. Den Port zu öffnen reicht also nicht – du musst auch festlegen, wie sich Clients authentifizieren. Lege eine kleine Konfigurationsdatei an:

listener 1883
allow_anonymous true

listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd

Starte den Broker neu (sudo systemctl restart mosquitto), und der Port ist aus dem Netzwerk erreichbar. Wie du die Passwortdatei anlegst und ACLs sowie TLS ergänzt, zeigen wir Schritt für Schritt unter Mosquitto absichern. Um eine Konfiguration zu bauen, ohne Direktiven auswendig zu lernen, nutze den mosquitto.conf-Generator.

Optional: WebSockets aktivieren

Browser-Clients können kein rohes TCP nutzen. Um deinen Broker von einer Webseite aus zu testen, füge einen zweiten Listener mit dem WebSockets-Protokoll hinzu (siehe MQTT über WebSockets und MQTT-Ports):

listener 9001
protocol websockets

Beachte, dass eine per HTTPS ausgelieferte Seite nur wss://-Verbindungen öffnen kann – für einen Browser-Client im öffentlichen Web brauchst du auf diesem Listener also auch TLS. Bevor du so weit gehst, kannst du MQTT im Browser gegen einen öffentlichen Test-Broker kennenlernen:

Im Online-MQTT-Client ausprobieren

Wo Mosquitto seine Dateien ablegt

Egal auf welcher Plattform: Wenn etwas nicht startet, führe mosquitto -c <path-to-conf> -v in einem Terminal aus – so werden Konfigurationsfehler direkt ausgegeben, statt in einem Dienst-Log zu verschwinden. Stoppe vorher den Dienst, sonst scheitert die Vordergrund-Instanz, weil der Port bereits belegt ist.

Fehlerbehebung bei einer frischen Installation

Zu weiteren CONNACK-Codes und Timeouts siehe den Leitfaden zu MQTT-Verbindungsfehlern.

Nächste Schritte

• Sichere ihn mit Passwörtern, ACLs und TLS ab: Mosquitto-Authentifizierung.
• Lieber Container? Mosquitto in Docker betreiben.
• Vergleiche Mosquitto mit anderen Brokern in unserem Broker-Verzeichnis.

Häufig gestellte Fragen