gfaservices/svc/mqttcl/cfg/README.md

Mögliche Parameter in mqttcl.cfg.json:

• brokerAddr:

  • Name oder IP-Adresse des Brokers.

• brokerPort:

  • Optional.
  • TCPIP-Port des Brokers.
  • Siehe Broker-Konfiguration weiter unten.
  • Default: 8883, wenn tlsMode > 0, sonst 1883.

• defaultQos:

  • Optional.
  • Default Quality of Service. 0, 1 oder 2, siehe MQTT-Dokumentation.
  • Default: 2.

• defaultRetain:

  • Optional.
  • Default Retained-Einstellung.
  • Default: false.

• devicePrefix:

  • Optional.
  • Wird u. a. verwendet, um zusammen mit der SHM-UUID das Topic-Prefix zu generieren.
  • Default: Leer, wenn nicht angegeben.

• deviceID:

  • Optional.
  • Wird u. a. verwendet, um zusammen mit der SHM-UUID das Topic-Prefix zu generieren.
  • Default: Automatisch generiert aus devicePrefix und MAC-Adresse, oder nur MAC-Adresse, wenn kein devicePrefix angegeben.

• disableTopicPrefix:

  • Optional.
  • Wenn true, wird kein Topic-Prefix gesendet. (Wenn nicht unbedingt notwendig, sollte das Topic-Prefix nicht deaktiviert werden!)
  • Default: false.

• topicPrefix:

  • Optional.
  • Nur wenn disableTopicPrefix = false.
  • Ersetzt, wenn angegeben, das Topic-Prefix.

• tlsMode:

  • Optional.
  • 0 = kein TLS, 1 = TLS mit Zertifikat, 2 = TLS mit Preshared Key. Ungültige Werte werden auf 0 korrigiert!
  • Siehe Broker-Konfiguration weiter unten.
  • Default: 0 (kein TLS).

• tlsCaCrtFile, tlsClKeyFile, tlsClCrtFile:

  • Erforderlich wenn tlsMode = 1.
  • Pfad zu den folgenden Dateien:
    • tlsCaCrtFile: öffentliches Zertifikat der Certificate Authority.
    • tlsClKeyFile: privater Schlüssel des Client.
    • tlsClCrtFile: öffentliches Zertifikat zu diesem Schlüssel.
  • Siehe Broker-Konfiguration weiter unten.

• tlsPsk:

  • Erforderlich wenn tlsMode = 2.
  • Preshared Key als String im Hex-Format ohne führendes "0x".
  • Siehe Broker-Konfiguration weiter unten.

• tlsPskClientID:

  • Optional.
  • Nur von Bedeutung wenn tlsMode = 2.
  • Default: Wird, wenn nicht angegeben, mit der Device-ID initialisiert.

• lastWillMsgStr:

  • Optional.
  • Wenn angegeben, wird diese Nachricht als "Last Will" gepublished.

• lastWillMsgInt:

  • Optional.
  • Nur wenn lastWillMsgStr nicht angegeben.
  • Wenn angegeben, wird dieser Wert als signed 64Bit-Wert binär als "Last Will" gepublished.

• lastWillTopic:

  • Optional.
  • Nur wenn lastWillMsgStr oder lastWillMsgInt konfiguriert.
  • Topic des "Last Will".
  • Default: "LWC".

• lastWillQos:

  • Optional.
  • Nur wenn lastWillMsgStr oder lastWillMsgInt konfiguriert.
  • Quality of Service des "Last Will".
  • Default: Wert des defaultQos.

• lastWillRetain:

  • Optional.
  • Nur wenn lastWillMsgStr oder lastWillMsgInt konfiguriert.
  • Retained-Einstellung des "Last Will".
  • Default: defaultRetain.

• lastWillOnExit:

  • Optional.
  • Nur wenn lastWillMsgStr oder lastWillMsgInt konfiguriert.
  • Wenn true, wird auch beim normalen Beenden des Clients eine "Last Will"-Message mit dem Wert von lastWillOnExitMsgStr oder lastWillOnExitMsgInt gepublished.
  • Default: true.

