Files
adguard-shield/docs/befehle.md
2026-05-01 01:17:05 +02:00

22 KiB

Befehle & Nutzung

AdGuard Shield wird in der Go-Version über ein einzelnes Binary bedient:

/opt/adguard-shield/adguard-shield

Dieses Binary ist Daemon, CLI, Installer, Updater, Uninstaller und Report-Generator. Dadurch gibt es keine getrennten Shell-Skripte mehr.

Grundform

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

Wenn du eine andere Konfigurationsdatei verwenden möchtest, muss -config direkt vor dem Befehl stehen:

sudo /opt/adguard-shield/adguard-shield -config /pfad/zur/adguard-shield.conf status

Standardpfade

Datei Pfad
Binary /opt/adguard-shield/adguard-shield
Konfiguration /opt/adguard-shield/adguard-shield.conf
SQLite-Datenbank /var/lib/adguard-shield/adguard-shield.db
Logdatei /var/log/adguard-shield.log
PID-Datei /var/run/adguard-shield.pid

Schnellübersicht

# Version anzeigen
/opt/adguard-shield/adguard-shield version

# Installation und Update
sudo ./adguard-shield install
sudo ./adguard-shield update
sudo ./adguard-shield install-status
sudo /opt/adguard-shield/adguard-shield uninstall --keep-config

# Service-Management über systemd
sudo systemctl start adguard-shield
sudo systemctl stop adguard-shield
sudo systemctl restart adguard-shield
sudo systemctl status adguard-shield

# Diagnose und Monitoring
sudo /opt/adguard-shield/adguard-shield test
sudo /opt/adguard-shield/adguard-shield status
sudo /opt/adguard-shield/adguard-shield live
sudo /opt/adguard-shield/adguard-shield history 100
sudo /opt/adguard-shield/adguard-shield logs --level warn --limit 100

# Manuelle Eingriffe
sudo /opt/adguard-shield/adguard-shield ban 192.168.1.100
sudo /opt/adguard-shield/adguard-shield unban 192.168.1.100
sudo /opt/adguard-shield/adguard-shield flush

Installation

Das installierte Binary landet standardmäßig unter:

/opt/adguard-shield/adguard-shield

Standardinstallation

chmod +x ./adguard-shield
sudo ./adguard-shield install

Am Ende fragt der Installer, ob AdGuard Shield direkt gestartet oder neu gestartet werden soll.

Installationsoptionen

Option Beschreibung
--config-source <pfad> Bestehende Konfigurationsdatei als Vorlage übernehmen
--skip-deps Automatische Paketprüfung und -installation überspringen
--no-enable systemd-Autostart nicht aktivieren
--install-dir <pfad> Abweichendes Installationsverzeichnis verwenden

Beispiele:

# Konfiguration aus anderem Pfad übernehmen
sudo ./adguard-shield install --config-source ./adguard-shield.conf

# Ohne Paketprüfung installieren
sudo ./adguard-shield install --skip-deps

# In anderes Verzeichnis installieren
sudo ./adguard-shield install --install-dir /opt/adguard-shield-test

Was der Installer macht

Der Installer führt diese Schritte automatisch durch:

Schritt Beschreibung
1 Linux- und Root-Prüfung
2 Prüfung auf alte Shell-Artefakte
3 Installation fehlender Abhängigkeiten über apt-get (sofern möglich)
4 Anlage von Installations- und State-Verzeichnissen
5 Kopieren des Binarys nach /opt/adguard-shield/
6 Anlage oder Migration der Konfiguration
7 Schreiben der systemd-Unit
8 systemctl daemon-reload
9 Optional: Autostart aktivieren
10 Nachfrage: Service direkt starten oder neu starten

Benötigte Systembefehle

Befehl Paket (Debian/Ubuntu) Zweck
iptables iptables IPv4-Firewall
ip6tables iptables IPv6-Firewall
ipset ipset IP-Set-Verwaltung für performante Sperren
systemctl systemd Service-Management

Auf Debian/Ubuntu installiert der Installer passende Pakete automatisch, sofern apt-get verfügbar ist und --skip-deps nicht gesetzt wurde.


Update

Ein Update wird immer mit dem neuen Binary ausgeführt, nicht mit dem bereits installierten alten Binary:

chmod +x ./adguard-shield
sudo ./adguard-shield update

Am Ende fragt der Updater, ob AdGuard Shield direkt neu gestartet werden soll.

Update mit expliziter Konfigurationsquelle

sudo ./adguard-shield update --config-source ./adguard-shield.conf

