update: Konfigurationsdatei aufräumen – Kommentare gekürzt, Verweis auf Doku ergänzt, fehlende Variable EXTERNAL_WHITELIST_CACHE_DIR hinzugefügt

adguard-shield.conf

@@ -1,271 +1,102 @@
 ###############################################################################
 # AdGuard Shield - Konfigurationsdatei
-# Schutz vor übermäßigen DNS-Anfragen einzelner Clients
+# Ausführliche Dokumentation: docs/konfiguration.md
 ###############################################################################
 
-# --- AdGuard Home API Einstellungen ---
-# URL der AdGuard Home Web-Oberfläche (ohne trailing slash)
+# --- AdGuard Home API ---
 ADGUARD_URL="https://dns1.domain.com"
-
-# AdGuard Home Zugangsdaten (Web-UI Login)
 ADGUARD_USER="admin"
 ADGUARD_PASS='changeme'
 
-# --- Rate-Limit Einstellungen ---
-# Maximale Anfragen pro Domain pro Client innerhalb des Zeitfensters
-RATE_LIMIT_MAX_REQUESTS=30
+# --- Rate-Limit ---
+RATE_LIMIT_MAX_REQUESTS=30          # Max. Anfragen pro Domain/Client im Zeitfenster
+RATE_LIMIT_WINDOW=60                # Zeitfenster in Sekunden
+CHECK_INTERVAL=10                   # Prüfintervall in Sekunden
 
-# Zeitfenster in Sekunden (60 = 1 Minute)
-RATE_LIMIT_WINDOW=60
-
-# Wie oft das Script die Logs prüft (in Sekunden)
-CHECK_INTERVAL=10
-
-# --- Subdomain-Flood-Erkennung (Random Subdomain Attack) ---
-# Erkennt Bots/Clients die massenhaft zufällige Subdomains einer Domain abfragen
-# Beispiel: abc123.microsoft.com, xyz456.microsoft.com, ...
-# Dabei wird pro Client gezählt, wie viele EINDEUTIGE Subdomains einer
-# Basisdomain (z.B. microsoft.com) im Zeitfenster aufgerufen werden.
-
-# Subdomain-Flood-Erkennung aktivieren
+# --- Subdomain-Flood-Erkennung ---
 SUBDOMAIN_FLOOD_ENABLED=true
-
-# Maximale Anzahl eindeutiger Subdomains pro Basisdomain pro Client im Zeitfenster
-# Beispiel: 50 = ein Client darf max. 50 verschiedene Subdomains von microsoft.com abfragen
-SUBDOMAIN_FLOOD_MAX_UNIQUE=50
-
-# Zeitfenster in Sekunden für die Subdomain-Flood-Erkennung (60 = 1 Minute)
-SUBDOMAIN_FLOOD_WINDOW=60
+SUBDOMAIN_FLOOD_MAX_UNIQUE=50       # Max. eindeutige Subdomains pro Basisdomain/Client
+SUBDOMAIN_FLOOD_WINDOW=60           # Zeitfenster in Sekunden
 
 # --- Sperr-Einstellungen ---
-# Wie lange ein Client gesperrt wird (in Sekunden, 3600 = 1 Stunde)
-BAN_DURATION=3600
-
-# iptables Chain-Name für die Sperren
+BAN_DURATION=3600                   # Basis-Sperrdauer in Sekunden
 IPTABLES_CHAIN="ADGUARD_SHIELD"
-
-# Welche Ports gesperrt werden sollen (IPv4 + IPv6)
-# Port 53  = DNS (UDP + TCP)
-# Port 443 = DNS-over-HTTPS (DoH)
-# Port 853 = DNS-over-TLS (tls://...:853) / DNS-over-QUIC (quic://...:853)
-# Hinweis: Das verwendete Protokoll (DNS/DoH/DoT/DoQ) wird automatisch
-# aus der AdGuard Home API erkannt und in Logs/History angezeigt.
-BLOCKED_PORTS="53 443 853"
+BLOCKED_PORTS="53 443 853"         # DNS(53), DoH(443), DoT/DoQ(853)
 
 # --- Whitelist ---