• lastWillOnExitMsgStr:

  • Optional.
  • Nur wenn lastWillMsgStr oder lastWillMsgInt konfiguriert ist und lastWillOnExit = true.
  • Nachricht, die beim normalen Beenden des Clients gepublished wird.
  • Default: Wenn weder lastWillOnExitMsgStr noch lastWillOnExitMsgInt angegeben sind, wird lastWillOnExitMsgStr auf lastWillMsgStr gesetzt, sofern dieser konfiguriert ist, ansonsten wird lastWillOnExitMsgInt auf lastWillMsgInt gesetzt.

• lastWillOnExitMsgInt:

  • Optional.
  • Nur wenn lastWillMsgStr oder lastWillMsgInt konfiguriert ist und lastWillOnExit = true.
  • Nur wenn lastWillOnExitMsgStr nicht angegeben.
  • Wird als signed 64Bit-Wert binär beim normalen Beenden des Clients gepublished.
  • Default: Wenn weder lastWillOnExitMsgStr noch lastWillOnExitMsgInt angegeben sind, wird lastWillOnExitMsgStr auf lastWillMsgStr gesetzt, sofern dieser konfiguriert ist, ansonsten wird lastWillOnExitMsgInt auf lastWillMsgInt gesetzt.

• connectMsgStr:

  • Optional.
  • Nachricht, die, wenn konfiguriert, beim Start des Clients gepublished wird.

• connectMsgInt:

  • Optional.
  • Nur wenn connectMsgStr nicht angegeben.
  • Wenn angegeben, wird dieser Wert als signed 64Bit-Wert binär beim Start des Clients gepublished.

• connectTopic:

  • Optional.
  • Nur wenn connectMsgStr oder connectMsgInt konfiguriert.
  • Topic der Nachricht, die beim Start des Clients gepublished wird.
  • Default: lastWillTopic, wenn konfiguriert, sonst "LWC".

• connectQos:

  • Optional.
  • Nur wenn connectMsgStr oder connectMsgInt konfiguriert.
  • Quality of Service der Startnachricht.
  • Default: defaultQos.

• connectRetain:

  • Optional.
  • Nur wenn connectMsgStr oder connectMsgInt konfiguriert.
  • Retained-Einstellung der Startnachricht.
  • Default: defaultRetain.

• maxKeepAlive:

  • Optional.
  • Maximales Zeitintervall in Sekunden, in dem der Broker Keep-Alive-Pakete an den Client sendet. Werte < 10 werden auf 10 korrigiert.
  • Default: 60.

• userName:

  • Optional.
  • Benutzername zur Identifikation am Broker (in Verbindung mit dem Passwort).
  • Siehe Broker-Konfiguration weiter unten.
  • Default: nicht konfiguriert.

• passWord:

  • Optional.
  • Passwort zur Identifikation am Broker (in Verbindung mit dem Benutzername).
  • Leeres Paswort nicht möglich.
  • Siehe Broker-Konfiguration weiter unten.
  • Default: nicht konfiguriert.

Broker-Konfiguration:

• Die folgende Beschreibung bezieht sich auf den Mosquitto-Broker. Für eine vollständige Beschreibung der Parameter siehe die Datei mosquitto-broker-conf-example.txt im Verzeichnis ./mosquitto-broker.

• Grundsätzlich unterstützt der Mosquitto-Broker zwei verschiedene Arten verschlüsselten Zugriffs mittels TLS sowie unverschlüsselten Zugriff. In jedem dieser Modi kann eine zusätzliche Benutzeridentifikation durch Benutzername und Passwort konfiguriert werden.

• Im Verzeichnis ./mosquitto-broker befindet sich jeweils eine Beispielkonfiguration für jede der möglichen Zugriffsarten. Die Datei ./mosquitto.conf enthält die gemeinsamen Einstellungen sowie die Möglichkeit, eine von drei Konfigurationsarten zu wählen. Zu diesem Zweck wird eines von drei möglichen Verzeichnissen inkludiert, die sich im Ordner "gfa.d" befinden. Die beiden anderen Zeilen müssen auskommentiert bleiben! Die tatsächlichen Einstellungen werden dann in der Datei gfa.conf im entsprechenden Verzeichnis "gfa.d/gfa.conf.*" vorgenommen.