Was beim Update passiert

  • Die Installation wird wie bei install aktualisiert
  • Vorhandene Konfiguration bleibt erhalten
  • Neue Konfigurationsparameter werden ergänzt
  • Bei einer Migration wird adguard-shield.conf.old geschrieben
  • Die systemd-Unit wird neu geschrieben und systemd neu geladen

Weitere Details stehen in der Update-Anleitung.


Installationsstatus

sudo ./adguard-shield install-status

Zeigt eine Übersicht mit:

  • Installationspfad und Binary-Status
  • Installierte Version
  • Konfiguration vorhanden
  • systemd-Service vorhanden und Status
  • Autostart aktiv
  • Gefundene Legacy-Artefakte

Für ein anderes Installationsverzeichnis:

sudo ./adguard-shield install-status --install-dir /opt/adguard-shield-test

Deinstallation

# Vollständige Deinstallation
sudo /opt/adguard-shield/adguard-shield uninstall

# Deinstallation mit Konfigurationserhalt
sudo /opt/adguard-shield/adguard-shield uninstall --keep-config

Was bei der Deinstallation passiert:

Schritt Beschreibung
1 Service stoppen
2 Autostart deaktivieren
3 Shield-Firewall-Struktur entfernen (Chain, ipsets)
4 systemd-Unit löschen
5 systemd neu laden
6 Installationsverzeichnis, State und Log entfernen

Mit --keep-config bleiben Konfigurationsdaten erhalten. Das ist sinnvoll, wenn du neu installieren oder migrieren möchtest.


Alte Shell-Installation

Die Go-Version darf nicht parallel zur alten Shell-Version laufen. Der Installer bricht ab, wenn er alte Artefakte findet, zum Beispiel:

/opt/adguard-shield/adguard-shield.sh
/opt/adguard-shield/iptables-helper.sh
/opt/adguard-shield/external-blocklist-worker.sh
/opt/adguard-shield/geoip-worker.sh
/etc/systemd/system/adguard-shield-watchdog.timer

Empfohlener Ablauf:

  1. Bestehende /opt/adguard-shield/adguard-shield.conf sichern.
  2. Alte Shell-Version mit deren Uninstaller entfernen und die Konfiguration behalten.
  3. Go-Binary erneut installieren.
  4. Konfiguration prüfen.
  5. Zuerst dry-run, dann produktiven Service starten.

Weitere Details stehen in der Update-Anleitung.


systemd-Service

Im produktiven Betrieb sollte AdGuard Shield über systemd laufen:

sudo systemctl start adguard-shield      # Service starten
sudo systemctl stop adguard-shield       # Service stoppen
sudo systemctl restart adguard-shield    # Service neu starten
sudo systemctl status adguard-shield     # Status anzeigen

Autostart

sudo systemctl enable adguard-shield     # Autostart aktivieren
sudo systemctl disable adguard-shield    # Autostart deaktivieren

Nach manuellen Änderungen an der Unit

sudo systemctl daemon-reload

Startbefehl der Unit

Die systemd-Unit startet den Daemon mit:

/opt/adguard-shield/adguard-shield -config /opt/adguard-shield/adguard-shield.conf run

Die Go-Version nutzt Restart=on-failure mit RestartSec=30s. Einen separaten Watchdog-Service oder Watchdog-Timer gibt es nicht mehr.


Daemon direkt starten

Für Debugging oder Dry-Run kann der Daemon im Vordergrund gestartet werden:

# Normaler Vordergrundlauf
sudo /opt/adguard-shield/adguard-shield run

# Alias für run
sudo /opt/adguard-shield/adguard-shield start

# Analysieren ohne echte Sperren
sudo /opt/adguard-shield/adguard-shield dry-run

Daemon über PID-Datei stoppen

sudo /opt/adguard-shield/adguard-shield stop

Für den Alltag gilt: Nutze systemctl. Der direkte Vordergrundlauf endet, sobald die Shell beendet wird oder du Strg+C drückst.


API-Test

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

Der test-Befehl prüft die Verbindung zur AdGuard-Home-API:

Prüfung Was getestet wird
Netzwerk Ist ADGUARD_URL erreichbar?
TLS Funktioniert HTTPS/TLS?
Authentifizierung Stimmen ADGUARD_USER und ADGUARD_PASS?
Querylog Liefert AdGuard Home Querylog-Daten?

Bei Erfolg:

Verbindung erfolgreich. 123 Querylog-Einträge gefunden.

Wenn der Test fehlschlägt, zuerst die Konfiguration und die AdGuard-Home-Weboberfläche prüfen.


Status

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

