MQTT Connector – Inbetriebnahme

Diese Anleitung führt Schritt für Schritt durch die Inbetriebnahme des MQTT Connectors (HP.MQTTConnector) auf einem FLECS-Gerät: von den Ports über die Passwörter der Benutzer bis zur ersten Verbindung der Steuerung. Die Verschlüsselung per TLS ist optional und in Schritt 7 beschrieben.

Wie die App arbeitet, steht in der Funktionsbeschreibung, warum die einzelnen Schutzmaßnahmen nötig sind, unter Sicherheit.

Auf einen Blick

Ablauf

Schritt 1: Voraussetzungen prüfen

• Das FLECS-Gerät steht im Steuerungsnetz der Anlage und hat eine feste IP-Adresse. Mit TLS ist das besonders wichtig: Die Adresse steht im Zertifikat (siehe Schritt 7).
• Der MQTT Connector und HP.CloudLink sind auf dem Gerät installiert und laufen.
• Die Steuerung hat einen MQTT-Client für MQTT 3.1.1 oder 5.0.
• Herborner Pumpen hat die Pumpen und Entities der Anlage in der Cloud angelegt. Ohne sie gibt es keine Pumpen-Topics.
• Auf einem Service-Rechner im selben Netz:
  • ein MQTT-Client zum Testen, etwa MQTT Explorer oder mosquitto_sub/mosquitto_pub (Paket mosquitto-clients),
  • Python 3 zum Erzeugen der Passwörter,
  • für TLS zusätzlich openssl, um den Fingerabdruck zu prüfen.

Schritt 2: Ports freigeben

1. Lassen Sie in der Firewall der Anlage diese Ports nur für die IP-Adressen der Steuerungen zu, die sie brauchen. Der Broker bremst falsche Anmeldeversuche nicht; die Firewall ist deshalb die erste Hürde.
2. Die Weboberfläche arbeitet ohne Anmeldung. Geben Sie sie nur für Service-Rechner frei.

Schritt 3: Zustand in der Weboberfläche prüfen

Öffnen Sie die Weboberfläche der App über FLECS. Unter Telemetry zeigt die App ihren Zustand. Direkt nach der Installation sieht er so aus:

Steht bei Devices 0 pumps / 0 entities, fehlen die Pumpen in der Cloud oder HP.CloudLink läuft nicht. Das hält die weitere Inbetriebnahme nicht auf; die Topics erscheinen, sobald die Konfiguration ankommt, ohne Neustart.

Darunter steht je Pumpe und Entity eine Tabelle. Ihre Überschrift nennt Nummer, Name und Seriennummer der Pumpe (bei Entities die UUID), die Zeile darunter das Topic des Geräts, etwa Topic HP/pump/AB-2400654-010-01. Die Zeilen der Tabelle zeigen das Topic jedes Datenpunkts und in der Spalte write access, wer ihn schreiben darf. Diese Topics brauchen Sie ab Schritt 6.

Schritt 4: Benutzer und Schreibrechte festlegen

Der Broker nimmt nur angemeldete Clients an; anonyme Verbindungen sind immer gesperrt. Lesen dürfen alle Benutzer alles. Festgelegt wird nur, wer was schreiben darf. Im Auslieferungszustand gibt es zwei Benutzer:

Ein Benutzer ohne Passwort ist gesperrt. Ein Benutzer, den Sie nicht brauchen, bekommt also einfach kein Passwort; entfernen müssen Sie ihn nicht.

Schreibrechte festlegen

Jeder Benutzer hat eine Liste write. Sie legt fest, welche Geräte er schreiben darf; "+" heißt alle, eine leere Liste keines:

Ein Eintrag ist "+" für alles, ein Gerätetyp (pump, entity) oder ein einzelnes Gerät mit seiner Seriennummer bzw. UUID, so wie es im Topic steht. Groß- und Kleinschreibung zählen. Sind die Topics über die Nummer eingeschaltet (siehe Schritt 8), geht auch pump/1; das Recht gilt dann nur für diesen Weg, nicht für die Seriennummer.

Benutzer und Schreibrechte trägt Herborner Pumpen in der Konfiguration ein. Benutzernamen bestehen aus Kleinbuchstaben, Ziffern und _, beginnen mit einem Buchstaben und sind höchstens 32 Zeichen lang.

