Dokumentation

Installation

Der Broker ist eine ausführbare Datei. Unter Linux legt das Debian-Paket zusätzlich eine systemd-Einheit an, erzeugt das Arbeitsverzeichnis und startet den Dienst; unter Windows läuft die Datei dort, wo Sie sie ablegen.

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

Für 32- und 64-Bit-ARM-Boards ist das Vorgehen gleich — nehmen Sie arm64 oder armhf. Welches Board Sie haben, sagt uname -m: aarch64 bedeutet arm64, armv7l bedeutet armhf.

Starten Sie das Installationsprogramm oder entpacken Sie den portablen Build und starten Sie elxmqttbroker.exe.
Die Oberfläche öffnet sich unter http://127.0.0.1:8567
Standardzugang: admin / admin

Der erste Start

1. Öffnen Sie http://<Adresse>:8567 und melden Sie sich an.
2. Ändern Sie im Profilmenü das Kennwort des Verwalters.
3. Legen Sie unter Benutzer ein Konto für Ihre Geräte an und geben Sie ihm die nötigen Topics — die Rechteliste ist zunächst leer, und eine leere Liste bedeutet keinen Zugriff.
4. Verbinden Sie einen Client und sehen Sie ihn unter Clients erscheinen: Das bestätigt Adresse, Port und Zugangsdaten in einem Schritt.
5. Veröffentlichen Sie unter Veröffentlichen eine Testnachricht und prüfen Sie, ob der Abonnent sie erhält.

Benutzer und Rechte

Jedes Konto trägt eine Liste von Regeln. Eine Regel besteht aus einem Topic-Filter, einer Zugriffsart — abonnieren, veröffentlichen oder beides — und einem Urteil: erlauben oder verweigern. Erlaubt ist nichts, was nicht dasteht: Ein Konto ohne Regeln verbindet sich und kann nichts tun.

Der Platzhalter $u wird beim Verbinden zum Kontonamen aufgelöst. Eine Regel bedient damit tausend Geräte statt tausend Regeln: Jedes sieht nur seinen eigenen Teilbaum.

Woher die Zugangsdaten kommen

Der Broker kann eine eigene Kontenliste führen oder woanders nachfragen. Die Quelle wird im laufenden Betrieb umgestellt, ohne Neustart, damit sich eine neue prüfen lässt, während die alte noch bedient.

• Eingebaut. Konten in der brokereigenen Datenbank. Richtig für einige Dutzend Geräte.
• MariaDB / MySQL. Eine Tabelle, die Sie schon haben, mit der Abfrage in den Einstellungen. Richtig, wenn ein Geräteverzeichnis anderswo bereits existiert.
• SQLite. Eine Datei gleicher Form, für ein System, das seine Daten lokal hält.
• CSV. Eine einfache Datei, bei Änderung neu gelesen. Praktisch für eine feste Liste, die ein anderes Werkzeug erzeugt.
• JWT. Das Gerät legt statt eines Kennworts ein signiertes Token vor; der Broker prüft die Signatur und liest die Rechte aus den Feldern.
• HTTP. Der Broker fragt Ihren Dienst, ob dieser Client sich verbinden darf, und Ihr Dienst antwortet. Alles, was Sie ohnehin umsetzen — Gerätesperren, Tarife, Kontingente —, gilt damit ohne Verdopplung.

TLS

Verweisen Sie den Broker auf ein Zertifikat und einen Schlüssel, und der verschlüsselte Zugang startet auf Port 8883; dieselbe Kombination kann die Oberfläche nutzen. Für ein geschlossenes Netz kann der Broker selbst ein selbstsigniertes Paar erzeugen, und das genügt, um Kennwörter von der Leitung fernzuhalten.

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

Brücken

Eine Brücke ist eine dauerhafte Verbindung zu einem anderen Broker mit einer Liste der Topics, die hinübergehen. Die Richtung gilt je Topic: hinaus schiebt lokale Nachrichten nach draußen, herein holt entfernte herein, beides tut beides.

• Auf jeder Seite lässt sich ein Präfix hinzufügen, damit Nachrichten von einem entfernten Standort unter site-b/… ankommen und nie mit lokalen zusammenstoßen.
• Der Schleifenschutz verhindert, dass eine über die Brücke gekommene Nachricht sofort wieder hinausgeht.
• Eine abgerissene Verbindung wird mit wachsender Pause erneut versucht; die Warteschlange läuft derweil weiter.
• TLS und Zugangsdaten werden je Brücke eingestellt, sodass zwei Standorte verschiedene Zertifikate nutzen können.

Verzögertes Veröffentlichen

Eine Veröffentlichung nach $delayed/<Sekunden>/<Topic> übergibt dem Broker eine Nachricht, die später zuzustellen ist. Sie wird gespeichert, übersteht einen Neustart und erscheint in der Oberfläche, wo sie sich vor dem Auslösen abbrechen lässt.

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

Die Schreibweise entspricht EMQX, deshalb laufen für jenen Broker geschriebene Skripte unverändert.

Verkehrsbegrenzung

Zwei Mechanismen für zwei verschiedene Sorgen. Ein Token-Eimer je Verbindung verhindert, dass ein Client den Broker flutet. Regeln je Topic behandeln den anderen Fall — ein Gerät ist schlicht zu eifrig: Statt es zu trennen, wird der Strom auf eine Rate ausgedünnt, wobei der jüngste Wert erhalten bleibt.

REST-API

Die Oberfläche ist ein Client derselben API, die auch Sie nutzen können. Legen Sie in den Einstellungen ein Token an, entscheiden Sie, ob es schreiben darf, und rufen Sie es aus Ihrem eigenen System auf.

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}]}'

Was einen Neustart übersteht

• Aufbewahrte Nachrichten — der letzte Wert jedes Topics, das darum gebeten hat.
• Dauerhafte Sitzungen — Abonnements von Clients, die mit abgeschaltetem clean_session verbunden waren.
• Warteschlangen für QoS 1 und 2 dieser Sitzungen, solange der Client fort ist.
• Verzögerte Nachrichten, deren Zeitpunkt noch nicht erreicht ist.
• Benutzer, Rechte, Brücken, Regeln und Einstellungen.

All das liegt in einer SQLite-Datei. Den Broker zu sichern heißt, diese Datei zu kopieren; ihn umzuziehen heißt, sie mitzunehmen.

Wenn etwas nicht stimmt