Add selective Postfix SRS installation and management

README-SRS.md

@@ -0,0 +1,147 @@
+# Selektives Sender Rewriting Scheme (SRS)
+
+**Stand:** 23. Oktober 2026
+**Projekt:** `mailsystem` – Debian 13, Postfix, PostfixAdmin/PostgreSQL
+**Status:** Integration auf `e.mx.oopen.de` erfolgreich getestet; Resttests ausstehend
+
+## Ziel und Geltungsbereich
+
+Das System soll den SMTP-Envelope-Absender **nur bei tatsaechlichen externen
+Weiterleitungen ueber virtuelle Mail-Aliase** mittels SRS umschreiben.
+Andere Nachrichten sollen ihren Envelope-Absender behalten. Virtuelle
+Aliase werden unter anderem ueber PostfixAdmin und PostgreSQL verwaltet.
+
+Bei einer Weiterleitung kann die urspruengliche Absenderdomain den SPF-Test
+am Zielserver nicht bestehen: Der weiterleitende Mailserver ist normalerweise
+nicht fuer diese Domain autorisiert. SRS ersetzt deshalb den SMTP-Envelope-
+Absender durch eine signierte Adresse der eigenen SRS-Domain. Der sichtbare
+`From:`-Header wird dadurch nicht veraendert; DKIM und DMARC muessen
+unabhaengig betrachtet werden.
+
+## Technischer Aufbau
+
+- **Regulaerer Postfix:** Annahme, AmaViS-Pruefung, virtuelle Aliasaufloesung.
+- **`srs-forward` (Pipe-Dienst):** Uebergabe an `srs-forward.py` und
+  selektive Entscheidung ueber externe Alias-Weiterleitungen.
+- **PostSRSd 2.4.1:** SRS-Umschreibung und Rueckuebersetzung ueber Socketmap.
+- **Zweite Postfix-Instanz:** SMTP-Reinjektion und anschliessende Zustellung.
+- **Reverse-Komponenten:** Annahme und Verarbeitung eingehender SRS-Ruecklaeufer
+  waehrend des aktiven SRS-Betriebs.
+
+Waehrend SRS **aktiviert** ist, wird `default_transport = srs-forward`
+verwendet. Deshalb durchlaufen auch Nachrichten ohne SRS-Bedarf die eigene
+Entscheidungs- und Reinjektionsstrecke. **Nur die eigentliche SRS-Umschreibung
+ist selektiv.** Dieses betriebliche Risiko ist weiterhin Teil der Architektur;
+der getestete Rueckbau beseitigt diese Abhaengigkeit im deaktivierten Zustand.
+
+### Lokale Endpunkte
+
+| Endpunkt | Funktion |
+| --- | --- |
+| `127.0.0.1:10003` | PostSRSd-Socketmap |
+| `127.0.0.1:10004` | Reverse-Socketmap |
+| `127.0.0.1:10028` | Reinjektion in die SRS-Delivery-Instanz |
+| `127.0.0.1:10029` | Reverse-SMTP-Eingang fuer Ruecklaeufer |
+
+### Wichtige Dateien und Dienste
+
+- `conf/srs.conf` – lokale SRS-Domain; **nicht** unveraendert als allgemeine
+  Vorlage auf andere Hosts uebertragen.
+- `conf/srs.conf.sample` – Konfigurationsbeispiel.
+- `/etc/postfix-srs/state.conf` – bei der Installation gespeicherter
+  urspruenglicher Postfix-Zustand; nach Deaktivierung beibehalten.
+- `/etc/postsrsd-srs/secret` – geheimer SRS-Schluessel; vor fremdem Zugriff
+  schuetzen und beim Update erhalten.
+- `/etc/postfix-srs/delivery/` – Konfiguration der zweiten Postfix-Instanz.
+- `/var/spool/postfix-srs-delivery/` – Queue der zweiten Instanz.
+- `/usr/local/postsrsd-<version>` und `/usr/local/postsrsd` – versionierte
+  Installation und Symlink.
+- Dienste: `postsrsd-srs.service`, `srs-reverse-map.service`,
+  `postfix@srs-delivery.service`.
+
+## Betriebszustaende
+
+**Installiert, aber DISABLED:** SRS-Dateien und der persistente Zustand
+bleiben erhalten. Der regulaere Postfix verwendet weder `srs-forward`
+noch die laufenden SRS-Dienste.
+
+**ENABLED:** Die Postfix-Hauptkonfiguration enthaelt die verwalteten
+SRS-Bloecke, die drei SRS-Dienste laufen und die Einbindung ist aktiv.
+
+**Inkonsistenter Zustand:** Die Verwaltungsskripte sollen nicht stillschweigend
+korrigieren, sondern mit Diagnose abbrechen.
+
+## Zweiphasige Deaktivierung
+
+`deactivate-srs.sh` stellt den urspruenglichen Postfix-Zustand wieder her.
+Vorher muss die SRS-Delivery-Queue leer sein.
+
+1. **Neue SRS-Uebergaben beenden:** Urspruengliche `main.cf`-Parameter und
+   Empfangseinstellungen wiederherstellen; den alten `srs-forward`-Pipe-Dienst
+   in `master.cf` vorerst belassen; alten Queue-Manager erfassen und den
+   regulaeren Postfix neu laden.
+2. **Alte Arbeit auslaufen lassen:** Auf den alten Queue-Manager, erkannte
+   `srs-forward`-Prozesse und eine leere SRS-Delivery-Queue warten (maximal
+   180 Sekunden). Die Queue wird wiederholt kontrolliert.
+3. **Abschalten:** `srs-forward` aus `master.cf` und SRS-systemd-Abhaengigkeiten
+   entfernen; Postfix erneut pruefen und neu laden; Queue erneut pruefen;
+   SRS-Dienste stoppen und deaktivieren; Endzustand verifizieren.
+
+Kann die Queue nicht geleert oder nicht gelesen werden, oder schlaegt ein
+Schritt fehl, bricht das Skript ab und **versucht**, den vorherigen aktiven
+Zustand zurueckzusetzen. Automatischer Rollback ist kein Ersatz fuer
+Backups und muss fuer Fehlerfaelle noch integriert getestet werden.
+
+**Wichtiger Unterschied:** Die zwei Phasen dienen der geordneten Umschaltung.
+Auch bei anfangs leerer SRS-Queue werden beide Phasen durchlaufen.
+
+### Bewusst akzeptierte Grenze: verspaetete Ruecklaeufer
+
+Ein Ruecklaeufer an eine bereits versendete SRS-Adresse kann erst Tage nach
+der Deaktivierung eintreffen. Eine solche Nachricht ist bei der Abschaltung
+noch nicht in der Queue und kann nicht abgewartet werden.
+
+**Projektentscheidung:** Nach vollstaendiger Deaktivierung muessen solche
+spaeten SRS-Ruecklaeufer nicht mehr zugestellt oder rueckuebersetzt werden.
+Es gibt absichtlich keinen Reverse-only-Modus und keine Uebergangsfrist.
+Vorrang haben die sichere Behandlung bereits angenommener Nachrichten und
+ein funktionierender, von SRS unabhaengiger regulaerer Postfix-Betrieb.
+
+## Nachgewiesene Integrationstests vom 23. Oktober 2026
+
+Auf `e.mx.oopen.de` mit der SRS-Domain `srs.e.mx.oopen.de`:
+
+- `install-update-srs.sh --check`: DNS-/SPF- und Installationsvorpruefung OK.
+- `install-update-srs.sh --install`: PostSRSd 2.4.1 gebaut; Upstream-CTest OK;
+  Installation ohne automatische Aktivierung.
+- `activate-srs.sh`: Zustand `DISABLED` erkannt; Aktivierung nach Bestaetigung
+  und abschliessende Pruefungen erfolgreich.
+- Externe virtuelle Weiterleitung `alias@henschelbuch.de` nach
+  `ckubu@oopen.de`: PostSRSd protokollierte die Umschreibung eines GMX-
+  Envelope-Absenders nach `SRS0=...@srs.e.mx.oopen.de`; der empfangende
+  SMTP-Server bestaetigte die Uebernahme (`250 2.0.0`).
+- `deactivate-srs.sh`: Beide Reloads, Drain-Pruefung, Entfernung des
+  Pipe-Dienstes, Abschaltung aller SRS-Dienste und Verifikation erfolgreich.
+- Dieselbe externe Weiterleitung nach der Deaktivierung: Regulaerer
+  `postfix/smtp` stellte mit unveraendertem Envelope-Absender an den
+  naechsten SMTP-Server zu (`250 2.0.0`). Die regulaere Postfix-Queue war leer.
+
+Die genannten SMTP-Ergebnisse belegen die Annahme durch den naechsten
+Mailserver, nicht automatisch die endgueltige Zustellung ins Postfach.
+
+**Noch offen:** Erzwungener Rollback-Integrationstest und Deaktivierung
+unter anhaltender Zustelllast. Eine uneingeschraenkte Freigabe fuer
+Produktivsysteme wird hieraus nicht abgeleitet.
+
+## Bekannte Hinweise
+
+In der Testumgebung erschienen unabhaengige Postfix-Dateiberechtigungswarnungen
+und Warnungen zur Verwendung von `nobody` durch den Reverse-Map-Dienst bzw.
+zur fehlenden seccomp-Sandbox von PostSRSd. Diese Meldungen sind bei einer
+spaeteren Wartung gesondert zu untersuchen. Sie wurden nicht als Nachweis
+fuer eine fehlerhafte SRS-Zustellung gewertet.
+
+Fuer Befehle zur Installation, Diagnose und Deaktivierung siehe
+[README-install-SRS.md](README-install-SRS.md). Der Stand vom 20. Oktober
+bleibt unter [`archive/selective-srs-2026/`](archive/selective-srs-2026/)
+unveraendert erhalten.