Aiuto

Domande comuni e intoppi tipici. Se la risposta non c'è, scrivici: l'indirizzo è in fondo alla pagina.

Primi passi

Quanto costa il broker?

Nulla. Il broker è gratuito, non ci sono limiti di dispositivi, messaggi, sottoscrizioni o server, non servono chiavi di licenza e non viene raccolta alcuna telemetria.

Quali sistemi sono supportati?

Debian e Ubuntu (un pacchetto nel repository APT), Windows 10 e 11 x64 (un .exe pronto) e build Linux per amd64, arm64 e armhf che si avviano a mano su qualsiasi distribuzione, Raspberry Pi compreso.

Che altro devo installare?

Nulla. Il binario è collegato staticamente e non richiede né ambiente di esecuzione, né libc, né database esterno: lo stato è conservato in SQLite in Go puro, dentro il broker stesso.

Dove vado dopo l'installazione?

Il pannello attende su http://tuo-server:8567. Le credenziali predefinite sono admin con la password admin: cambiala nella sezione Profilo subito dopo il primo accesso.

Quali porte sono aperte per impostazione predefinita?

1883 per MQTT su TCP, 8883 per MQTT su TLS e 8567 per il pannello web e MQTT su WebSocket in /mqtt. Le porte si cambiano in config.json o con le opzioni da riga di comando.

Connessione dei dispositivi

Un dispositivo non si connette: «not authorized». Che cosa succede?

Molto probabilmente stai usando le credenziali dell'amministratore del pannello. Sono due cose diverse: l'amministratore gestisce solo l'interfaccia web, mentre i dispositivi si collegano con account distinti della sezione Utenti. Creane uno lì e collegati con quel nome e quella password.

Il client si connette ma non vede messaggi.

Controlla i permessi. Le ACL negano per impostazione predefinita: senza una regola di autorizzazione esplicita non c'è accesso. Assicurati che l'utente abbia, per quel filtro di topic, una regola con accesso read o readwrite e che stia sopra le regole di negazione: le regole si controllano dall'alto verso il basso fino alla prima corrispondenza.

Come do a un dispositivo l'accesso al solo ramo suo?

Aggiungi una regola con il filtro $u/# e accesso readwrite. Il segnaposto $u diventa il nome del client connesso, quindi una sola regola vale per tutti: ogni dispositivo vede soltanto il proprio ramo. Nel pannello c'è un pulsante «Ramo proprio» apposta.

Posso consentire l'accesso anonimo?

Sì, con un interruttore dedicato in Impostazioni → Broker. Tieni presente che ai client anonimi è negato l'intero spazio dei nomi $, incluso $SYS.

Perché sottoscrivere # non mostra $SYS?

Lo impone la specifica: i caratteri jolly non raggiungono i topic che iniziano con $. Per leggere le statistiche serve una regola esplicita come $SYS/#. Nelle impostazioni del broker c'è anche un interruttore globale per $SYS.

Come mi collego dal browser?

Tramite MQTT su WebSocket: l'indirizzo ws://tuo-server:8567/mqtt con il sottoprotocollo mqtt. Non serve alcun gateway separato, perché il WebSocket gira sulla stessa porta del pannello.

Sicurezza e TLS

Il client si lamenta del certificato quando si collega alla 8883.

Al primo avvio il broker genera un certificato autofirmato: va bene per le prove, ma i client non si fidano. Per un sistema in produzione indica il tuo certificato nel blocco tls della configurazione (i campi cert e key) e riavvia il broker.

Come cambio la password dell'amministratore?

Nella sezione Profilo. La nuova password viene scritta in config.json come impronta: nel file non resta alcuna password in chiaro.

Ho dimenticato la password dell'amministratore.

Ferma il broker, togli il campo passwordHash dal blocco auth di config.json e mettici al suo posto "password": "la-tua-nuova-password". Al riavvio successivo il broker ne calcola l'impronta e cancella dal file il valore in chiaro.

Il pannello è raggiungibile da internet: è un problema?

L'installazione standard su Linux fa ascoltare il pannello solo su 127.0.0.1 e lo pubblica tramite nginx, dove è facile aggiungere HTTPS e restrizioni di accesso. Esporre direttamente la porta 8567 non è una buona idea.

Come do accesso all'API a un altro sistema?

Impostazioni → API: crea un token bearer. Viene mostrato una sola volta e ne è conservata solo l'impronta. Se al sistema servono solo le statistiche, spunta «sola lettura»: allora passeranno soltanto GET, HEAD e OPTIONS.

Carico e affidabilità

Un dispositivo sta inondando il broker di messaggi. E adesso?

Attiva i limitatori in Impostazioni → Broker: messaggi al secondo, raffica e byte al secondo. Valgono per connessione. Superarli non chiude la connessione e non perde messaggi: il broker legge il socket più lentamente e il mittente si modera da sé.

Un topic preciso è rumoroso, ma il client per il resto va bene.

È un caso per Regole → Limiti per topic. Una regola per schema riduce il flusso a una cadenza conservando l'ultimo valore, oppure scarta del tutto il topic. Un sensore che invia dieci volte al secondo diventa un messaggio al secondo, e sarà la lettura più fresca.

Che cosa sopravvive a un riavvio del broker?

I messaggi ritenuti, le sessioni persistenti con le loro sottoscrizioni e code offline, gli handshake QoS rimasti a metà e i messaggi differiti. Le sessioni pulite non vengono salvate: per specifica muoiono con la connessione.

È supportato il clustering?

No. Il broker è progettato come processo unico. Per collegare più broker c'è il bridge, che inoltra i topic tra server nei due sensi.

Come vedo che cosa sta succedendo adesso?

La sezione Traffico mostra un flusso in diretta di messaggi ed eventi del broker, con filtro e pausa, mentre la Panoramica offre grafici del ritmo, salute della macchina e un flusso di eventi. I dati arrivano via WebSocket.

Manutenzione

Come aggiorno il broker su Debian o Ubuntu?

Insieme al resto del sistema: sudo apt-get update && sudo apt-get upgrade. Non serve altro, e impostazioni e dati restano intatti.

Come trasferisco la configurazione su un altro server?

Impostazioni → Importazione ed esportazione: scarica il file sul vecchio server e caricalo sul nuovo. Impostazioni, utenti e regole vengono con te.

Dove sono i dati e i log?

I dati stanno nella cartella data accanto al binario (su Linux, /opt/elxmqttbroker): broker.db, users.json e i certificati. Su Linux i log vanno a journald: journalctl -u elxmqttbroker -f.

Come faccio a sapere quale versione sta girando?

Versione, numero di build e data di compilazione sono incisi nel binario: compaiono in fondo alla barra laterale, nella sezione Informazioni e lanciando elxmqttbroker -version.

Posso disattivare la persistenza dello stato?

Sì, con persistence: false in config.json. Allora tutto resta solo in memoria e si perde al riavvio, il che ha senso sui banchi di prova.

Non hai trovato la risposta?

Scrivici: cercheremo di aiutarti e di ampliare questa sezione.

serjaru@gmail.com Sfoglia la documentazione