Zeigt eine Übersicht des aktuellen Zustands:

  • Verwendete Konfigurationsdatei
  • Firewall-Backend, -Modus und Chain
  • GeoIP-Aktivierung, Modus und Länderliste
  • Externe Blocklist (aktiv/inaktiv, Anzahl URLs)
  • Externe Whitelist (aktiv/inaktiv, Anzahl URLs)
  • Aktive Sperren mit IP, Quelle, Grund und Ablaufzeit

Bei sehr vielen aktiven Sperren werden nur die ersten 50 angezeigt. Für Details nutze history oder frage SQLite direkt ab.


Live-Ansicht

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

Die live-Ansicht ist das beste Werkzeug, wenn du verstehen möchtest, was gerade passiert. Sie zeigt in Echtzeit:

Bereich Inhalt
Query-Poller API-Einträge, Zeitfenster und Rate-Limit-Status
Top-Kombinationen Häufigste Client/Domain-Paare
Subdomain-Flood Aktuelle Subdomain-Flood-Kandidaten
Letzte Queries Die neuesten Querylog-Einträge
Aktive Sperren Alle derzeit gesperrten IPs
Externe Listen Status von Blocklist und Whitelist
GeoIP GeoIP-Konfiguration und Status
Offense-Cleanup Progressive-Ban-Status
Systemereignisse Aktuelle Logeinträge

Optionen

Option Beschreibung Beispiel
--interval <sek> Aktualisierungsintervall in Sekunden live --interval 2
--top <n> Anzahl der Top-Einträge live --top 20
--recent <n> Anzahl letzter Queries und Logs live --recent 25
--logs <level> Log-Level anzeigen (debug, info, warn, error, off) live --logs debug
--once Einmaligen Snapshot ausgeben, nicht fortlaufend live --once

Alias

sudo /opt/adguard-shield/adguard-shield watch

History

# Letzte 50 Einträge (Standard)
sudo /opt/adguard-shield/adguard-shield history

# Letzte 200 Einträge
sudo /opt/adguard-shield/adguard-shield history 200

Die History kommt aus der SQLite-Tabelle ban_history.

Ausgabeformat

Zeit | Aktion | Client-IP | Domain | Anzahl | Dauer | Protokoll | Grund

Aktionstypen

Aktion Bedeutung
BAN Echte Sperre gesetzt
UNBAN Sperre aufgehoben
DRY Im Dry-Run erkannt, aber nicht gesperrt

Sperrgründe

Grund Bedeutung
rate-limit Gleiche Domain zu oft angefragt
subdomain-flood Zu viele eindeutige Subdomains einer Basisdomain
dns-flood-watchlist Watchlist-Treffer mit sofortigem Permanent-Ban
external-blocklist Sperre aus externer Blocklist
geoip GeoIP-Länderfilter
manual Manueller Ban oder Unban
manual-flush Freigabe durch flush
expired Temporäre Sperre abgelaufen
external-whitelist Freigabe durch externe Whitelist
geoip-flush Freigabe aller GeoIP-Sperren
external-blocklist-flush Freigabe aller Blocklist-Sperren

Logs

AdGuard Shield schreibt Daemon-Ereignisse in LOG_FILE, standardmäßig:

/var/log/adguard-shield.log

CLI-Befehle

# Letzte INFO/WARN/ERROR-Einträge
sudo /opt/adguard-shield/adguard-shield logs

# Letzte 100 Warnungen und Fehler
sudo /opt/adguard-shield/adguard-shield logs --level warn --limit 100

# Kurzform (Level als Argument)
sudo /opt/adguard-shield/adguard-shield logs debug

# Laufende Ansicht (wie tail -f)
sudo /opt/adguard-shield/adguard-shield logs-follow --level info

Erlaubte Log-Level

Level Beschreibung
DEBUG Detaillierte Informationen für Fehlersuche
INFO Normale Betriebsmeldungen (Start, Sperren, Freigaben)
WARN Warnungen (z.B. API-Fehler, fehlende Dateien)
ERROR Fehler, die den Betrieb beeinträchtigen

systemd-Journal

sudo journalctl -u adguard-shield -f
sudo journalctl -u adguard-shield --no-pager -n 100

Hinweis: Query-Inhalte werden nicht dauerhaft in die Logdatei geschrieben. Für Query-nahe Diagnose ist die live-Ansicht gedacht.


Manuelle Sperren und Freigaben

IP permanent sperren

sudo /opt/adguard-shield/adguard-shield ban 192.168.1.100

Legt eine manuelle permanente Sperre an. Die IP wird sofort in die Firewall eingetragen.

IP entsperren

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

Entfernt die IP aus Firewall und Datenbank. Funktioniert für alle Sperrtypen (automatisch, manuell, GeoIP, Blocklist).

