mosquitto_pub und mosquitto_sub: Befehlsbeispiele & Cheat Sheet

mosquitto_pub und mosquitto_sub sind die Schweizer Taschenmesser von MQTT. Sie kommen mit Mosquitto (unter Debian/Ubuntu im Paket mosquitto-clients – siehe Mosquitto installieren) und funktionieren mit jedem MQTT-Broker, nicht nur mit Mosquitto. Dieses Cheat Sheet sammelt die Flags und Beispiele, die du wirklich brauchst.

Der grundlegende Round Trip

Subscribe in einem Terminal, publishe in einem anderen:

mosquitto_sub -h test.mosquitto.org -t 'testmqtt/cheatsheet/#' -v

mosquitto_pub -h test.mosquitto.org -t 'testmqtt/cheatsheet/hello' -m 'hello world'

Setze Topics in der Shell immer in Anführungszeichen: # leitet in bash und zsh einen Kommentar ein, und + oder * können unerwartet expandiert werden. Die Wildcard-Regeln erklärt MQTT-Topics und Wildcards.

Nachrichten im Online-Client ansehen

Cheat Sheet der Flags

Beispiele für mosquitto_pub

mosquitto_pub -h broker.example.com -u alice -P 'secret' -i sensor-01 \
  -q 1 -t 'home/livingroom/temp' -m '21.5'

mosquitto_pub -t 'devices/42/state' -m '{"on":true,"brightness":80}'

mosquitto_pub -t 'firmware/blob' -f ./payload.bin
tail -f /var/log/app.log | mosquitto_pub -t 'logs/app' -l

Retained Messages setzen und löschen

# store "online" as the retained value
mosquitto_pub -t 'devices/42/status' -m 'online' -r

# clear it: empty payload + retain flag
mosquitto_pub -t 'devices/42/status' -r -n

Jeder neue Subscriber bekommt den Retained-Wert sofort, bis du ihn löschst. Hintergrund: MQTT Retained Messages.

Beispiele für mosquitto_sub

mosquitto_sub -h broker.example.com -u alice -P 'secret' -q 1 -v \
  -t 'home/+/temp' -t 'home/+/humidity'

value=$(mosquitto_sub -t 'home/livingroom/temp' -C 1 -W 10)
echo "temperature: $value"

mosquitto_sub -t 'devices/#' -v -R

# ISO-8601 timestamp, QoS, topic, payload
mosquitto_sub -t 'devices/#' -F '%I q%q %t %p'

# just the payloads, one per line, e.g. for jq
mosquitto_sub -t 'devices/+/state' -F '%p' | jq .

Gängige -F-Tokens: %t Topic, %p Payload, %q QoS, %r Retain-Flag, %l Länge der Payload, %I ISO-8601-Zeit, %U Unix-Zeit mit Nanosekunden, %x Payload als Hex.

TLS-Beispiele

mosquitto_sub -h broker.example.com -p 8883 --cafile ca.crt -t 'secure/#' -v

mosquitto_pub -h broker.example.com -p 8883 --capath /etc/ssl/certs \
  -u alice -P 'secret' -t 'secure/hello' -m 'over TLS'

mosquitto_pub -h broker.example.com -p 8883 --cafile ca.crt \
  --cert client.crt --key client.key -t 'secure/hello' -m 'mTLS'

--insecure überspringt die Hostnamen-Prüfung – praktisch im Labor, überall sonst gefährlich. Welcher Port wofür ist, fasst MQTT-Ports zusammen.

MQTT-5-Beispiele

# publish with a message expiry and content type
mosquitto_pub -V mqttv5 -t 'jobs/1' -m '{"run":true}' \
  -D publish message-expiry-interval 60 \
  -D publish content-type application/json

# subscriber prints properties with -F
mosquitto_sub -V mqttv5 -t 'jobs/#' -F '%t %p (expiry %E)'

-D setzt eine MQTT-5-Property für einen bestimmten Pakettyp. Was die neuen Properties bewirken, erklärt MQTT 5 vs. 3.1.1.

Muster für Skripte

Da beide Tools mit einem Exit-Status ungleich null enden, wenn sie sich nicht verbinden können, passen sie nahtlos in Shell-Skripte, Cronjobs und Health Checks.

#!/usr/bin/env bash
# exits 0 if a message makes the round trip within 5 seconds
TOPIC="health/$(hostname)/$RANDOM"
mosquitto_sub -h broker.example.com -u monitor -P 'secret' -t "$TOPIC" -C 1 -W 5 > /dev/null &
SUB=$!
sleep 1
mosquitto_pub -h broker.example.com -u monitor -P 'secret' -t "$TOPIC" -m ping
wait $SUB && echo "broker OK" || { echo "broker FAILED"; exit 1; }

while true; do
  mosquitto_pub -t 'lab/cpu/load' -m "$(cut -d' ' -f1 /proc/loadavg)"
  sleep 10
done

mosquitto_sub -h broker.example.com -u alice -P 'secret' -t 'devices/#' \
  -F '%I %t %p' >> mqtt.log

Für jede Nachricht eine neue Verbindung zu öffnen ist bei ein paar Nachrichten pro Sekunde in Ordnung. Bei höheren Raten hältst du mit -l eine Verbindung offen und pipest Zeilen hinein – oder wechselst zu einer Client-Bibliothek.

Häufige Fehler

• # ohne Anführungszeichen – mosquitto_sub -t devices/# funktioniert in manchen Shells und wird in anderen stillschweigend zu devices/. Setz es in Anführungszeichen.
• Dieselbe Client-ID doppelt – laufen zwei Befehle mit demselben -i, trennt der Broker den älteren, was wie ein zufälliger Abbruch aussieht. Lass -i weg, wenn du es nicht brauchst, oder nutze den Client-ID-Generator.
• Alte Nachrichten erwarten – mosquitto_sub empfängt nur Nachrichten, die nach dem Subscribe gepublisht werden, plus die Retained Message pro Topic. Für eine neue Clean Session wird sonst nichts gespeichert.
• Payload zu groß – Broker können die Nachrichtengröße begrenzen; prüfe deine mit dem Paketgrößen-Rechner.

Und WebSockets?

Die Standard-Builds von mosquitto_pub und mosquitto_sub sprechen MQTT nur über TCP und TLS; mit einem ws://- oder wss://-Endpunkt können sie sich nicht verbinden. Um den WebSocket-Listener eines Brokers zu testen, nutze den Online-MQTT-Client oder eine Bibliothek wie MQTT.js – Details findest du unter MQTT über WebSockets. Wenn du lieber ein fertiges Snippet in deiner Sprache willst, schreibt dir der MQTT-Code-Generator eins.

Häufig gestellte Fragen