mosquitto_pub e mosquitto_sub: exemplos de comandos e colinha

mosquitto_pub e mosquitto_sub são os canivetes suíços do MQTT. Eles vêm com o Mosquitto (no Debian/Ubuntu, no pacote mosquitto-clients — veja como instalar o Mosquitto) e funcionam com qualquer broker MQTT, não só com o Mosquitto. Esta colinha reúne as flags e os exemplos de que você realmente precisa.

A ida e volta básica

Assine em um terminal e publique em outro:

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

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

Sempre coloque os tópicos entre aspas no shell: # inicia um comentário no bash e no zsh, e + ou * podem ser expandidos de forma inesperada. As regras de curingas são explicadas em tópicos e curingas MQTT.

Veja as mensagens no cliente online

Colinha de flags

Exemplos 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

Definir e apagar mensagens retidas

# 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

Todo novo assinante recebe o valor retido imediatamente, até você apagá-lo. Contexto: mensagens retidas (retained) no MQTT.

Exemplos 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 comuns do -F: %t tópico, %p payload, %q QoS, %r flag retain, %l tamanho do payload, %I hora em ISO-8601, %U hora Unix com nanossegundos, %x payload em hexadecimal.

Exemplos com 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 pula a verificação do hostname — útil em laboratório, perigoso em qualquer outro lugar. Qual porta é qual está resumido em portas MQTT.

Exemplos com 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 define uma propriedade do MQTT 5 para um determinado tipo de pacote. Veja MQTT 5 vs 3.1.1 para saber o que as novas propriedades fazem.

Padrões para scripts

Como as duas ferramentas saem com status diferente de zero quando não conseguem conectar, elas se encaixam bem em scripts shell, cron jobs e 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 uma nova conexão para cada mensagem não tem problema com poucas mensagens por segundo. Para taxas maiores, mantenha uma conexão aberta com -l e envie linhas para ela por pipe, ou passe a usar uma biblioteca cliente.

Erros comuns

• # sem aspas — mosquitto_sub -t devices/# funciona em alguns shells e, em outros, vira devices/ sem aviso. Use aspas.
• O mesmo client ID duas vezes — rodar dois comandos com o mesmo -i faz o broker desconectar o mais antigo, o que parece uma queda aleatória. Omita o -i a menos que precise dele, ou use o gerador de client ID.
• Esperar mensagens antigas — o mosquitto_sub só recebe mensagens publicadas depois que ele assina, mais a mensagem retida de cada tópico. Nada mais é armazenado para uma nova sessão limpa.
• Payload grande demais — brokers podem limitar o tamanho das mensagens; confira o seu com a calculadora de tamanho de pacote.

E os WebSockets?

Os builds padrão do mosquitto_pub e do mosquitto_sub falam MQTT apenas sobre TCP e TLS; eles não conseguem se conectar a um endpoint ws:// ou wss://. Para testar o listener WebSocket de um broker, use o cliente MQTT online ou uma biblioteca como o MQTT.js — e leia MQTT sobre WebSockets para os detalhes. Se preferir um snippet pronto na sua linguagem, o gerador de código MQTT escreve um para você.

Perguntas frequentes