adguard-shield/docs/report.md

E-Mail Report

AdGuard Shield kann Statistik-Reports direkt aus der SQLite-Datenbank erzeugen und per E-Mail versenden. Es gibt in der Go-Version keinen separaten report-generator.sh mehr.

Was der Report enthält

Der Report basiert auf:

/var/lib/adguard-shield/adguard-shield.db

Ausgewertet werden vor allem:

• ban_history
• active_bans

Inhalte:

• Zeitraum des Reports
• Anzahl Sperren im Zeitraum
• Anzahl Freigaben im Zeitraum
• aktuell aktive Sperren
• Top-Clients
• Gründe der Sperren
• Quellen aktiver Sperren
• letzte Ereignisse aus der History

Konfiguration

REPORT_ENABLED=false
REPORT_INTERVAL="weekly"
REPORT_TIME="08:00"
REPORT_EMAIL_TO="admin@example.com"
REPORT_EMAIL_FROM="adguard-shield@example.com"
REPORT_FORMAT="html"
REPORT_MAIL_CMD="msmtp"
REPORT_BUSIEST_DAY_RANGE=30

Parameter:

Parameter	Bedeutung
REPORT_ENABLED	dokumentiert, ob Reports gewünscht sind; der Cron-Job wird über report-install angelegt
REPORT_INTERVAL	daily, weekly, biweekly oder monthly
REPORT_TIME	Uhrzeit im Format HH:MM
REPORT_EMAIL_TO	Empfängeradresse
REPORT_EMAIL_FROM	Absenderadresse
REPORT_FORMAT	html oder txt
REPORT_MAIL_CMD	Mailprogramm, z.B. msmtp
REPORT_BUSIEST_DAY_RANGE	Kompatibilitätsparameter für den Zeitraum "Aktivster Tag"

Beispiel:

REPORT_ENABLED=true
REPORT_INTERVAL="weekly"
REPORT_TIME="08:00"
REPORT_EMAIL_TO="admin@example.com"
REPORT_EMAIL_FROM="adguard-shield@example.com"
REPORT_FORMAT="html"
REPORT_MAIL_CMD="msmtp"

Befehle

# 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

# aktuellen Report erzeugen und versenden
sudo /opt/adguard-shield/adguard-shield report-send

# Cron-Job installieren
sudo /opt/adguard-shield/adguard-shield report-install

# Cron-Job entfernen
sudo /opt/adguard-shield/adguard-shield report-remove

Mailversand

AdGuard Shield übergibt die fertige Mail an ein lokales Mailprogramm. Der Standard ist:

REPORT_MAIL_CMD="msmtp"

Minimaler Ablauf mit msmtp:

sudo apt install msmtp msmtp-mta
sudo /opt/adguard-shield/adguard-shield report-test

report-test sendet eine einfache Testmail. Erst wenn diese funktioniert, lohnt sich die Fehlersuche am eigentlichen Report.

Wenn dein Mailprogramm zusätzliche Argumente braucht, können sie in REPORT_MAIL_CMD stehen. AdGuard Shield hängt intern -t an, damit Empfänger und Header aus der generierten Mail gelesen werden.

Beispiel:

REPORT_MAIL_CMD="msmtp --account=default"

Automatischer Versand

Cron installieren:

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

Dadurch wird diese Datei geschrieben:

/etc/cron.d/adguard-shield-report

Der Cron-Eintrag ruft das installierte Binary mit der installierten Konfiguration auf:

/opt/adguard-shield/adguard-shield -config /opt/adguard-shield/adguard-shield.conf report-send

Zeitplan nach REPORT_INTERVAL:

Intervall	Cron-Verhalten
daily	täglich zur Uhrzeit aus REPORT_TIME
weekly	montags zur Uhrzeit aus REPORT_TIME
biweekly	am 1. und 15. des Monats
monthly	am 1. des Monats

Cron entfernen:

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

Manuelle Prüfung

Status:

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

Report lokal erzeugen:

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

Versand testen:

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

Logs:

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

Je nach Distribution heißt der Cron-Service auch cron, crond oder wird über das allgemeine Syslog protokolliert.

Häufige Probleme

REPORT_EMAIL_TO ist leer

Setze einen Empfänger:

REPORT_EMAIL_TO="admin@example.com"

Mailprogramm nicht gefunden

Prüfen:

which msmtp

Installieren:

sudo apt install msmtp msmtp-mta

Oder REPORT_MAIL_CMD auf dein vorhandenes Mailprogramm setzen.

Cron läuft, aber keine Mail kommt an

Prüfen:

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

Achte darauf, dass:

• REPORT_EMAIL_TO stimmt
• REPORT_MAIL_CMD im Cron-PATH verfügbar ist
• der lokale Mailer für root konfiguriert ist
• Spam-Ordner geprüft wurde
• ausgehende SMTP-Verbindungen erlaubt sind

HTML und TXT

HTML ist für normale E-Mail-Clients angenehmer zu lesen:

REPORT_FORMAT="html"

TXT ist robuster für sehr einfache Mail-Setups oder Log-Ablage:

REPORT_FORMAT="txt"

Du kannst das Format beim manuellen Generieren überschreiben:

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