Konfigurationsdatei

Für den Betrieb des LxLogger wird eine Konfigurationsdatei im TOML-Format benötigt. Sie enthält im Wesentlichen die Angaben zu deinem Loxone Miniserver und genau ein Ausgabeziel (Sink) – die Datenbank, in die geschrieben wird.

Anlegen der Konfiguration

Lege die Konfiguration auf Basis der mitgelieferten, vollständig kommentierten Vorlage an. Bei der Linux-Paketinstallation (deb/rpm) liegt sie direkt neben der Konfiguration unter /etc/lxlogger/lxlogger.toml.example:

sudo cp /etc/lxlogger/lxlogger.toml.example /etc/lxlogger/lxlogger.toml
sudo nano /etc/lxlogger/lxlogger.toml

LxLogger sucht die Konfigurationsdatei in dieser Reihenfolge:

1. der mit --config <pfad> angegebene Pfad
2. $HOME/.lxlogger.toml
3. ./.lxlogger.toml (aktuelles Verzeichnis)
4. /etc/lxlogger/lxlogger.toml (üblich beim Dienstbetrieb)
5. /usr/lib/lxlogger/.lxlogger.toml (Pfad aus Version 1.1.x, veraltet – mit Hinweis im Log)

Jeder Wert lässt sich zusätzlich über eine Umgebungsvariable LXL_<SEKTION>_<KEY> überschreiben (z. B. LXL_MINISERVER_HOST=192.168.1.77).

Beispiel

Eine minimale Konfiguration besteht aus [miniserver] und genau einem [[sinks]]-Eintrag:

[miniserver]
host     = "192.168.1.77"   # Hostname oder IP des Miniservers
# port   = 80               # HTTP-Port (Default: 80)
username = "lxlogger"       # Login-Benutzer
password = "CHANGE-ME"      # Login-Passwort
# timezone = "Europe/Berlin" # Zeitzone des Miniservers für den Import (Default: Zeitzone des Hosts)

[[sinks]]
kind   = "influxdb_v2"
url    = "http://localhost:8086"   # Basis-URL des InfluxDB-v2-Servers
org    = "mein-haus"               # Organisation
bucket = "lxlogger"                # Ziel-Bucket
token  = "CHANGE-ME-TOKEN"         # API-Token

Zeitzone des Miniservers

Der Miniserver speichert seine Statistiken in Ortszeit, ohne Angabe der Zeitzone. Mit timezone legst du fest, in welcher Zeitzone der Datenimport sie liest:

[miniserver]
timezone = "Europe/Berlin"

• Wert: ein IANA-Name, z. B. Europe/Berlin, Europe/Vienna oder Europe/Zurich. Ein unbekannter Name ist ein Konfigurationsfehler.
• Umgebungsvariable: LXL_MINISERVER_TIMEZONE. Sie hat Vorrang vor dem Wert in der Datei.
• Standard: die Zeitzone des Systems, auf dem der LxLogger läuft. Das Docker-Image setzt LXL_MINISERVER_TIMEZONE=Europe/Berlin.

Die Zeitzonendaten sind im LxLogger enthalten. Die Option funktioniert deshalb auch unter Windows und im Docker-Image. Das laufende Logging betrifft sie nicht.

Das Ausgabeziel ([[sinks]])

Der Sink legt fest, wohin die Daten geschrieben werden. Er besteht aus einem kind-Tag plus den Feldern, die dieses kind benötigt. Es ist genau ein Sink erlaubt – ein zweiter [[sinks]]-Eintrag führt zu einem Konfigurationsfehler.

InfluxDB v2 (empfohlen)

[[sinks]]
kind   = "influxdb_v2"
url    = "http://localhost:8086"
org    = "mein-haus"
bucket = "lxlogger"
token  = "CHANGE-ME-TOKEN"
# admin_token = "CHANGE-ME-ADMIN"  # optional: legt den Bucket an, falls er noch nicht existiert

InfluxDB v1.8

[[sinks]]
kind     = "influxdb_v1"
url      = "http://localhost:8086"
username = "admin"        # optional (v1.8 läuft oft ohne Authentifizierung)
password = "CHANGE-ME"    # optional

Der Datenbankname wird nicht konfiguriert, sondern automatisch aus der Seriennummer deines Miniservers abgeleitet (lxlogger_<seriennummer>) und beim Start angelegt.

Geheimnisse (Passwörter & Tokens)

Passwörter und API-Tokens müssen nicht im Klartext in der Konfigurationsdatei stehen. LxLogger löst jedes Geheimnis in dieser Reihenfolge auf:

