AdGuard Shield ist ein Go-Daemon, der das Query Log von AdGuard Home auswertet, auffällige DNS-Clients erkennt und diese über eine eigene Firewall-Struktur sperrt. Die Dokumentation ist bewusst ausführlich gehalten: Sie soll nicht nur Befehle auflisten, sondern erklären, was im Hintergrund passiert, welche Werte sinnvoll sind und wie du Fehler sauber eingrenzt.

Schnellnavigation

Dokument	Wofür es gedacht ist
Architektur & Funktionsweise	Erklärt den Aufbau, den Datenfluss, Firewall-Modell, SQLite-Schema, Hintergrundjobs und Sperrlogik
Befehle & Nutzung	Vollständige CLI-Referenz mit Beispielen und typischen Betriebsabläufen
Konfiguration	Alle Parameter aus `adguard-shield.conf` mit Beispielen, Empfehlungen und Beispielkonfigurationen
Docker-Installationen	Firewall-Modi für klassische Installation, Docker Host Network und veröffentlichte Docker-Ports
Benachrichtigungen	Einrichtung von Ntfy, Discord, Slack, Gotify und Generic Webhooks mit Beispielinhalten
E-Mail Report	Report-Inhalte, Formate, Mailversand, Cron-Job und manuelle Tests
Update-Anleitung	Update der Go-Version, Konfigurationsmigration und Migration von alten Shell-Installationen
Tipps & Troubleshooting	Diagnosewege für API, Firewall, GeoIP, Reports, externe Listen und falsch gesetzte Sperren

Das Binary

Die Go-Version bündelt alle Aufgaben in einem einzelnen Binary:

/opt/adguard-shield/adguard-shield

Dieses Binary ist gleichzeitig:

Daemon für den produktiven Betrieb (Querylog-Polling, Erkennung, Sperren)
CLI für Status, History, Logs, Firewall, Listen, GeoIP und Reports
Installer, Updater und Uninstaller
Report-Generator für HTML- und Text-Reports
Hintergrundprozess für externe Whitelist, externe Blocklist, GeoIP und Offense-Cleanup

Die meisten Befehle beginnen daher mit:

sudo /opt/adguard-shield/adguard-shield <befehl>

Für Installation oder Update nutzt du das neue Binary aus dem Repository, Release oder Build-Verzeichnis:

sudo ./adguard-shield install
sudo ./adguard-shield update

Empfohlener Lesefluss

Neueinrichtung

Lies zuerst Architektur & Funktionsweise, damit klar ist, was genau gesperrt wird und wie der Datenfluss aussieht.
Passe danach Konfiguration an, besonders API-Zugang, Whitelist und Rate-Limits.
Nutze Befehle & Nutzung für Installation, Dry-Run und Service-Start.
Richte optional Benachrichtigungen, Reports, GeoIP oder externe Listen ein.
Bei Problemen hilft Tipps & Troubleshooting.

Migration von der Shell-Version

Wenn du von der alten Shell-Version kommst, beginne mit Update-Anleitung. Dort findest du den empfohlenen Migrationsablauf und Hinweise zu den erkannten Legacy-Artefakten.

Docker-Setups

Wenn AdGuard Home in Docker läuft, lies Docker-Installationen zusätzlich zur Grundkonfiguration. Der Firewall-Modus bestimmt, in welcher Chain die Sperren greifen.

Wichtigster Unterschied zur alten Shell-Version

Die frühere Version bestand aus mehreren Shell-Skripten, Hilfs-Workern, Cron-Jobs und einem separaten Watchdog:

Alte Shell-Version	Go-Version
`adguard-shield.sh` (Hauptskript)	Ein Binary für alles
`iptables-helper.sh`	Integriert im Binary
`external-blocklist-worker.sh`	Goroutine im Daemon
`external-whitelist-worker.sh`	Goroutine im Daemon
`geoip-worker.sh`	Goroutine im Daemon
`offense-cleanup-worker.sh`	Goroutine im Daemon
`report-generator.sh`	Integriert im Binary
`unban-expired.sh`	Integriert im Daemon
Watchdog-Service + Timer	`Restart=on-failure` in systemd
Mehrere Cron-Jobs	Ein optionaler Cron-Job für Reports