feat: GeoIP-Länderfilter mit MaxMind Auto-Download

2026-04-14 20:30:37 +02:00
parent 4d7e053ce7
commit 3d60771a1b
9 changed files with 1231 additions and 3 deletions
--- a/README.md
+++ b/README.md
@@ -30,6 +30,7 @@ Wenn ein Client eine bestimmte Domain zu oft anfragt (z.B. >30x pro Minute), wir
 - Automatisches Entsperren nach konfigurierbarer Dauer
 - **Externe Blocklisten** — IP-Adressen von externen Textdateien (URLs) laden und automatisch sperren
 - **Externe Whitelisten** — Domains/IPs aus externen Listen laden und automatisch whitelisten (ideal für DynDNS)
+- **GeoIP-Länderfilter** — Länder sperren oder erlauben (Blocklist/Allowlist), mit automatischem MaxMind-DB-Download
 - **AbuseIPDB Reporting** — permanent gesperrte IPs automatisch an AbuseIPDB melden
 - **E-Mail Reports** — periodische Statistik-Reports als HTML oder TXT (täglich, wöchentlich, zweiwöchentlich, monatlich)
 - **Ban-History** — lückenlose Protokollierung aller Sperren/Entsperrungen mit Zeitstempel
@@ -94,6 +95,9 @@ sudo /opt/adguard-shield/adguard-shield.sh blocklist-status   # Externe Blocklis
 sudo /opt/adguard-shield/adguard-shield.sh blocklist-sync     # Blocklisten manuell synchronisieren
 sudo /opt/adguard-shield/adguard-shield.sh whitelist-status   # Externe Whitelisten Status
 sudo /opt/adguard-shield/adguard-shield.sh whitelist-sync     # Whitelisten manuell synchronisieren
+sudo /opt/adguard-shield/adguard-shield.sh geoip-status       # GeoIP-Status anzeigen
+sudo /opt/adguard-shield/adguard-shield.sh geoip-sync         # GeoIP einmalig prüfen
+sudo /opt/adguard-shield/adguard-shield.sh geoip-lookup IP    # GeoIP-Lookup einer IP
 sudo /opt/adguard-shield/report-generator.sh send                # Report jetzt senden
 sudo /opt/adguard-shield/report-generator.sh status              # Report-Status anzeigen
 sudo /opt/adguard-shield/report-generator.sh install             # Cron-Job einrichten
--- a/adguard-shield.conf
+++ b/adguard-shield.conf
@@ -207,6 +207,56 @@ ABUSEIPDB_API_KEY=""
 # 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_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_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=""
+
 # --- Erweiterte Einstellungen ---
 # Pfad zur State-Datei (speichert aktive Sperren)
 STATE_DIR="/var/lib/adguard-shield"
--- a/adguard-shield.sh
+++ b/adguard-shield.sh
@@ -330,6 +330,7 @@ cleanup() {
    fi
    stop_blocklist_worker
    stop_whitelist_worker
+    stop_geoip_worker
    rm -f "$PID_FILE"
    exit 0
 }
@@ -987,6 +988,17 @@ show_status() {
        echo ""
    fi

+    # GeoIP-Filter Info
+    if [[ "${GEOIP_ENABLED:-false}" == "true" ]]; then
+        local geoip_mode_label
+        [[ "${GEOIP_MODE:-blocklist}" == "blocklist" ]] && geoip_mode_label="Blocklist" || geoip_mode_label="Allowlist"
+        echo "  🌍 GeoIP-Filter: AKTIV"
+        echo "     Modus: ${geoip_mode_label}"
+        echo "     Länder: ${GEOIP_COUNTRIES:-<keine>}"
+        echo "     Sperrdauer: PERMANENT (Auto-Unban bei Änderung der Länderliste)"
+        echo ""
+    fi
+
    # Aktive Sperren
    local ban_count=0
    if [[ -d "$STATE_DIR" ]]; then
@@ -1212,6 +1224,39 @@ stop_whitelist_worker() {
    fi
 }

+# ─── GeoIP-Worker starten ────────────────────────────────────────────────────
+start_geoip_worker() {
+    if [[ "${GEOIP_ENABLED:-false}" != "true" ]]; then
+        log "DEBUG" "GeoIP-Worker ist deaktiviert"
+        return
+    fi
+
+    local worker_script="${SCRIPT_DIR}/geoip-worker.sh"
+    if [[ ! -f "$worker_script" ]]; then
+        log "WARN" "GeoIP-Worker Script nicht gefunden: $worker_script"
+        return
+    fi
+
+    log "INFO" "Starte GeoIP-Worker im Hintergrund..."
+    bash "$worker_script" start &
+    GEOIP_WORKER_PID=$!
+    log "INFO" "GeoIP-Worker gestartet (PID: $GEOIP_WORKER_PID)"
+}
+
+# ─── GeoIP-Worker stoppen ────────────────────────────────────────────────────
+stop_geoip_worker() {
+    local worker_pid_file="/var/run/adguard-geoip-worker.pid"
+    if [[ -f "$worker_pid_file" ]]; then
+        local wpid
+        wpid=$(cat "$worker_pid_file")
+        if kill -0 "$wpid" 2>/dev/null; then
+            log "INFO" "Stoppe GeoIP-Worker (PID: $wpid)..."
+            kill "$wpid" 2>/dev/null || true
+            rm -f "$worker_pid_file"
+        fi
+    fi
+}
+
 # ─── Hauptschleife ──────────────────────────────────────────────────────────
 main_loop() {
    log "INFO" "═══════════════════════════════════════════════════════════"
@@ -1238,6 +1283,11 @@ main_loop() {
    else
        log "INFO" "  AbuseIPDB Reporting: deaktiviert"
    fi
+    if [[ "${GEOIP_ENABLED:-false}" == "true" ]]; then
+        log "INFO" "  GeoIP-Filter: AKTIV (Modus: ${GEOIP_MODE:-blocklist}, Länder: ${GEOIP_COUNTRIES:-<keine>})"
+    else
+        log "INFO" "  GeoIP-Filter: deaktiviert"
+    fi
    log "INFO" "═══════════════════════════════════════════════════════════"

    # Service-Start-Benachrichtigung senden
@@ -1251,6 +1301,9 @@ main_loop() {
    # Whitelist-Worker als Hintergrundprozess starten
    start_whitelist_worker

+    # GeoIP-Worker als Hintergrundprozess starten
+    start_geoip_worker
+
    while true; do
        # Abgelaufene Sperren prüfen
        check_expired_bans
@@ -1344,6 +1397,47 @@ case "${1:-start}" in
            echo "Whitelist-Worker nicht gefunden"
        fi
        ;;
+    geoip-status)
+        init_directories
+        _worker_script="${SCRIPT_DIR}/geoip-worker.sh"
+        if [[ -f "$_worker_script" ]]; then
+            bash "$_worker_script" status
+        else
+            echo "GeoIP-Worker nicht gefunden"
+        fi
+        ;;
+    geoip-sync)
+        init_directories
+        setup_iptables_chain
+        _worker_script="${SCRIPT_DIR}/geoip-worker.sh"
+        if [[ -f "$_worker_script" ]]; then
+            bash "$_worker_script" sync
+        else
+            echo "GeoIP-Worker nicht gefunden"
+        fi
+        ;;
+    geoip-flush)
+        init_directories
+        _worker_script="${SCRIPT_DIR}/geoip-worker.sh"
+        if [[ -f "$_worker_script" ]]; then
+            bash "$_worker_script" flush
+        else
+            echo "GeoIP-Worker nicht gefunden"
+        fi
+        ;;
+    geoip-lookup)
+        if [[ -z "${2:-}" ]]; then
+            echo "Nutzung: $0 geoip-lookup <IP-Adresse>" >&2
+            exit 1
+        fi
+        init_directories
+        _worker_script="${SCRIPT_DIR}/geoip-worker.sh"
+        if [[ -f "$_worker_script" ]]; then
+            bash "$_worker_script" lookup "$2"
+        else
+            echo "GeoIP-Worker nicht gefunden"
+        fi
+        ;;
    status)
        init_directories
        show_status