-# IP-Adressen die NIEMALS gesperrt werden (kommagetrennt)
-# Lokale Netze und wichtige Server hier eintragen
+# IPs die niemals gesperrt werden (kommagetrennt)
 WHITELIST="127.0.0.1,::1"
 
 # --- Logging ---
-# Log-Datei Pfad
 LOG_FILE="/var/log/adguard-shield.log"
-
-# Log-Level: DEBUG, INFO, WARN, ERROR
-LOG_LEVEL="INFO"
-
-# Maximale Größe der Log-Datei in MB (danach wird rotiert)
-LOG_MAX_SIZE_MB=50
-
-# Ban-History Datei (protokolliert alle Sperren & Entsperrungen dauerhaft)
+LOG_LEVEL="INFO"                    # DEBUG, INFO, WARN, ERROR
+LOG_MAX_SIZE_MB=50                  # Max. Größe in MB (danach Rotation)
 BAN_HISTORY_FILE="/var/log/adguard-shield-bans.log"
+BAN_HISTORY_RETENTION_DAYS=0        # 0 = unbegrenzt
 
-# Maximale Aufbewahrungsdauer der Ban-History in Tagen
-# 0 = unbegrenzt (niemals automatisch löschen)
-# Beispiel: 90 = Einträge älter als 90 Tage werden beim nächsten Report entfernt
-BAN_HISTORY_RETENTION_DAYS=0
-
-# --- Benachrichtigungen (optional) ---
-# Aktiviert Benachrichtigungen bei Sperren/Entsperrungen
+# --- Benachrichtigungen ---
 NOTIFY_ENABLED=false
+NOTIFY_TYPE="ntfy"                  # ntfy, discord, slack, gotify, generic
+NOTIFY_WEBHOOK_URL=""               # Webhook-URL (nicht für ntfy)
 
-# Benachrichtigungs-Typ: "ntfy", "discord", "slack", "gotify", "generic"
-NOTIFY_TYPE="ntfy"
-
-# Webhook-URL (nur für discord, slack, gotify, generic – bei ntfy nicht nötig)
-# Discord: https://discord.com/api/webhooks/xxx/yyy
-# Gotify:  https://gotify.example.com/message?token=xxx
-NOTIFY_WEBHOOK_URL=""
-
-# --- Ntfy Einstellungen (nur bei NOTIFY_TYPE="ntfy") ---
-# Server-URL der Ntfy-Instanz (ohne trailing slash)
+# Ntfy-Einstellungen (nur bei NOTIFY_TYPE="ntfy")
 NTFY_SERVER_URL="https://ntfy.sh"
-
-# Topic-Name für die Benachrichtigungen
 NTFY_TOPIC=""
-
-# Optionaler Access-Token (leer lassen wenn nicht benötigt)
 NTFY_TOKEN=""
+NTFY_PRIORITY="4"                   # 1=min, 3=default, 5=max
 
-# Priorität der Ntfy-Nachrichten (1=min, 3=default, 5=max)
-NTFY_PRIORITY="4"
-
-# --- E-Mail Report (optional) ---
-# Regelmäßiger Statistik-Report per E-Mail
-# Voraussetzung: Ein funktionierender Mail-Transport (z.B. msmtp)
-# Anleitung für msmtp: https://www.cleveradmin.de/blog/2024/12/linux-einfach-emails-versenden-mit-msmtp/
+# --- E-Mail Report ---
 REPORT_ENABLED=false
-
-# Report-Intervall: "daily", "weekly", "biweekly", "monthly"
-# daily    = täglich um die konfigurierte Uhrzeit
-# weekly   = wöchentlich am Montag
-# biweekly = alle zwei Wochen am Montag
-# monthly  = monatlich am 1. des Monats
-REPORT_INTERVAL="weekly"
-
-# Uhrzeit für den Report-Versand (Format: HH:MM, 24h)
+REPORT_INTERVAL="weekly"            # daily, weekly, biweekly, monthly
 REPORT_TIME="08:00"
