mosquitto_pub y mosquitto_sub: ejemplos de comandos y chuleta

mosquitto_pub y mosquitto_sub son las navajas suizas de MQTT. Vienen con Mosquitto (en Debian/Ubuntu en el paquete mosquitto-clients — consulta cómo instalar Mosquitto) y funcionan con cualquier broker MQTT, no solo con Mosquitto. Esta chuleta reúne las opciones y los ejemplos que de verdad necesitas.

La ida y vuelta básica

Suscríbete en una terminal y publica en otra:

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

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

Pon siempre los topics entre comillas en la shell: # inicia un comentario en bash y zsh, y + o * pueden expandirse de forma inesperada. Las reglas de los comodines se explican en topics y comodines MQTT.

Mira los mensajes en el cliente online

Chuleta de opciones

Ejemplos de 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

Fijar y borrar mensajes retenidos

# 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

Cada nuevo suscriptor recibe de inmediato el valor retenido hasta que lo borres. Contexto: mensajes retenidos de MQTT.

Ejemplos de 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 .

Tokens habituales de -F: %t topic, %p payload, %q QoS, %r flag retain, %l longitud del payload, %I hora ISO-8601, %U hora Unix con nanosegundos, %x payload en hexadecimal.

Ejemplos con 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 omite la verificación del nombre de host — práctico en un laboratorio, peligroso en cualquier otro sitio. Qué puerto es cuál se resume en puertos MQTT.

Ejemplos con 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 fija una propiedad de MQTT 5 para un tipo de paquete concreto. Consulta MQTT 5 vs 3.1.1 para ver qué hacen las nuevas propiedades.

Patrones para scripts

Como ambas herramientas terminan con un código de salida distinto de cero cuando no pueden conectarse, encajan muy bien en scripts de shell, tareas cron y 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

Abrir una conexión nueva para cada mensaje está bien para unos pocos mensajes por segundo. Para tasas más altas, mantén una conexión abierta con -l y envíale líneas por una tubería, o pasa a una librería cliente.

Errores habituales

• # sin comillas — mosquitto_sub -t devices/# funciona en algunas shells y en otras se convierte silenciosamente en devices/. Ponlo entre comillas.
• El mismo client ID dos veces — ejecutar dos comandos con el mismo -i hace que el broker desconecte el más antiguo, lo que parece una caída aleatoria. Omite -i salvo que lo necesites, o usa el generador de client ID.
• Esperar mensajes antiguos — mosquitto_sub solo recibe los mensajes publicados después de suscribirse, más el mensaje retenido de cada topic. No se guarda nada más para una nueva sesión limpia.
• Payload demasiado grande — los brokers pueden limitar el tamaño de los mensajes; comprueba el tuyo con la calculadora de tamaño de paquete.

¿Y los WebSockets?

Las builds estándar de mosquitto_pub y mosquitto_sub solo hablan MQTT sobre TCP y TLS; no pueden conectarse a un endpoint ws:// o wss://. Para probar el listener WebSocket de un broker, usa el cliente MQTT online o una librería como MQTT.js — y lee MQTT sobre WebSockets para los detalles. Si prefieres un fragmento listo en tu lenguaje, el generador de código MQTT te lo escribe.

Preguntas frecuentes