544 lines
14 KiB
Markdown
544 lines
14 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 fünf Befehle liefern meistens schon genug Hinweise, um ein Problem einzugrenzen:
|
|
|
|
```bash
|
|
# 1. Läuft der Service?
|
|
sudo systemctl status adguard-shield
|
|
|
|
# 2. Was sagt das Journal?
|
|
sudo journalctl -u adguard-shield --no-pager -n 100
|
|
|
|
# 3. Funktioniert die API?
|
|
sudo adguard-shield test
|
|
|
|
# 4. Was ist der aktuelle Zustand?
|
|
sudo adguard-shield status
|
|
|
|
# 5. Gibt es Warnungen oder Fehler?
|
|
sudo adguard-shield logs --level warn --limit 100
|
|
```
|
|
|
|
Wenn du aktuelle Queries und den Echtzeit-Zustand sehen willst:
|
|
|
|
```bash
|
|
sudo 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
|
|
|
|
| Ursache | Lösung |
|
|
|---|---|
|
|
| Konfigurationsdatei fehlt | `/opt/adguard-shield/adguard-shield.conf` prüfen |
|
|
| Falsche Dateirechte | `sudo chmod 600 /opt/adguard-shield/adguard-shield.conf` |
|
|
| Binary fehlt oder nicht ausführbar | `ls -l /opt/adguard-shield/adguard-shield` prüfen |
|
|
| Systempakete fehlen | `which iptables ip6tables ipset systemctl` prüfen |
|
|
| API nicht erreichbar | Erst AdGuard Home starten |
|
|
| Alte Shell-Artefakte | Go-Installer meldet Konflikte, alte Version deinstallieren |
|
|
| Unit manuell geändert | `sudo systemctl daemon-reload` ausführen |
|
|
|
|
### Nützliche Prüfbefehle
|
|
|
|
```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 adguard-shield test
|
|
```
|
|
|
|
### Konfiguration prüfen
|
|
|
|
```bash
|
|
ADGUARD_URL="http://127.0.0.1:3000"
|
|
ADGUARD_USER="admin"
|
|
ADGUARD_PASS="..."
|
|
```
|
|
|
|
### Häufige Fehler und Lösungen
|
|
|
|
| Symptom | Mögliche Ursache | Lösung |
|
|
|---|---|---|
|
|
| HTTP 401/403 | Benutzername oder Passwort falsch | Zugangsdaten in der Konfiguration prüfen |
|
|
| HTTP 404 | Falsche URL oder falscher Port | URL und Port prüfen, AdGuard-Home-Weboberfläche testen |
|
|
| Timeout | Firewall, DNS-Problem oder falsche IP | Netzwerk und Erreichbarkeit prüfen |
|
|
| Connection refused | AdGuard Home läuft nicht oder anderer Port | `systemctl status AdGuardHome` prüfen |
|
|
| Keine Querylog-Einträge | Querylog deaktiviert oder leer | In AdGuard Home prüfen: Einstellungen > Querylog |
|
|
|
|
### Direkt testen (unabhängig von AdGuard Shield)
|
|
|
|
```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 adguard-shield live --once
|
|
sudo adguard-shield history 50
|
|
sudo adguard-shield logs --level debug --limit 100
|
|
```
|
|
|
|
### Mögliche Ursachen und Lösungen
|
|
|
|
| Ursache | Lösung |
|
|
|---|---|
|
|
| `RATE_LIMIT_MAX_REQUESTS` zu hoch | Grenzwert senken oder `live` beobachten |
|
|
| `RATE_LIMIT_WINDOW` zu kurz | Zeitfenster verlängern |
|
|
| `API_QUERY_LIMIT` zu niedrig | Erhöhen, damit Spitzen nicht verpasst werden |
|
|
| Client steht in `WHITELIST` | Whitelist prüfen |
|
|
| Externe Whitelist enthält die IP | `whitelist-status` prüfen |
|
|
| Proxy/Forwarder maskiert echte Client-IPs | AdGuard Home sieht nur die Forwarder-IP; Forwarder whitelisten |
|
|
| Querylog enthält die Anfragen nicht | In AdGuard Home prüfen, ob Querylog aktiviert ist |
|
|
| `DRY_RUN=true` ist gesetzt | In der Konfiguration auf `false` setzen |
|
|
|
|
**Wichtig bei Proxies und Forwardern:** Wenn AdGuard Home nur eine einzige interne IP sieht (z.B. die IP eines Routers oder Reverse Proxy), zählt AdGuard Shield auch nur diese IP. In solchen Setups muss die Architektur geprüft oder der Forwarder gewhitelistet werden.
|
|
|
|
---
|
|
|
|
## Zu viele Sperren
|
|
|
|
### Übersicht verschaffen
|
|
|
|
```bash
|
|
sudo adguard-shield status
|
|
sudo adguard-shield history 100
|
|
```
|
|
|
|
### Ursachen und Gegenmaßnahmen
|
|
|
|
| Ursache | Gegenmaßnahme |
|
|
|---|---|
|
|
| Legitimer Client fragt häufig dieselbe Domain | Client whitelisten oder `RATE_LIMIT_MAX_REQUESTS` erhöhen |
|
|
| Router/Resolver bündelt viele Clients | Router/Resolver in `WHITELIST` aufnehmen |
|
|
| CDN/App erzeugt viele Subdomains | `SUBDOMAIN_FLOOD_MAX_UNIQUE` erhöhen |
|
|
| Externe Blocklist ist sehr groß | `blocklist-status` prüfen und ggf. Liste anpassen |
|
|
| GeoIP Allowlist zu eng | Länder prüfen oder `GEOIP_MODE` wechseln |
|
|
|
|
### Falsch gesperrte IP freigeben
|
|
|
|
```bash
|
|
# Sperre aufheben
|
|
sudo adguard-shield unban 192.168.1.100
|
|
|
|
# Offense-Zähler zurücksetzen (damit progressive Sperren nicht sofort eskalieren)
|
|
sudo 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 über AdGuard Shield
|
|
|
|
```bash
|
|
sudo adguard-shield firewall-status
|
|
```
|
|
|
|
### Direkte Prüfung mit Systembefehlen
|
|
|
|
```bash
|
|
# ipsets anzeigen
|
|
sudo ipset list adguard_shield_v4
|
|
sudo ipset list adguard_shield_v6
|
|
|
|
# iptables-Regeln anzeigen
|
|
sudo iptables -n -L ADGUARD_SHIELD --line-numbers -v
|
|
sudo ip6tables -n -L ADGUARD_SHIELD --line-numbers -v
|
|
|
|
# Prüfen, ob Chain in INPUT eingehängt ist
|
|
sudo iptables -n -L INPUT --line-numbers -v | grep ADGUARD
|
|
|
|
# Bei Docker Bridge: DOCKER-USER prüfen
|
|
sudo iptables -n -L DOCKER-USER --line-numbers -v | grep ADGUARD
|
|
```
|
|
|
|
### Firewall neu aufbauen
|
|
|
|
```bash
|
|
sudo adguard-shield firewall-remove
|
|
sudo 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 adguard-shield status
|
|
sudo adguard-shield history 100
|
|
```
|
|
|
|
Temporäre Sperren werden beim Start und während jedes Pollings auf Ablauf geprüft. Wenn eine Sperre als permanent angezeigt wird, wird sie nicht automatisch freigegeben.
|
|
|
|
### Permanente Sperren (gewollt)
|
|
|
|
| Typ | Warum permanent |
|
|
|---|---|
|
|
| DNS-Flood-Watchlist-Treffer | Sofortiger Permanent-Ban |
|
|
| Progressive-Ban auf Maximalstufe | Eskalation durch wiederholte Verstöße |
|
|
| Manuelle `ban`-Sperren | Manuell gesetzt, manuell aufheben |
|
|
| GeoIP-Sperren | Permanent bis Konfigurationsänderung |
|
|
| Externe Blocklist mit `BAN_DURATION=0` | Permanent bis IP aus Liste entfernt |
|
|
|
|
### Manuell freigeben
|
|
|
|
```bash
|
|
sudo adguard-shield unban 192.168.1.100
|
|
```
|
|
|
|
---
|
|
|
|
## Dry-Run verwenden
|
|
|
|
Dry-Run ist ideal, um neue Konfigurationen zu prüfen, bevor sie produktiv gehen:
|
|
|
|
```bash
|
|
# Dry-Run starten (Strg+C zum Beenden)
|
|
sudo adguard-shield dry-run
|
|
```
|
|
|
|
Währenddessen die Ergebnisse prüfen:
|
|
|
|
```bash
|
|
sudo 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 prüfen
|
|
|
|
```bash
|
|
sudo adguard-shield whitelist-status
|
|
```
|
|
|
|
### Manuell synchronisieren
|
|
|
|
```bash
|
|
sudo adguard-shield whitelist-sync
|
|
```
|
|
|
|
### Typische Probleme
|
|
|
|
| Problem | Lösung |
|
|
|---|---|
|
|
| URL nicht erreichbar | URL im Browser oder mit `curl` testen |
|
|
| Windows-Zeilenenden oder BOM | Datei in UTF-8 ohne BOM und mit `LF`-Zeilenenden speichern |
|
|
| Hostname nicht auflösbar | DNS-Auflösung prüfen, ggf. alternativen Hostnamen verwenden |
|
|
| Einträge enthalten Ports oder URLs | Nur IPs, CIDR-Netze und Hostnamen werden unterstützt |
|
|
| DNS liefert `0.0.0.0` | AdGuard blockiert den Host; Ausnahme in AdGuard Home einrichten |
|
|
|
|
### Erwartetes Listenformat
|
|
|
|
```text
|
|
192.168.1.100 # IPv4-Adresse
|
|
10.0.0.0/24 # CIDR-Netz
|
|
trusted.example.com # Hostname (wird per DNS aufgelöst)
|
|
# Kommentare sind erlaubt
|
|
```
|
|
|
|
---
|
|
|
|
## Externe Blocklist
|
|
|
|
### Status prüfen
|
|
|
|
```bash
|
|
sudo adguard-shield blocklist-status
|
|
```
|
|
|
|
### Manuell synchronisieren
|
|
|
|
```bash
|
|
sudo adguard-shield blocklist-sync
|
|
```
|
|
|
|
### Alle Blocklist-Sperren freigeben
|
|
|
|
```bash
|
|
sudo adguard-shield blocklist-flush
|
|
```
|
|
|
|
### Zu viele IPs gesperrt?
|
|
|
|
1. `EXTERNAL_BLOCKLIST_URLS` prüfen: Welche Listen sind konfiguriert?
|
|
2. Liste manuell ansehen: Wie viele Einträge enthält sie?
|
|
3. Whitelist ergänzen: Eigene IPs sollten dort stehen.
|
|
4. `EXTERNAL_BLOCKLIST_NOTIFY=false` belassen, um den Benachrichtigungskanal nicht zu überfluten.
|
|
5. `EXTERNAL_BLOCKLIST_AUTO_UNBAN=true` setzen, damit entfernte Einträge automatisch freigegeben werden.
|
|
|
|
---
|
|
|
|
## GeoIP
|
|
|
|
### Status prüfen
|
|
|
|
```bash
|
|
sudo adguard-shield geoip-status
|
|
```
|
|
|
|
### Einzelne IP prüfen
|
|
|
|
```bash
|
|
sudo adguard-shield geoip-lookup 8.8.8.8
|
|
```
|
|
|
|
### Cache leeren
|
|
|
|
```bash
|
|
sudo adguard-shield geoip-flush-cache
|
|
```
|
|
|
|
### Alle GeoIP-Sperren freigeben
|
|
|
|
```bash
|
|
sudo adguard-shield geoip-flush
|
|
```
|
|
|
|
### Typische Probleme und Lösungen
|
|
|
|
| Problem | Lösung |
|
|
|---|---|
|
|
| Keine Länder erkannt | MaxMind-Key, MMDB-Pfad oder `geoiplookup`-Befehl prüfen |
|
|
| Private IPs werden nicht geprüft | `GEOIP_SKIP_PRIVATE=true` ist Standard und korrekt |
|
|
| 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; alle anderen werden gesperrt |
|
|
| Datenbank nicht gefunden | `GEOIP_LICENSE_KEY` oder `GEOIP_MMDB_PATH` setzen |
|
|
| Datenbank veraltet | `geoip-flush-cache` und Service neu starten |
|
|
|
|
### Ländercodes nachschlagen
|
|
|
|
Die GeoIP-Ländercodes folgen dem Standard ISO 3166-1 Alpha-2. Eine vollständige Liste findest du in der [ISO-3166-1-Kodierliste auf Wikipedia](https://de.wikipedia.org/wiki/ISO-3166-1-Kodierliste).
|
|
|
|
---
|
|
|
|
## Reports
|
|
|
|
### Status prüfen
|
|
|
|
```bash
|
|
sudo adguard-shield report-status
|
|
```
|
|
|
|
### Funktionstest
|
|
|
|
```bash
|
|
# Testmail senden
|
|
sudo adguard-shield report-test
|
|
|
|
# Text-Report in der Konsole ansehen
|
|
sudo adguard-shield report-generate txt
|
|
```
|
|
|
|
### Keine Mail kommt an?
|
|
|
|
| Prüfpunkt | Befehl / Aktion |
|
|
|---|---|
|
|
| `REPORT_EMAIL_TO` gesetzt? | Konfiguration prüfen |
|
|
| `REPORT_MAIL_CMD` vorhanden? | `which msmtp` |
|
|
| Mailer für root konfiguriert? | `/root/.msmtprc` oder `/etc/msmtprc` prüfen |
|
|
| Cron installiert? | `sudo cat /etc/cron.d/adguard-shield-report` |
|
|
| Spam-Ordner geprüft? | E-Mail-Provider prüfen |
|
|
| SMTP-Port offen? | Ausgehende Verbindung auf Port 587/465 testen |
|
|
|
|
### Cron prüfen
|
|
|
|
```bash
|
|
sudo cat /etc/cron.d/adguard-shield-report
|
|
sudo adguard-shield report-send
|
|
```
|
|
|
|
---
|
|
|
|
## Benachrichtigungen
|
|
|
|
### Prüfen
|
|
|
|
```bash
|
|
sudo adguard-shield logs --level warn --limit 100
|
|
```
|
|
|
|
### Checkliste
|
|
|
|
| Prüfpunkt | Beschreibung |
|
|
|---|---|
|
|
| `NOTIFY_ENABLED=true` | Benachrichtigungen global aktiviert? |
|
|
| `NOTIFY_TYPE` | Korrekt geschrieben? (`ntfy`, `discord`, `slack`, `gotify`, `generic`) |
|
|
| Webhook-URL | Gesetzt und erreichbar? |
|
|
| Ntfy-Topic | Nicht leer? |
|
|
| Token | Gültig und nicht abgelaufen? |
|
|
| Netzwerk | Ausgehende HTTPS-Verbindungen möglich? |
|
|
| Modul-Schalter | `EXTERNAL_BLOCKLIST_NOTIFY` und `GEOIP_NOTIFY` separat prüfen |
|
|
|
|
Bei `generic` Webhook kannst du testweise einen lokalen HTTP-Empfänger oder einen Request-Inspector (z.B. webhook.site) verwenden, um den gesendeten Payload zu sehen.
|
|
|
|
---
|
|
|
|
## SQLite direkt auswerten
|
|
|
|
Für tiefergehende Analysen kannst du die SQLite-Datenbank direkt abfragen:
|
|
|
|
### Sperren nach Quelle und Grund
|
|
|
|
```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-Einträge
|
|
|
|
```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;"
|
|
```
|
|
|
|
### Whitelist-Cache
|
|
|
|
```bash
|
|
sudo sqlite3 /var/lib/adguard-shield/adguard-shield.db \
|
|
"SELECT ip, source FROM whitelist_cache ORDER BY ip;"
|
|
```
|
|
|
|
### GeoIP-Cache
|
|
|
|
```bash
|
|
sudo sqlite3 /var/lib/adguard-shield/adguard-shield.db \
|
|
"SELECT ip, country_code FROM geoip_cache ORDER BY ip LIMIT 50;"
|
|
```
|
|
|
|
---
|
|
|
|
## Alte Shell-Artefakte entfernen
|
|
|
|
Wenn der Installer alte Dateien meldet, zuerst sauber migrieren. Typische alte Dateien:
|
|
|
|
| Datei | Funktion in der alten Version |
|
|
|---|---|
|
|
| `adguard-shield.sh` | Hauptskript |
|
|
| `iptables-helper.sh` | Firewall-Management |
|
|
| `external-blocklist-worker.sh` | Blocklist-Synchronisation |
|
|
| `external-whitelist-worker.sh` | Whitelist-Synchronisation |
|
|
| `geoip-worker.sh` | GeoIP-Prüfung |
|
|
| `offense-cleanup-worker.sh` | Offense-Bereinigung |
|
|
| `report-generator.sh` | Report-Erstellung |
|
|
| `unban-expired.sh` | Ablauf temporärer Sperren |
|
|
| `adguard-shield-watchdog.sh` | Watchdog-Skript |
|
|
|
|
Die Go-Version ersetzt diese Funktionen durch das eine Binary. Alte Worker sollten nicht parallel laufen.
|
|
|
|
Details zur Migration stehen in der [Update-Anleitung](update.md).
|
|
|
|
---
|
|
|
|
## Service hart zurücksetzen
|
|
|
|
Wenn der Zustand unklar ist und ein sauberer Neustart nötig ist:
|
|
|
|
```bash
|
|
# Service stoppen
|
|
sudo systemctl stop adguard-shield
|
|
|
|
# Firewall-Struktur entfernen
|
|
sudo adguard-shield firewall-remove
|
|
|
|
# Service neu starten (baut Firewall aus SQLite wieder auf)
|
|
sudo systemctl start adguard-shield
|
|
|
|
# Status prüfen
|
|
sudo adguard-shield status
|
|
```
|
|
|
|
Das entfernt die Firewall-Struktur und lässt den Daemon sie beim Start wieder aus dem SQLite-State aufbauen. Aktive Sperren bleiben in der Datenbank erhalten.
|
|
|
|
---
|
|
|
|
## Deinstallation
|
|
|
|
### Konfiguration behalten
|
|
|
|
```bash
|
|
sudo adguard-shield uninstall --keep-config
|
|
```
|
|
|
|
### Alles entfernen
|
|
|
|
```bash
|
|
sudo adguard-shield uninstall
|
|
```
|
|
|
|
Ohne `--keep-config` werden Installationsverzeichnis, State-Verzeichnis und Logdatei entfernt.
|
|
|
|
---
|
|
|
|
## Zusammenfassung: Wichtigste Diagnosebefehle
|
|
|
|
| Befehl | Zweck |
|
|
|---|---|
|
|
| `systemctl status adguard-shield` | Service-Status prüfen |
|
|
| `journalctl -u adguard-shield -n 100` | Systemd-Journal ansehen |
|
|
| `test` | API-Verbindung prüfen |
|
|
| `status` | Aktuellen Zustand und aktive Sperren anzeigen |
|
|
| `live` | Echtzeit-Ansicht mit Queries, Sperren und Logs |
|
|
| `history 100` | Ban-History anzeigen |
|
|
| `logs --level warn --limit 100` | Warnungen und Fehler anzeigen |
|
|
| `firewall-status` | Firewall-Regeln und ipsets anzeigen |
|
|
| `dry-run` | Konfiguration testen ohne echte Sperren |
|