1. Umgebungsvariable (z. B. LXL_MINISERVER_PASSWORD)
2. Umgebungsvariable mit _FILE-Suffix (Pfad zu einer Datei mit dem Wert – ideal für als Datei gemountete Docker-/Kubernetes-Secrets)
3. OS-Schlüsselbund (macOS Schlüsselbund / Windows-Anmeldeinformationsverwaltung / Linux Secret Service)
4. die Konfigurationsdatei (Klartext)

Den OS-Schlüsselbund verwaltest du mit dem Befehl secret:

# Geheimnis interaktiv (ohne Anzeige) hinterlegen
lxlogger secret set miniserver.password

# zeigt je Geheimnis die Quelle an – nie den Wert selbst
lxlogger secret list

Stabile Schlüssel sind u. a. miniserver.password, influxdb_v1.password, influxdb_v2.token und influxdb_v2.admin_token.

Headless-Betrieb / Docker

Auf einem Server ohne angemeldete Sitzung (z. B. systemd-Dienst oder Container) steht kein Schlüsselbund zur Verfügung. Nutze dort die _FILE-Variante, z. B. LXL_SINK_INFLUXDB_V2_TOKEN_FILE=/run/secrets/influx_token.

Konfiguration prüfen

Vor dem ersten Start kannst du die Konfiguration und die Erreichbarkeit des Miniservers prüfen:

lxlogger check --config /etc/lxlogger/lxlogger.toml

Der Befehl gibt strukturiert ✓/✗ aus und beendet sich mit Code 0, wenn alles in Ordnung ist – sonst mit 1.

Weitere Abschnitte

Die folgenden Abschnitte sind optional und in der mitgelieferten Vorlage ausführlich kommentiert:

• [wal] – justiert den lokalen Crash-Puffer (Write-Ahead-Log), der jedes Event zwischenpuffert, bevor es in die Datenbank geschrieben wird. Alle Werte haben sinnvolle Standardwerte; eine Anpassung ist im Normalfall nicht nötig.
• [backup] – legt mit dest das Zielverzeichnis für Backup-Archive fest (siehe Backup). Mit ftps = true wird das Backup verschlüsselt übertragen, ftps_server_name überschreibt bei Bedarf den Namen für die Prüfung des Zertifikats (siehe Verschlüsselte Übertragung (FTPS)).

Messwert-Namensänderung

Über den optionalen Abschnitt [grafana] kannst du den Namen der einzelnen Statistiken (das Measurement) selbst bestimmen. Dazu dient der Wert msmntNameTmpl. Wird keine eigene Formatierung festgelegt, wird nur der reine Name der Statistik verwendet.

[grafana]
msmntNameTmpl = "[$r|$c] $n.$s"

Folgende Variablen stehen zur Verfügung:

Variable	Beschreibung
$n	Der Name der Statistik.
$r	Der Raum, der dem Sensor/Gerät in der Loxone Config zugewiesen wurde.
$c	Die Kategorie, die dem Sensor/Gerät in der Loxone Config zugewiesen wurde.
$s	Der Status des verwendeten Geräts. Am Beispiel einer Intelligenten Raumregelung sind zum Beispiel die folgenden Werte möglich: tempActual, tempTarget, usw. Trennzeichen wie der Punkt werden dabei automatisch gekürzt.

Pflichtangaben im Template

Das Template muss mindestens $n und $s enthalten, sonst wird es als Konfigurationsfehler abgewiesen.

Beispiel

Für einen Temperatursensor mit dem Namen Temperatur in der Kategorie Klima im Raum Badezimmer würde das obige Template die Werte unter dem folgenden Measurement bereitstellen:

[Badezimmer|Klima] Temperatur

Ohne eigene Angabe wären die Werte unter dem Namen

Temperatur

zu finden.

Achtung

Wird der Wert msmntNameTmpl im Nachhinein geändert, bleiben die bereits geloggten Werte unter dem alten Namen innerhalb von Grafana bestehen und müssen manuell über die Datenbank mit den neuen Werten zusammengeführt werden!

Hinweis zum bisherigen [db]-Block

Ab v1.2.1 werden Konfigurationen aus Version 1.1.x mit einem [db]-Block beim Start automatisch in einen [[sinks]]-Eintrag übersetzt. Im Log erscheint dazu ein Hinweis mit dem passenden [[sinks]]-Block. Verwende für neue Konfigurationen direkt den [[sinks]]-Abschnitt – der [db]-Block wird in einer zukünftigen Version entfernt. Mehr zum Umstieg unter Von 1.1.x auf 1.2.x umsteigen.