scriptos/adguard-shield
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 18 Wiki Activity
Files
v1.0.0
adguard-shield/docs/tipps-und-troubleshooting.md
Patrick Asmus 4f17f7ff81 feat!: Migration auf Go-Binary 
BREAKING CHANGE: Die alte Shell-Version muss vor der Installation der Go-Version deinstalliert werden.
2026-05-01 00:08:57 +02:00

9.7 KiB
Raw Permalink Blame History

Tipps & Troubleshooting

Dieses Dokument hilft beim Eingrenzen typischer Probleme im Betrieb. Die Reihenfolge ist bewusst praktisch: erst prüfen, ob der Dienst läuft, dann API, Firewall, Sperren, Listen und optionale Module.

Erste Diagnose

Diese Befehle liefern meistens schon genug Hinweise:

sudo systemctl status adguard-shield
sudo journalctl -u adguard-shield --no-pager -n 100
sudo /opt/adguard-shield/adguard-shield test
sudo /opt/adguard-shield/adguard-shield status
sudo /opt/adguard-shield/adguard-shield logs --level warn --limit 100

Wenn du aktuelle Queries sehen willst:

sudo /opt/adguard-shield/adguard-shield live

Service startet nicht

Prüfen:

sudo systemctl status adguard-shield
sudo journalctl -u adguard-shield --no-pager -n 100

Typische Ursachen:

  • Konfigurationsdatei fehlt oder hat falsche Rechte
  • Binary fehlt oder ist nicht ausführbar
  • iptables, ip6tables oder ipset fehlen
  • AdGuard-Home-API ist nicht erreichbar
  • alte Shell-Artefakte verursachen Konflikte
  • systemd-Unit wurde manuell geändert, aber daemon-reload fehlt

Nützliche Prüfungen:

ls -l /opt/adguard-shield/adguard-shield
ls -l /opt/adguard-shield/adguard-shield.conf
which iptables ip6tables ipset systemctl
sudo systemctl daemon-reload

Verbindung zu AdGuard Home schlägt fehl

Test:

sudo /opt/adguard-shield/adguard-shield test

Prüfe in /opt/adguard-shield/adguard-shield.conf:

ADGUARD_URL="http://127.0.0.1:3000"
ADGUARD_USER="admin"
ADGUARD_PASS="..."

Häufige Fehler:

Symptom Mögliche Ursache
HTTP 401/403 Benutzername oder Passwort falsch
HTTP 404 falsche URL oder AdGuard Home nicht hinter dieser URL
Timeout Firewall, DNS, falsche IP, Dienst nicht erreichbar
connection refused AdGuard Home läuft nicht oder anderer Port
keine Querylog-Einträge Querylog in AdGuard Home deaktiviert oder leer

Direkt testen:

curl -k -u "admin:passwort" "http://127.0.0.1:3000/control/querylog?limit=1&response_status=all"

Passe URL und Zugangsdaten entsprechend an.

Keine Sperren trotz vieler Anfragen

Prüfen:

sudo /opt/adguard-shield/adguard-shield live --once
sudo /opt/adguard-shield/adguard-shield history 50
sudo /opt/adguard-shield/adguard-shield logs --level debug --limit 100

Mögliche Ursachen:

  • RATE_LIMIT_MAX_REQUESTS ist zu hoch
  • RATE_LIMIT_WINDOW ist zu kurz
  • API_QUERY_LIMIT ist zu niedrig und verpasst Spitzen
  • Client steht in WHITELIST
  • externe Whitelist enthält die IP
  • AdGuard Home sieht nicht die echte Client-IP, sondern nur einen Proxy/Forwarder
  • Querylog enthält die Anfragen nicht
  • DRY_RUN=true ist gesetzt

Wichtig bei Proxies und Forwardern: Wenn AdGuard Home nur eine einzige interne IP sieht, zählt AdGuard Shield auch nur diese IP. In solchen Setups muss die Architektur geprüft oder der Forwarder gewhitelistet werden.

Zu viele Sperren

Erst Übersicht:

sudo /opt/adguard-shield/adguard-shield status
sudo /opt/adguard-shield/adguard-shield history 100