-
-# E-Mail-Empfänger
 REPORT_EMAIL_TO="admin@example.com"
-
-# E-Mail-Absender
 REPORT_EMAIL_FROM="adguard-shield@example.com"
-
-# E-Mail-Format: "html" oder "txt"
-REPORT_FORMAT="html"
-
-# Mail-Befehl (z.B. "msmtp", "sendmail", "mail")
+REPORT_FORMAT="html"                # html, txt
 REPORT_MAIL_CMD="msmtp"
+REPORT_BUSIEST_DAY_RANGE=30         # Tage für "Aktivster Tag" (0 = nur Berichtszeitraum)
 
-# Zeitraum für "Aktivster Tag" im Report (in Tagen)
-# Bestimmt, über wie viele Tage zurück der aktivste Tag ermittelt wird.
-# 30 = Aktivster Tag der letzten 30 Tage (empfohlen)
-# 0  = Nur innerhalb des Berichtszeitraums (altes Verhalten)
-REPORT_BUSIEST_DAY_RANGE=30
-
-# --- Externe Whitelist (optional) ---
-# Ermöglicht das Einbinden externer Whitelist-Dateien mit Domains/IPs.
-# Domains werden regelmäßig per DNS aufgelöst (ideal für dynamische IPs/DynDNS).
+# --- Externe Whitelist ---
+# Externe Whitelist-Dateien mit Domains/IPs; Domains werden per DNS aufgelöst
 EXTERNAL_WHITELIST_ENABLED=false
+EXTERNAL_WHITELIST_URLS=""          # URL(s) kommagetrennt
+EXTERNAL_WHITELIST_INTERVAL=300     # Prüfintervall in Sekunden
+EXTERNAL_WHITELIST_CACHE_DIR="/var/lib/adguard-shield/external-whitelist"
 
-# URL(s) zu externen Textdateien mit Domains/IPs (eine pro Zeile)
-# Mehrere URLs kommagetrennt angeben
-# Beispiel: "https://example.com/whitelist.txt,https://other.com/trusted-hosts.txt"
-EXTERNAL_WHITELIST_URLS=""
-
-# Wie oft die externe Whitelist geprüft und Domains neu aufgelöst werden (in Sekunden, 300 = 5 Minuten)
-# Kürzere Intervalle empfohlen bei vielen DynDNS-Einträgen
-EXTERNAL_WHITELIST_INTERVAL=300
-
-# --- Externe Blocklist (optional) ---
-# Aktiviert den externen Blocklist-Worker
+# --- Externe Blocklist ---
 EXTERNAL_BLOCKLIST_ENABLED=false
-
-# URL(s) zu externen Textdateien mit IP-Adressen (eine IP pro Zeile)
-# Mehrere URLs kommagetrennt angeben
-# Beispiel: "https://example.com/blocklist.txt,https://other.com/bad-ips.txt"
-EXTERNAL_BLOCKLIST_URLS=""
-
-# Wie oft die externe Blocklist geprüft wird (in Sekunden, 300 = 5 Minuten)
-EXTERNAL_BLOCKLIST_INTERVAL=300
-
-# Sperrdauer für externe Blocklist-IPs in Sekunden (0 = permanent bis IP aus Liste entfernt)
-EXTERNAL_BLOCKLIST_BAN_DURATION=0
-
-# Automatisch IPs entsperren die aus der externen Liste entfernt wurden?
+EXTERNAL_BLOCKLIST_URLS=""          # URL(s) kommagetrennt
+EXTERNAL_BLOCKLIST_INTERVAL=300     # Prüfintervall in Sekunden
+EXTERNAL_BLOCKLIST_BAN_DURATION=0   # 0 = permanent bis IP aus Liste entfernt
 EXTERNAL_BLOCKLIST_AUTO_UNBAN=true
