Ajuda
Dúvidas comuns e tropeços típicos. Se a resposta não estiver aqui, escreva para nós — o endereço está no rodapé da página.
Primeiros passos
Quanto custa o broker?
Nada. O broker é gratuito, não há limites de dispositivos, mensagens, assinaturas ou servidores, não são necessárias chaves de licença e nenhuma telemetria é coletada.
Quais sistemas são suportados?
Debian e Ubuntu (um pacote no repositório APT), Windows 10 e 11 x64 (um .exe pronto) e compilações de Linux para amd64, arm64 e armhf que rodam manualmente em qualquer distribuição, inclusive no Raspberry Pi.
O que mais preciso instalar?
Nada. O binário é ligado estaticamente e não precisa de ambiente de execução, nem de libc, nem de banco de dados externo: o estado fica em SQLite em Go puro, dentro do próprio broker.
Para onde vou depois de instalar?
O painel espera em http://seu-servidor:8567. O acesso padrão é admin com a senha admin — troque-a na seção Perfil logo após o primeiro login.
Quais portas ficam abertas por padrão?
1883 para MQTT sobre TCP, 8883 para MQTT sobre TLS e 8567 para o painel web e MQTT sobre WebSocket em /mqtt. As portas são alteradas em config.json ou por opções de linha de comando.
Conexão de dispositivos
Um dispositivo não conecta: «not authorized». O que houve?
Muito provavelmente você está usando as credenciais do administrador do painel. São coisas diferentes: o administrador cuida apenas da interface web, enquanto os dispositivos se conectam com contas separadas da seção Usuários. Crie um usuário ali e conecte-se com esse nome e senha.
O cliente conecta, mas não vê mensagens.
Verifique as permissões. As ACLs negam por padrão: sem uma regra de permissão explícita não há acesso. Confirme que o usuário tem, para aquele filtro de tópico, uma regra com acesso read ou readwrite e que ela está acima das regras de negação — as regras são verificadas de cima para baixo até a primeira correspondência.
Como dou a um dispositivo acesso apenas ao próprio ramo?
Adicione uma regra com o filtro $u/# e acesso readwrite. O curinga $u vira o nome do cliente conectado, então uma única regra vale para todos: cada dispositivo enxerga só o próprio ramo. O painel tem um botão «Ramo próprio» para isso.
Posso permitir acesso anônimo?
Sim, com um interruptor próprio em Configurações → Broker. Note que clientes anônimos têm todo o espaço de nomes $ negado, inclusive $SYS.
Por que assinar # não mostra $SYS?
A especificação exige isso: curingas não alcançam tópicos que começam com $. Para ler as estatísticas é preciso uma regra explícita como $SYS/#. Há também um interruptor global de $SYS nas configurações do broker.
Como conecto pelo navegador?
Por MQTT sobre WebSocket: o endereço ws://seu-servidor:8567/mqtt com o subprotocolo mqtt. Não é preciso gateway à parte — o WebSocket roda na mesma porta do painel.
Segurança e TLS
O cliente reclama do certificado ao conectar na 8883.
Na primeira execução o broker gera um certificado autoassinado — bom para testes, mas os clientes não confiam nele. Para um sistema em produção, informe seu próprio certificado no bloco tls da configuração (os campos cert e key) e reinicie o broker.
Como troco a senha do administrador?
Na seção Perfil. A nova senha é gravada em config.json como resumo — nenhuma senha em texto puro fica no arquivo.
Esqueci a senha do administrador.
Pare o broker, remova o campo passwordHash do bloco auth de config.json e coloque no lugar "password": "sua-nova-senha". Na próxima inicialização o broker calcula o resumo e apaga do arquivo o valor em texto puro.
O painel está acessível pela internet — tudo bem?
A instalação padrão no Linux deixa o painel escutando apenas em 127.0.0.1 e o publica via nginx, onde é fácil acrescentar HTTPS e restrições de acesso. Expor a porta 8567 diretamente não é boa ideia.
Como dou acesso de API a outro sistema?
Configurações → API — crie um token bearer. Ele é mostrado uma única vez e apenas o resumo é guardado. Se o sistema só precisa de estatísticas, marque «somente leitura»: então passam apenas GET, HEAD e OPTIONS.
Carga e confiabilidade
Um dispositivo está inundando o broker de mensagens. E agora?
Ative os limitadores em Configurações → Broker: mensagens por segundo, rajada e bytes por segundo. Eles valem por conexão. Exceder não derruba a conexão nem perde mensagens: o broker lê o socket mais devagar e o emissor se contém sozinho.
Um tópico específico é barulhento, mas o cliente no geral está bem.
É um caso para Regras → Limites por tópico. Uma regra por padrão reduz o fluxo a uma taxa mantendo o último valor, ou descarta o tópico por completo. Um sensor que envia dez vezes por segundo passa a uma mensagem por segundo — e será a leitura mais recente.
O que sobrevive a uma reinicialização do broker?
Mensagens retidas, sessões persistentes com suas assinaturas e filas offline, handshakes de QoS inacabados e mensagens adiadas. Sessões limpas não são salvas — pela especificação, elas morrem com a conexão.
Há suporte a cluster?
Não. O broker foi projetado como um processo único. Para ligar vários brokers existe a ponte, que encaminha tópicos entre servidores nos dois sentidos.
Como vejo o que está acontecendo agora?
A seção Tráfego mostra um fluxo ao vivo de mensagens e eventos do broker, com filtro e pausa, e a Visão geral traz gráficos de taxa, saúde da máquina e um fluxo de eventos. Os dados chegam por WebSocket.
Manutenção
Como atualizo o broker no Debian ou no Ubuntu?
Junto com o resto do sistema: sudo apt-get update && sudo apt-get upgrade. Não é preciso mais nada, e as configurações e os dados ficam intactos.
Como transfiro a configuração para outro servidor?
Configurações → Importar e exportar: baixe o arquivo no servidor antigo e envie-o no novo. Configurações, usuários e regras vão junto.
Onde ficam os dados e os logs?
Os dados ficam no diretório data ao lado do binário (no Linux, /opt/elxmqttbroker): broker.db, users.json e os certificados. No Linux os logs vão para o journald: journalctl -u elxmqttbroker -f.
Como sei qual versão está rodando?
Versão, número de build e data de compilação estão gravados no binário: aparecem no rodapé da barra lateral, na seção Sobre e ao executar elxmqttbroker -version.
Posso desligar a persistência do estado?
Sim, com persistence: false em config.json. Então tudo fica só na memória e se perde ao reiniciar — o que faz sentido em bancadas de teste.
Nada encontrado. Tente outra palavra ou escreva para nós.
Não encontrou a resposta?
Escreva para nós — vamos tentar ajudar e ampliar esta seção.