Documentazione ELX-MQTT Broker — installazione e permessi

Installazione

Il broker è un eseguibile. Su Linux il pacchetto Debian aggiunge un'unità systemd, crea la cartella di lavoro e avvia il servizio; su Windows il file gira dove lo mettete.

Debian / Ubuntu, amd64

wget https://elxsoftware.com/download/elxmqttbroker-linux-amd64
sudo install -m 755 elxmqttbroker-linux-amd64 /usr/local/bin/elxmqttbroker
sudo elxmqttbroker --install-service
sudo systemctl enable --now elxmqttbroker

Per le schede ARM a 32 e 64 bit il procedimento è identico — prendete arm64 o armhf. Quale sia la vostra lo dice uname -m: aarch64 significa arm64, armv7l significa armhf.

Windows

Avviate l'installatore, oppure estraete la build portatile e aprite elxmqttbroker.exe.
L'interfaccia si apre su http://127.0.0.1:8567
Accesso predefinito: admin / admin

Cambiate la password prima che la macchina sia raggiungibileIl primo account è admin / admin, perché il primo avvio riesca senza configurazione. Cambiatelo dall'interfaccia prima che la macchina sia raggiungibile da qualcosa che non sia la vostra scrivania.

Il primo avvio

Aprite http://<indirizzo>:8567 ed entrate.
Cambiate la password dell'amministratore dal menu del profilo.
Create in Utenti un account per i vostri dispositivi e dategli gli argomenti necessari — l'elenco dei permessi all'inizio è vuoto, e un elenco vuoto significa nessun accesso.
Collegate un client e guardatelo comparire in Client: questo conferma in un colpo solo indirizzo, porta e credenziali.
Pubblicate un messaggio di prova da Pubblica e verificate che l'iscritto lo riceva.

Se un client non si collegaIl flusso di eventi dell'interfaccia dice il motivo — credenziali sbagliate, argomento negato, versione di protocollo diversa o errore TLS. È più rapido che leggere i registri del client.

Utenti e permessi

Ogni account porta un elenco di regole. Una regola è un filtro di argomenti, un tipo di accesso — iscriversi, pubblicare o entrambi — e un verdetto: permettere o negare. Non è permesso nulla che non sia scritto: un account senza regole si collega e non può fare niente.

Regola	Significato
`sensors/#` · iscriversi · permettere	Può leggere l'intero ramo dei sensori
`sensors/kitchen/+` · pubblicare · permettere	Può scrivere in qualsiasi argomento un livello sotto kitchen
`devices/$u/#` · entrambi · permettere	Può fare tutto nel proprio ramo e nulla fuori
`#` · entrambi · negare	Nega esplicitamente tutto ciò che sopra non è stato permesso

Il segnaposto $u diventa il nome dell'account al momento del collegamento. Una sola regola serve quindi mille dispositivi senza mille regole: ciascuno vede soltanto il proprio sottoalbero.

L'ordine contaLe regole si valutano dall'alto in basso e vince la prima che corrisponde. Una negazione ampia posta sopra un permesso ristretto lo nasconde del tutto — è il motivo consueto per cui un permesso «non funziona».

Da dove vengono le credenziali

Il broker può tenere un proprio elenco di account oppure chiedere a qualcos'altro. La fonte si cambia a caldo, senza riavvio, così da poterne provare una nuova mentre la vecchia serve ancora.

Interno. Account nella base del broker. Adatto a qualche decina di dispositivi.
MariaDB / MySQL. Una tabella che avete già, con la query scritta nelle impostazioni. Adatto quando un inventario dei dispositivi esiste altrove.
SQLite. Un file della stessa forma, per un sistema che tiene i propri dati in locale.
CSV. Un semplice file, riletto quando cambia. Comodo per un elenco fisso prodotto da un altro strumento.
JWT. Il dispositivo presenta un token firmato invece di una password; il broker verifica la firma e legge i permessi dai campi.
HTTP. Il broker chiede al vostro servizio se questo client può collegarsi, e il vostro servizio risponde. Tutto ciò che già applicate — blocco dei dispositivi, tariffe, quote — vale allora senza duplicazioni.

TLS

Indicate al broker un certificato e una chiave e l'ascolto cifrato parte sulla porta 8883; la stessa coppia può servire all'interfaccia. Per una rete chiusa il broker sa generare da sé una coppia autofirmata, e tanto basta a tenere le password fuori dal cavo.

Verificare il certificato da riga di comando

openssl s_client -connect broker.example.com:8883 -servername broker.example.com </dev/null | head -20