Prüfen: Unter Telemetry zeigt die Spalte write access je Datenpunkt die Benutzer, die ihn schreiben dürfen. Zeigt ein Eintrag auf ein Gerät, das es nicht gibt, etwa wegen eines Tippfehlers, wird die Zeile Users gelb und nennt ihn.

Schritt 5: Passwörter erzeugen und setzen

Ein Benutzer ohne Passwort kann sich nicht anmelden. Auf dem Gerät und in der Konfiguration steht nie das Passwort selbst, sondern nur sein Hash. Der Hash wird mit der Konfiguration auch in die Herborner-Cloud übertragen; aus ihm lässt sich ein kurzes Passwort durch Ausprobieren erraten, ein langes zufälliges nicht.

5.1 Passwort erzeugen

Erzeugen Sie für jeden benötigten Benutzer ein eigenes, zufälliges Passwort mit mindestens 20 Zeichen, etwa so:

python3 -c 'import secrets; print(secrets.token_urlsafe(24))'

Notieren Sie das Passwort sicher, etwa im Passwort-Tresor der Anlage. Die Steuerung speichert es; niemand muss es sich merken.

5.2 Passwort setzen

Es gibt zwei Wege. Beide enden gleich: Auf dem Gerät steht nur der Hash, und der Broker übernimmt ihn.

Weg A – Umgebungsvariable

1. Legen Sie in FLECS bei der App je Benutzer eine Umgebungsvariable an. Ihr Name ist MQTT_PASSWORD_ und der Benutzername in Großbuchstaben, der Wert das Passwort:

   MQTT_PASSWORD_PLC=<Passwort für plc>
   MQTT_PASSWORD_MONITOR=<Passwort für monitor, nur falls benötigt>
   

   Für einen Benutzer plc_halle1 heißt die Variable MQTT_PASSWORD_PLC_HALLE1.

2. Starten Sie die App neu.

3. Prüfen Sie unter Logs die Meldung MQTT password set by environment variable for: plc.

Solange die Variable gesetzt ist, überschreibt die App ein abweichendes Passwort aus eThemis bei jedem Abgleich wieder. Jeder mit Zugriff auf die Einstellungen der App in FLECS kann die Variable lesen; schützen Sie den Zugang zu FLECS entsprechend.

Weg B – eThemis

1. Setzen Sie in der Weboberfläche von eThemis beim MQTT Connector des Geräts für den Benutzer das Passwort aus 5.1.
2. Auf das Gerät gelangt nur der Hash des Passworts. Der Broker übernimmt ihn sofort, ohne Neustart der App.

Haben Sie keinen Zugang zu eThemis, setzt Herborner Pumpen das Passwort auf Anfrage. Schicken Sie dafür kein Passwort per E-Mail; wie das Passwort sicher übergeben wird, stimmt Herborner Pumpen mit Ihnen ab.

Ist für den Benutzer zusätzlich eine Umgebungsvariable gesetzt (Weg A), gilt deren Passwort.

5.3 Ergebnis prüfen

Die Zeile Users unter Telemetry ist jetzt grün, etwa mit 2 of 2 users can log in oder, ohne Leitsystem, 1 of 2 users can log in (no password, disabled: monitor). Grün wird sie, sobald sich ein schreibender Benutzer wie plc anmelden kann; ein Benutzer ohne Passwort ist nur gesperrt.

Steht ein benötigter Benutzer noch unter no password, ist für ihn kein Passwort angekommen: Bei Weg A Name der Variable und Neustart prüfen, bei Weg B die Eingabe in eThemis prüfen oder bei Herborner Pumpen nachfragen.

Passwort später ändern oder Zugang sperren

• Ändern: neues Passwort erzeugen, auf einem der beiden Wege setzen und in der Steuerung hinterlegen. Das alte Passwort gilt ab dann nicht mehr.
• Sperren: Herborner Pumpen entfernt das Passwort oder den Benutzer. Ist eine Umgebungsvariable gesetzt, entfernen Sie auch sie, sonst trägt die App das Passwort beim nächsten Start wieder ein.

Schritt 6: Verbindung testen

Prüfen Sie vom Service-Rechner aus, dass Anmeldung, Lesen und Schreiben funktionieren. Ist TLS bereits eingeschaltet, folgen Sie stattdessen Schritt 7.5.