-
-# Benachrichtigungen bei Blocklist-Sperren senden?
-# Bei Listen mit vielen IPs empfiehlt sich false, da sonst beim Sync
-# hunderte Benachrichtigungen auf einmal verschickt werden.
-EXTERNAL_BLOCKLIST_NOTIFY=false
-
-# Lokaler Cache-Pfad für die heruntergeladene Blocklist
+EXTERNAL_BLOCKLIST_NOTIFY=false     # Bei großen Listen auf false lassen
 EXTERNAL_BLOCKLIST_CACHE_DIR="/var/lib/adguard-shield/external-blocklist"
 
 # --- Progressive Sperren (Recidive) ---
-# Wiederholungstäter werden stufenweise länger gesperrt (wie bei fail2ban)
-# Aktiviert das progressive Sperrsystem
+# Wiederholungstäter werden stufenweise länger gesperrt
 PROGRESSIVE_BAN_ENABLED=true
+PROGRESSIVE_BAN_MULTIPLIER=2        # Multiplikator pro Stufe (2 = Verdopplung)
+PROGRESSIVE_BAN_MAX_LEVEL=5         # Ab dieser Stufe permanent sperren (0 = nie)
+PROGRESSIVE_BAN_RESET_AFTER=86400   # Zähler-Reset nach X Sekunden ohne Vergehen
 
-# Multiplikator pro Wiederholung (2 = Verdopplung der Sperrdauer)
-# Stufe 1: BAN_DURATION × 1 (Standard-Sperrdauer)
-# Stufe 2: BAN_DURATION × 2
-# Stufe 3: BAN_DURATION × 4
-# Stufe 4: BAN_DURATION × 8 ... usw.
-PROGRESSIVE_BAN_MULTIPLIER=2
-
-# Ab dieser Stufe wird die IP permanent gesperrt (0 = nie permanent sperren)
-# Beispiel: 5 = nach dem 5. Vergehen wird die IP dauerhaft gesperrt
-PROGRESSIVE_BAN_MAX_LEVEL=5
-
-# Nach wie vielen Sekunden ohne erneutes Vergehen wird der Zähler zurückgesetzt
-# (86400 = 24 Stunden, 604800 = 7 Tage)
-PROGRESSIVE_BAN_RESET_AFTER=86400
-
-# --- AbuseIPDB Reporting (optional) ---
-# Meldet permanent gesperrte IPs automatisch an AbuseIPDB
-# Nur bei PERMANENTEN Sperren wird ein Report gesendet.
+# --- AbuseIPDB Reporting ---
+# Meldet nur permanent gesperrte IPs an AbuseIPDB
 ABUSEIPDB_ENABLED=false
-
-# AbuseIPDB API-Key (https://www.abuseipdb.com/account/api)
 ABUSEIPDB_API_KEY=""
+ABUSEIPDB_CATEGORIES="4"            # 4 = DDoS Attack (siehe abuseipdb.com/categories)
 
-# Kategorien für den Report (kommagetrennt)
-# 4 = DDoS Attack
-# Siehe: https://www.abuseipdb.com/categories
-ABUSEIPDB_CATEGORIES="4"
-
-# --- GeoIP-basierte Länderfilter (optional) ---
-# Sperrt oder erlaubt DNS-Anfragen basierend auf dem Herkunftsland der Client-IP.
-# Alle Lookups erfolgen LOKAL über eine Datenbank – es werden keine Online-API-Calls gemacht.
-#
-# Einfachster Weg (empfohlen):
-#   sudo apt install geoip-bin geoip-database
-#   → Damit funktioniert GeoIP sofort, ohne Account oder API-Key.
-#
-# Für genauere/aktuellere Daten (optional):
-#   Kostenlosen MaxMind-Account erstellen (https://www.maxmind.com/en/geolite2/signup)
-#   und License-Key unter GEOIP_LICENSE_KEY eintragen. Die GeoLite2-Datenbank
-#   wird dann automatisch heruntergeladen und alle 24 Stunden aktualisiert.
-#   Alternativ kann ein bereits vorhandener DB-Pfad über GEOIP_MMDB_PATH angegeben werden.
+# --- GeoIP-basierte Länderfilter ---
+# Sperrt/erlaubt DNS-Anfragen nach Herkunftsland (lokale DB, keine Online-API)
 GEOIP_ENABLED=false