Alle Sperren aufheben

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

Hebt alle aktiven Sperren auf. Bei aktivierten Benachrichtigungen wird eine zusammenfassende Meldung gesendet, nicht eine Nachricht pro IP.

Wichtig: Whitelist-Regeln gelten auch für manuelle Sperren. Eine IP aus WHITELIST oder externer Whitelist wird nicht gesperrt.


Progressive Sperren und Offenses

Offense-Status anzeigen

sudo /opt/adguard-shield/adguard-shield offense-status

Zeigt die Gesamtzahl der Offense-Zähler, davon abgelaufene, und die Konfiguration.

Abgelaufene Zähler entfernen

sudo /opt/adguard-shield/adguard-shield offense-cleanup

Alle Offense-Zähler zurücksetzen

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

Zähler für eine IP zurücksetzen

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

Typischer Ablauf nach Fehlkonfiguration

Wenn ein Client fälschlicherweise eskaliert wurde:

# Sperre aufheben
sudo /opt/adguard-shield/adguard-shield unban 192.168.1.100

# Offense-Zähler zurücksetzen
sudo /opt/adguard-shield/adguard-shield reset-offenses 192.168.1.100

# IP dauerhaft in Whitelist aufnehmen (in adguard-shield.conf)
# WHITELIST="127.0.0.1,::1,192.168.1.100"
sudo systemctl restart adguard-shield

Firewall-Befehle

Chain und ipsets anlegen

sudo /opt/adguard-shield/adguard-shield firewall-create

Status anzeigen

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

Zeigt die aktuelle Firewall-Struktur: Chain, ipsets und eingehängte Regeln.

ipsets leeren

sudo /opt/adguard-shield/adguard-shield firewall-flush

Entfernt alle IPs aus den ipsets. Die Firewall-Struktur (Chain, Regeln) bleibt bestehen.

Chain und ipsets vollständig entfernen

sudo /opt/adguard-shield/adguard-shield firewall-remove

Firewall-Regeln sichern

sudo /opt/adguard-shield/adguard-shield firewall-save

Speichert die aktuellen Regeln nach:

/var/lib/adguard-shield/iptables-rules.v4
/var/lib/adguard-shield/iptables-rules.v6

Gesicherte Regeln wiederherstellen

sudo /opt/adguard-shield/adguard-shield firewall-restore

Hinweis: Normalerweise musst du diese Befehle nicht manuell ausführen. Der Daemon erstellt die Firewall beim Start und schreibt aktive Sperren aus SQLite wieder hinein. Welche Host-Chain genutzt wird, hängt von FIREWALL_MODE ab. Details stehen in Docker-Installationen.


Externe Whitelist

Status anzeigen

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

Sofort synchronisieren

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

Aufgelöste externe Whitelist entfernen

sudo /opt/adguard-shield/adguard-shield whitelist-flush

Hinweise

  • Die externe Whitelist kann IPs, CIDR-Netze und Hostnamen enthalten.
  • Hostnamen werden per DNS aufgelöst und als IPs in SQLite gespeichert.
  • Eine gewhitelistete IP wird nicht gesperrt.
  • Wird eine bereits gesperrte IP später gewhitelistet, wird sie automatisch freigegeben.
  • Die dauerhafte Synchronisation läuft im Daemon im konfigurierten Intervall.
  • whitelist-sync erzwingt nur einen einzelnen, sofortigen Lauf.

Externe Blocklist

Status anzeigen

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

Sofort synchronisieren

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

Alle Sperren aus externer Blocklist aufheben

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

Hinweise

  • Die externe Blocklist kann IPs, CIDR-Netze und Hostnamen enthalten.
  • Hostnamen werden per DNS aufgelöst.
  • IPs aus der Whitelist werden übersprungen.
  • Bei EXTERNAL_BLOCKLIST_AUTO_UNBAN=true hebt der Daemon Blocklist-Sperren automatisch auf, sobald sie nicht mehr in der externen Liste vorkommen.

GeoIP

Status anzeigen

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

Einzelne IP nachschlagen

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

Ausgabe:

IP: 8.8.8.8 -> Land: US

Aktuelle Clients prüfen

sudo /opt/adguard-shield/adguard-shield geoip-sync

Liest das aktuelle Querylog und prüft alle darin enthaltenen Client-IPs einmalig gegen die GeoIP-Regeln.

Alle GeoIP-Sperren aufheben

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

Cache leeren

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

Hinweise

  • GeoIP-Sperren sind permanent, werden aber bei Konfigurationsänderungen automatisch neu bewertet.
  • Die Ländercodes verwenden ISO 3166-1 Alpha-2 (siehe ISO-3166-1-Kodierliste auf Wikipedia).

