HiveMQ MQTT CLI: Jeden Broker im Terminal testen

Die HiveMQ MQTT CLI (mqtt-cli) ist ein quelloffener, Java-basierter Kommandozeilen-Client, der mit jedem MQTT-Broker funktioniert. Der Befehl heißt einfach mqtt, und vier Subcommands decken fast jeden Terminal-Test ab: mqtt pub, mqtt sub, die interaktive mqtt shell und mqtt test, das prüft, was ein Broker unterstützt.

Diese Anleitung zeigt, wie du sie installierst, dich mit TLS und Zugangsdaten mit einem echten Broker verbindest, MQTT-5-Properties nutzt und den Feature-Test ausführst — mit Befehlen zum Kopieren.

mqtt-cli installieren

Aktuelle Releases liefern auch native Binaries, Java ist also nicht immer nötig. Prüfe die Installation mit mqtt --version. Bei Docker ist die CLI der Entry Point des Images, docker run --rm -it hivemq/mqtt-cli pub -h ... ersetzt also mqtt pub -h ....

Publizieren und abonnieren

Öffne zwei Terminals. Starte zuerst den Subscriber, damit er zuhört, wenn die Nachricht ankommt:

mqtt sub -h broker.connectmq.com -p 1883 \
  -t 'testmqtt/cli/#' -q 1 -T

mqtt pub -h broker.connectmq.com -p 1883 \
  -t 'testmqtt/cli/hello' -m 'Hello from mqtt-cli' -q 1

-T (--showTopics) gibt vor jedem Payload das Topic aus — beim Abonnieren mit Wildcards brauchst du das. Die wichtigsten Optionen:

Zwei Subscriber-Flags sind in Scripts nützlich: -J (--jsonOutput) gibt jede Nachricht als JSON-Objekt mit Topic, QoS und Payload aus, und -of messages.log (--outputToFile) hängt alles an eine Datei an. Leite das JSON durch jq, und du hast ein schnelles Assertion-Werkzeug.

Zugangsdaten und TLS

mqtt pub -h broker.connectmq.com -p 8883 -s \
  -u "$MQTT_USER" -pw "$MQTT_PASS" \
  -t 'testmqtt/cli/secure' -m 'over TLS'

-s (--secure) aktiviert TLS mit dem Trust Store des Systems. Bei einem Broker mit privater CA ergänzt du --cafile ca.pem, für Mutual TLS --cert client.pem --key client.key. Ein fehlgeschlagener Handshake gibt eine Java-SSL-Exception aus — unter TLS-Verbindung testen erfährst du, wie du Zertifikatsprobleme zuerst mit openssl eingrenzt.

WebSocket

Browser-Apps erreichen den Broker über WebSocket, und Proxys brechen manchmal genau diesen Weg. Teste ihn direkt:

mqtt sub -h broker.connectmq.com -p 8084 -s \
  -ws -ws:path /mqtt \
  -t 'testmqtt/cli/#' -T

Funktioniert das, deine Web-App aber nicht, liegt das Problem im Browser (Mixed Content, CORS, falsche URL) und nicht beim Broker.

MQTT-5-Properties

mqtt pub stellt die PUBLISH-Properties von MQTT 5 als Flags bereit — praktisch, um zu prüfen, ob ein Broker sie weiterleitet:

mqtt pub -h broker.connectmq.com -p 1883 \
  -t 'testmqtt/cli/props' -m '{"cmd":"reboot"}' -q 1 \
  -up 'source=ci' -up 'trace-id=abc123' \
  -ct application/json \
  -e 60 \
  -rt 'testmqtt/cli/replies' -cd 'req-42'

Damit setzt du zwei User Properties, einen Content Type, ein Message Expiry von 60 Sekunden, ein Response Topic und Correlation Data. Starte den Subscriber mit -J, dann erscheinen die Properties in seiner Ausgabe. Die Anleitung zum Testen von MQTT-5-Features erklärt, was jede Property bewirken soll und wie du es prüfst.

Die interaktive Shell

mqtt shell startet eine REPL, in der du mehrere verbundene Clients gleichzeitig halten und zwischen ihnen wechseln kannst — ideal, um Abläufe wie Session-Übernahme oder No-Local-Abos nachzustellen, ohne fünf Terminals zu öffnen.

mqtt> con -i sensor-1 -h broker.connectmq.com -p 1883
sensor-1@broker.connectmq.com> sub -t testmqtt/cli/commands -q 1
sensor-1@broker.connectmq.com> con -i backend-1 -h broker.connectmq.com -p 1883
backend-1@broker.connectmq.com> pub -t testmqtt/cli/commands -m 'restart'
backend-1@broker.connectmq.com> switch sensor-1
sensor-1@broker.connectmq.com> ls
sensor-1@broker.connectmq.com> dis
mqtt> exit

