4.0 KiB
Dokumentation
Willkommen in der Dokumentation von AdGuard Shield.
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 |