mosquitto_pub et mosquitto_sub : exemples de commandes et aide-mémoire

mosquitto_pub et mosquitto_sub sont les couteaux suisses de MQTT. Ils sont fournis avec Mosquitto (sur Debian/Ubuntu dans le paquet mosquitto-clients — voir installer Mosquitto) et fonctionnent avec n’importe quel broker MQTT, pas seulement Mosquitto. Cet aide-mémoire rassemble les options et exemples dont vous avez réellement besoin.

L’aller-retour de base

Abonnez-vous dans un terminal, publiez dans un autre :

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

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

Mettez toujours les topics entre guillemets dans le shell : # débute un commentaire en bash et zsh, et + ou * peuvent être développés de façon inattendue. Les règles des jokers (wildcards) sont expliquées dans topics et jokers MQTT.

Voir les messages dans le client en ligne

Aide-mémoire des options

Exemples 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

Définir et effacer des messages retenus

# 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

Chaque nouvel abonné reçoit immédiatement la valeur retenue tant que vous ne l’effacez pas. Pour le contexte : les messages retenus MQTT.

Exemples 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 .

Jetons -F courants : %t topic, %p payload, %q QoS, %r flag retain, %l longueur du payload, %I heure ISO-8601, %U heure Unix avec nanosecondes, %x payload en hexadécimal.

Exemples TLS

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 désactive la vérification du nom d’hôte — pratique en labo, dangereux partout ailleurs. La correspondance des ports est résumée dans les ports MQTT.

Exemples MQTT 5

# 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 définit une propriété MQTT 5 pour un type de paquet donné. Voir MQTT 5 vs 3.1.1 pour le rôle des nouvelles propriétés.

Motifs pour les scripts

Comme les deux outils se terminent avec un code non nul lorsqu’ils ne peuvent pas se connecter, ils s’intègrent parfaitement aux scripts shell, aux tâches cron et aux 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

Ouvrir une nouvelle connexion par message convient pour quelques messages par seconde. Pour des débits plus élevés, gardez une seule connexion ouverte avec -l et envoyez-lui des lignes par un pipe, ou passez à une bibliothèque cliente.

Erreurs courantes

• # sans guillemets — mosquitto_sub -t devices/# fonctionne dans certains shells et devient silencieusement devices/ dans d’autres. Mettez-le entre guillemets.
• Le même client ID deux fois — lancer deux commandes avec le même -i amène le broker à déconnecter la plus ancienne, ce qui ressemble à une coupure aléatoire. Omettez -i sauf si vous en avez besoin, ou utilisez le générateur de client ID.
• Attendre d’anciens messages — mosquitto_sub ne reçoit que les messages publiés après son abonnement, plus le message retenu de chaque topic. Rien d’autre n’est conservé pour une nouvelle session propre.
• Payload trop volumineux — les brokers peuvent plafonner la taille des messages ; vérifiez la vôtre avec le calculateur de taille de paquet.

Et les WebSockets ?

Les versions standard de mosquitto_pub et mosquitto_sub ne parlent MQTT que sur TCP et TLS ; elles ne peuvent pas se connecter à un endpoint ws:// ou wss://. Pour tester le listener WebSocket d’un broker, utilisez le client MQTT en ligne ou une bibliothèque comme MQTT.js — et lisez MQTT sur WebSockets pour les détails. Si vous préférez un extrait prêt à l’emploi dans votre langage, le générateur de code MQTT l’écrit pour vous.

Questions fréquentes