Andreas.O.Schmidt
7c61208741
initiale anlage Signed-off-by: Andreas.O.Schmidt <cert.a.o.schmidt@outlook.de>
138 lines
7.4 KiB
Markdown
138 lines
7.4 KiB
Markdown
# 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.
|
||
|
||
# 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.
|
||
|
||
|