4f17f7ff81
BREAKING CHANGE: Die alte Shell-Version muss vor der Installation der Go-Version deinstalliert werden.
425 lines
9.7 KiB
Markdown
425 lines
9.7 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
sudo /opt/adguard-shield/adguard-shield live
|
|
```
|
|
|
|
## Service startet nicht
|
|
|
|
Prüfen:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
sudo /opt/adguard-shield/adguard-shield test
|
|
```
|
|
|
|
Prüfe in `/opt/adguard-shield/adguard-shield.conf`:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
WHITELIST="127.0.0.1,::1,192.168.1.1,192.168.1.100"
|
|
```
|
|
|
|
Danach:
|
|
|
|
```bash
|
|
sudo systemctl restart adguard-shield
|
|
```
|
|
|
|
## Firewall prüfen
|
|
|
|
Status:
|
|
|
|
```bash
|
|
sudo /opt/adguard-shield/adguard-shield firewall-status
|
|
```
|
|
|
|
Direkt prüfen:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
sudo /opt/adguard-shield/adguard-shield unban 192.168.1.100
|
|
```
|
|
|
|
## Dry-Run verwenden
|
|
|
|
Dry-Run ist ideal für neue Regeln:
|
|
|
|
```bash
|
|
sudo /opt/adguard-shield/adguard-shield dry-run
|
|
```
|
|
|
|
Währenddessen:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
sudo /opt/adguard-shield/adguard-shield whitelist-status
|
|
```
|
|
|
|
Manuell synchronisieren:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
192.168.1.100
|
|
10.0.0.0/24
|
|
trusted.example.com
|
|
# Kommentare sind erlaubt
|
|
```
|
|
|
|
## Externe Blocklist
|
|
|
|
Status:
|
|
|
|
```bash
|
|
sudo /opt/adguard-shield/adguard-shield blocklist-status
|
|
```
|
|
|
|
Manuell synchronisieren:
|
|
|
|
```bash
|
|
sudo /opt/adguard-shield/adguard-shield blocklist-sync
|
|
```
|
|
|
|
Alle externen Blocklist-Sperren freigeben:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
sudo /opt/adguard-shield/adguard-shield geoip-status
|
|
```
|
|
|
|
Einzelne IP prüfen:
|
|
|
|
```bash
|
|
sudo /opt/adguard-shield/adguard-shield geoip-lookup 8.8.8.8
|
|
```
|
|
|
|
Cache leeren:
|
|
|
|
```bash
|
|
sudo /opt/adguard-shield/adguard-shield geoip-flush-cache
|
|
```
|
|
|
|
Alle GeoIP-Sperren freigeben:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
sudo /opt/adguard-shield/adguard-shield report-status
|
|
```
|
|
|
|
Test:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
sudo cat /etc/cron.d/adguard-shield-report
|
|
sudo /opt/adguard-shield/adguard-shield report-send
|
|
```
|
|
|
|
## Benachrichtigungen
|
|
|
|
Prüfen:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
sudo /opt/adguard-shield/adguard-shield uninstall --keep-config
|
|
```
|
|
|
|
Alles entfernen:
|
|
|
|
```bash
|
|
sudo /opt/adguard-shield/adguard-shield uninstall
|
|
```
|
|
|
|
Ohne `--keep-config` werden Installationsverzeichnis, State-Verzeichnis und Logdatei entfernt.
|