Reports

Konfiguration und Cron-Status anzeigen

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

HTML-Report in Datei schreiben

sudo /opt/adguard-shield/adguard-shield report-generate html /tmp/adguard-shield-report.html

Text-Report auf stdout ausgeben

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

Testmail senden

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

Sendet eine einfache Testmail. Erst wenn diese funktioniert, lohnt sich die Fehlersuche am eigentlichen Report.

Aktuellen Report erzeugen und versenden

sudo /opt/adguard-shield/adguard-shield report-send

Cron-Job installieren

sudo /opt/adguard-shield/adguard-shield report-install

Erstellt die Datei /etc/cron.d/adguard-shield-report mit dem konfigurierten Intervall und der Versandzeit.

Cron-Job entfernen

sudo /opt/adguard-shield/adguard-shield report-remove

Details zum Report-System stehen in E-Mail Report.


Dry-Run

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

Der Dry-Run ist der sicherste Weg, neue Konfigurationen zu prüfen, bevor sie produktiv gehen.

Verhalten im Dry-Run

Was passiert Was nicht passiert
Querylogs werden normal gelesen Keine aktiven Bans werden angelegt
Rate-Limit, Subdomain-Flood, Watchlist werden ausgewertet Keine Firewall-Regeln werden gesetzt
GeoIP und externe Blocklist werden geprüft Keine Benachrichtigungen werden gesendet
Mögliche Sperren werden als DRY in die History geschrieben

Typischer Ablauf nach größeren Änderungen

# Dry-Run starten (Strg+C zum Beenden)
sudo /opt/adguard-shield/adguard-shield dry-run

# Ergebnisse prüfen
sudo /opt/adguard-shield/adguard-shield history 50
sudo /opt/adguard-shield/adguard-shield logs --level warn --limit 80

Version

/opt/adguard-shield/adguard-shield version

Zeigt die installierte Version an. Aliase: --version, -v.


Typische Betriebsabläufe

Nach Konfigurationsänderung

sudo systemctl restart adguard-shield
sudo /opt/adguard-shield/adguard-shield status
sudo /opt/adguard-shield/adguard-shield logs --level info --limit 80

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

Danach die IP dauerhaft in WHITELIST oder eine externe Whitelist aufnehmen.

Externe Listen neu laden

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

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 schreibt der Daemon aktive Sperren aus SQLite wieder in die Firewall.

Service-Problem eingrenzen

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 logs --level debug --limit 100

DNS-Abfragen zum Testen

Die folgenden Befehle sind ausschließlich für kontrollierte Tests gegen deinen eigenen DNS-Server gedacht. Ersetze 203.0.113.50 durch deine eigene DNS-Server-IP und example.com durch eine Testdomain.

Nicht gegen fremde DNS-Server, fremde Dienste oder fremde Infrastruktur verwenden.

Voraussetzungen auf dem Testclient

Protokoll Paket Installationsbefehl
Klassisches DNS dnsutils sudo apt install dnsutils
DNS-over-HTTPS curl sudo apt install curl
DNS-over-TLS knot-dnsutils sudo apt install knot-dnsutils

Klassisches DNS: Rate-Limit testen

Gleiche Domain mehrfach abfragen (40 parallele Anfragen):

for i in {1..40}; do \
  dig @203.0.113.50 example.com +short +cookie=$(openssl rand -hex 8) > /dev/null & \
done; wait

Klassisches DNS: Subdomain-Flood testen

Viele zufällige Subdomains abfragen (60 parallele Anfragen):

for i in {1..60}; do \
  dig @203.0.113.50 $(openssl rand -hex 6).example.com +short > /dev/null & \
done; wait

DNS-over-HTTPS testen

for i in {1..40}; do \
  curl -s -H "accept: application/dns-json" \
    "https://203.0.113.50/dns-query?name=example.com&type=A" > /dev/null & \
done; wait

Bei selbstsigniertem Zertifikat auf dem eigenen Testserver kann für diesen lokalen Test -k ergänzt werden.

DNS-over-TLS testen

for i in {1..40}; do \
  kdig @203.0.113.50 example.com +tls +short > /dev/null & \
done; wait

Die Beispielzahlen liegen bewusst nahe an den Standardlimits RATE_LIMIT_MAX_REQUESTS=30 und SUBDOMAIN_FLOOD_MAX_UNIQUE=50.


Eingebaute Hilfe

/opt/adguard-shield/adguard-shield --help

Bei unbekannten Befehlen gibt das Binary die Usage-Ausgabe aus.