Dann Ursachen einordnen:

Ursache Gegenmaßnahme
legitimer Client fragt häufig dieselbe Domain Client whitelisten oder Limit erhöhen
Router/Resolver bündelt viele Clients Router/Resolver whitelisten
CDN/App erzeugt viele Subdomains SUBDOMAIN_FLOOD_MAX_UNIQUE erhöhen
externe Blocklist ist sehr groß blocklist-status prüfen und Benachrichtigungen deaktiviert lassen
GeoIP Allowlist zu eng Länder prüfen oder GEOIP_MODE ändern

Falsch gesperrte IP freigeben:

sudo /opt/adguard-shield/adguard-shield unban 192.168.1.100
sudo /opt/adguard-shield/adguard-shield reset-offenses 192.168.1.100

Dauerhaft ausnehmen:

WHITELIST="127.0.0.1,::1,192.168.1.1,192.168.1.100"

Danach:

sudo systemctl restart adguard-shield

Firewall prüfen

Status:

sudo /opt/adguard-shield/adguard-shield firewall-status

Direkt prüfen:

sudo ipset list adguard_shield_v4
sudo ipset list adguard_shield_v6
sudo iptables -n -L ADGUARD_SHIELD --line-numbers -v
sudo ip6tables -n -L ADGUARD_SHIELD --line-numbers -v

Firewall neu aufbauen:

sudo /opt/adguard-shield/adguard-shield firewall-remove
sudo /opt/adguard-shield/adguard-shield firewall-create
sudo systemctl restart adguard-shield

Nach dem Neustart werden aktive Sperren aus SQLite wieder in die ipsets geschrieben.

Sperren bleiben nach Ablauf aktiv

Prüfen:

sudo /opt/adguard-shield/adguard-shield status
sudo /opt/adguard-shield/adguard-shield history 100

Temporäre Sperren werden beim Start und während des Pollings auf Ablauf geprüft. Wenn eine Sperre permanent ist, wird sie nicht automatisch freigegeben.

Permanent sind typischerweise:

  • DNS-Flood-Watchlist-Treffer
  • Progressive-Ban-Maximalstufe
  • manuelle ban-Sperren
  • GeoIP-Sperren
  • externe Blocklist mit EXTERNAL_BLOCKLIST_BAN_DURATION=0

Manuell freigeben:

sudo /opt/adguard-shield/adguard-shield unban 192.168.1.100

Dry-Run verwenden

Dry-Run ist ideal für neue Regeln:

sudo /opt/adguard-shield/adguard-shield dry-run

Währenddessen:

sudo /opt/adguard-shield/adguard-shield history 50

Im Dry-Run werden mögliche Sperren als DRY protokolliert. Es entstehen keine aktiven Sperren und keine Firewall-Änderungen.

Externe Whitelist

Status:

sudo /opt/adguard-shield/adguard-shield whitelist-status

Manuell synchronisieren:

sudo /opt/adguard-shield/adguard-shield whitelist-sync

Typische Probleme:

  • URL nicht erreichbar
  • Datei enthält Windows-Zeilenenden oder BOM
  • Hostname ist nicht auflösbar
  • Einträge enthalten Ports oder URLs statt IP/Hostname
  • DNS-Auflösung liefert 0.0.0.0, weil AdGuard den Host blockiert

Format prüfen:

192.168.1.100
10.0.0.0/24
trusted.example.com
# Kommentare sind erlaubt

Externe Blocklist

Status:

sudo /opt/adguard-shield/adguard-shield blocklist-status

Manuell synchronisieren:

sudo /opt/adguard-shield/adguard-shield blocklist-sync

Alle externen Blocklist-Sperren freigeben:

sudo /opt/adguard-shield/adguard-shield blocklist-flush

Wenn zu viele IPs gesperrt werden:

  1. EXTERNAL_BLOCKLIST_URLS prüfen.
  2. Liste manuell ansehen.
  3. Whitelist für eigene IPs ergänzen.
  4. EXTERNAL_BLOCKLIST_NOTIFY=false lassen.
  5. Bei Bedarf EXTERNAL_BLOCKLIST_AUTO_UNBAN=true setzen.