1. Anmelden und Zustand lesen:

   mosquitto_sub -h <IP-Adresse> -p 1883 -u plc -P <Passwort> -t HP/status -v
   

   Erwartet: HP/status online. Meldet der Client not authorised, ist das Passwort falsch oder nicht gesetzt. mosquitto_sub verbindet sich mit MQTT 3.1.1; mit -V 5 prüfen Sie MQTT 5.0.

2. Werte lesen: HP/pump/<Seriennummer>/# abonnieren, die Seriennummer aus der Telemetrie (Schritt 3). Es erscheinen sofort die Werte der Pumpe.

3. Schreiben: mit dem Benutzer plc einen Wert schreiben und im zweiten Fenster beobachten:

   mosquitto_sub -h <IP-Adresse> -u plc -P <Passwort> -t HP/pump/<Seriennummer>/flow_rate -t HP/error -v
   mosquitto_pub -h <IP-Adresse> -u plc -P <Passwort> -q 1 -t HP/pump/<Seriennummer>/set/flow_rate -m 12.5
   

   Erwartet: HP/pump/<Seriennummer>/flow_rate 12.5. Ein abgelehnter Wert erscheint mit Grund auf HP/error.

4. Rechte prüfen: Derselbe mosquitto_pub mit einem Benutzer, der dieses Gerät nicht schreiben darf – etwa monitor, falls er ein Passwort hat – und einem anderen Wert darf nichts ändern: Der Broker verwirft die Nachricht, flow_rate bleibt bei 12.5.

Schritt 7 (optional): TLS einrichten

Ohne TLS gehen Benutzername, Passwort und alle Werte im Klartext über das Netz. Mit TLS ist die Verbindung verschlüsselt, und die Steuerung prüft anhand des Zertifikats, dass sie mit diesem Gerät spricht. Wir empfehlen TLS für jedes Anlagennetz, das nicht vollständig abgeschottet ist.

Die App erzeugt Schlüssel und Zertifikat selbst (selbstsigniert, gültig 10 Jahre). Der private Schlüssel entsteht auf dem Gerät und verlässt es nie. Die Steuerung hinterlegt genau dieses Zertifikat als vertrauenswürdig; man nennt das Pinnen.

Wichtig: Sobald TLS eingeschaltet ist, nimmt der Broker Verbindungen von außen nur noch auf Port 8883 an. Steuerungen, die noch über 1883 verbunden sind, werden getrennt. Planen Sie die Umstellung so, dass Sie die Steuerungen direkt danach umstellen können.

7.1 Vorbereiten

1. Port 8883 in FLECS und in der Firewall freigeben (siehe Schritt 2).
2. Klären, unter welchen Adressen die Steuerungen das Gerät erreichen. Die IP-Adressen des Geräts, die FLECS meldet, kommen automatisch ins Zertifikat. Erreichen die Steuerungen das Gerät über einen Namen (etwa plc-gateway.local) oder eine weitere Adresse, muss dieser zusätzlich ins Zertifikat.

7.2 TLS einschalten lassen

Herborner Pumpen setzt in der Konfiguration unter broker:

Die App erzeugt daraufhin das Zertifikat und startet den Broker neu.

7.3 Zustand prüfen

Die Zeile TLS unter Telemetry zeigt jetzt etwa Port 8883, valid until 2036-10-16 (grün).

7.4 Zertifikat herunterladen und Fingerabdruck prüfen

1. In der Zeile TLS auf Download certificate klicken. Die Datei mqtt-broker.crt enthält nur das Zertifikat, nie den Schlüssel.

2. In derselben Zeile steht der SHA-256-Fingerabdruck; das Symbol daneben kopiert ihn.

3. Den Fingerabdruck der heruntergeladenen Datei berechnen und vergleichen:

   openssl x509 -in mqtt-broker.crt -noout -fingerprint -sha256
   

   Beide müssen übereinstimmen. Zusätzlich können Sie ihn mit dem Fingerabdruck vergleichen, den Herborner Pumpen aus der Cloud nennt. So stellen Sie sicher, dass unterwegs niemand ein anderes Zertifikat untergeschoben hat.

7.5 Verbindung mit TLS testen

mosquitto_sub -h <IP-Adresse> -p 8883 --cafile mqtt-broker.crt -u plc -P <Passwort> -t HP/status -v

