Restore detailed backup mail reports with bounded local delivery

Dokumentation.md

@@ -338,6 +338,59 @@ Neue Backup-/Restore-Logs liegen unter `/var/log/app-backup` und werden nach `LO
 
 ## Betrieb und Monitoring
 
+### Ausführliche Mailberichte
+
+`ENABLE_MAIL_REPORT=true` sendet nach jedem regulär beendeten Backup einen Bericht
+über den lokalen sendmail-kompatiblen MTA. Die bisherigen Optionen `MAIL_TO`,
+`MAIL_FROM`, `MAIL_SUBJECT_PREFIX` und `MAIL_INCLUDE_LOG_TAIL_LINES` werden wieder
+ausgewertet und bei einem Update beibehalten. Defaults: Empfänger `johannes`,
+Absender `app-backup@<FQDN>` bei leerem/fehlendem `MAIL_FROM`, Betreffpräfix
+`[app-backup]`, 200 Protokollzeilen. `MAIL_SENDMAIL_BIN` ist standardmäßig
+`/usr/sbin/sendmail`; `MAIL_SEND_TIMEOUT` begrenzt dessen Aufruf auf 30 Sekunden
+(zulässig 1–300). Der Log-Auszug darf 0–10000 Zeilen umfassen.
+
+Der UTF-8-Bericht enthält Zeit, Host, Status, Exit-Code, Dauer, Lauf-ID und letzte
+Phase, Konfigurations-/Arbeits-/Archivpfade, Kompression, Crypt-Ziel und getrennten
+Uploadstatus. Dieser wird erst nach erfolgreichem Rücklesen aller Inhalte und
+bytegenauer Markerbestätigung `OK`. Bei deaktiviertem Upload steht ausdrücklich
+„nur lokal“; bei Fehlern bleibt die nicht abgeschlossene Uploadphase sichtbar.
+Ein Fehler bei nachgelagerter Retention kann deshalb korrekt `Status: FAIL` bei
+bereits verifiziertem Upload ergeben.
+Die Dateikopien protokollieren außerdem rsync-Statistiken zu Dateianzahl und
+übertragenen Bytes; laufende rclone-Statistiken erscheinen im gleichen Log.
+
+Die Größen werden nach Wiederaufnahme der Dienste und vor erfolgreicher
+Staging-Bereinigung erfasst: belegter Speicher pro vorhandener Komponente und
+insgesamt, dazu Archiv-Dateigrößen und deren Summe. Komponentengrößen werden
+einzeln gemessen; bei gemeinsamen Hardlinks müssen sie sich nicht zum Gesamtwert
+addieren. Es werden keine Live-Quellen erneut kopiert. Fehlende Messwerte heißen
+„nicht verfügbar“, nicht fälschlich `0`. Bei Abbruch können aufgeführte Archive
+unvollständig sein; Status und letzte Phase sind maßgeblich. Die Messung erfolgt
+mit `du`, je Aufruf auf 30 Sekunden begrenzt, und verlängert nicht die Dienstpause.
+
+Vor dem Lesen des Log-Auszuges wird der Logger beendet und auf vollständiges
+Schreiben gewartet. Mailheader werden über die Python-Mailbibliothek erzeugt;
+eingeschleuste Header-Zeilenumbrüche werden abgewiesen. `sendmail -oi -t` schützt
+gegen vorzeitiges Nachrichtenende durch eine einzelne Punktzeile im Log.
+Konfigurationsinhalte und Zugangsdaten werden nicht für den Bericht gelesen;
+enthaltene Dateinamen/Pfade und der Log-Auszug sind dennoch vertraulich.
+
+Die MIME-Nachricht bleibt mit Modus `600` unter
+`$LOG_DIR/report_LAUF.eml` erhalten, auch bei MTA-Fehlern oder Zustellungs-Timeout.
+Alte Berichte werden wie Logs nach `LOG_RETENTION_DAYS` bei erfolgreichem regulärem
+Backup bereinigt; der Update-Abnahmelauf überspringt diese Retention.
+Ein Mailfehler ist eine protokollierte Warnung und ändert den Backup-Exit-Code nicht.
+Erfolgreiche Übergabe an den MTA bestätigt noch keine Zustellung im Postfach.
+
+`--check`, Restore und reine Restore-Prüfungen erzeugen keine Backup-Mail.
+Sehr frühe Fehler vor der Laufinitialisierung und SIGKILL/Stromausfall können
+keinen Abschlussbericht erzeugen. Beim Update bezieht sich die Mail auf dessen
+Backup-Teil; `SUCCESS` in der Update-Ergebnisdatei bestätigt zusätzlich den
+anschließenden separaten Remote-Restore-Prüflauf und die Timer-Aktivierung.
+Unabhängige Überwachung bleibt deshalb erforderlich.
+
+### Status und Zeitplan prüfen
+
 ```bash
 sudo /usr/local/sbin/app-backup.sh --check
 sudo systemctl start app-backup.service