• Benutzeridentifikation durch Benutzername und Passwort:

  • Für eine Benutzeridentifikation mittels Benutzername und Passwort sind folgende Einstellungen nötig:

  • gfa.conf[.*]/gfa.conf:

    • allow_anonymous false - (verhindert den anonymen Zugriff auf den Broker)
    • password_file <passwordfile> - (Pfad zu einer Passwortdatei. Diese Datei wird mit dem Tool mosquitto_passwd erstellt bzw. modifiziert. Näheres dazu kann der Hilfe des Tools (mosquitto_passwd --help) entnommen werden.)

  • mqttcl.conf.json:

    • userName - (Benutzername wie in der Passwortdatei)
    • passWord - (Passwort wie in der Passwortdatei)

• Unverschlüsselter Zugriff auf den Broker:

  • Für den unverschlüsselten Zugriff wird in mosquitto.conf die Zeile "include_dir /etc/mosquitto/gfa.d/gfa.conf" einkommentiert.

  • gfa.conf/gfa.conf:

    • listener 1883 - (Standard-Mqtt-Port für Verbindung ohne TLS)

  • mqttcl.conf.json:

    • tlsMode: 0 - (Kein TLS)
    • brokerPort: 1883 - (Standard-Mqtt-Port für Verbindung ohne TLS)

• Zugriff auf den Broker mittels TLS-PSK:

  • Für den Zugriff mittels TLS-PSK wird in mosquitto.conf die Zeile "include_dir /etc/mosquitto/gfa.d/gfa.conf.psk" einkommentiert.
    Achtung: Der MQTT Explorer funktioniert nicht mit PSK!

  • gfa.conf.psk/gfa.conf:

    • listener 8883 - (Standard-Mqtt-Port für Verbindung mittels TLS.)
    • psk_file <pskfile> - (Pfad zur PSK-Datei. Siehe mosquitto-broker-conf-example.txt zum Format.)
    • psk_hint <Hint> - (Frei wählbarer String. Schaltet PSK ein.)

  • mqttcl.conf.json:

    • tlsMode: 2 - (TLS-PSK)
    • brokerPort: 8883 - (Standard-Mqtt-Port für Verbindung mittels TLS)
    • tlsPsk: <psk> - (Pre-shared Key im Hexformat ohne '0x'. Dieser Key muss dem Key im PSK-File entsprechen.)
    • tlsPskClientID: <clid> - Client Identity für PSK. Muss der Identity im PSK-File entsprechen.)

• Zugriff auf den Broker mittels TLS-Zertifikaten:

  • Für den Zugriff mittels TLS-Zertifikaten wird in mosquitto.conf die Zeile "include_dir /etc/mosquitto/gfa.d/gfa.conf.cert" einkommentiert.

  • gfa.conf.cert/gfa.conf:

    • listener 8883 - (Standard-Mqtt-Port für Verbindung mittels TLS.)
    • require_certificate true - (Verbindung nur mit Zertifikat)
    • cafile <rootcert> - (Pfad zum Rootzertifikat)
    • keyfile <serverkey> - (Pfad zum Private Key des Servers)
    • certfile <servercert> - (Pfad zum Serverzertifikat)

  • mqttcl.conf.json:

    • tlsMode: 1 - (TLS-Zertifikate)
    • brokerPort: 8883 - (Standard-Mqtt-Port für Verbindung mittels TLS)
    • tlsCaCrtFile <rootcert> - (Pfad zum Rootzertifikat. Dieses Zertifikat muss dem des Brokers entsprechen!)
    • tlsClKeyFile <clientkey> - (Pfad zum Private Key des Clients)
    • tlsClCrtFile <clientcert> - (Pfad zum Client-Zertifikat)