Certificati autofirmati e clientUn client che verifica i certificati rifiuterà quello autofirmato finché non gli si dirà di fidarsene. Aggiungete dunque il certificato all'archivio di fiducia del client, oppure prendetene uno vero — disattivare la verifica toglie al TLS la sua ragion d'essere.

Ponti

Un ponte è un collegamento permanente verso un altro broker, con l'elenco degli argomenti da trasportare. La direzione vale per argomento: in uscita spinge fuori i messaggi locali, in entrata porta dentro quelli remoti, entrambe fa l'una e l'altra cosa.

Da ciascun lato si può aggiungere un prefisso, perché i messaggi di un sito remoto arrivino sotto site-b/… e non collidano mai con quelli locali.
La protezione dai cicli impedisce che un messaggio arrivato dal ponte riparta subito.
Un collegamento caduto viene ritentato con pausa crescente; la coda intanto continua.
TLS e credenziali si impostano per ogni ponte, così due sedi possono usare certificati diversi.

Un ponte o una rete comune?Un ponte unisce due broker attraverso l'Internet pubblico con un elenco esplicito di ciò che attraversa il confine. Se invece volete che siano le macchine stesse a stare su una sola rete, è un altro strumento — si veda ELX-VNetwork.

Pubblicazione differita

Pubblicare su $delayed/<secondi>/<argomento> affida al broker un messaggio da consegnare più tardi. Viene conservato, sopravvive a un riavvio e compare nell'interfaccia, dove si può annullare prima che scatti.

Spegnere la luce fra cinque minuti

mosquitto_pub -h broker -t '$delayed/300/home/light/kitchen' -m 'off'

La sintassi corrisponde a quella di EMQX, perciò gli script scritti per quel broker funzionano senza ritocchi.

Limiti di ritmo

Due meccanismi per due problemi diversi. Un secchio a gettoni per collegamento impedisce a un client di inondare il broker. Le regole per argomento affrontano l'altro caso — un dispositivo semplicemente troppo zelante: invece di scollegarlo, si dirada il flusso a un certo ritmo conservando il valore più recente.

Regola	Effetto
`sensors/+/raw` · 1 al secondo	Al massimo un messaggio al secondo per argomento; vince il più recente
`debug/#` · scartare	Scartato al broker, gli iscritti non lo vedono mai
Collegamento · 200 al secondo	Un client che va oltre viene frenato e poi scollegato

API REST

L'interfaccia è un client della stessa API che potete usare anche voi. Create un token nelle impostazioni, decidete se può scrivere e chiamatela dal vostro sistema.

Creare un account per un dispositivo da uno script

curl -X POST https://broker.example.com/api/users \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"sensor-42","password":"...","acl":[{"filter":"devices/sensor-42/#","access":"both","allow":true}]}'

Token di sola letturaA un sistema di monitoraggio servono statistiche, non la facoltà di cancellare utenti. Dategli un token di sola lettura e la questione non si pone.

Cosa sopravvive a un riavvio

I messaggi conservati — l'ultimo valore di ogni argomento che l'ha chiesto.
Le sessioni persistenti — le sottoscrizioni dei client collegati con clean_session disattivato.
Le code QoS 1 e 2 di quelle sessioni mentre il client è assente.
I messaggi differiti la cui scadenza non è ancora giunta.
Utenti, permessi, ponti, regole e impostazioni.

Tutto questo sta in un file SQLite. Salvare il broker vuol dire copiare quel file; trasferirlo vuol dire portarlo con sé.

Quando qualcosa non va

Sintomo	Dove guardare
Il client si collega e si scollega subito	Credenziali, oppure un elenco di permessi che nega tutto. Il flusso di eventi ne dice il motivo.
I messaggi vengono pubblicati ma nessuno li riceve	I permessi di chi pubblica consentono la scrittura, quelli dell'iscritto non consentono la lettura di quel filtro.
Il valore conservato non torna dopo un riavvio	La persistenza è disattivata, oppure la cartella di lavoro non è scrivibile dall'utente del servizio.
Un dispositivo si ricollega in continuazione	Due client con lo stesso identificatore — ogni collegamento butta fuori l'altro.
Un client TLS si lamenta del certificato	Un certificato autofirmato di cui non si fida, o un nome che non corrisponde al certificato.
L'interfaccia non è raggiungibile da un'altra macchina	È legata all'indirizzo di loopback; cambiate l'indirizzo di ascolto nelle impostazioni.

Documentazione