HiveMQ MQTT CLI : tester n'importe quel broker depuis le terminal

La HiveMQ MQTT CLI (mqtt-cli) est un client en ligne de commande open source, écrit en Java, qui fonctionne avec n'importe quel broker MQTT. Sa commande s'appelle simplement mqtt, et quatre sous-commandes couvrent presque tous les tests en terminal : mqtt pub, mqtt sub, le shell interactif mqtt shell et mqtt test, qui sonde ce qu'un broker prend en charge.

Ce guide montre comment l'installer, se connecter à un vrai broker avec TLS et identifiants, utiliser les propriétés MQTT 5 et lancer le test de fonctionnalités — avec des commandes prêtes à copier.

Installer mqtt-cli

Les versions récentes fournissent aussi des binaires natifs : Java n'est donc pas toujours nécessaire. Vérifiez l'installation avec mqtt --version. Avec Docker, l'entry point de l'image est la CLI : docker run --rm -it hivemq/mqtt-cli pub -h ... remplace mqtt pub -h ....

Publier et s'abonner

Ouvrez deux terminaux. Lancez d'abord l'abonné pour qu'il écoute au moment où le message arrive :

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) affiche le topic avant chaque payload, indispensable lorsque vous vous abonnez avec des wildcards. Les options les plus utilisées :

Deux flags de l'abonné sont utiles dans les scripts : -J (--jsonOutput) affiche chaque message sous forme d'objet JSON avec topic, QoS et payload, et -of messages.log (--outputToFile) ajoute tout dans un fichier. Passez le JSON dans jq et vous obtenez un outil d'assertion rapide.

Identifiants et 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) active TLS avec le magasin de certificats du système. Pour un broker avec une CA privée, ajoutez --cafile ca.pem ; pour du TLS mutuel, ajoutez --cert client.pem --key client.key. Un handshake raté affiche une exception SSL Java — voir tester la connexion TLS pour isoler d'abord les problèmes de certificat avec openssl.

WebSocket

Les applications navigateur atteignent le broker en WebSocket, et les proxys cassent parfois précisément ce chemin. Testez-le directement :

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

Si cela fonctionne mais pas votre application web, le problème vient du navigateur (contenu mixte, CORS, mauvaise URL), pas du broker.

Propriétés MQTT 5

mqtt pub expose les propriétés du PUBLISH MQTT 5 sous forme de flags, ce qui est pratique pour vérifier qu'un broker les transmet :

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'

Cette commande définit deux user properties, un content type, un message expiry de 60 secondes, un response topic et des correlation data. Lancez l'abonné avec -J et les propriétés apparaissent dans sa sortie. Le guide des tests des fonctionnalités MQTT 5 explique le rôle de chaque propriété et comment le vérifier.

Le shell interactif

mqtt shell démarre un REPL dans lequel vous gardez plusieurs clients connectés en même temps et passez de l'un à l'autre — idéal pour reproduire des interactions comme la reprise de session ou les abonnements no-local sans ouvrir cinq terminaux.

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 connecte un nouveau client et en fait le contexte actif ; pub, sub et unsub agissent sur le client actif ; switch change de contexte ; ls liste les clients connectés ; dis déconnecte. Les messages reçus par un client abonné s'affichent dans le shell dès leur arrivée. Petite expérience : connectez un second client avec le même -i sensor-1 et regardez le premier se faire déconnecter — le symptôme classique d'un client ID dupliqué.

mqtt test : découvrir ce que le broker prend en charge

mqtt test se connecte à un broker et indique quelles fonctionnalités MQTT marchent. C'est le moyen le plus rapide de répondre à la question « ce broker gère-t-il MQTT 5, la QoS 2, les messages retenus et les abonnements partagés ? ».

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

La sortie comporte une section par version du protocole. Sa mise en forme exacte dépend de la version de la CLI, mais elle ressemble à ceci (les valeurs varient selon le broker et sa configuration) :

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

Les « connect restrictions » MQTT 5 proviennent directement des propriétés du CONNACK envoyées par le broker ; les lignes MQTT 3 sont mesurées en publiant et en s'abonnant réellement. Ajoutez -a (--all) pour exécuter aussi les tests MQTT 3 quand MQTT 5 réussit, et -V 3 ou -V 5 pour limiter le test à une version. Si vous avez besoin des mêmes informations dans vos propres outils, tester les fonctionnalités MQTT d'un broker montre comment construire la sonde en Python.

Valeurs par défaut et scripts

Taper -h broker.connectmq.com -p 8883 -s à chaque fois devient vite pénible. mqtt-cli lit des valeurs par défaut comme l'hôte, le port, la version du protocole et le préfixe du client ID dans un fichier de propriétés situé dans ~/.mqtt-cli/ — consultez la documentation de votre version pour les clés exactes. Une fois ces valeurs définies, mqtt pub -t x -m y part vers votre broker.

Un smoke test minimal pour un script shell ou un job CI :

#!/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
# un message retenu est livré dès l'abonnement ; écouter pendant 5 s
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; }
# effacer le message retenu
mqtt pub -h broker.connectmq.com -p 1883 -t "$TOPIC" -m '' -r

Le message retenu rend le test indépendant du timing : l'abonné le reçoit dès que l'abonnement est actif. Pour d'autres modèles, voir scripts MQTT en bash et les exemples mosquitto_pub et mosquitto_sub ; le client en ligne permet de suivre rapidement le même topic dans le navigateur pendant l'exécution du script.

Suivre le trafic mqtt-cli dans le navigateur

mqtt-cli est un excellent client terminal par défaut : des flags MQTT 5 complets, un shell pour les scénarios multi-clients et un test de fonctionnalités du broker intégré. Gardez quelques commandes dans votre dépôt et chaque membre de l'équipe pourra reproduire un problème de broker de la même manière.

Questions fréquentes