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 findest du sie unter /usr/share/doc/lxlogger/example.lxlogger.toml:

sudo cp /usr/share/doc/lxlogger/example.lxlogger.toml /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)

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

[[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

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 das Zielverzeichnis für Backup-Archive fest (siehe Backup).

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

Konfigurationen aus älteren Versionen mit einem [db]-Block werden beim Start automatisch in einen [[sinks]]-Eintrag übernommen (mit einem entsprechenden Hinweis im Log). Verwende für neue Konfigurationen direkt den [[sinks]]-Abschnitt – der [db]-Block wird in einer zukünftigen Version entfernt.