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.

Não encontrou a resposta?

Escreva para nós — vamos tentar ajudar e ampliar esta seção.

serjaru@gmail.com Consultar a documentação