@@ -1407,7 +1501,7 @@ Service-Steuerung (empfohlen):
  sudo systemctl restart adguard-shield
  sudo systemctl status adguard-shield

-Nutzung: $0 {status|history|flush|unban|reset-offenses|test|dry-run|blocklist-status|blocklist-sync|blocklist-flush|whitelist-status|whitelist-sync|whitelist-flush}
+Nutzung: $0 {status|history|flush|unban|reset-offenses|test|dry-run|blocklist-status|blocklist-sync|blocklist-flush|whitelist-status|whitelist-sync|whitelist-flush|geoip-status|geoip-sync|geoip-flush|geoip-lookup}

 Verwaltungsbefehle:
  status             Zeigt aktive Sperren, Regeln und Wiederholungstäter
@@ -1423,6 +1517,10 @@ Verwaltungsbefehle:
  whitelist-status   Zeigt Status der externen Whitelisten
  whitelist-sync     Einmalige Synchronisation der externen Whitelisten
  whitelist-flush    Entfernt alle aufgelösten Whitelist-IPs
+  geoip-status       Zeigt Status der GeoIP-Länderfilter
+  geoip-sync         Einmalige GeoIP-Prüfung aller aktiven Clients
+  geoip-flush        Alle GeoIP-Sperren aufheben
+  geoip-lookup IP    GeoIP-Lookup für eine einzelne IP-Adresse

 Interne Befehle (nicht direkt verwenden — nur über systemd):
  start              Startet den Monitor im Vordergrund
--- a/docs/architektur.md
+++ b/docs/architektur.md
@@ -136,7 +136,9 @@ Das ermöglicht:
 ├── iptables-helper.sh             # iptables Verwaltung
 ├── external-blocklist-worker.sh   # Externer Blocklist-Worker
 ├── external-whitelist-worker.sh   # Externer Whitelist-Worker (DNS-Auflösung)
-└── unban-expired.sh               # Cron-basiertes Entsperren
+├── geoip-worker.sh                # GeoIP-Länderfilter-Worker
+├── unban-expired.sh               # Cron-basiertes Entsperren
+└── geoip/                         # Auto-Download MaxMind GeoLite2 DB (optional)

 /etc/systemd/system/
 ├── adguard-shield.service         # systemd Service (Autostart aktiv)
@@ -147,7 +149,8 @@ Das ermöglicht:
 ├── *.ban                          # State-Dateien aktiver Sperren
 ├── *.offenses                     # Offense-Zähler (Progressive Sperren)
 ├── external-blocklist/            # Cache für externe Blocklisten
-└── external-whitelist/            # Cache für externe Whitelisten + aufgelöste IPs
+├── external-whitelist/            # Cache für externe Whitelisten + aufgelöste IPs
+└── geoip-cache/                   # Cache für GeoIP-Lookups (24h)

 /var/log/
 ├── adguard-shield.log             # Laufzeit-Log
--- a/docs/befehle.md
+++ b/docs/befehle.md
@@ -239,6 +239,49 @@ sudo /opt/adguard-shield/external-blocklist-worker.sh status
 sudo /opt/adguard-shield/external-blocklist-worker.sh flush
 ```

+## GeoIP-Worker (Länderfilter)
+
+Der GeoIP-Worker prüft Client-IPs auf ihr Herkunftsland und sperrt/erlaubt sie basierend auf der Konfiguration:
+
+```bash
+# GeoIP-Status anzeigen (Modus, Länder, aktive Sperren, verfügbare Tools)
+sudo /opt/adguard-shield/adguard-shield.sh geoip-status
+
+# Einmalige GeoIP-Prüfung aller aktiven Clients
+sudo /opt/adguard-shield/adguard-shield.sh geoip-sync
+
+# Alle GeoIP-Sperren aufheben
+sudo /opt/adguard-shield/adguard-shield.sh geoip-flush
+
+# GeoIP-Lookup für eine einzelne IP
+sudo /opt/adguard-shield/adguard-shield.sh geoip-lookup 8.8.8.8
+```
+
+Der Worker kann auch standalone gesteuert werden:
+
+```bash
+# Worker manuell starten (normalerweise automatisch per Hauptscript)
+sudo /opt/adguard-shield/geoip-worker.sh start
+
+# Worker stoppen
+sudo /opt/adguard-shield/geoip-worker.sh stop
+
+# Einmalige Synchronisation
+sudo /opt/adguard-shield/geoip-worker.sh sync
+
+# Status anzeigen
+sudo /opt/adguard-shield/geoip-worker.sh status
+
+# IP nachschlagen
+sudo /opt/adguard-shield/geoip-worker.sh lookup 1.2.3.4
+
+# Alle GeoIP-Sperren aufheben
+sudo /opt/adguard-shield/geoip-worker.sh flush
+
+# GeoIP-Lookup-Cache leeren
+sudo /opt/adguard-shield/geoip-worker.sh flush-cache
+```
+
 ## E-Mail Report

 ```bash
--- a/docs/konfiguration.md
+++ b/docs/konfiguration.md
@@ -255,6 +255,93 @@ Der Report an AbuseIPDB enthält (auf Englisch):
 - **Bei Subdomain-Flood:** `DNS flooding on our DNS server: 85x *.microsoft.com in 60s (random subdomain attack). Banned by Adguard Shield 🔗 https://tnvs.de/as`

 Die Kategorie `4` (DDoS Attack) wird standardmäßig verwendet. Weitere Kategorien können kommagetrennt angegeben werden (z.B. `"4,15"`).
