8.5 KiB
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 der SQLite-Datenbank:
/var/lib/adguard-shield/adguard-shield.db
Ausgewertete Daten
| Bereich | Inhalt |
|---|---|
| Zeitraum | Start- und Enddatum des Berichtszeitraums |
| Sperren | Anzahl der Sperren im Zeitraum |
| Freigaben | Anzahl der Freigaben im Zeitraum |
| Zeitraum-Schnellübersicht | Heute (ab 20 Uhr), gestern, letzte 7/14/30 volle Tage bis gestern |
| Aktive Sperren | Derzeit aktive Sperren zum Zeitpunkt der Report-Erstellung |
| Permanente Sperren | Anzahl permanenter Sperren im Zeitraum |
| AbuseIPDB | Anzahl erfolgreicher AbuseIPDB-Meldungen im Zeitraum |
| Angriffsarten | Rate-Limit, Subdomain-Flood, DNS-Flood Watchlist, externe Blocklist, GeoIP, manuell (ggf. Sonstige) mit Anteil und Summe |
| Top-Clients | Die 10 am häufigsten gesperrten Client-IPs |
| Top-Domains | Die 10 am häufigsten betroffenen Domains (ohne GeoIP-, Blocklist- und manuelle Sperren) |
| Protokolle | Verteilung nach DNS, DoH, DoT, DoQ usw.; Sperren ohne Protokoll (GeoIP, Blocklist, manuell) erscheinen als "ohne Protokoll" |
| Letzte Sperren | Die letzten 10 Sperren im Berichtszeitraum |
Templates
Die Standard-Templates liegen im Code unter:
internal/report/templates/report.html
internal/report/templates/report.txt
Sie werden ins Binary eingebettet und bei install sowie update nach /opt/adguard-shield/templates geschrieben. Zur Laufzeit verwendet AdGuard Shield zuerst externe Templates aus ADGUARD_SHIELD_TEMPLATE_DIR, danach templates neben der Konfiguration bzw. neben dem Binary und fällt erst zuletzt auf die eingebetteten Standard-Templates zurück.
Konfiguration
| Parameter | Standard | Beschreibung |
|---|---|---|
REPORT_ENABLED |
false |
Report-Funktion logisch aktivieren |
REPORT_INTERVAL |
weekly |
Versandintervall |
REPORT_TIME |
08:00 |
Versandzeit im Format HH:MM |
REPORT_EMAIL_TO |
admin@example.com |
Empfängeradresse |
REPORT_EMAIL_FROM |
adguard-shield@example.com |
Absenderadresse |
REPORT_FORMAT |
html |
Report-Format (html oder txt) |
REPORT_MAIL_CMD |
msmtp |
Mailprogramm für den Versand |
REPORT_BUSIEST_DAY_RANGE |
30 |
Zeitraum für "Aktivster Tag"; 0 nutzt den Berichtszeitraum |
REPORT_EMAIL_FROM erwartet genau eine Adresse, REPORT_EMAIL_TO eine oder mehrere kommagetrennte Adressen; beide auch in der Form Name <adresse@example.com>. Werte mit Zeilenumbrüchen oder anderen Steuerzeichen werden abgelehnt.
Versandintervalle
| Intervall | Versandzeitpunkt |
|---|---|
daily |
Täglich zur Uhrzeit aus REPORT_TIME |
weekly |
Montags zur Uhrzeit aus REPORT_TIME |
biweekly |
Montags in ungeraden ISO-Kalenderwochen zur Uhrzeit aus REPORT_TIME |
monthly |
Am 1. des Monats zur Uhrzeit aus REPORT_TIME |
Berichtszeitraum
Der Berichtszeitraum endet immer gestern um 23:59:59, der Tag des Versands zählt also nicht mit.
| Intervall | Berichtszeitraum |
|---|---|
daily |
Der Vortag |
weekly |
Die letzten 7 vollen Tage |
biweekly |
Die letzten 14 vollen Tage |
monthly |
Der komplette Vormonat (1. bis letzter Tag), unabhängig von der Monatslänge |
Jede Sperre wird genau einer Angriffsart zugeordnet. Die Summe der Angriffsarten entspricht daher immer "Sperren gesamt".
AbuseIPDB-Zählung
Erfolgreiche AbuseIPDB-Meldungen werden in der Tabelle abuseipdb_reports der SQLite-Datenbank gespeichert und bleiben so auch nach einer Logrotation erhalten. Für Zeiträume vor der ersten gespeicherten Meldung (ältere Versionen) wertet der Report zusätzlich die Logdatei aus LOG_FILE aus.
Formate
| Format | Beschreibung | Empfehlung |
|---|---|---|
html |
HTML-formatierte E-Mail mit Tabellen und Formatierung | Standard-Mail-Clients |
txt |
Reiner Text ohne Formatierung | Einfache Mail-Setups, Log-Ablage |
Beispielkonfiguration
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 adguard-shield report-status
HTML-Report in Datei schreiben
sudo adguard-shield report-generate html /tmp/adguard-shield-report.html
Die Datei kann im Browser geöffnet werden, um das Ergebnis zu prüfen.
Text-Report auf stdout ausgeben
sudo adguard-shield report-generate txt
Testmail senden
sudo adguard-shield report-test
Sendet eine einfache Testmail. Erst wenn diese ankommt, lohnt sich die Fehlersuche am eigentlichen Report.
Aktuellen Report erzeugen und versenden
sudo adguard-shield report-send
Cron-Job installieren
sudo adguard-shield report-install
Cron-Job entfernen
sudo adguard-shield report-remove
Mailversand
AdGuard Shield übergibt die fertige Mail an ein lokales Mailprogramm. Der Standard ist:
REPORT_MAIL_CMD="msmtp"
Einrichtung mit msmtp
# msmtp installieren
sudo apt install msmtp msmtp-mta
# Testmail senden
sudo adguard-shield report-test
Eigene Mailprogramm-Argumente
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.
REPORT_MAIL_CMD="msmtp --account=default"
Alternativen zu msmtp
| Programm | REPORT_MAIL_CMD |
|---|---|
| msmtp | msmtp |
| sendmail | sendmail |
| ssmtp | ssmtp |
| Benutzerdefiniert | Vollständiger Pfad zum Programm |
Automatischer Versand
Cron-Job installieren
sudo adguard-shield report-install
Dadurch wird diese Datei geschrieben:
/etc/cron.d/adguard-shield-report
Der Cron-Eintrag ruft den globalen CLI-Befehl mit der installierten Konfiguration auf, sofern er registriert ist:
/usr/local/bin/adguard-shield -config /opt/adguard-shield/adguard-shield.conf report-send
Falls die Installation mit --no-register erfolgt ist, verwendet report-install stattdessen /opt/adguard-shield/adguard-shield.
Zeitplan nach Intervall
| Intervall | Cron-Verhalten |
|---|---|
daily |
Täglich zur Uhrzeit aus REPORT_TIME |
weekly |
Montags zur Uhrzeit aus REPORT_TIME |
biweekly |
Montags in ungeraden ISO-Kalenderwochen |
monthly |
Am 1. des Monats |
Cron-Job entfernen
sudo adguard-shield report-remove
Manuelle Prüfung
Schritt 1: Status prüfen
sudo adguard-shield report-status
Schritt 2: Report lokal erzeugen
# HTML-Report zum Ansehen im Browser
sudo adguard-shield report-generate html /tmp/adguard-shield-report.html
# Text-Report in der Konsole
sudo adguard-shield report-generate txt
Schritt 3: Versand testen
# Einfache Testmail
sudo adguard-shield report-test
# Vollständigen Report senden
sudo adguard-shield report-send
Schritt 4: Logs prüfen
sudo adguard-shield logs --level warn --limit 100
sudo journalctl -u cron --no-pager -n 100
Je nach Distribution heißt der Cron-Service cron, crond oder wird über das allgemeine Syslog protokolliert.
Häufige Probleme
REPORT_EMAIL_TO ist leer
Setze einen Empfänger in der Konfiguration:
REPORT_EMAIL_TO="admin@example.com"
Mailprogramm nicht gefunden
Prüfe, ob das Mailprogramm installiert ist:
which msmtp
Installiere es bei Bedarf:
sudo apt install msmtp msmtp-mta
Oder setze REPORT_MAIL_CMD auf dein vorhandenes Mailprogramm.
Cron läuft, aber keine Mail kommt an
Prüfe die Konfiguration und den Cron-Job:
sudo adguard-shield report-send
sudo cat /etc/cron.d/adguard-shield-report
Checkliste:
| Prüfpunkt | Beschreibung |
|---|---|
| Empfänger | REPORT_EMAIL_TO korrekt gesetzt? |
| Mailprogramm | REPORT_MAIL_CMD im Cron-PATH verfügbar? |
| Root-Konfiguration | Mailer für root konfiguriert? (msmtp benötigt /root/.msmtprc oder /etc/msmtprc) |
| Spam | Spam-Ordner geprüft? |
| SMTP | Ausgehende SMTP-Verbindungen erlaubt? (Port 587/465) |
Format beim Generieren überschreiben
Du kannst das Format unabhängig von der Konfiguration wählen:
sudo adguard-shield report-generate txt
sudo adguard-shield report-generate html /tmp/report.html