con verbindet einen neuen Client und macht ihn zum aktiven Kontext; pub, sub und unsub wirken auf den aktiven Client; switch wechselt den Kontext; ls listet verbundene Clients; dis trennt die Verbindung. Nachrichten, die ein abonnierter Client empfängt, erscheinen sofort in der Shell. Ein schnelles Experiment: Verbinde einen zweiten Client mit derselben -i sensor-1 und sieh zu, wie der erste getrennt wird — das klassische Symptom einer doppelten Client ID.

mqtt test: herausfinden, was der Broker kann

mqtt test verbindet sich mit einem Broker und meldet, welche MQTT-Features funktionieren. Schneller lässt sich die Frage „Unterstützt dieser Broker MQTT 5, QoS 2, Retained Messages und Shared Subscriptions?“ nicht beantworten.

mqtt test -h broker.connectmq.com -p 1883 -u "$MQTT_USER" -pw "$MQTT_PASS"

Die Ausgabe hat einen Abschnitt pro Protokollversion. Das genaue Layout hängt von der CLI-Version ab, sieht aber ungefähr so aus (die Werte hängen von Broker und Konfiguration ab):

MQTT 3: OK
	- Maximum topic length: ... bytes
	- QoS 0: Received .../10 publishes in ...ms
	- QoS 1: ...
	- QoS 2: ...
	- Retain: OK
	- Wildcard subscriptions: OK
	- Shared subscriptions: OK
	- Payload size: >= ... bytes
	- Maximum client id length: ... bytes
MQTT 5: OK
	- Connect restrictions:
		> Retain: OK
		> Wildcard subscriptions: OK
		> Shared subscriptions: OK
		> Subscription identifiers: OK
		> Maximum QoS: 2
		> Receive maximum: ...
		> Maximum packet size: ... bytes
		> Topic alias maximum: ...
		> Session expiry interval: ...
		> Server keep alive: ...

Die „Connect restrictions“ unter MQTT 5 stammen direkt aus den CONNACK-Properties, die der Broker sendet; die MQTT-3-Zeilen werden durch echtes Publizieren und Abonnieren gemessen. Mit -a (--all) laufen die MQTT-3-Tests auch dann, wenn MQTT 5 klappt, und mit -V 3 oder -V 5 beschränkst du den Test auf eine Version. Brauchst du dieselben Infos in deinen eigenen Tools, zeigt testen, welche MQTT-Features ein Broker unterstützt, wie du die Sonde in Python baust.

Standardwerte und Scripting

Ständig -h broker.connectmq.com -p 8883 -s zu tippen nervt. mqtt-cli liest Standardwerte wie Host, Port, Protokollversion und Client-ID-Präfix aus einer Properties-Datei in ~/.mqtt-cli/ — die genauen Schlüssel stehen in der Dokumentation deiner Version. Sind die Standards gesetzt, geht mqtt pub -t x -m y an deinen Broker.

Ein minimaler Smoke-Test für ein Shell-Script oder einen CI-Job:

#!/usr/bin/env bash
set -euo pipefail
TOPIC="testmqtt/cli/smoke-$RANDOM"

mqtt pub -h broker.connectmq.com -p 1883 -t "$TOPIC" -m 'ping' -r -q 1
# eine retained Nachricht wird sofort beim Abonnieren zugestellt; 5 s zuhören
OUT=$(timeout 5 mqtt sub -h broker.connectmq.com -p 1883 -t "$TOPIC" -q 1 || true)
echo "$OUT" | grep -q 'ping' && echo "OK" || { echo "FAIL: '$OUT'"; exit 1; }
# retained Nachricht löschen
mqtt pub -h broker.connectmq.com -p 1883 -t "$TOPIC" -m '' -r

Durch die retained Nachricht ist der Test unabhängig vom Timing: Der Subscriber erhält sie, sobald das Abo aktiv ist. Weitere Muster findest du unter MQTT-Bash-Scripting und in den Beispielen für mosquitto_pub und mosquitto_sub; mit dem Online-Client beobachtest du dasselbe Topic schnell im Browser, während das Script läuft.

mqtt-cli-Traffic im Browser beobachten

mqtt-cli ist ein solider Standard-Client fürs Terminal: vollständige MQTT-5-Flags, eine Shell für Szenarien mit mehreren Clients und ein eingebauter Feature-Test für Broker. Leg ein paar Befehle ins Repository, und jeder im Team kann ein Broker-Problem auf dieselbe Weise reproduzieren.

Häufig gestellte Fragen