Syslog-Server Docker Stack mit Webinterface für Log-Analyse

Dieser Artikel beschreibt den Aufbau eines containerisierten Syslog-Servers als Docker Stack mit Webinterface zur Log-Analyse. Das Setup basiert auf syslog-ng, einer MariaDB-Datenbank zur Speicherung der Logdaten und dem PHP-basierten LogAnalyzer als Weboberfläche. Zusätzlich sorgt ein Cleanup-Container für die automatische Datenbereinigung. Parallel zur Datenbank werden die Nachrichten in rotierende Logdateien geschrieben.
Ziel ist eine zentrale, leicht erweiterbare Logging-Plattform zur Erfassung, Auswertung und Visualisierung von Syslog-Nachrichten – z. B. von Netzwerkgeräten oder Smart-Home-Komponenten wie Shelly. Und das alles vereinfacht mithilfe von Docker-Containern, die als gemeinsames Docker-Compose-Projekt miteinander verbunden sind – für schnellen Einsatz, klare Struktur und einfache Wartung.
Voraussetzungen und Setup
Systemvoraussetzungen
Um den Syslog-Server Docker Stack mit Webinterface erfolgreich einzurichten, werden folgende Voraussetzungen benötigt:
- Ein 64-Bit-Linux-Server oder eine VM mit Docker und Docker Compose
- Empfohlen: mindestens 2 CPU-Kerne und 2 GB RAM; auch ein 64-Bit-Raspberry-Pi mit mindestens 2 GB RAM ist geeignet
- Netzwerkzugriff zwischen den Syslog-Quellen und dem Server, z. B. für Shelly-Geräte, Server und Netzwerkhardware
- Verfügbare Ports 514/UDP, 514/TCP und 8181/TCP; die Host-Ports sind konfigurierbar
- Internetzugang zum Herunterladen der Container-Images
Software-Voraussetzungen
- Docker ab Version 25
- Docker Compose als Plugin ab Version 2.20.2; verwendet wird der Befehl
docker compose - Optional: Git, um das Projekt aus dem Repository zu klonen
Projektstruktur (Überblick)
Das Projekt besteht aus mehreren Docker-Containern:
- syslogng: empfängt UDP/TCP-Syslog-Nachrichten und schreibt sie in die Datenbank sowie in Logdateien
- database: MariaDB speichert die Logs strukturiert in einer Datenbanktabelle
- loganalyzer: PHP-basierte Weboberfläche zur Analyse der Logs
- dbcleanup: Wartungscontainer zur regelmäßigen, zeitgesteuerten Datenbankbereinigung
Die Kommunikation erfolgt über ein gemeinsames Docker-Netzwerk und wird zentral über eine compose.yml gesteuert. Die drei Datenbank-Clients warten beim Start darauf, dass MariaDB ihren Healthcheck erfolgreich abgeschlossen hat.
Installation und Konfiguration
1. Projekt klonen oder bereitstellen
Falls du das Projekt aus dem Git-Repository beziehst:
cd /opt
git clone https://github.com/alaub81/syslogserver.git
cd syslogserver
Alternativ entpackst du die bereitgestellte ZIP-Datei in ein Verzeichnis auf deinem Server.
Die folgenden Befehle werden im Projektverzeichnis ausgeführt.
2. .env-Datei anpassen
Erstelle bei einer neuen Installation die Datei .env aus der mitgelieferten Vorlage:
cp .env.example .env
Bei einer bestehenden Installation bleibt die vorhandene .env erhalten. Ergänze neue Variablen anhand der aktuellen .env.example, ohne deine Zugangsdaten und bisherigen Einstellungen zu überschreiben.
Beispielinhalt für dauerhafte Logdateien und einen moderaten RAM-Verbrauch:
# Host UDP port for ordinary syslog and optional Shelly debug output.
# Example with a specific bind address: 192.168.1.10:514.
SYSLOG_UDP_PORT=514
# Host TCP port for ordinary syslog.
SYSLOG_TCP_PORT=514
# Host HTTP port for LogAnalyzer; no login is enabled by default.
LOGANALYZER_PORT=8181
# MariaDB root password, used when initializing a new database volume.
# Generate a unique value with: openssl rand -hex 32
DB_ROOT_PASSWORD=replace-with-a-generated-root-password
# Application account created in a new database.
DB_USER=syslog
# Application password shared by syslog-ng, LogAnalyzer and dbcleanup.
# Generate a separate value with: openssl rand -hex 32
# Changing this value does not update accounts in an existing database.
DB_PASSWORD=replace-with-a-generated-application-password
# Database initialized in a new volume.
DB_NAME=syslogdb
# Delete database messages whose ReceivedAt is older than this many days.
LOG_RETENTION_DAYS=7
# Cleanup schedule in TZ; five cron fields without a user field.
# Example: daily at 08:45.
DBCLEANUP_CRON="45 8 * * *"
# Maximum rows per deletion transaction; allowed range: 1..10000.
DBCLEANUP_BATCH_SIZE=1000
# Seconds to pause between full deletion batches.
DBCLEANUP_BATCH_PAUSE=0.1
# InnoDB buffer pool; not a limit on total MariaDB RAM.
DB_BUFFER_POOL_SIZE=256M
# Commit durability: 1 = durable; 2 can lose recent commits on power/OS failure.
DB_FLUSH_AT_COMMIT=1
# Persistent host directory or the named RAM volume "ramlogs".
# Standard: ./data/syslog-ng/logs; SD-saving RAM mode: ramlogs.
SYSLOG_LOG_STORAGE=./data/syslog-ng/logs
# RAM log volume ceiling; used only with SYSLOG_LOG_STORAGE=ramlogs.
# Changing the size requires recreating the RAM volume.
SYSLOG_LOG_RAM_SIZE=128m
# File rotation check schedule in TZ; standard: hourly.
# RAM mode example: "*/5 * * * *".
LOGROTATE_CRON="0 * * * *"
# Rotate files above this size when checked; not a hard size limit.
# Standard: 50M; RAM mode: 2M.
LOGROTATE_SIZE=50M
# Remove rotated files older than this many days when rotating.
LOGROTATE_MAX_AGE_DAYS=30
# Number of rotated archives retained per logfile.
# Standard: 7; RAM mode: 2.
LOGROTATE_ROTATIONS=7
# IANA timezone for containers, timestamps and cron schedules.
TZ=Europe/Berlin
Diese Datei enthält die zentralen Einstellungen für Ports, Datenbankzugang, Zeitzone, Aufbewahrungsdauer, Speicherort und Rotation.
Erzeuge für beide Passwortvariablen jeweils ein eigenes Passwort:
openssl rand -hex 32
Wichtig: Die Datenbankzugangsdaten werden beim ersten Start mit einem leeren Datenbank-Volume eingerichtet. Eine spätere Änderung in .env ändert keine bereits bestehenden MariaDB-Benutzer oder Passwörter.
Die früheren Variablen LOGANALYZER_VERSION und LOGANALYZER_URL gehören nicht mehr in die normale .env. Die Build-Vorgaben stehen im Dockerfile unter resources/loganalyzer/.
3. Erster Start
Mit vorgefertigten Images ausführen:
Führe folgenden Befehl im Projektverzeichnis aus, wenn du die veröffentlichten Images verwenden möchtest:
docker compose up -d --wait
Der Befehl lädt fehlende Images, erstellt die Container und startet den gesamten Stack im Hintergrund. Mit --wait wird auf den erfolgreichen Start einschließlich der konfigurierten Healthchecks gewartet. Die Produktionsdatei baut keine eigenen Images.
Lokal entwickeln und Images aus Dockerfiles erstellen:
Hierbei wird die eigenständige compose.dev.yml verwendet:
docker compose -f compose.dev.yml up -d --build --wait
Die Entwicklungsdatei enthält dieselben Laufzeiteinstellungen wie die Produktionsdatei und ergänzt die lokalen Builds. Weitere Compose-Dateien oder Build-Parameter sind für den normalen Start nicht erforderlich. In VS Code steht außerdem der Task compose:dev:up bereit.
Verwende für spätere Befehle dieselbe Compose-Datei und denselben Projektnamen. Bei einem Entwicklungsstack ersetzt du in den folgenden Beispielen docker compose durch docker compose -f compose.dev.yml.
4. Webinterface aufrufen
Öffne deinen Browser und rufe das LogAnalyzer-Interface auf:
http://<SERVER-IP>:8181
Falls du LOGANALYZER_PORT geändert hast, verwende den entsprechenden Port. Die Datenbankquelle ist bereits eingerichtet; ein Installationsassistent ist nicht erforderlich. Dort kannst du die Logdaten direkt durchsuchen und filtern.
Der Stack aktiviert standardmäßig keine Anmeldung für das Webinterface. Beschränke den Zugriff auf vertrauenswürdige Netze oder verwende einen vorgeschalteten Reverse Proxy mit Authentifizierung. Auch die Syslog-Ports sollten nur für die gewünschten Quellen erreichbar sein.
Konfiguration syslogng und Advanced-Funktionen
Ohne zusätzliche Aktivierung arbeitet der Stack als normaler Syslog-Server. Nachrichten werden in MariaDB und in die gemeinsame Datei /var/log/events.log geschrieben.
Shelly-Parsing, Reverse DNS und zusätzliche Diagnose-Dateien sind standardmäßig deaktiviert. Die Vorlagen liegen unter ./data/syslog-ng/config/ und enden auf .conf.disabled. Erst eine aktive Kopie mit der Endung .conf wird geladen.
Die aktiven Kopien sind Git-ignoriert. Aktiviere die gewünschten Funktionen deshalb auf jedem Server separat. Ein git pull aktualisiert die Vorlagen, überschreibt aber keine vorhandene aktive Konfiguration.
Die folgenden Kopierbefehle sind für die erstmalige Aktivierung gedacht. Überschreibe vorhandene, angepasste .conf-Dateien nicht ungeprüft.
Shelly-Unterstützung aktivieren
Shelly-Geräte senden ihre Debug-Ausgaben an denselben UDP-Port 514 wie normale Syslog-Quellen. Es ist kein zusätzlicher öffentlicher Port erforderlich.
Aktiviere den Shelly-Parser:
cp data/syslog-ng/config/20-shelly.conf.disabled data/syslog-ng/config/20-shelly.conf
Das Modul trennt auch mehrere NUL-getrennte Meldungen innerhalb eines UDP-Pakets und bereitet die Felder für Datenbank und Dateiausgabe auf.
Nach dem Übernehmen der Konfiguration erscheinen die Shelly-Meldungen:
- in MariaDB und damit im LogAnalyzer
- gemeinsam mit den übrigen Nachrichten in
/var/log/events.log
Eine zusätzliche shelly.log ist dafür nicht erforderlich.
Die Darstellung des Absenders wird in der aktiven 20-shelly.conf festgelegt:
@define shelly-host-mode "sender"
- sender: verwendet den Absendernamen beziehungsweise die Absender-IP. Dies ist die Vorgabe der Vorlage.
- device: verwendet die Shelly-Hardware-ID, beispielsweise
shellyplus1-aabbccddeeff. Das kann hilfreich sein, wenn NAT oder Docker Desktop unterschiedliche Geräte hinter derselben Absenderadresse zusammenfasst.
Für den zweiten Modus ändere die Zeile in:
@define shelly-host-mode "device"
Eine durch NAT verborgene ursprüngliche Absender-IP kann das Modul nicht wiederherstellen.
Reverse DNS und vollständige Hostnamen aktivieren
Standardmäßig bleiben Absender-IP-Adressen erhalten; zusätzliche DNS-Abfragen bei der Verarbeitung sind deaktiviert.
Wenn dein DNS-Server passende Rückwärtsauflösungen kennt, kannst du Reverse DNS aktivieren:
cp data/syslog-ng/config/11-dns.conf.disabled data/syslog-ng/config/11-dns.conf
Die Vorlage aktiviert:
options {
use_dns(yes);
use_fqdn(yes);
dns_cache(yes);
};
Voraussetzungen und Auswirkungen:
- Der Resolver im Container muss die Absender-IP auflösen können, beispielsweise über einen PTR-Eintrag im lokalen DNS.
- Für aufgelöste Shelly-Absender muss
shelly-host-mode "sender"eingestellt sein. Im Modusdevicebleibt die Hardware-ID maßgeblich. - Bereits in normalen Syslog-Nachrichten enthaltene Hostnamen werden weiterhin berücksichtigt.
- Nicht auflösbare Adressen bleiben als IP sichtbar.
- Die aufgelösten Namen werden für neue Einträge in MariaDB und
events.loggespeichert. Es handelt sich nicht nur um eine Anzeigeoption des Webinterfaces. - Vorhandene Datenbankeinträge und Logdateien werden nicht nachträglich umgeschrieben. Der eigentliche Nachrichtentext bleibt unverändert.
Die Auflösung einer Geräte-IP lässt sich beispielsweise so prüfen:
docker compose exec syslogng getent hosts 192.168.1.42
Ersetze die Beispieladresse durch die IP deines Geräts. Bei einem nicht erreichbaren DNS-Server können zusätzliche Wartezeiten entstehen; der DNS-Cache reduziert wiederholte Abfragen.
Separate Shelly-Logdatei aktivieren
Wenn du zusätzlich zu MariaDB und events.log eine eigene Datei ausschließlich für Shelly-Meldungen möchtest, aktiviere die Diagnose-Ausgabe:
cp data/syslog-ng/config/shelly-debug/30-debug.conf.disabled \
data/syslog-ng/config/shelly-debug/30-debug.conf
Voraussetzung ist die aktivierte Shelly-Unterstützung über 20-shelly.conf.
Die zusätzliche Datei heißt innerhalb des Containers:
/var/log/shelly.log
Der Unterordner shelly-debug/ wird nur vom aktiven Shelly-Modul eingebunden, weil die Diagnose-Ausgabe dessen Quellen und Parser benötigt.
Die Datei entsteht, sobald passende Nachrichten eintreffen. Nach dem Übernehmen der Konfiguration kannst du sie verfolgen:
docker compose exec syslogng tail -F /var/log/shelly.log
Ohne diese zusätzliche Aktivierung erscheinen Shelly-Meldungen weiterhin in MariaDB und events.log. Es entfällt lediglich die separate Kopie in shelly.log.
Raw-UDP-Diagnose aktivieren
Für die Fehlersuche kannst du eingehende UDP-Nachrichten vor dem Shelly-Parsing zusätzlich protokollieren:
cp data/syslog-ng/config/15-rawlog.conf.disabled data/syslog-ng/config/15-rawlog.conf
Die Ausgabe liegt innerhalb des Containers unter:
/var/log/raw-udp.log
Diese Diagnose funktioniert unabhängig vom Shelly-Modul. Sie erfasst UDP-Eingänge; die normale Verarbeitung in Datenbank und weiteren Dateiausgaben läuft unverändert weiter.
docker compose exec syslogng tail -F /var/log/raw-udp.log
Zusätzliche Diagnose-Dateien benötigen weiteren Platz und erzeugen zusätzliche Schreibzugriffe. Deaktiviere sie wieder, wenn sie nicht mehr benötigt werden.
Änderungen übernehmen oder Funktionen deaktivieren
Vor dem ersten Start genügt es, die gewünschten Vorlagen zu kopieren und anschließend den Stack normal zu starten:
docker compose up -d --wait
Bei einem laufenden Stack prüfst du zuerst die Syntax. Nur wenn diese Prüfung erfolgreich ist, wird neu geladen:
docker compose exec -T syslogng syslog-ng --syntax-only --no-caps && \
docker compose exec -T syslogng syslog-ng-ctl reload
Ein Image-Neubau ist für diese Konfigurationsänderungen nicht erforderlich.
Zum Deaktivieren benennst du ausschließlich die aktive Datei so um, dass sie nicht mehr auf .conf endet, oder entfernst diese aktive Kopie. Die mitgelieferte .disabled-Vorlage bleibt erhalten.
Beispiel für das Deaktivieren der zusätzlichen Shelly-Datei:
mv data/syslog-ng/config/shelly-debug/30-debug.conf \
data/syslog-ng/config/shelly-debug/30-debug.conf.local-disabled
docker compose exec -T syslogng syslog-ng --syntax-only --no-caps && \
docker compose exec -T syslogng syslog-ng-ctl reload
Dauerhafte Logdateien oder RAM-Speicherung
Alle genannten Logdateien liegen im Container unter /var/log/. Ob sie zusätzlich im Projektverzeichnis auf dem Host sichtbar sind, hängt von SYSLOG_LOG_STORAGE ab.
Standard: dauerhafte Dateien auf dem Host
Die normale Konfiguration verwendet folgende Werte in .env:
SYSLOG_LOG_STORAGE=./data/syslog-ng/logs
SYSLOG_LOG_RAM_SIZE=128m
LOGROTATE_CRON="0 * * * *"
LOGROTATE_SIZE=50M
LOGROTATE_MAX_AGE_DAYS=30
LOGROTATE_ROTATIONS=7
Damit findest du die Dateien auf dem Host unter:
./data/syslog-ng/logs/events.log: gemeinsame, normalisierte Nachrichten als JSON Lines./data/syslog-ng/logs/shelly.log: nur bei aktivierter Shelly-Diagnose./data/syslog-ng/logs/raw-udp.log: nur bei aktivierter Raw-UDP-Diagnose./data/syslog-ng/logs/rotated/: rotierte Dateien
Die Größenprüfung läuft stündlich. Dateien oberhalb von 50 MiB werden rotiert, und es werden bis zu sieben Archive pro Logdatei behalten. Die Größenangabe ist keine harte Obergrenze: Zwischen zwei Prüfungen können Dateien weiter wachsen.
Die Archive werden komprimiert; das neueste Archiv bleibt zunächst unkomprimiert. LOGROTATE_MAX_AGE_DAYS wird bei Rotationsläufen berücksichtigt und ist keine unabhängig laufende Löschfrist.
In diesem Modus ist SYSLOG_LOG_RAM_SIZE unbenutzt. Die Dateien bleiben bei einem Containerwechsel erhalten, weil sie in einem Host-Verzeichnis liegen.
Raspberry Pi: SD-schonende RAM-Variante
Wenn du die zusätzlichen Dateischreibzugriffe auf die SD-Karte vermeiden möchtest, kannst du folgende Werte wählen:
SYSLOG_LOG_STORAGE=ramlogs
SYSLOG_LOG_RAM_SIZE=128m
LOGROTATE_CRON="*/5 * * * *"
LOGROTATE_SIZE=2M
LOGROTATE_MAX_AGE_DAYS=30
LOGROTATE_ROTATIONS=2
Die Dateiausgabe verwendet dann ein temporäres RAM-Volume mit maximal 128 MiB. Die Rotation wird alle fünf Minuten geprüft, ab 2 MiB rotiert und auf zwei Archive pro Datei begrenzt.
In diesem Modus erscheinen die Logdateien nicht unter ./data/syslog-ng/logs/ auf dem Host. Du liest sie über den Container:
docker compose exec syslogng tail -F /var/log/events.log
docker compose exec syslogng df -h /var/log
Die 128 MiB sind eine Obergrenze für alle Dateien in diesem Volume zusammen und werden nicht vollständig im Voraus reserviert. Zusätzliche Diagnose-Dateien teilen sich diesen Platz.
RAM-Logs sind flüchtig: Wenn der letzte Container, der dieses Volume verwendet, stoppt, geht dessen Dateiinhalt verloren. MariaDB bleibt in ihrem separaten Datenbank-Volume dauerhaft gespeichert.
Bei hoher Nachrichtenrate können Dateien zwischen zwei Rotationsprüfungen wachsen und den verfügbaren Platz aufbrauchen. Der RAM-Modus reduziert außerdem nur diese Dateischreibzugriffe; MariaDB und die Docker-Betriebslogs schreiben weiterhin auf ihren jeweiligen Speicher.
Speicher- oder Rotationseinstellungen übernehmen
Nach Änderungen an den Speicher- oder Rotationseinstellungen in .env wird der Collector über Compose neu erstellt:
docker compose up -d --wait syslogng
Ein bloßes docker compose restart übernimmt keine geänderten Umgebungsvariablen.
Beim Wechsel zwischen Datei- und RAM-Modus werden vorhandene Dateien nicht automatisch kopiert. Sichere benötigte RAM-Dateien deshalb vor dem Stoppen, beispielsweise:
mkdir -p .local/logs/ram-snapshot
docker compose cp syslogng:/var/log/. .local/logs/ram-snapshot/
Vorhandene Host-Dateien bleiben beim Wechsel auf RAM erhalten. Die Datenbank und deren Aufbewahrungsdauer bleiben von der Wahl des Dateispeichers unabhängig.
Wenn du später nur die Größe eines bereits vorhandenen RAM-Volumes änderst, muss auch dieses temporäre Volume neu erstellt werden. Die Schritte dazu stehen in der Raspberry-Pi-Dokumentation. Das Datenbank-Volume dbdata wird dafür nicht gelöscht.
Hinweise für bestehende Installationen
Ältere Versionen verwendeten die Dateinamen 20-shellylog.conf und 90-rawlog.conf. Diese werden durch die aktuellen Vorlagen ersetzt. Benenne vorhandene alte aktive Dateien beispielsweise auf .conf.legacy um und übernimm benötigte Anpassungen in die aktuellen Konfigurationen.
Prüfe außerdem bei einer älteren aktiven 20-shelly.conf, ob die normalisierte Shelly-Route auch die gemeinsame Dateiausgabe enthält:
log {
source(s_shelly_frames);
shelly_normalize();
destination(d_mysql);
destination(d_events_file);
flags(flow-control);
};
Fehlt destination(d_events_file);, erscheinen Shelly-Meldungen zwar in MariaDB und LogAnalyzer, aber nicht in events.log. Ergänze die Zeile direkt hinter destination(d_mysql);, ohne deine übrigen Einstellungen zu überschreiben. Prüfe danach die Syntax und lade die Konfiguration neu.
Ein git pull allein behebt das bei einer bestehenden aktiven Kopie nicht, weil diese Datei bewusst lokal bleibt. Die zusätzliche Shelly-Diagnose ist auch nach dieser Korrektur nicht erforderlich.
Komponentenübersicht und Konfigurationsdateien
Das Projekt besteht aus mehreren spezialisierten Docker-Containern, die jeweils durch eigene Konfigurationsdateien gesteuert werden. Alle Komponenten sind im Docker-Compose-Verbund integriert und arbeiten über ein gemeinsames virtuelles Netzwerk zusammen.
syslog-ng (Syslog-Empfang und Parsing)
- Aufgabe: Empfängt UDP- und TCP-basierte Syslog-Nachrichten, verarbeitet sie und speichert sie in MariaDB sowie in Logdateien.
- Image:
ghcr.io/alaub81/syslogng:latest, eigenes Debian-basiertes Image - Ports: 514/UDP und 514/TCP, konfigurierbar über
.env - Konfigurationsdateien:
./data/syslog-ng/config/10-syslogsrv.conf: gemeinsame Listener, Standardparser und Datenbank-/Dateiziele./data/syslog-ng/config/11-dns.conf.disabled: Vorlage für optionale DNS-Auflösung./data/syslog-ng/config/15-rawlog.conf.disabled: Vorlage für die zusätzliche Raw-UDP-Datei./data/syslog-ng/config/20-shelly.conf.disabled: Vorlage für Shelly-Erkennung, Aufteilung und Parsing./data/syslog-ng/config/shelly-debug/30-debug.conf.disabled: Vorlage für die separate Shelly-Datei./data/syslog-ng/config/90-default.conf: Standard-Syslog-Routing und interne syslog-ng-Meldungen
- Besonderheiten:
- Strukturierte Feldzuweisung für MariaDB und JSON-Dateiausgabe
- Optionaler Parser für Shelly-Nachrichten
- Logrotate mit konfigurierbarer Größe, Aufbewahrung und Prüfung über Supercronic
- Gemeinsame Rotation für normale Logdateien und aktivierte Diagnose-Dateien
mariadb (Log-Datenbank)
- Compose-Service:
database - Aufgabe: Speichert die Logeinträge strukturiert in der Tabelle
SystemEvents. - Image: Offizielles
mariadb:13 - Port: 3306, nur innerhalb des Docker-Netzwerks
- Speicherung: dauerhaft im Volume
dbdata - Konfigurationsdateien:
./data/init.sql: erstellt beim ersten Start mit einem leeren Datenbank-Volume die benötigten Tabellen und Indizescompose.ymlund.env: Datenbankname, Benutzer, Passwörter und Laufzeiteinstellungen
- Datenstruktur:
- Tabelle
SystemEventsmit Feldern wie ReceivedAt, FromHost, Message und SysLogTag utf8mb4für Unicode-Nachrichten- Normale Indizes unter anderem auf Absender, Zeit, Facility und Priorität
- Kein zusätzlicher Volltextindex auf
Messagebei neuen Installationen, weil die mitgelieferte LogAnalyzer-Konfiguration über LIKE/REGEXP sucht
- Tabelle
Bestehende Datenbanken werden durch eine geänderte init.sql nicht nachträglich angepasst. Informationen zur optionalen Migration stehen in der Raspberry-Pi-Dokumentation.
loganalyzer (Webinterface)
- Aufgabe: PHP-basierte Webanwendung zur Durchsuchung und Darstellung der Logs.
- Image:
ghcr.io/alaub81/loganalyzer:latest - Image-Basis: eigener Dockerfile auf Basis von
php:8.5-apache; aktuell mit LogAnalyzer 5.0.2 im Projekt - Port: standardmäßig 8181 auf dem Host, konfigurierbar über
.env - Konfigurationsdateien:
./data/loganalyzer/config/config.php: zentrale Konfiguration der Weboberfläche und Datenbankquelle./resources/loganalyzer/apache-pi.conf: begrenzte Apache-Worker für moderaten RAM-Verbrauch./resources/loganalyzer/php-overrides.ini: PHP- und OPcache-Einstellungen.env: unter anderem HTTP-Port, Datenbankzugang und Zeitzone
- Besonderheiten: Such- und Filterfunktionen, verschiedene Ansichten und konfigurierbare Darstellung; Benutzeranmeldung ist in der ausgelieferten Konfiguration deaktiviert.
Version und Downloadquelle für lokale Builds stehen im Dockerfile unter resources/loganalyzer/, nicht in der normalen .env.
dbcleanup (Cleanup-Dienst für alte Logs)
- Aufgabe: Löscht regelmäßig veraltete Datenbankeinträge anhand von
ReceivedAt. - Image:
ghcr.io/alaub81/dbcleanup:latest, eigenes Debian-Image mitmariadb-clientundsupercronic - Zeitsteuerung: über Supercronic und den Zeitplan in
DBCLEANUP_CRON - Konfigurationsdateien:
./resources/dbcleanup/dbcleanup.sh: Cleanup-Skript; wird auch bei vorgefertigten Images aus dem Checkout eingebunden.env:LOG_RETENTION_DAYS,DBCLEANUP_CRON,DBCLEANUP_BATCH_SIZE,DBCLEANUP_BATCH_PAUSEundTZ
- Logging: Ausgaben und SQL-Fehler stehen in den Docker-Logs des Dienstes.
Die Bereinigung arbeitet in kleinen Transaktionen, standardmäßig mit bis zu 1.000 Zeilen pro Durchlauf und kurzen Pausen zwischen vollen Batches. Ein regelmäßiges OPTIMIZE TABLE gehört nicht mehr zum Cleanup; InnoDB kann freigewordenen Platz wiederverwenden.
Die Ausgaben kannst du so prüfen:
docker compose logs --tail=100 dbcleanup
Die Aufbewahrungsdauer in MariaDB und die Rotation der Logdateien sind getrennte Einstellungen.
docker-compose (Orchestrierung aller Komponenten)
- Datei:
compose.ymloder die eigenständigecompose.dev.yml - Aufgabe: Verbindet alle Container, Volumes, Netzwerke und Healthchecks.
- Konfigurierbar über:
.env - Startreihenfolge: syslog-ng, LogAnalyzer und dbcleanup warten auf eine gesunde Datenbank.
- Neustartverhalten: Die Dienste verwenden
restart: unless-stopped. Ein fehlgeschlagener Healthcheck allein startet einen Container allerdings nicht automatisch neu.
Betrieb auf dem Raspberry Pi
Die normalen Compose-Dateien enthalten bereits Einstellungen für moderaten RAM-Verbrauch und geringeren Verwaltungsaufwand. Eine zusätzliche Pi-Compose-Datei ist nicht erforderlich.
Dazu gehören:
- MariaDB-Buffer-Pool mit standardmäßig 256 MiB
- SQL-Transaktionen für bis zu 100 Nachrichten mit einem Batch-Timeout von einer Sekunde
- Begrenzte Apache-Worker und ein gemeinsamer PHP-OPcache
- Temporäre Arbeitsverzeichnisse in begrenzten tmpfs-Dateisystemen
- Begrenzte Docker-Betriebslogs mit drei Dateien à ungefähr 10 MiB pro Dienst
- Datenbankbereinigung in kleinen Batches statt regelmäßiger Tabellen-Rebuilds
Die normale Dateiprotokollierung bleibt trotzdem dauerhaft auf dem Host gespeichert. Erst SYSLOG_LOG_STORAGE=ramlogs aktiviert die oben beschriebene flüchtige RAM-Variante.
DB_FLUSH_AT_COMMIT=1 bleibt die Vorgabe für dauerhafte Datenbank-Commits. Der optionale Wert 2 reduziert Synchronisationsaufwand, kann bei Stromausfall oder Betriebssystemabsturz aber zum Verlust kürzlich bestätigter Transaktionen führen. Für den normalen Betrieb ist keine Änderung erforderlich.
Auch bei dauerhaften Datenbank-Commits können noch nicht geschriebene Nachrichten in RAM-Warteschlangen oder unbestätigten Batches bei einem Absturz verloren gehen. UDP bietet außerdem keine Zustellgarantie.
Die RAM-Variante macht den gesamten Stack nicht schreibfrei. Besonders bei vielen Nachrichten kann eine USB-SSD für das Datenbank-Volume sinnvoll sein. Weitere Einzelheiten zu RAM, Haltbarkeit und bestehenden Datenbanken stehen in der Raspberry-Pi-Dokumentation.
Hinweise zur Nutzung von LogAnalyzer
Nach dem Start kannst du die empfangenen Syslog-Meldungen im Webinterface durchsuchen, nach Absender und Schweregrad filtern und die Ansicht aktualisieren lassen. Die wichtigsten Felder:
- FromHost – Absender-IP, aufgelöster Hostname oder die gewählte Shelly-Hardware-ID
- Facility / Priority – Syslog-Kategorie und Schweregrad
- SysLogTag – Programm beziehungsweise zugewiesener Tag, z. B.
shelly-scriptoder ein erkannter Shelly-Programmname - Message – der eigentliche Log-Inhalt
- ReceivedAt – Empfangszeitpunkt
- DeviceReportedTime – gemeldeter Zeitpunkt; für Shelly-Debug-Ausgaben wird die Empfangszeit verwendet
- EventSource – bei passenden Shelly-Meldungen beispielsweise die erkannte Quelldatei mit Zeilennummer
- ProcessID – Prozess-ID, sofern vorhanden; eine Shelly-Quellcodezeile wird nicht als Prozess-ID interpretiert
Für die Fehlersuche helfen außerdem:
docker compose ps
docker compose logs --tail=100 syslogng database loganalyzer dbcleanup
docker compose exec syslogng syslog-ng-ctl stats
Ein gesunder Container allein bestätigt noch nicht die vollständige Zustellung von der Quelle bis zum Webinterface. Prüfe bei fehlenden Meldungen deshalb auch Netzwerkzugriff, aktivierte Module und mögliche SQL-Fehler.
Weiterführende Links
Hier findest du offizielle Ressourcen und Dokumentationen zu den eingesetzten Komponenten und Technologien:
GitHub Repository
- Syslogserver-Projekt auf GitHub
- README und Schnellstart
- Dokumentierte Umgebungsvariablen
- Konfiguration und Betrieb
- Raspberry-Pi- und Speicheroptimierungen
- Entwicklung und Dependency-Updates
Offizielle Projektseiten
- syslog-ng – Syslog-Server mit erweiterten Parsing-Funktionen
- MariaDB – Relationale Open-Source-Datenbank, MySQL-kompatibel
- LogAnalyzer – Webbasierte Analyse- und Darstellungsschicht für Syslog-Daten
Docker & Orchestrierung
- Docker Homepage
- Docker Compose Dokumentation
- Offizielles MariaDB Docker Image
- PHP Docker Image mit Apache
Tools und Hilfsmittel
- Supercronic – leichtgewichtiger Cron-Ersatz für Docker-Container
Weitere Ressourcen
- RFC 5424 – Syslog-Protokoll-Spezifikation, IETF
- rsyslog Dokumentation – falls du Vergleichswerte brauchst oder zu rsyslog wechseln möchtest
- Syslog im Freifunk-Wiki – Grundlagenartikel zu Syslog im deutschsprachigen Kontext