Como instalar o broker MQTT Mosquitto (Ubuntu, Debian, Windows, macOS)

O Eclipse Mosquitto é o broker MQTT open source mais usado: pequeno, rápido e disponível para praticamente todo sistema operacional. Este tutorial mostra como instalar o Mosquitto no Ubuntu, Debian, Windows e macOS, rodá-lo como serviço em segundo plano, verificá-lo com os clientes de linha de comando e evitar a armadilha mais comum do Mosquitto 2.x — o broker recusando conexões remotas sem dar aviso.

É novo em MQTT? Leia primeiro o que é MQTT; se preferir não instalar nada no host, veja como rodar o Mosquitto no Docker.

Instalar o Mosquitto no Ubuntu e no Debian

O Mosquitto está nos repositórios padrão do Ubuntu e do Debian. O broker e os clientes de CLI são pacotes separados, então instale os dois:

sudo apt update
sudo apt install -y mosquitto mosquitto-clients

Os pacotes das distribuições podem ficar atrás das versões upstream. Se você precisa da versão mais recente no Ubuntu, o projeto Mosquitto publica um PPA:

sudo apt-add-repository ppa:mosquitto-dev/mosquitto-ppa
sudo apt update
sudo apt install -y mosquitto mosquitto-clients

Confira o que foi instalado:

mosquitto -h | head -n 1

Rodar o Mosquitto como serviço do systemd

O pacote do Debian registra uma unit mosquitto no systemd e geralmente já a inicia. Use os comandos de sempre para gerenciá-la:

sudo systemctl enable --now mosquitto   # start now and at boot
sudo systemctl status mosquitto         # is it running?
sudo systemctl restart mosquitto        # after editing the config
journalctl -u mosquitto -f              # follow the logs

O arquivo de configuração principal é /etc/mosquitto/mosquitto.conf. Ele inclui todos os arquivos *.conf em /etc/mosquitto/conf.d/, que é o lugar mais limpo para as suas próprias configurações.

Instalar o Mosquitto no Windows

1. Baixe o instalador para Windows (.exe de 64 bits) na página oficial de download em mosquitto.org/download.
2. Execute-o. Mantenha o componente Service selecionado se quiser que o Mosquitto rode como serviço do Windows. O caminho de instalação padrão é C:\Program Files\mosquitto.
3. Adicione essa pasta ao seu PATH para que mosquitto_pub e mosquitto_sub funcionem em qualquer terminal.

Inicie o serviço em um PowerShell ou Prompt de Comando como administrador:

net start mosquitto
# or run in the foreground with verbose logging:
cd "C:\Program Files\mosquitto"
.\mosquitto.exe -c mosquitto.conf -v

Instalar o Mosquitto no macOS

Com o Homebrew é um comando só, e o gerenciador de serviços do Homebrew o mantém rodando em segundo plano:

brew install mosquitto
brew services start mosquitto     # run as a background service
brew services info mosquitto      # check status

O arquivo de configuração fica sob o prefixo do Homebrew: /opt/homebrew/etc/mosquitto/mosquitto.conf no Apple Silicon ou /usr/local/etc/mosquitto/mosquitto.conf em Macs Intel. Os clientes vêm na mesma fórmula.

Verificar a instalação com mosquitto_sub e mosquitto_pub

Abra dois terminais na máquina que roda o broker. Assine no primeiro:

mosquitto_sub -h localhost -t 'test/#' -v

Publique a partir do segundo:

mosquitto_pub -h localhost -t 'test/hello' -m 'Mosquitto works'

O terminal 1 deve imprimir test/hello Mosquitto works. Para o conjunto completo de flags, deixe aberta a nossa colinha de mosquitto_pub e mosquitto_sub.

A pegadinha do "local only mode" do Mosquitto 2.x

O teste no localhost funciona, mas um cliente em outra máquina recebe connection refused. Isso é intencional. Desde a versão 2.0, se o mosquitto.conf não define nenhum listener, o Mosquitto escuta apenas na interface de loopback e registra algo como:

Starting in local only mode. Connections will only be possible from clients running on this machine.
Create a configuration file which defines a listener to allow remote access.

O Mosquitto 2.x também usa allow_anonymous false por padrão assim que você define um listener. Então abrir a porta não basta — você também precisa decidir como os clientes se autenticam. Crie um pequeno arquivo de configuração:

listener 1883
allow_anonymous true

listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd

Reinicie o broker (sudo systemctl restart mosquitto) e a porta fica acessível pela rede. Criar o arquivo de senhas e adicionar ACLs e TLS é explicado passo a passo em como proteger o Mosquitto. Para montar uma configuração sem decorar diretivas, use o gerador de mosquitto.conf.

Opcional: habilitar WebSockets

Clientes no navegador não podem usar TCP bruto. Para testar seu broker a partir de uma página web, adicione um segundo listener com o protocolo WebSockets (veja MQTT sobre WebSockets e portas MQTT):

listener 9001
protocol websockets

Observe que uma página servida via HTTPS só pode abrir conexões wss://, então, para um cliente no navegador na web pública, você também precisará de TLS nesse listener. Antes de ir tão longe, você pode experimentar o MQTT com um broker público de teste no navegador:

Teste no cliente MQTT online

Onde o Mosquitto guarda seus arquivos

Seja qual for a plataforma, rode mosquitto -c <path-to-conf> -v em um terminal quando algo não iniciar: ele imprime os erros de configuração diretamente, em vez de escondê-los em um log de serviço. Pare o serviço antes, ou a instância em primeiro plano vai falhar porque a porta já está em uso.

Solução de problemas em uma instalação nova

Para outros códigos de CONNACK e timeouts, veja o guia de erros de conexão MQTT.

Próximos passos

• Proteja-o com senhas, ACLs e TLS: autenticação no Mosquitto.
• Prefere containers? Rode o Mosquitto no Docker.
• Compare o Mosquitto com outros brokers no nosso diretório de brokers.

Perguntas frequentes