+
+### GeoIP-basierte Länderfilter
+
+Ermöglicht das Sperren oder Erlauben von DNS-Anfragen basierend auf dem Herkunftsland der Client-IP. Unterstützt zwei Modi:
+
+- **Blocklist-Modus:** Nur die gelisteten Länder werden gesperrt (alle anderen erlaubt)
+- **Allowlist-Modus:** Nur die gelisteten Länder werden erlaubt (alle anderen gesperrt)
+
+| Parameter | Standard | Beschreibung |
+|-----------|----------|--------------|
+| `GEOIP_ENABLED` | `false` | GeoIP-Filter aktivieren |
+| `GEOIP_MODE` | `blocklist` | Modus: `blocklist` oder `allowlist` |
+| `GEOIP_COUNTRIES` | *(leer)* | ISO 3166-1 Alpha-2 Ländercodes (kommagetrennt), z.B. `CN,RU,KP,IR` |
+| `GEOIP_CHECK_INTERVAL` | `0` | Prüfintervall in Sekunden (`0` = nutzt `CHECK_INTERVAL`) |
+| `GEOIP_NOTIFY` | `true` | Benachrichtigungen bei GeoIP-Sperren senden |
+| `GEOIP_SKIP_PRIVATE` | `true` | Private/lokale IPs von der GeoIP-Prüfung ausnehmen |
+| `GEOIP_LICENSE_KEY` | *(leer)* | MaxMind License-Key für automatischen DB-Download (kostenlos) |
+| `GEOIP_MMDB_PATH` | *(leer)* | Manueller Pfad zur MaxMind GeoLite2 Datenbank (überschreibt Auto-Download) |
+
+#### Voraussetzungen
+
+Es muss mindestens eines der folgenden GeoIP-Tools installiert sein:
+
+1. **Automatischer MaxMind-Download** (empfohlen):
+   ```bash
+   # Kostenlosen Account erstellen: https://www.maxmind.com/en/geolite2/signup
+   # License-Key generieren und in adguard-shield.conf eintragen:
+   GEOIP_LICENSE_KEY="dein_license_key_hier"
+   ```
+   Die GeoLite2-Country-Datenbank wird automatisch heruntergeladen und alle 24 Stunden aktualisiert.
+   Es wird zusätzlich `mmdbinspect` oder `mmdblookup` benötigt:
+   ```bash
+   sudo apt install mmdb-bin    # für mmdblookup
+   ```
+
+2. **geoiplookup** (einfachster Einstieg, weniger genau):
+   ```bash
+   sudo apt install geoip-bin geoip-database
+   ```
+
+3. **Manueller MaxMind-Pfad** (eigene Datenbank):
+   ```bash
+   # mmdbinspect oder mmdblookup installieren
+   # Datenbank manuell herunterladen: https://dev.maxmind.com/geoip/geolite2-free-geolocation-data
+   GEOIP_MMDB_PATH="/usr/share/GeoIP/GeoLite2-Country.mmdb"
+   ```
+
+> **Priorität:** `GEOIP_MMDB_PATH` (manuell) → Auto-Download-DB → `geoiplookup` (Legacy-Fallback)
+
+#### Beispiel: Bestimmte Länder sperren (Blocklist)
+
+```bash
+GEOIP_ENABLED=true
+GEOIP_MODE="blocklist"
+GEOIP_COUNTRIES="CN,RU,KP,IR"
+GEOIP_LICENSE_KEY="dein_maxmind_license_key"   # optional, für Auto-Download
+```
+
+→ Alle Anfragen aus China, Russland, Nordkorea und Iran werden permanent gesperrt.
+
+#### Beispiel: Nur bestimmte Länder erlauben (Allowlist)
+
+```bash
+GEOIP_ENABLED=true
+GEOIP_MODE="allowlist"
+GEOIP_COUNTRIES="DE,AT,CH"
+```
+
+→ Nur Anfragen aus Deutschland, Österreich und der Schweiz werden erlaubt. Alle anderen Länder werden gesperrt.
+
+> **Hinweis:** Private IP-Adressen (10.x.x.x, 192.168.x.x, etc.) und Whitelist-IPs werden niemals durch GeoIP gesperrt. GeoIP-Sperren sind **immer permanent**.
+
+> **Auto-Unban:** Wird ein Land aus `GEOIP_COUNTRIES` entfernt oder der Modus (`GEOIP_MODE`) geändert, werden die nicht mehr zutreffenden Sperren beim nächsten Sync **automatisch aufgehoben**. Dasselbe gilt, wenn GeoIP komplett deaktiviert wird (`GEOIP_ENABLED=false`).
+
+> **Tipp:** GeoIP-Lookups werden für 24 Stunden gecacht. Mit `geoip-flush-cache` kann der Cache manuell geleert werden.
+
+> **Auto-Download:** Ist `GEOIP_LICENSE_KEY` gesetzt, wird die GeoLite2-Country-Datenbank automatisch nach `<INSTALL_DIR>/geoip/` heruntergeladen und alle 24 Stunden aktualisiert. Bei einem Update wird der Download im Hintergrund durchgeführt — der Worker läuft während des Downloads normal weiter. Ein manuell gesetzter `GEOIP_MMDB_PATH` hat immer Vorrang vor der automatisch heruntergeladenen Datenbank.
+
+#### GeoIP-Befehle
+
+| Befehl | Beschreibung |
+|--------|--------------|
+| `adguard-shield.sh geoip-status` | Zeigt GeoIP-Status, aktive Sperren und verfügbare Tools |
+| `adguard-shield.sh geoip-sync` | Einmalige GeoIP-Prüfung aller aktiven Clients |
+| `adguard-shield.sh geoip-flush` | Alle GeoIP-Sperren aufheben |
+| `adguard-shield.sh geoip-lookup <IP>` | GeoIP-Lookup einer einzelnen IP-Adresse |
+
 #### Externe Blocklist einrichten

 1. Erstelle eine Textdatei auf einem Webserver. Pro Zeile ein Eintrag — IPv4, IPv6, CIDR oder Hostname:
