Ao instalar o Mosquitto no Raspberry Pi, você ganha um broker MQTT rápido e leve que continua funcionando na sua rede local mesmo quando a internet cai. Neste tutorial você vai instalar os pacotes do Mosquitto no Raspberry Pi a partir do repositório do sistema, configurar um listener com autenticação por senha, testá-lo pela linha de comando e decidir quando um broker local basta e quando ele deve fazer bridge com um broker na nuvem. Todo arquivo de configuração está completo e pronto para copiar.
Quando um broker Mosquitto local faz sentido
Um broker no Pi se encaixa bem em alguns trabalhos e mal em outros. Seja honesto sobre qual é o seu caso antes de investir tempo nele.
| Situação | Mosquitto local no Pi | Broker na nuvem |
|---|---|---|
| Todos os dispositivos em uma única LAN, nada necessário remotamente | Bom encaixe | Opcional |
| Precisa continuar funcionando durante quedas de internet | Bom encaixe | Combinar com um broker local |
| Dispositivos em vários prédios ou em redes móveis | Mau encaixe, exige redirecionamento de portas | Bom encaixe |
| Apps de celular e dashboards de qualquer lugar | Mau encaixe, exige VPN ou portas abertas | Bom encaixe |
| Você quer que outra pessoa cuide de TLS, autenticação e atualizações | Mau encaixe | Bom encaixe |
| Latência muito baixa entre dispositivos locais | Bom encaixe | Acrescenta uma ida e volta pela internet |
O padrão que combina os dois é comum na prática: os dispositivos falam com um Mosquitto local no Pi, e o Mosquitto faz bridge de topics selecionados para um broker na nuvem. As automações locais continuam rodando offline, e o lado da nuvem recebe os dados para dashboards e acesso remoto. É aí que este tutorial termina. Se quiser relembrar antes o papel do broker, veja o que faz um broker MQTT.
Passo 1: instale o Mosquitto no Raspberry Pi OS
O Raspberry Pi OS Bookworm traz o Mosquitto 2.0 no repositório, versão recente o bastante para a maioria dos usos:
sudo apt update
sudo apt install -y mosquitto mosquitto-clients
sudo systemctl enable --now mosquitto
mosquitto -h | head -n 1
systemctl status mosquitto --no-pager
O pacote mosquitto-clients adiciona o mosquitto_pub e o mosquitto_sub, que você usará nos testes.
Logo após a instalação, o Mosquitto 2.0 é deliberadamente fechado: sem um listener configurado, ele só aceita conexões do próprio Pi (localhost) e recusa clientes remotos anônimos. Isso surpreende quem seguiu guias antigos, em que o broker aceitava qualquer um na porta 1883. É o padrão correto, e o próximo passo o abre com segurança.
Passo 2: crie usuários e um arquivo de senhas
Crie um arquivo de senhas com um usuário por dispositivo ou serviço. A flag -c cria o arquivo, então use-a apenas para o primeiro usuário:
sudo mosquitto_passwd -c /etc/mosquitto/passwd sensors
sudo mosquitto_passwd /etc/mosquitto/passwd nodered
sudo mosquitto_passwd /etc/mosquitto/passwd dashboard
Cada comando pede uma senha e armazena um hash com salt, não o texto puro. Restrinja o arquivo para que apenas o root e o broker possam lê-lo:
sudo chown root:mosquitto /etc/mosquitto/passwd
sudo chmod 0640 /etc/mosquitto/passwd
Versões recentes do Mosquitto emitem um aviso no log quando o arquivo de senhas pode ser lido por todos, e versões futuras podem recusá-lo; por isso, ajuste as permissões agora.
Passo 3: configure o listener
Mantenha o /etc/mosquitto/mosquitto.conf principal como veio; ele inclui todos os arquivos de /etc/mosquitto/conf.d/. Adicione sua própria configuração ali:
sudo nano /etc/mosquitto/conf.d/local.conf
# Local network listener with authentication
per_listener_settings true
listener 1883 0.0.0.0
allow_anonymous false
password_file /etc/mosquitto/passwd
# Limits that protect a small Pi
max_connections 200
max_inflight_messages 20
max_queued_messages 1000
message_size_limit 262144
# Keep the SD card happy: persistence is on by default in the main file,
# save to disk every 5 minutes rather than continuously
autosave_interval 300
Algumas observações sobre essas configurações. per_listener_settings true permite que cada listener tenha sua própria autenticação, o que você vai precisar se depois adicionar um listener WebSocket com regras diferentes. message_size_limit impede que um cliente com mau comportamento envie payloads enormes para um Pi com pouca RAM. autosave_interval controla a frequência com que o banco de persistência em memória é gravado, o que importa para o desgaste do cartão SD.
Reinicie e confira o log:
sudo systemctl restart mosquitto
sudo journalctl -u mosquitto -n 30 --no-pager
O log deve mostrar Opening ipv4 listen socket on port 1883. Se o serviço falhar, a linha do log logo acima da falha indica a opção incorreta.
Passo 4: teste o broker local
Em um terminal no Pi, assine com o usuário dashboard:
mosquitto_sub -h localhost -p 1883 -u dashboard -P 'dashboard-password' \
-i test-sub -t 'home/#' -v
Em outro terminal, ou de um notebook na mesma rede usando o endereço IP do Pi, publique como sensors:
mosquitto_pub -h 192.168.1.50 -p 1883 -u sensors -P 'sensors-password' \
-i test-pub -t home/kitchen/temperature -m 21.6
O assinante imprime home/kitchen/temperature 21.6. Agora tente sem credenciais para confirmar que o acesso anônimo é recusado:
mosquitto_pub -h 192.168.1.50 -p 1883 -i anon-test -t home/x -m test
# Connection error: Connection Refused: not authorised.
Para mais padrões de linha de comando, veja os exemplos de mosquitto_pub e mosquitto_sub.
Passo 5: listener WebSocket opcional para dashboards locais
Se um dashboard no navegador da sua LAN precisar falar com o broker do Pi, adicione um listener WebSocket no mesmo arquivo:
listener 9001 0.0.0.0
protocol websockets
allow_anonymous false
password_file /etc/mosquitto/passwd
Como per_listener_settings está ativado, este listener precisa de suas próprias linhas allow_anonymous e password_file. O ws:// sem criptografia é aceitável em uma LAN confiável, mas não pela internet.
Checklist de proteção depois de instalar o Mosquitto no Raspberry Pi
- Troque a senha do usuário padrão do Pi e mantenha o sistema atualizado com
sudo apt full-upgrade. - Não redirecione a porta 1883 no seu roteador. Expor um broker sem criptografia à internet convida tentativas de adivinhar senhas e a interceptação do tráfego.
- Use um usuário MQTT separado por dispositivo ou serviço, para poder revogar um sem mexer nos demais.
- Adicione uma regra de firewall para que só a sua LAN alcance o broker:
sudo ufw allow from 192.168.1.0/24 to any port 1883. - Mova a persistência para um SSD ou reduza as gravações se o Pi for rodar a partir de um cartão SD por anos.
- Monitore o próprio Pi; o publicador de estatísticas do sistema do Raspberry Pi informa disco e temperatura.
Para acessar o broker de fora, resista à tentação de abrir portas. Esse é o trabalho que um broker na nuvem faz melhor.
Fazendo bridge do Mosquitto local com a ConnectMQ
É aqui que o broker local e um broker na nuvem se encontram. O Mosquitto tem um bridge embutido: ele se conecta a um broker remoto como um cliente MQTT comum e encaminha os topics que você escolher. A ConnectMQ é um broker MQTT na nuvem, então, do ponto de vista dela, o seu Pi é apenas mais um cliente que faz login com o usuário, a senha e o client ID gerados no portal. Nenhum recurso especial de bridge é necessário no lado da nuvem, e nenhuma porta de entrada é aberta na sua rede.
Um arquivo de bridge mínimo, /etc/mosquitto/conf.d/bridge-connectmq.conf, fica assim:
connection connectmq
address broker.connectmq.com:8883
bridge_capath /etc/ssl/certs
remote_clientid YOUR_CLIENT_ID
remote_username YOUR_USERNAME
remote_password YOUR_PASSWORD
bridge_protocol_version mqttv311
try_private false
cleansession false
notifications false
start_type automatic
# Local topic home/... appears in the cloud as site1/home/...
topic home/# out 1 "" site1/
# Commands from the cloud reach local devices
topic home/+/set in 1 "" site1/
Reinicie o Mosquitto e o log mostrará Connecting bridge connectmq. As mensagens publicadas localmente em home/kitchen/temperature agora também aparecem em site1/home/kitchen/temperature na ConnectMQ, onde o explorador de topics ao vivo e o dashboard do portal podem exibi-las. Se a internet cair, os dispositivos locais continuam falando com o Pi e, com cleansession false e QoS 1, as mensagens de saída ficam enfileiradas localmente até o bridge reconectar, até o limite de max_queued_messages.
O broker na nuvem usa um certificado Let's Encrypt, e é por isso que bridge_capath /etc/ssl/certs é toda a configuração de TLS necessária. try_private false é importante: impede o Mosquitto de usar uma flag de protocolo específica do Mosquitto que outros brokers não esperam. O passo a passo completo, opção por opção, incluindo prevenção de loops e testes, está no guia de configuração de bridge do Mosquitto.
Se você perceber que está mantendo o broker do Pi apenas para chegar à nuvem, considere removê-lo completamente e apontar os dispositivos direto para a nuvem. O guia de migração do Mosquitto para um broker na nuvem cobre esse caminho.
Solução de problemas
| Erro ou sintoma | Causa | Correção |
|---|---|---|
Connection refused a partir de outras máquinas |
Nenhum listener em 0.0.0.0 | Adicione listener 1883 0.0.0.0 |
not authorised |
Usuário ou senha errados, ou arquivo sem permissão de leitura para o broker | Execute mosquitto_passwd novamente e confira chown root:mosquitto |
| O serviço falha depois de editar a configuração | Listener duplicado ou erro de digitação | Leia journalctl -u mosquitto |
| Os clientes ficam se desconectando | Dois clientes compartilham o mesmo ID | Use client IDs únicos |
| O bridge conecta e depois cai | Client ID ou credenciais não conferem | Copie os três exatamente do portal |
Comece com a ConnectMQ
Mantenha o Mosquitto para o tráfego local rápido e deixe um broker MQTT gerenciado cuidar de tudo o que atravessa a internet. Crie um broker Serverless gratuito em app.connectmq.com, sem cartão de crédito, copie as credenciais geradas para o seu arquivo de bridge e veja seus topics locais aparecerem no portal. Para um primeiro experimento com os clientes do Mosquitto, o servidor MQTT público em broker.connectmq.com aceita testes sem credenciais, mas não serve para dados de produção. Mais projetos com o Pi estão reunidos no tutorial de MQTT com Raspberry Pi.
Perguntas frequentes
Por que o Mosquitto recusa conexões de outros dispositivos depois da instalação?
O Mosquitto 2.0 escuta apenas no localhost e rejeita clientes anônimos, a menos que você configure um listener. Adicione listener 1883 0.0.0.0 com allow_anonymous false e um arquivo de senhas.
Devo expor o broker Mosquitto do meu Raspberry Pi à internet?
Não é recomendado. Em vez disso, faça um bridge de saída para um broker na nuvem, para que o acesso remoto passe por um serviço protegido com TLS e seu roteador mantenha todas as portas de entrada fechadas.
O Mosquitto em um Raspberry Pi aguenta muitos dispositivos?
Para uma casa ou um site pequeno, um Pi lida facilmente com o tráfego típico de sensores. Os limites que aparecem primeiro costumam ser o desgaste do cartão SD e o esforço de manutenção, não a vazão bruta.
O bridge precisa de uma conta especial na ConnectMQ?
Não. O bridge é um cliente MQTT comum, então usa o mesmo usuário, senha e client ID que o portal gera para qualquer dispositivo.