Erwartet: HP/status online. Die Adresse hinter -h muss im Zertifikat stehen; sonst bricht der Client mit einem Zertifikatsfehler ab (siehe 7.3). Ein Versuch auf Port 1883 von außen schlägt jetzt fehl – das ist gewollt.

7.6 Steuerung umstellen

In der Steuerung:

• Port 8883, TLS ein,
• mqtt-broker.crt als vertrauenswürdiges Zertifikat (CA) hinterlegen – oder, wenn die Steuerung das so vorsieht, den SHA-256-Fingerabdruck,
• Hostname- bzw. Zertifikatsprüfung eingeschaltet lassen,
• Benutzer und Passwort wie bisher.

TLS im laufenden Betrieb

• Erneuerung: Nach zwei Dritteln der Laufzeit, also nach knapp sieben Jahren, erzeugt die App ein neues Zertifikat. Dann müssen alle Steuerungen das neue Zertifikat hinterlegen (Schritte 7.4 und 7.6).
• Neue IP-Adresse des Geräts: Die App tauscht das Zertifikat nicht von selbst aus, weil sonst alle Steuerungen auf einmal getrennt würden. Die Zeile TLS zeigt die fehlende Adresse gelb an. Erst wenn Herborner Pumpen sie in tls_subject_alt_names einträgt, entsteht ein neues Zertifikat, das alle Steuerungen neu hinterlegen müssen.
• Neuer Name in tls_subject_alt_names: führt ebenfalls zu einem neuen Zertifikat.

Schritt 8: Steuerung anbinden

Hinterlegen Sie in der Steuerung:

Topics der Geräte

Jedes Gerät ist im Standard über seine Seriennummer erreichbar (Entities über ihre UUID):

HP/pump/AB-2400654-010-01/flow_rate          Wert lesen
HP/pump/AB-2400654-010-01/set/flow_rate      Wert schreiben

Die Seriennummer bleibt gleich, auch wenn Pumpen in der Cloud neu nummeriert werden. Auf Wunsch schaltet Herborner Pumpen zusätzlich oder stattdessen Topics über die Nummer des Geräts ein (number_paths), etwa HP/pump/1/flow_rate. Das ist bequemer, aber:

Achtung: Werden die Geräte umnummeriert, liest und schreibt eine Steuerung, die mit HP/pump/1/… arbeitet, ab dann ein anderes Gerät. Für feste Zuordnungen die Seriennummer verwenden.

Abonnieren Sie in der Steuerung nur die Geräte, die sie braucht, etwa HP/pump/AB-2400654-010-01/#, nicht HP/#. Sind beide Wege eingeschaltet, käme über HP/# jeder Wert doppelt an.

Was die Steuerung sonst braucht

Welche Topics die Steuerung abonniert und beschreibt, wie sie den Zustand der App überwacht und wie sie abgelehnte Werte erkennt, beschreibt die Funktionsbeschreibung unter Implementierung in der Steuerung. Die verfügbaren Topics mit Datentypen und Grenzwerten stehen in der Standard-Konfiguration.

Wichtig für die Steuerung:

• Befehle mit QoS 1 und ohne Retain-Flag senden.
• HP/status und HP/error abonnieren.

Nach dem Anbinden zählt die Zeile Clients jede verbundene Steuerung und jedes andere System, etwa ein Leitsystem oder einen MQTT Explorer; die App selbst zählt nicht mit.

Checkliste zum Abschluss

1. Gerät mit fester IP-Adresse im Steuerungsnetz, MQTT-Port nur für die Steuerungen freigegeben.
2. Weboberfläche nur von Service-Rechnern erreichbar.
3. Jeder benötigte Benutzer hat ein eigenes, zufälliges Passwort; Users ist grün. Nicht benötigte Benutzer wie ein ungenutzter monitor haben kein Passwort und sind damit gesperrt.
4. Lesende Systeme verwenden einen Benutzer ohne Schreibrechte (write: []). Die Spalte write access zeigt je Gerät nur die Benutzer, die es schreiben sollen; Users ist nicht gelb.
5. Optional: TLS eingeschaltet, TLS grün, Fingerabdruck verglichen, alle Steuerungen verbinden sich auf Port 8883.
6. Clients zeigt die erwartete Anzahl Verbindungen; Statistics zeigt keine abgelehnten Befehle.

Fehlerbehebung