@@ -483,12 +536,15 @@ Die Entfernung der drei DB-Dateien aus dem aktuellen Baum löscht deren Historie
 
 Reproduzierbar mit `tests/Dockerfile` und `tests/run.sh`. Der Container bekommt das Repository nur lesbar und benötigt während der Tests kein Netzwerk. Die MariaDB läuft ohne TCP-Port in einem temporären Verzeichnis. systemd/occ werden simuliert; alle eigentlichen Archive, Dateikopien, Dumps/Imports und Crypt-Operationen sind real.
 
-Verifikation am 10.09.2026: **59 Testfälle erfolgreich** — 58 im vollständigen Durchlauf (524,6 Sekunden), dazu der ergänzte Test für zusätzliche Marker-Zeilenumbrüche. Die vier betroffenen Markertests und der echte Crypt-Upload mit Remote-Restore wurden nach der Marker-Korrektur nochmals gezielt erfolgreich ausgeführt. Shell-Syntax und ShellCheck ohne Befund. Testumgebung: Debian 13.6, MariaDB 11.8.6, rclone 1.60.1-DEV (Distributionspaket), ShellCheck 0.10.0. Diese Versionsangaben beschreiben die Testumgebung, keine Empfehlung für die Produktivversion.
+Verifikation am 10.09.2026: **65 Testfälle im vollständigen Durchlauf erfolgreich** (603,4 Sekunden), einschließlich ausführlicher Mailberichte und der aktualisierten Paketinstallation. Shell-Syntax und ShellCheck ohne Befund. Testumgebung: Debian 13.6, MariaDB 11.8.6, rclone 1.60.1-DEV (Distributionspaket), ShellCheck 0.10.0. Diese Versionsangaben beschreiben die Testumgebung, keine Empfehlung für die Produktivversion. Der MTA wird durch eine lokale Nachrichten-Attrappe ersetzt; es wurden keine echten E-Mails versendet. Die Zustellung auf Gemini ist nach Installation zu prüfen.
 
 Die Regressionstests für `RCLONE_SIZE_ONLY` und zusätzliche Marker-Zeilenumbrüche scheiterten vor den jeweiligen Korrekturen mit einem fälschlich erfolgreichen Backup und bestanden danach. Upload-/Markerfehler werden an den Befehlsgrenzen injiziert, während Crypt-Übertragung und Inhaltsvergleich real bleiben. Die Tests bilden keine OneDrive-API nach; das tatsächliche HTTP-409-Wiederholungsverhalten ist durch den Betreiberlauf und den rclone-1.74.3-Quellcode separat belegt.
 
 Geprüfte Fälle umfassen:
 
+- Ausführliche UTF-8-Erfolgs-/Fehlermails mit erhaltenen Header-Einstellungen, Größen vor Bereinigung, finalem Fehlerauszug und korrektem Upload-Prüfstatus.
+- MTA-Fehler und begrenzter Versand-Timeout verändern den Backup-Exit-Code nicht; die lokale Nachricht bleibt erhalten. Header-Injection wird abgewiesen; Prüfläufe/Restore versenden keine Backup-Mail.
+- Paketupdate installiert die Berichtskomponente, erhält alte Mail-Einstellungen und erzeugt beim Abnahmebackup einen Bericht über die MTA-Attrappe.
 - Endgültiger Upload-Fehler trotz bereits übertragener Bytes: vollständiger lokaler Satz, vorheriger Erfolgsstatus und alte lokale/entfernte Retention-Kandidaten bleiben erhalten.
 - Veränderte Remote-Datei gleicher Größe, Marker-Schreibfehler, abweichender Marker-Inhalt und zusätzliche Zeilenumbrüche verhindern den lokalen Upload-Erfolg und die Retention.
 - Nicht unterstützte rclone-Umgebungsoptionen werden vor Remote-Zugriff und Writer-Stopp abgewiesen; unterstützte exportierte Einstellungen bleiben nutzbar.