--- a/geoip-worker.sh
+++ b/geoip-worker.sh
@@ -0,0 +1,932 @@
+#!/bin/bash
+###############################################################################
+# AdGuard Shield - GeoIP Worker
+# Prüft Client-IPs auf Herkunftsland und sperrt/erlaubt basierend auf Konfig.
+# Wird als Hintergrundprozess vom Hauptscript gestartet.
+#
+# Autor:   Patrick Asmus
+# E-Mail:  support@techniverse.net
+# Lizenz:  MIT
+###############################################################################
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CONFIG_FILE="${SCRIPT_DIR}/adguard-shield.conf"
+
+# ─── Konfiguration laden ───────────────────────────────────────────────────────
+if [[ ! -f "$CONFIG_FILE" ]]; then
+    echo "FEHLER: Konfigurationsdatei nicht gefunden: $CONFIG_FILE" >&2
+    exit 1
+fi
+# shellcheck source=adguard-shield.conf
+source "$CONFIG_FILE"
+
+# ─── Worker PID-File ──────────────────────────────────────────────────────────
+WORKER_PID_FILE="/var/run/adguard-geoip-worker.pid"
+
+# ─── GeoIP Cache ──────────────────────────────────────────────────────────────
+GEOIP_CACHE_DIR="${STATE_DIR}/geoip-cache"
+
+# ─── MaxMind Auto-Download Verzeichnis ────────────────────────────────────────
+GEOIP_DB_DIR="${SCRIPT_DIR}/geoip"
+GEOIP_AUTO_DB="${GEOIP_DB_DIR}/GeoLite2-Country.mmdb"
+GEOIP_DB_UPDATE_INTERVAL=86400  # 24 Stunden (fest)
+
+# ─── Logging (eigene Funktion, nutzt gleiche Log-Datei) ───────────────────────
+declare -A LOG_LEVELS=([DEBUG]=0 [INFO]=1 [WARN]=2 [ERROR]=3)
+
+log() {
+    local level="$1"
+    shift
+    local message="$*"
+    local configured_level="${LOG_LEVEL:-INFO}"
+
+    if [[ ${LOG_LEVELS[$level]:-1} -ge ${LOG_LEVELS[$configured_level]:-1} ]]; then
+        local timestamp
+        timestamp="$(date '+%Y-%m-%d %H:%M:%S')"
+        local log_entry="[$timestamp] [$level] [GEOIP-WORKER] $message"
+        echo "$log_entry" | tee -a "$LOG_FILE" >&2
+    fi
+}
+
+# ─── Ban-History ─────────────────────────────────────────────────────────────
+log_ban_history() {
+    local action="$1"
+    local client_ip="$2"
+    local country="${3:-}"
+    local reason="${4:-geoip}"
+    local timestamp
+    timestamp="$(date '+%Y-%m-%d %H:%M:%S')"
+
+    if [[ ! -f "$BAN_HISTORY_FILE" ]]; then
+        echo "# AdGuard Shield - Ban History" > "$BAN_HISTORY_FILE"
+        echo "# Format: ZEITSTEMPEL | AKTION | CLIENT-IP | DOMAIN | ANFRAGEN | SPERRDAUER | PROTOKOLL | GRUND" >> "$BAN_HISTORY_FILE"
+        echo "#──────────────────────────────────────────────────────────────────────────────────────────────────" >> "$BAN_HISTORY_FILE"
+    fi
+
+    local duration="permanent"
+
+    printf "%-19s | %-6s | %-39s | %-30s | %-8s | %-10s | %-10s | %s\n" \
+        "$timestamp" "$action" "$client_ip" "Land: ${country:-?}" "-" "$duration" "-" "$reason" \
+        >> "$BAN_HISTORY_FILE"
+}
+
+# ─── Verzeichnisse erstellen ──────────────────────────────────────────────────
+init_directories() {
+    mkdir -p "$GEOIP_CACHE_DIR"
+    mkdir -p "$GEOIP_DB_DIR"
+    mkdir -p "$STATE_DIR"
+    mkdir -p "$(dirname "$LOG_FILE")"
+}
+
+# ─── Private IP-Adressen erkennen ────────────────────────────────────────────
+is_private_ip() {
+    local ip="$1"
+
+    # IPv6 Loopback und Link-Local
+    if [[ "$ip" == "::1" || "$ip" == fe80:* || "$ip" == fc00:* || "$ip" == fd00:* ]]; then
+        return 0
+    fi
+
+    # IPv4 private Bereiche
+    if [[ "$ip" =~ ^10\. || "$ip" =~ ^172\.(1[6-9]|2[0-9]|3[0-1])\. || "$ip" =~ ^192\.168\. || "$ip" =~ ^127\. || "$ip" == "0.0.0.0" ]]; then
+        return 0
+    fi
+
+    # IPv4 CGNAT
+    if [[ "$ip" =~ ^100\.(6[4-9]|[7-9][0-9]|1[0-1][0-9]|12[0-7])\. ]]; then
+        return 0
+    fi
+
+    return 1
+}
+
+# ─── Whitelist Prüfung ───────────────────────────────────────────────────────
+is_whitelisted() {
+    local ip="$1"
+    IFS=',' read -ra wl_entries <<< "$WHITELIST"
+    for entry in "${wl_entries[@]}"; do
+        entry=$(echo "$entry" | xargs)  # trim
+        if [[ "$ip" == "$entry" ]]; then
+            return 0
+        fi
+    done
+
+    # Externe Whitelist prüfen
+    local ext_wl_file="${EXTERNAL_WHITELIST_CACHE_DIR:-/var/lib/adguard-shield/external-whitelist}/resolved_ips.txt"
+    if [[ -f "$ext_wl_file" ]] && grep -qxF "$ip" "$ext_wl_file" 2>/dev/null; then
+        return 0
+    fi
+
+    return 1
+}
+
+# ─── MaxMind GeoLite2 Auto-Download & Update ─────────────────────────────────
+# Lädt die GeoLite2-Country.mmdb herunter, wenn GEOIP_LICENSE_KEY gesetzt ist
+# und kein eigener GEOIP_MMDB_PATH angegeben wurde.
+# Aktualisiert automatisch alle 24 Stunden.
+update_maxmind_db() {
+    local license_key="${GEOIP_LICENSE_KEY:-}"
+
+    # Kein License-Key → nichts zu tun
+    if [[ -z "$license_key" ]]; then
+        return 0
+    fi
+
+    # User hat eigenen Pfad gesetzt → kein Auto-Download
+    if [[ -n "${GEOIP_MMDB_PATH:-}" ]]; then
+        return 0
+    fi
+
+    # Prüfen ob Update nötig (alle 24h)
+    if [[ -f "$GEOIP_AUTO_DB" ]]; then
+        local db_age
+        db_age=$(( $(date '+%s') - $(stat -c '%Y' "$GEOIP_AUTO_DB" 2>/dev/null || stat -f '%m' "$GEOIP_AUTO_DB" 2>/dev/null || echo "0") ))
+        if [[ "$db_age" -lt "$GEOIP_DB_UPDATE_INTERVAL" ]]; then
+            log "DEBUG" "MaxMind DB ist aktuell (Alter: $((db_age / 3600))h, nächstes Update in $(( (GEOIP_DB_UPDATE_INTERVAL - db_age) / 3600 ))h)"
+            return 0
+        fi
+        log "INFO" "MaxMind DB ist älter als 24h – starte Update..."
+    else
+        log "INFO" "MaxMind DB nicht vorhanden – starte Erstdownload..."
+    fi
+
+    # Download-URL zusammenbauen (MaxMind Permalink)
+    local download_url="https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-Country&license_key=${license_key}&suffix=tar.gz"
+    local tmp_file="${GEOIP_DB_DIR}/GeoLite2-Country.tar.gz"
+    local tmp_extract="${GEOIP_DB_DIR}/extract_tmp"
+
+    # Herunterladen
+    local http_code
+    http_code=$(curl -s -o "$tmp_file" -w "%{http_code}" \
+        --connect-timeout 10 \
+        --max-time 60 \
+        "$download_url" 2>/dev/null) || true
+
+    if [[ "$http_code" != "200" ]]; then
+        rm -f "$tmp_file"
+        case "$http_code" in
+            401) log "ERROR" "MaxMind Download fehlgeschlagen: Ungültiger License-Key (HTTP 401)" ;;
+            403) log "ERROR" "MaxMind Download fehlgeschlagen: Zugriff verweigert (HTTP 403) – License-Key prüfen" ;;
+            *)   log "ERROR" "MaxMind Download fehlgeschlagen (HTTP ${http_code:-timeout})" ;;
+        esac
+        return 1
+    fi
+
+    # Entpacken
+    rm -rf "$tmp_extract"
+    mkdir -p "$tmp_extract"
+
+    if ! tar -xzf "$tmp_file" -C "$tmp_extract" 2>/dev/null; then
+        log "ERROR" "MaxMind DB: tar-Archiv konnte nicht entpackt werden"
+        rm -f "$tmp_file"
+        rm -rf "$tmp_extract"
+        return 1
+    fi
+
+    # .mmdb Datei finden und verschieben
+    local mmdb_file
+    mmdb_file=$(find "$tmp_extract" -name 'GeoLite2-Country.mmdb' -type f 2>/dev/null | head -1)
+
+    if [[ -z "$mmdb_file" || ! -f "$mmdb_file" ]]; then
+        log "ERROR" "MaxMind DB: GeoLite2-Country.mmdb nicht im Archiv gefunden"
+        rm -f "$tmp_file"
+        rm -rf "$tmp_extract"
+        return 1
+    fi
+
+    mv "$mmdb_file" "$GEOIP_AUTO_DB"
+    rm -f "$tmp_file"
+    rm -rf "$tmp_extract"
+
+    log "INFO" "MaxMind GeoLite2-Country DB erfolgreich aktualisiert: $GEOIP_AUTO_DB"
+    return 0
+}
+
+# ─── Effektiven MMDB-Pfad ermitteln ──────────────────────────────────────────
+# Priorität: GEOIP_MMDB_PATH (User) > Auto-Download > leer (Fallback auf geoiplookup)
+resolve_mmdb_path() {
+    # User hat eigenen Pfad gesetzt
+    if [[ -n "${GEOIP_MMDB_PATH:-}" && -f "${GEOIP_MMDB_PATH:-}" ]]; then
+        echo "$GEOIP_MMDB_PATH"
+        return 0
+    fi
+
+    # Auto-Download DB vorhanden
+    if [[ -f "$GEOIP_AUTO_DB" ]]; then
+        echo "$GEOIP_AUTO_DB"
+        return 0
+    fi
+
+    # Kein MMDB verfügbar
+    echo ""
+    return 1
+}
+
+# ─── GeoIP Lookup ────────────────────────────────────────────────────────────
+# Gibt den ISO 3166-1 Alpha-2 Ländercode zurück (z.B. "DE", "US", "CN")
+# Nutzt Cache um wiederholte Lookups zu vermeiden
+geoip_lookup() {
+    local ip="$1"
+    local cache_file="${GEOIP_CACHE_DIR}/${ip//[:\/]/_}.country"
+
+    # Cache prüfen (max 24 Stunden alt)
+    if [[ -f "$cache_file" ]]; then
+        local cache_age
+        cache_age=$(( $(date '+%s') - $(stat -c '%Y' "$cache_file" 2>/dev/null || stat -f '%m' "$cache_file" 2>/dev/null || echo "0") ))
+        if [[ "$cache_age" -lt 86400 ]]; then
+            cat "$cache_file"
+            return 0
+        fi
+    fi
+
+    local country_code=""
+
+    # Effektiven MMDB-Pfad ermitteln (User-Pfad oder Auto-Download)
+    local effective_mmdb
+    effective_mmdb=$(resolve_mmdb_path 2>/dev/null) || true
+
+    # Methode 1: MaxMind mmdbinspect (bevorzugt, genauer)
+    if [[ -n "$effective_mmdb" && -f "$effective_mmdb" ]] && command -v mmdbinspect &>/dev/null; then
+        country_code=$(mmdbinspect -db "$effective_mmdb" -ip "$ip" 2>/dev/null \
+            | jq -r '.[0].Records[0].Record.country.iso_code // empty' 2>/dev/null || true)
+    fi
+
+    # Methode 2: geoiplookup (GeoIP Legacy)
+    if [[ -z "$country_code" ]] && command -v geoiplookup &>/dev/null; then
+        if [[ "$ip" == *:* ]]; then
+            # IPv6
+            if command -v geoiplookup6 &>/dev/null; then
+                country_code=$(geoiplookup6 "$ip" 2>/dev/null \
+                    | grep -oP '(?<=: )[A-Z]{2}(?=,)' | head -1 || true)
+            fi
+        else
+            # IPv4
+            country_code=$(geoiplookup "$ip" 2>/dev/null \
+                | grep -oP '(?<=: )[A-Z]{2}(?=,)' | head -1 || true)
+        fi
+    fi
+
+    # Methode 3: mmdblookup (libmaxminddb)
+    if [[ -z "$country_code" && -n "$effective_mmdb" && -f "$effective_mmdb" ]] && command -v mmdblookup &>/dev/null; then
+        country_code=$(mmdblookup --file "$effective_mmdb" --ip "$ip" country iso_code 2>/dev/null \
+            | grep -oP '"[A-Z]{2}"' | tr -d '"' | head -1 || true)
+    fi
+
+    if [[ -n "$country_code" ]]; then
+        echo "$country_code" > "$cache_file"
+        echo "$country_code"
+        return 0
+    fi
+
+    # Unbekannt – nicht cachen (könnte temporärer Fehler sein)
+    echo ""
+    return 1
+}
+
+# ─── GeoIP Prüfung: Soll eine IP gesperrt werden? ────────────────────────────
+# Return 0 = sperren, Return 1 = erlauben
+should_block_by_geoip() {
+    local country_code="$1"
+    local mode="${GEOIP_MODE:-blocklist}"
+    local countries="${GEOIP_COUNTRIES:-}"
+
+    [[ -z "$country_code" || -z "$countries" ]] && return 1
+
+    # Länder-Liste in Array umwandeln
+    IFS=',' read -ra country_list <<< "$countries"
+
+    local found=false
+    for c in "${country_list[@]}"; do
+        c=$(echo "$c" | xargs | tr '[:lower:]' '[:upper:]')  # trim + uppercase
+        if [[ "$country_code" == "$c" ]]; then
+            found=true
+            break
+        fi
+    done
+
+    if [[ "$mode" == "blocklist" ]]; then
+        # Blocklist-Modus: Sperren wenn Land in der Liste
+        [[ "$found" == "true" ]] && return 0 || return 1
+    elif [[ "$mode" == "allowlist" ]]; then
+        # Allowlist-Modus: Sperren wenn Land NICHT in der Liste
+        [[ "$found" == "true" ]] && return 1 || return 0
+    fi
+
+    return 1
+}
+
+# ─── IP via iptables sperren ─────────────────────────────────────────────────
+ban_ip_geoip() {
+    local client_ip="$1"
+    local country_code="$2"
+    local mode="${GEOIP_MODE:-blocklist}"
+
+    # Prüfen ob bereits gesperrt
+    local state_file="${STATE_DIR}/${client_ip//[:\/]/_}.ban"
+    if [[ -f "$state_file" ]]; then
+        log "DEBUG" "GeoIP: $client_ip ist bereits gesperrt"
+        return 0
+    fi
+
+    # GeoIP-Sperren sind immer permanent
+    local ban_until=0
+    local ban_until_display="PERMANENT"
+
+    local reason_text
+    if [[ "$mode" == "blocklist" ]]; then
+        reason_text="geoip-blocklist (Land: $country_code)"
+    else
+        reason_text="geoip-allowlist (Land: $country_code)"
+    fi
+
+    log "WARN" "GeoIP SPERRE: $client_ip (Land: $country_code, Modus: $mode) PERMANENT"
+
+    # iptables Regel setzen
+    if [[ "$client_ip" == *:* ]]; then
+        ip6tables -I "$IPTABLES_CHAIN" -s "$client_ip" -j DROP 2>/dev/null || true
+    else
+        iptables -I "$IPTABLES_CHAIN" -s "$client_ip" -j DROP 2>/dev/null || true
+    fi
+
+    # State-Datei erstellen
+    cat > "$state_file" << EOF
+CLIENT_IP=$client_ip
+DOMAIN=GeoIP:${country_code}
+COUNT=-
+BAN_TIME=$(date '+%Y-%m-%d %H:%M:%S')
+BAN_UNTIL_EPOCH=0
+BAN_UNTIL=PERMANENT
+BAN_DURATION=0
+OFFENSE_LEVEL=0
+IS_PERMANENT=true
+REASON=geoip
+PROTOCOL=-
+GEOIP_COUNTRY=$country_code
+GEOIP_MODE=$mode
+EOF
+
+    # Ban-History
+    log_ban_history "BAN" "$client_ip" "$country_code" "$reason_text"
+
+    # Benachrichtigung senden
+    if [[ "${GEOIP_NOTIFY:-true}" == "true" && "${NOTIFY_ENABLED:-false}" == "true" ]]; then
+        send_geoip_notification "ban" "$client_ip" "$country_code" "PERMANENT" "$mode"
+    fi
+}
+
+# ─── GeoIP Benachrichtigung ──────────────────────────────────────────────────
+send_geoip_notification() {
+    local action="$1"
+    local client_ip="$2"
+    local country_code="$3"
+    local duration="${4:-PERMANENT}"
+    local mode="${5:-blocklist}"
+    local my_hostname
+    my_hostname=$(hostname)
+
+    local title="🌍 🛡️ AdGuard Shield"
+    local mode_label
+    [[ "$mode" == "blocklist" ]] && mode_label="Blocklist" || mode_label="Allowlist"
+
+    local message="🌍 AdGuard Shield GeoIP-Sperre auf ${my_hostname}
+---
+IP: ${client_ip}
+Land: ${country_code}
+Modus: ${mode_label}
+Dauer: ${duration}
+
+Whois: https://www.whois.com/whois/${client_ip}
+AbuseIPDB: https://www.abuseipdb.com/check/${client_ip}"
+
+    case "${NOTIFY_TYPE:-}" in
+        discord)
+            local json_payload
+            json_payload=$(jq -nc --arg msg "$message" '{content: $msg}')
+            curl -s -H "Content-Type: application/json" \
+                -d "$json_payload" \
+                "$NOTIFY_WEBHOOK_URL" &>/dev/null &
+            ;;
+        slack)
+            local json_payload
+            json_payload=$(jq -nc --arg msg "$message" '{text: $msg}')
+            curl -s -H "Content-Type: application/json" \
+                -d "$json_payload" \
+                "$NOTIFY_WEBHOOK_URL" &>/dev/null &
+            ;;
+        gotify)
+            local clean_message
+            clean_message=$(echo "$message" | sed 's/\*\*//g')
+            curl -s -X POST "$NOTIFY_WEBHOOK_URL" \
+                -F "title=${title}" \
+                -F "message=${clean_message}" \
+                -F "priority=5" &>/dev/null &
+            ;;
+        ntfy)
+            local ntfy_url="${NTFY_SERVER_URL:-https://ntfy.sh}"
+            local -a curl_args=(
+                -s -X POST
+                "${ntfy_url}/${NTFY_TOPIC}"
+                -H "Title: 🛡️ AdGuard Shield GeoIP"
+                -H "Priority: ${NTFY_PRIORITY:-4}"
+                -H "Tags: globe_with_meridians,ban"
+                -d "$message"
+            )
+            [[ -n "${NTFY_TOKEN:-}" ]] && curl_args+=(-H "Authorization: Bearer ${NTFY_TOKEN}")
+            curl "${curl_args[@]}" &>/dev/null &
+            ;;
+        generic)
+            local json_payload
+            json_payload=$(jq -nc --arg msg "$message" --arg cl "$client_ip" --arg cc "$country_code" \
+                '{message: $msg, action: "geoip-ban", client: $cl, country: $cc}')
+            curl -s -H "Content-Type: application/json" \
+                -d "$json_payload" \
+                "$NOTIFY_WEBHOOK_URL" &>/dev/null &
+            ;;
+    esac
+}
+
+# ─── iptables Chain Setup ────────────────────────────────────────────────────
+setup_iptables_chain() {
+    if ! iptables -n -L "$IPTABLES_CHAIN" &>/dev/null; then
+        iptables -N "$IPTABLES_CHAIN"
+        for port in $BLOCKED_PORTS; do
+            iptables -I INPUT -p tcp --dport "$port" -j "$IPTABLES_CHAIN"
+            iptables -I INPUT -p udp --dport "$port" -j "$IPTABLES_CHAIN"
+        done
+    fi
+    if ! ip6tables -n -L "$IPTABLES_CHAIN" &>/dev/null; then
+        ip6tables -N "$IPTABLES_CHAIN"
+        for port in $BLOCKED_PORTS; do
+            ip6tables -I INPUT -p tcp --dport "$port" -j "$IPTABLES_CHAIN"
+            ip6tables -I INPUT -p udp --dport "$port" -j "$IPTABLES_CHAIN"
+        done
+    fi
+}
+
+# ─── GeoIP-Tools Verfügbarkeit prüfen ────────────────────────────────────────
+check_geoip_tools() {
+    # Effektiven MMDB-Pfad ermitteln
+    local effective_mmdb
+    effective_mmdb=$(resolve_mmdb_path 2>/dev/null) || true
+
+    # mmdbinspect + MMDB
+    if [[ -n "$effective_mmdb" && -f "$effective_mmdb" ]]; then
+        if command -v mmdbinspect &>/dev/null; then
+            echo "mmdbinspect"
+            return 0
+        elif command -v mmdblookup &>/dev/null; then
+            echo "mmdblookup"
+            return 0
+        fi
+    fi
+
+    # geoiplookup (Legacy GeoIP)
+    if command -v geoiplookup &>/dev/null; then
+        echo "geoiplookup"
+        return 0
+    fi
+
+    echo "none"
+    return 1
+}
+
+# ─── Client-IPs aus AdGuard API extrahieren ──────────────────────────────────
+get_active_clients() {
+    local response
+    response=$(curl -s -u "${ADGUARD_USER}:${ADGUARD_PASS}" \
+        --connect-timeout 5 \
+        --max-time 10 \
+        -k "${ADGUARD_URL}/control/querylog?limit=${API_QUERY_LIMIT:-500}&response_status=all" 2>/dev/null)
+
+    if [[ -z "$response" || "$response" == "null" ]]; then
+        log "ERROR" "Keine Antwort von AdGuard Home API"
+        return 1
+    fi
+
+    # Eindeutige Client-IPs extrahieren
+    echo "$response" | jq -r '.data // [] | [.[].client // .[].client_info.ip] | unique | .[]' 2>/dev/null | sort -u
+}
+
+# ─── Auto-Unban: GeoIP-Sperren aufheben bei Konfigurationsänderung ────────────
+# Prüft alle bestehenden GeoIP-Sperren und hebt sie auf, wenn:
+# - Das Land nicht mehr in GEOIP_COUNTRIES steht
+# - Der Modus gewechselt wurde (blocklist ↔ allowlist)
+# - GeoIP deaktiviert wurde
+auto_unban_geoip() {
+    local unban_count=0
+
+    for f in "${STATE_DIR}"/*.ban; do
+        [[ -f "$f" ]] || continue
+
+        local reason
+        reason=$(grep '^REASON=' "$f" | cut -d= -f2 || true)
+        [[ "$reason" != "geoip" ]] && continue
+
+        local client_ip country_code old_mode
+        client_ip=$(grep '^CLIENT_IP=' "$f" | cut -d= -f2 || true)
+        country_code=$(grep '^GEOIP_COUNTRY=' "$f" | cut -d= -f2 || true)
+        old_mode=$(grep '^GEOIP_MODE=' "$f" | cut -d= -f2 || true)
+
+        local should_unban=false
+
+        # GeoIP deaktiviert → alle GeoIP-Sperren aufheben
+        if [[ "${GEOIP_ENABLED:-false}" != "true" ]]; then
+            should_unban=true
+        # Modus gewechselt → alle GeoIP-Sperren aufheben und neu prüfen
+        elif [[ -n "$old_mode" && "$old_mode" != "${GEOIP_MODE:-blocklist}" ]]; then
+            should_unban=true
+        # Prüfen ob das Land nach aktueller Konfiguration noch gesperrt sein soll
+        elif [[ -n "$country_code" ]] && ! should_block_by_geoip "$country_code"; then
+            should_unban=true
+        fi
+
+        if [[ "$should_unban" == "true" ]]; then
+            log "INFO" "GeoIP Auto-Unban: $client_ip (Land: ${country_code:-?}, war: ${old_mode:-?})"
+
+            # iptables Regel entfernen
+            if [[ "$client_ip" == *:* ]]; then
+                ip6tables -D "$IPTABLES_CHAIN" -s "$client_ip" -j DROP 2>/dev/null || true
+            else
+                iptables -D "$IPTABLES_CHAIN" -s "$client_ip" -j DROP 2>/dev/null || true
+            fi
+
+            rm -f "$f"
+            log_ban_history "UNBAN" "$client_ip" "$country_code" "geoip-auto-unban"
+            unban_count=$((unban_count + 1))
+        fi
+    done
+
+    if [[ $unban_count -gt 0 ]]; then
+        log "INFO" "GeoIP Auto-Unban: $unban_count Sperren aufgehoben (Länderliste/Modus geändert)"
+    fi
+}
+
+# ─── Einmaliger GeoIP-Sync ──────────────────────────────────────────────────
+sync_geoip() {
+    # Auto-Unban zuerst: bestehende Sperren prüfen, die nicht mehr zur Config passen
+    auto_unban_geoip
+
+    if [[ "${GEOIP_ENABLED:-false}" != "true" ]]; then
+        log "INFO" "GeoIP ist deaktiviert"
+        return 0
+    fi
+
+    # MaxMind DB automatisch herunterladen/aktualisieren (falls License-Key gesetzt)
+    update_maxmind_db || true
+
+    local countries="${GEOIP_COUNTRIES:-}"
+    if [[ -z "$countries" ]]; then
+        log "WARN" "GeoIP: Keine Länder konfiguriert (GEOIP_COUNTRIES ist leer)"
+        return 0
+    fi
+
+    local tool
+    tool=$(check_geoip_tools) || {
+        log "ERROR" "GeoIP: Kein GeoIP-Tool verfügbar. Installiere geoip-bin oder mmdbinspect."
+        return 1
+    }
+    log "INFO" "GeoIP-Sync gestartet (Tool: $tool, Modus: ${GEOIP_MODE:-blocklist}, Länder: $countries)"
+
+    # Client-IPs aus der API holen
+    local clients
+    clients=$(get_active_clients) || {
+        log "ERROR" "GeoIP: Konnte aktive Clients nicht ermitteln"
+        return 1
+    }
+
+    local checked=0
+    local blocked=0
+    local skipped=0
+
+    while IFS= read -r client_ip; do
+        [[ -z "$client_ip" || "$client_ip" == "null" ]] && continue
+
+        # Private IPs überspringen
+        if [[ "${GEOIP_SKIP_PRIVATE:-true}" == "true" ]] && is_private_ip "$client_ip"; then
+            log "DEBUG" "GeoIP: Private IP übersprungen: $client_ip"
+            skipped=$((skipped + 1))
+            continue
+        fi
+
+        # Whitelist prüfen
+        if is_whitelisted "$client_ip"; then
+            log "DEBUG" "GeoIP: Whitelisted IP übersprungen: $client_ip"
+            skipped=$((skipped + 1))
+            continue
+        fi
+
+        # Bereits gesperrt?
+        local state_file="${STATE_DIR}/${client_ip//[:\/]/_}.ban"
+        if [[ -f "$state_file" ]]; then
+            skipped=$((skipped + 1))
+            continue
+        fi
+
+        checked=$((checked + 1))
+
+        # GeoIP Lookup
+        local country_code
+        country_code=$(geoip_lookup "$client_ip") || true
+
+        if [[ -z "$country_code" ]]; then
+            log "DEBUG" "GeoIP: Kein Ergebnis für $client_ip"
+            continue
+        fi
+
+        log "DEBUG" "GeoIP: $client_ip → $country_code"
+
+        # Prüfen ob gesperrt werden soll
+        if should_block_by_geoip "$country_code"; then
+            ban_ip_geoip "$client_ip" "$country_code"
+            blocked=$((blocked + 1))
+        fi
+    done <<< "$clients"
+
+    log "INFO" "GeoIP-Sync abgeschlossen: $checked geprüft, $blocked gesperrt, $skipped übersprungen"
+}
+
+# ─── Worker-Hauptschleife ────────────────────────────────────────────────────
+start_worker() {
+    if [[ "${GEOIP_ENABLED:-false}" != "true" ]]; then
+        log "DEBUG" "GeoIP-Worker ist deaktiviert"
+        return 0
+    fi
+
+    # PID schreiben
+    echo $$ > "$WORKER_PID_FILE"
+    trap 'rm -f "$WORKER_PID_FILE"; exit 0' SIGTERM SIGINT SIGHUP
+
+    local interval="${GEOIP_CHECK_INTERVAL:-0}"
+    [[ "$interval" -le 0 ]] && interval="${CHECK_INTERVAL:-10}"
+
+    log "INFO" "GeoIP-Worker gestartet (PID: $$, Intervall: ${interval}s)"
+
+    # Beim Start: MaxMind DB herunterladen/aktualisieren (falls License-Key gesetzt)
+    update_maxmind_db || true
+
+    while true; do
+        sync_geoip
+        sleep "$interval"
+    done
+}
+
+# ─── Status anzeigen ─────────────────────────────────────────────────────────
+show_status() {
+    echo "═══════════════════════════════════════════════════════════════"
+    echo "  AdGuard Shield - GeoIP Status"
+    echo "═══════════════════════════════════════════════════════════════"
+    echo ""
+
+    if [[ "${GEOIP_ENABLED:-false}" != "true" ]]; then
+        echo "  ℹ️  GeoIP ist deaktiviert"
+        echo ""
+        return
+    fi
+
+    echo "  Modus:    ${GEOIP_MODE:-blocklist}"
+    echo "  Länder:   ${GEOIP_COUNTRIES:-<keine>}"
+    echo "  Sperrdauer: PERMANENT (Auto-Unban bei Änderung der Länderliste)"
+    echo "  Private IPs überspringen: ${GEOIP_SKIP_PRIVATE:-true}"
+    echo ""
+
+    # MaxMind DB Info
+    local eff_mmdb
+    eff_mmdb=$(resolve_mmdb_path)
+    if [[ -n "${GEOIP_MMDB_PATH:-}" ]]; then
+        echo "  MMDB-Pfad: ${GEOIP_MMDB_PATH} (manuell konfiguriert)"
+    elif [[ -n "${GEOIP_LICENSE_KEY:-}" ]]; then
+        echo "  MMDB-Pfad: ${GEOIP_AUTO_DB} (Auto-Download)"
+        if [[ -f "${GEOIP_AUTO_DB}" ]]; then
+            local db_age db_age_h
+            db_age=$(( $(date +%s) - $(stat -c %Y "${GEOIP_AUTO_DB}" 2>/dev/null || echo 0) ))
+            db_age_h=$(( db_age / 3600 ))
+            echo "  DB-Alter:  ${db_age_h}h (Update alle 24h)"
+        else
+            echo "  DB-Status: ⚠️  Noch nicht heruntergeladen"
+        fi
+    elif [[ -n "$eff_mmdb" ]]; then
+        echo "  MMDB-Pfad: ${eff_mmdb}"
+    else
+        echo "  MMDB-Pfad: <nicht konfiguriert> (Fallback auf geoiplookup)"
+    fi
+    echo "  License-Key: $(if [[ -n "${GEOIP_LICENSE_KEY:-}" ]]; then echo "✅ konfiguriert"; else echo "❌ nicht gesetzt (kein Auto-Download)"; fi)"
+    echo ""
+
+    # GeoIP Tools prüfen
+    echo "  GeoIP Tools:"
+    local tool
+    tool=$(check_geoip_tools 2>/dev/null) || tool="none"
+    case "$tool" in
+        mmdbinspect) echo "  ✅ mmdbinspect mit MaxMind DB" ;;
+        mmdblookup)  echo "  ✅ mmdblookup mit MaxMind DB" ;;
+        geoiplookup) echo "  ✅ geoiplookup (Legacy GeoIP)" ;;
+        none)        echo "  ❌ Kein GeoIP-Tool gefunden!" ;;
+    esac
+    echo ""
+
+    # Worker-Status
+    if [[ -f "$WORKER_PID_FILE" ]]; then
+        local wpid
+        wpid=$(cat "$WORKER_PID_FILE")
+        if kill -0 "$wpid" 2>/dev/null; then
+            echo "  Worker: Läuft (PID: $wpid)"
+        else
+            echo "  Worker: Abgestürzt (PID: $wpid existiert nicht mehr)"
+        fi
+    else
+        echo "  Worker: Nicht gestartet"
+    fi
+    echo ""
+
+    # GeoIP-Sperren anzeigen
+    local geoip_bans=0
+    if [[ -d "$STATE_DIR" ]]; then
+        for f in "${STATE_DIR}"/*.ban; do
+            [[ -f "$f" ]] || continue
+            local reason
+            reason=$(grep '^REASON=' "$f" | cut -d= -f2 || true)
+            if [[ "$reason" == "geoip" ]]; then
+                geoip_bans=$((geoip_bans + 1))
+                local s_ip s_country s_until
+                s_ip=$(grep '^CLIENT_IP=' "$f" | cut -d= -f2 || true)
+                s_country=$(grep '^GEOIP_COUNTRY=' "$f" | cut -d= -f2 || true)
+                s_until=$(grep '^BAN_UNTIL=' "$f" | cut -d= -f2 || true)
+                echo "  🌍 $s_ip → Land: ${s_country:-?} (bis: ${s_until:-?})"
+            fi
+        done
+    fi
+
+    if [[ $geoip_bans -eq 0 ]]; then
+        echo "  Keine aktiven GeoIP-Sperren"
+    else
+        echo ""
+        echo "  Gesamt: $geoip_bans aktive GeoIP-Sperren"
+    fi
+
+    # Cache-Statistik
+    if [[ -d "$GEOIP_CACHE_DIR" ]]; then
+        local cache_count
+        cache_count=$(find "$GEOIP_CACHE_DIR" -name '*.country' -type f 2>/dev/null | wc -l)
+        echo ""
+        echo "  Cache: $cache_count IP-Lookups zwischengespeichert"
+    fi
+
+    echo ""
+    echo "═══════════════════════════════════════════════════════════════"
+}
+
+# ─── Einzelne IP nachschlagen ────────────────────────────────────────────────
+lookup_ip() {
+    local ip="$1"
+
+    local eff_mmdb
+    eff_mmdb=$(resolve_mmdb_path)
+
+    local tool
+    tool=$(check_geoip_tools 2>/dev/null) || tool="none"
+
+    if [[ "$tool" == "none" ]]; then
+        echo "❌ Kein GeoIP-Tool verfügbar."
+        echo "   Installiere geoip-bin: sudo apt install geoip-bin geoip-database"
+        echo "   Oder mmdbinspect mit MaxMind GeoLite2 DB"
+        return 1
+    fi
+
+    local country_code
+    country_code=$(geoip_lookup "$ip") || true
+
+    if [[ -z "$country_code" ]]; then
+        echo "IP: $ip → Land: unbekannt (kein GeoIP-Ergebnis)"
+        return 1
+    fi
+
+    echo "IP: $ip → Land: $country_code (Tool: $tool)"
+    [[ -n "$eff_mmdb" ]] && echo "   MMDB: $eff_mmdb"
+
+    # Prüfen ob diese IP gesperrt werden würde
+    if [[ "${GEOIP_ENABLED:-false}" == "true" && -n "${GEOIP_COUNTRIES:-}" ]]; then
+        if should_block_by_geoip "$country_code"; then
+            echo "→ Würde GESPERRT werden (Modus: ${GEOIP_MODE:-blocklist}, Länder: ${GEOIP_COUNTRIES})"
+        else
+            echo "→ Würde ERLAUBT werden (Modus: ${GEOIP_MODE:-blocklist}, Länder: ${GEOIP_COUNTRIES})"
+        fi
+    fi
+}
+
+# ─── Cache leeren ────────────────────────────────────────────────────────────
+flush_cache() {
+    if [[ -d "$GEOIP_CACHE_DIR" ]]; then
+        local count
+        count=$(find "$GEOIP_CACHE_DIR" -name '*.country' -type f 2>/dev/null | wc -l)
+        rm -f "${GEOIP_CACHE_DIR}"/*.country 2>/dev/null || true
+        echo "✅ GeoIP-Cache geleert ($count Einträge entfernt)"
+        log "INFO" "GeoIP-Cache geleert ($count Einträge)"
+    else
+        echo "ℹ️  GeoIP-Cache-Verzeichnis existiert nicht"
+    fi
+}
+
+# ─── GeoIP-Sperren aufheben ─────────────────────────────────────────────────
+flush_geoip_bans() {
+    local count=0
+    if [[ -d "$STATE_DIR" ]]; then
+        for f in "${STATE_DIR}"/*.ban; do
+            [[ -f "$f" ]] || continue
+            local reason
+            reason=$(grep '^REASON=' "$f" | cut -d= -f2 || true)
+            if [[ "$reason" == "geoip" ]]; then
+                local client_ip
+                client_ip=$(grep '^CLIENT_IP=' "$f" | cut -d= -f2 || true)
+
+                # iptables Regel entfernen
+                if [[ "$client_ip" == *:* ]]; then
+                    ip6tables -D "$IPTABLES_CHAIN" -s "$client_ip" -j DROP 2>/dev/null || true
+                else
+                    iptables -D "$IPTABLES_CHAIN" -s "$client_ip" -j DROP 2>/dev/null || true
+                fi
+
+                rm -f "$f"
+                log_ban_history "UNBAN" "$client_ip" "" "geoip-flush"
+                count=$((count + 1))
+            fi
+        done
+    fi
+
+    echo "✅ $count GeoIP-Sperren aufgehoben"
+    log "INFO" "$count GeoIP-Sperren aufgehoben (flush)"
+}
+
+# ─── Hauptprogramm ──────────────────────────────────────────────────────────
+case "${1:-help}" in
+    start)
+        init_directories
+        setup_iptables_chain
+        start_worker
+        ;;
+    sync)
+        init_directories
+        setup_iptables_chain
+        sync_geoip
+        ;;
+    status)
+        init_directories
+        show_status
+        ;;
+    lookup)
+        if [[ -z "${2:-}" ]]; then
+            echo "Nutzung: $0 lookup <IP-Adresse>" >&2
+            exit 1
+        fi
+        init_directories
+        lookup_ip "$2"
+        ;;
+    flush)
+        init_directories
+        flush_geoip_bans
+        ;;
+    flush-cache)
+        init_directories
+        flush_cache
+        ;;
+    stop)
+        if [[ -f "$WORKER_PID_FILE" ]]; then
+            local wpid
+            wpid=$(cat "$WORKER_PID_FILE")
+            if kill -0 "$wpid" 2>/dev/null; then
+                kill "$wpid" 2>/dev/null || true
+                rm -f "$WORKER_PID_FILE"
+                echo "GeoIP-Worker gestoppt"
+            else
+                rm -f "$WORKER_PID_FILE"
+                echo "GeoIP-Worker war nicht aktiv"
+            fi
+        else
+            echo "GeoIP-Worker läuft nicht"
+        fi
+        ;;
+    *)
+        cat << USAGE
+AdGuard Shield - GeoIP Worker
+
+Nutzung: $0 {start|stop|sync|status|lookup|flush|flush-cache}
+
+Befehle:
+  start        Startet den GeoIP-Worker (Hintergrundprozess)
+  stop         Stoppt den GeoIP-Worker
+  sync         Einmalige GeoIP-Prüfung aller aktiven Clients
+  status       Zeigt GeoIP-Status und aktive Sperren
+  lookup <IP>  GeoIP-Lookup für eine einzelne IP
+  flush        Alle GeoIP-Sperren aufheben
+  flush-cache  GeoIP-Lookup-Cache leeren
+
+Konfiguration in: $CONFIG_FILE
+  GEOIP_ENABLED=true/false
+  GEOIP_MODE=blocklist/allowlist
+  GEOIP_COUNTRIES="CN,RU,..."
+
+USAGE
+        exit 0
+        ;;
+esac
--- a/install.sh
+++ b/install.sh
@@ -132,11 +132,18 @@ print_help() {
    echo -e "  ${CYAN}sudo systemctl disable adguard-shield-watchdog.timer${NC}   # Watchdog deaktivieren"
    echo -e "  ${CYAN}sudo journalctl -u adguard-shield-watchdog.service${NC}     # Watchdog-Logs"
    echo ""
+    echo -e "${BOLD}GeoIP-Befehle:${NC}"
+    echo -e "  ${CYAN}sudo /opt/adguard-shield/adguard-shield.sh geoip-status${NC}    # GeoIP-Status anzeigen"
+    echo -e "  ${CYAN}sudo /opt/adguard-shield/adguard-shield.sh geoip-sync${NC}      # Einmalige GeoIP-Prüfung"
+    echo -e "  ${CYAN}sudo /opt/adguard-shield/adguard-shield.sh geoip-flush${NC}     # Alle GeoIP-Sperren aufheben"
+    echo -e "  ${CYAN}sudo /opt/adguard-shield/adguard-shield.sh geoip-lookup IP${NC}  # GeoIP-Lookup einer IP"
+    echo ""
    echo -e "${BOLD}Voraussetzungen:${NC}"
    echo "  - Linux Server (Debian/Ubuntu empfohlen)"
    echo "  - Root-Zugriff (sudo)"
    echo "  - AdGuard Home installiert und erreichbar"
    echo "  - Pakete: curl, jq, iptables, gawk (werden bei Installation automatisch installiert)"
+    echo "  - GeoIP (optional): geoip-bin + geoip-database oder MaxMind GeoLite2 DB"
    echo ""
    echo -e "${BOLD}Dokumentation:${NC}"
    echo "  https://git.techniverse.net/scriptos/adguard-shield"
@@ -257,6 +264,7 @@ install_files() {
    cp "$SCRIPT_DIR/report-generator.sh" "$INSTALL_DIR/"
    cp "$SCRIPT_DIR/adguard-shield-watchdog.sh" "$INSTALL_DIR/"
    cp "$SCRIPT_DIR/uninstall.sh" "$INSTALL_DIR/"
+    cp "$SCRIPT_DIR/geoip-worker.sh" "$INSTALL_DIR/"

    # Templates kopieren
    mkdir -p "$INSTALL_DIR/templates"
@@ -272,6 +280,7 @@ install_files() {
    chmod +x "$INSTALL_DIR/report-generator.sh"
    chmod +x "$INSTALL_DIR/adguard-shield-watchdog.sh"
    chmod +x "$INSTALL_DIR/uninstall.sh"
+    chmod +x "$INSTALL_DIR/geoip-worker.sh"

    echo -e "  ✅ Dateien installiert"
    echo ""
--- a/uninstall.sh
+++ b/uninstall.sh
@@ -125,8 +125,10 @@ do_uninstall() {
        rm -f "$INSTALL_DIR/external-whitelist-worker.sh"
        rm -f "$INSTALL_DIR/report-generator.sh"
        rm -f "$INSTALL_DIR/adguard-shield-watchdog.sh"
+        rm -f "$INSTALL_DIR/geoip-worker.sh"
        rm -f "$INSTALL_DIR/uninstall.sh"
        rm -rf "$INSTALL_DIR/templates"
+        rm -rf "$INSTALL_DIR/geoip"
        echo "  ✅ Scripts entfernt (Konfiguration und Logs behalten)"
        echo ""
        echo -e "${YELLOW}  Konfiguration verbleibt in: $INSTALL_DIR/adguard-shield.conf${NC}"