-
-# Modus: "blocklist" = nur gelistete Länder sperren
-#         "allowlist" = nur gelistete Länder erlauben (alle anderen werden gesperrt)
-GEOIP_MODE="blocklist"
-
-# Kommagetrennte Liste von ISO 3166-1 Alpha-2 Ländercodes
-# Blocklist-Modus: Diese Länder werden gesperrt
-# Allowlist-Modus: NUR diese Länder werden erlaubt (Rest wird gesperrt)
-# Beispiel: "CN,RU,KP,IR" oder "DE,AT,CH"
-GEOIP_COUNTRIES=""
-
-# Wie oft die GeoIP-Prüfung durchgeführt wird (in Sekunden, 0 = bei jedem Check-Intervall)
-# Empfohlen: Gleicher Wert wie CHECK_INTERVAL oder höher
-GEOIP_CHECK_INTERVAL=0
-
-# Benachrichtigungen bei GeoIP-Sperren senden?
+GEOIP_MODE="blocklist"              # blocklist oder allowlist
+GEOIP_COUNTRIES=""                   # ISO 3166-1 Alpha-2 Codes, z.B. "CN,RU,KP,IR"
+GEOIP_CHECK_INTERVAL=0              # 0 = nutzt CHECK_INTERVAL
 GEOIP_NOTIFY=true
-
-# Lokale IPs und private Netze von GeoIP-Prüfung ausnehmen (empfohlen: true)
-GEOIP_SKIP_PRIVATE=true
-
-# MaxMind GeoLite2 License-Key (optional, für automatischen Download & Update)
-# Kostenloser Account: https://www.maxmind.com/en/geolite2/signup
-# License-Key erstellen: Account → Manage License Keys → Generate New License Key
-# Wenn gesetzt, wird die GeoLite2-Country-Datenbank automatisch heruntergeladen
-# und alle 24 Stunden aktualisiert. Die DB wird lokal gespeichert unter:
-#   <INSTALL_DIR>/geoip/GeoLite2-Country.mmdb
-GEOIP_LICENSE_KEY=""
-
-# Pfad zur MaxMind GeoLite2 .mmdb-Datenbank (optional)
-# Wenn leer UND GEOIP_LICENSE_KEY gesetzt → automatischer Download (s.o.)
-# Wenn leer UND GEOIP_LICENSE_KEY leer → Fallback auf geoiplookup (apt install geoip-bin)
-# Wenn gesetzt → diese Datei wird direkt verwendet (kein automatischer Download)
-# Beispiel: "/usr/share/GeoIP/GeoLite2-Country.mmdb"
-GEOIP_MMDB_PATH=""
+GEOIP_SKIP_PRIVATE=true             # Private IPs ausnehmen
+GEOIP_LICENSE_KEY=""                 # MaxMind GeoLite2 Key (optional, für Auto-Download)
+GEOIP_MMDB_PATH=""                   # Manueller DB-Pfad (optional, hat Vorrang)
 
 # --- Erweiterte Einstellungen ---
-# Pfad zur State-Datei (speichert aktive Sperren)
 STATE_DIR="/var/lib/adguard-shield"
-
-# Pfad zum PID-File
 PID_FILE="/var/run/adguard-shield.pid"
-
-# Anzahl der API-Einträge die pro Abfrage geholt werden (max 5000)
-API_QUERY_LIMIT=500
-
-# Dry-Run Modus: true = nur loggen, nicht sperren (zum Testen)
-DRY_RUN=false
+API_QUERY_LIMIT=500                 # API-Einträge pro Abfrage (max 5000)
+DRY_RUN=false                       # true = nur loggen, nicht sperren