GeoIP

Status:

sudo /opt/adguard-shield/adguard-shield geoip-status

Einzelne IP prüfen:

sudo /opt/adguard-shield/adguard-shield geoip-lookup 8.8.8.8

Cache leeren:

sudo /opt/adguard-shield/adguard-shield geoip-flush-cache

Alle GeoIP-Sperren freigeben:

sudo /opt/adguard-shield/adguard-shield geoip-flush

Typische Ursachen:

Problem Lösung
keine Länder erkannt MaxMind-Key, MMDB-Pfad oder geoiplookup prüfen
private IPs werden nicht geprüft GEOIP_SKIP_PRIVATE=true ist aktiv, das ist Standard
zu viele Länder gesperrt GEOIP_MODE und GEOIP_COUNTRIES prüfen
Allowlist sperrt fast alles im Allowlist-Modus sind nur genannte Länder erlaubt

Reports

Status:

sudo /opt/adguard-shield/adguard-shield report-status

Test:

sudo /opt/adguard-shield/adguard-shield report-test
sudo /opt/adguard-shield/adguard-shield report-generate txt

Wenn keine Mail ankommt:

  • REPORT_EMAIL_TO gesetzt?
  • REPORT_MAIL_CMD vorhanden?
  • Mailer für root konfiguriert?
  • Cron installiert?
  • Spam-Ordner geprüft?

Cron prüfen:

sudo cat /etc/cron.d/adguard-shield-report
sudo /opt/adguard-shield/adguard-shield report-send

Benachrichtigungen

Prüfen:

sudo /opt/adguard-shield/adguard-shield logs --level warn --limit 100

Häufige Ursachen:

  • NOTIFY_ENABLED=false
  • falscher NOTIFY_TYPE
  • Webhook-URL leer
  • Ntfy-Topic leer
  • Token ungültig
  • ausgehende HTTPS-Verbindung blockiert
  • externe Blocklist meldet nichts, weil EXTERNAL_BLOCKLIST_NOTIFY=false
  • GeoIP meldet nichts, weil GEOIP_NOTIFY=false

SQLite direkt auswerten

Für tiefergehende Analysen:

sudo sqlite3 /var/lib/adguard-shield/adguard-shield.db \
  "select source, reason, count(*) from active_bans group by source, reason order by count(*) desc;"

Letzte History:

sudo sqlite3 /var/lib/adguard-shield/adguard-shield.db \
  "select timestamp_text, action, client_ip, domain, reason from ban_history order by id desc limit 20;"

Offense-Zähler:

sudo sqlite3 /var/lib/adguard-shield/adguard-shield.db \
  "select client_ip, offense_level, last_offense from offense_tracking order by offense_level desc;"

Alte Shell-Artefakte entfernen

Wenn der Installer alte Dateien meldet, zuerst sauber migrieren. Typische alte Dateien:

adguard-shield.sh
iptables-helper.sh
external-blocklist-worker.sh
external-whitelist-worker.sh
geoip-worker.sh
offense-cleanup-worker.sh
report-generator.sh
unban-expired.sh
adguard-shield-watchdog.sh

Die Go-Version ersetzt diese Funktionen durch das eine Binary. Alte Worker sollten nicht parallel laufen.

Service hart zurücksetzen

Wenn der Zustand unklar ist:

sudo systemctl stop adguard-shield
sudo /opt/adguard-shield/adguard-shield firewall-remove
sudo systemctl start adguard-shield
sudo /opt/adguard-shield/adguard-shield status

Das entfernt die Firewall-Struktur und lässt den Daemon sie beim Start wieder aus SQLite aufbauen.

Deinstallation

Konfiguration behalten:

sudo /opt/adguard-shield/adguard-shield uninstall --keep-config

Alles entfernen:

sudo /opt/adguard-shield/adguard-shield uninstall

Ohne --keep-config werden Installationsverzeichnis, State-Verzeichnis und Logdatei entfernt.

Reference in New Issue View Git Blame Copy Permalink