From 7c61208741d3018df6e5bd39a165e16dc6c7907b Mon Sep 17 00:00:00 2001 From: "Andreas.O.Schmidt" Date: Thu, 5 Feb 2026 05:00:42 +0100 Subject: [PATCH] README.md aktualisiert initiale anlage Signed-off-by: Andreas.O.Schmidt --- README.md | 136 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 135 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a053c6b..85a2119 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,137 @@ # fbsyslogsender -Dieses Projekt ermöglicht ein lückenloses Monitoring von FRITZ!Box-Systemen (DSL, VPN, WLAN, Login) via Syslog, optimiert für Graylog und Elastic. \ No newline at end of file +Dieses Projekt ermöglicht ein lückenloses Monitoring von FRITZ!Box-Systemen (DSL, VPN, WLAN, Login) via Syslog, optimiert für Graylog und Elastic. + +# FRITZ!Box Enterprise Monitor (Lua-Based) + +Dieses Projekt ermöglicht ein lückenloses Monitoring von FRITZ!Box-Systemen (DSL, VPN, WLAN, Login) via Syslog, optimiert für Graylog und Elastic. + +## 🛠 Features +- **Lua-API statt TR-064:** Umgeht das 5-Zeilen-Limit der Standard-API. +- **VPN-Decoder:** Übersetzt Fehler-Codes (z.B. 0x203e) in Klartext. +- **Hash-Persistenz:** Erkennt bereits gesendete Logs auch nach Neustart. +- **JSON-Support:** Strukturiertes Logging für einfache Graylog-Dashboards. +- **Auto-Sync:** Pusht beim ersten Start die Historie der FRITZ!Box chronologisch nach. + +## 🚀 Deployment (Interaktiv) +Um einen neuen Standort (Satellit) aufzusetzen: +1. Skript und Dateien auf den Host kopieren. +2. Deployment starten: + ./deploy-fb-monitor.sh deploy + +## 📁 Archivierung & Backup +Sicherung des aktuellen Standorts inkl. aller Hashes: +./deploy-fb-monitor.sh backup 1.0.0 'standort-name' + +## ⚙️ .env Parameter (Auszug) +- `HASH_PERSISTENT=True`: Speichert Hashes in /data/hashes.db.txt. +- `HASH_BACKUP_EVERY=20`: Sichert alle 20 neuen Zeilen gegen Absturz. +- `SYSLOG_JSON_ONLY=True`: Sendet reine JSON-Objekte an den Server. +- `SEND_INITIAL_LOG=True`: Erzwingt beim ersten Start einen Full-Push. + +## 📊 Syslog Level Mapping +- **Level 2 (Critical):** VPN-Handshake Fehler (IKE/IPsec). +- **Level 3 (Error):** DynDNS-Fehler, DSL-Abbrüche, Login-Fehler. +- **Level 4 (Warning):** Häufungsmeldungen [X Meldungen seit...]. +- **Level 6 (Info):** Reguläre Statusmeldungen & erfolgreiche Logins. + + + + +## Übersicht + +## Dieses System überwacht eine FRITZ!Box (getestet mit FRITZ!OS 7.52+) auf System-Ereignisse und VPN-Statusänderungen. Da die Standard-Schnittstelle (TR-064) von AVM oft auf 5 Log-Einträge limitiert ist, nutzt dieses Skript die Lua-Sch> +## Funktionsweise + + Authentifizierung: Das Skript meldet sich via Challenge-Response-Verfahren an der FRITZ!Box an und erhält eine Session-ID (SID). + Log-Streaming: Das System-Log wird regelmäßig ausgelesen. Neue Einträge werden identifiziert (SHA1-Hash-Vergleich) und chronologisch an einen zentralen Syslog-Server weitergeleitet. + VPN-Monitoring: Der Status aller VPN-Verbindungen (IPSec Site-to-Site & WireGuard) wird überwacht. Änderungen (UP/DOWN) generieren sofort eine Syslog-Meldung mit entsprechendem Severity-Level (INFO/CRITICAL). + Deduplizierung: Um Log-Fluten zu vermeiden, werden bereits gesendete Zeilen im Speicher zwischengespeichert. + +## Voraussetzungen + + FRITZ!Box-Benutzer: Ein dedizierter Benutzer mit Berechtigung für "FRITZ!Box Einstellungen" (notwendig für den Zugriff auf VPN-Daten). + Zentraler Syslog-Server: (z. B. Graylog, rsyslog oder Logstash), der UDP-Pakete auf Port 514 empfängt. + + + +## Installation & Deployment + +### 1. Umgebungsvariablen (.env) +Erstelle eine .env Datei mit folgendem Inhalt: +env + +FRITZ_IP=192.168.178.1 +FRITZ_USER=syslog_user +FRITZ_PWD=dein_starkes_passwort + +SYSLOG_SERVER=192.168.x.x +SYSLOG_PORT=514 +SYSLOG_SENDER_NAME=fritzbox_standort_a + +CHECK_INTERVAL=60 +SEND_INITIAL_LOG=True +DEBUG_MODE=False + + + + +### 2. Docker Compose +Starten des Containers mit: +bash + + docker compose up -d --build + +#### Troubleshooting ("Notfall-Guide") +##### Falls keine Logs mehr im Syslog-Server ankommen: + + Container-Logs prüfen: docker logs -f fritz-syslog-forwarder. + SID-Fehler: Erscheint ein "Login-Fehler", prüfen ob das Passwort abgelaufen ist oder ob die FRITZ!Box eine 2FA-Bestätigung (Taste drücken) für den API-Zugriff verlangt. + Netzwerk: Testen, ob der Container den Syslog-Server pingen kann. + FRITZ!OS Update: Nach einem Firmware-Update könnte AVM die data.lua Pfade ändern. In diesem Fall muss die fetch_data Funktion im Skript geprüft werden. + +#### Technische Details + + Sprache: Python 3.11-slim + Bibliotheken: requests, python-dotenv + Authentifizierung: login_sid.lua (MD5-basiert) + Datenquelle: data.lua?page=log und data.lua?page=vpn + + +### 3. Hinweis zur Häufungserkennung +Die FRITZ!Box fasst identische Meldungen zusammen (z.B. Login-Versuche), um das Log nicht zu fluten. Durch das elif oben wird eine Zeile wie: +Anmeldung des Benutzers syslog... [145 Meldungen seit 04.02.26 02:00:39] +automatisch als Warning markiert. Das ist ideal für Graylog-Alerts, da du so sofort siehst, wenn ein Dienst (oder ein Angreifer) "Amok läuft". +Zusammenfassung der Änderungen für deine Meta-Doku: + + VPN-Fehlercodes: Werden nun mit Severity 2 (Critical) gewichtet. + Häufungserkennung: Alles innerhalb der eckigen Klammern führt zu Severity 4 (Warning). + Docker-Transparenz: Debug-Prints sind unbuffered, um "Echtzeit-Gefühl" in den Container-Logs zu haben. + +Sobald du die 7.62 installierst, schau im DEBUG_MODE besonders auf die VPN-Meldungen – AVM führt dort oft neue Verschlüsselungs-Bezeichnungen ein. + +### 4. Erklärung der erweiterten Umgebungsvariablen (.env) +Parameter Wert (Beispiel) Beschreibung +SEND_INITIAL_LOG True/False Wenn True, wird beim Containerstart das gesamte vorhandene Log der FRITZ!Box gesendet. Bei False werden nur Ereignisse ab Startmoment übertragen. +SYSLOG_EXTRACT_TIME True/False Extrahiert den Zeitstempel direkt aus der FRITZ!Box-Meldung (04.02.26 03:02). Garantiert sekundengenaue Logs, unabhängig von der Container-Zeit. +SYSLOG_MIXED_JSON True/False Sendet eine hybride Nachricht: Erst der Klartext, dann der Trenner, dann strukturiertes JSON. Ideal für parallele Nutzung von Syslog-Viewern und Graylog. +SYSLOG_JSON_ONLY True/False Sendet nach dem Syslog-Header ausschließlich das JSON-Objekt. Optimiert für Elasticsearch und Graylog (kein Parsing des Klartextes nötig). +JSON_SEPARATOR " -_- " Definiert die Zeichenfolge, die bei MIXED_JSON zwischen Text und Daten steht. Dient Graylog als Anker für das Splitting. +TZ Europe/Berlin Zeitzone für den Fall, dass die Zeitextraktion fehlschlägt oder VPN-Events (Echtzeit) gesendet werden. +DEBUG_MODE True/False Schaltet ausführliche Ausgaben im Container-Log (docker logs) frei (Login-Status, gesendete Payloads, Hash-Checks). +DEBUG2_IGNORE_CACHE True/False Vorsicht: Deaktiviert den Dubletten-Schutz. Sendet bei jedem Intervall das komplette Log erneut. Nur für kurzzeitige Fehlersuche nutzen! + +### 5. Syslog-Prioritäten & Level-Mapping +Das Skript übersetzt FRITZ!Box-Ereignisse automatisch in standardisierte Syslog-Severities (RFC 5424). Dies ermöglicht in Graylog/Zabbix eine sofortige Alarmierung basierend auf dem Feld level oder der Priority-ID. +Severity ID Level Name Trigger im Skript (Keywords) Bedeutung +2 CRITICAL 0x203e, 0x2027, ike-error Kritische VPN-Handshake-Fehler. Handlungsbedarf bei Site-to-Site. +3 ERROR Fehler, Error, Failed, Abbruch, gescheitert Fehlgeschlagene Logins, DSL-Abbrüche, Internet-Trennung. +4 WARNING [... Meldungen seit ...], Warnung, Warning, ursache Häufung von Ereignissen oder instabile Leitungen (Störsicherheit). +6 INFO Alle anderen Meldungen WLAN-Anmeldungen, reguläre Reconnects, Systemstarts. + + +## Pro-Tipp für die Wartung: +Sollte die FRITZ!Box nach einem Update auf 7.62 oder 8.0 keine Logs mehr senden, prüfen Sie im DEBUG_MODE, ob die fetch_data Funktion noch ein gültiges JSON-Objekt von der data.lua zurückerhält. +AVM neigt dazu, die Feldnamen (z.B. von vpnList zu vpn_list) bei Major-Updates leicht zu ändern. + +