95.1.38. pepsi-stage-quarantine¶
hold a message until an operator releases or deletes it
- Handbuchabschnitt:
1
95.1.38.1.1. Name¶
pepsi-stage-quarantine - die Quarantäne-Stage der Pepsi-Pipeline.
95.1.38.1.2. Übersicht¶
pepsi-stage-quarantine [GLOBAL-OPTIONS] worker
95.1.38.1.3. Beschreibung¶
pepsi-stage-quarantine ist ein Stage-Programm, das von pepsi-dispatch(1) als persistenter Worker ausgeführt wird, der Nachrichten-IDs von der Standardeingabe liest. Es hält jede Nachricht zurück, die es erreicht, bis ein Betreiber sie mit pepsi-queue(1) quarantine freigibt oder löscht. Mail erreicht es überall dort, wo die Pipeline Mail zu ihm routet: über die Quarantäne-Anforderung eines Milters (das QUARANTINE_STAGE von pepsi-stage-milter(1) oder eines Pre-Queue-Milters von pepsi-ingress(1)), über das QUARANTINE_STAGE von pepsi-stage-decrypt(1) oder über die Route einer beliebigen anderen Stage.
Die Stage sieht eine Nachricht höchstens dreimal:
Beim Eintreffen hält sie
state.quarantine.sincefest und lässt den Datensatzpausedstehen. Ohne MAX_HOLD hat der Datensatz keintimeout, sodass pepsi-dispatch(1) ihn nie von sich aus aufweckt; die Nachricht wartet, bis jemand handelt. Mit MAX_HOLD ist dastimeoutdas Ende des Zurückhaltens, undstate.quarantine.untilhält es fest.Bei der Freigabe (
pepsi-queue quarantine releaseoder einpepsi-queue set-stageoder administratives erneutes Einreihen eines Betreibers in diese Stage) kommt der Datensatz alspendingzu dieser Stage zurück. Die Stage hältreleased_atfest und schickt die Nachricht an RELEASE_STAGE weiter. Der WebhookPOST /resumevon pepsi-httpd(1), der eine Nachricht fortsetzt, sobald eine Zahlung eintrifft, lässt eine zurückgehaltene Nachricht unberührt: Sein Token ist eine Zahlungsbenachrichtigung, keine Entscheidung eines Betreibers.Beim Ablauf, wenn der Dispatcher den Datensatz am Ende von MAX_HOLD aufweckt, hält die Stage
expiredfest und routet die Nachricht zu EXPIRE_STAGE oder löscht sie, wenn diese Option nicht gesetzt ist.
Eine Freigabe und ein Ablauf sehen für die Stage gleich aus, daher unterscheidet sie beide anhand ihrer Uhr: Eine Beanspruchung zum Zeitpunkt until oder danach ist der Ablauf. Eine kleine Toleranz von bis zu fünf Sekunden, höchstens aber der Hälfte der Haltedauer, gleicht einen Uhrenunterschied zwischen dem Datenbankhost und diesem Host aus; eine Freigabe in diesem letzten Moment zählt daher als Ablauf, nie umgekehrt. MAX_HOLD wird gelesen, wenn ein Zurückhalten beginnt: Eine spätere Änderung ändert weder das Ende eines bereits festgehaltenen Zurückhaltens noch, ob es überhaupt endet.
Eine Nachricht auf dem Weg zu EXPIRE_STAGE wird so markiert, wie pepsi-queue(1) gc eine abgelaufene Quarantäne markiert: state.failed_stage ist diese Stage, state.failure_class ist quarantine-expired, ein vom Absender angefordertes RET=FULL wird zu RET=HDRS, und ein mitgeführtes state.bounce wird verworfen, damit pepsi-stage-bounce(1) dem Absender mitteilen kann, dass die Nachricht zurückgehalten und nicht freigegeben wurde, ohne ihren Inhalt zurückzugeben. Zwei Arten von Nachrichten werden beim Ablauf gelöscht statt geroutet, so wie gc sie löscht: die Kopie eines Listenbeitrags für ein Mitglied, deren Umschlagabsender die Bounce-Verarbeitung der Liste ist, und eine Nachricht, deren Inhalt aus einem Chiffrat ohne Integritätsschutz stammt oder sich aus einem solchen nicht öffnen ließ (Telemetrie decrypt-dropped). Bei der zweiten Art kann schon die Frage, ob die Nachricht überhaupt zurückgehalten wurde, vom Padding eines Chiffrats abhängen, das ihr Absender verändert haben kann; ein Bericht am Ende des Zurückhaltens würde also die Padding-Frage beantworten.
Die Stage versendet selbst keine Benachrichtigung, weder an den Absender noch an die Empfänger.
Die Optionen werden aus der Basiskonfiguration gelesen, nie aus Einstellungen pro Adresse: Was eine Quarantäne zurückhält und wie lange, entscheidet der Host.
Eine Nachricht, die einmal aus einer Quarantäne freigegeben wurde und später wieder eine Quarantäne-Stage erreicht, wird erneut zurückgehalten. Wer eine Quarantäne anfordert, schreibt einen frischen Eintrag, und die Stage beginnt auch für einen Eintrag, dessen früheres Zurückhalten beendet ist, ein neues Zurückhalten.
Ein Zurückhalten ohne MAX_HOLD ist dennoch durch pepsi-queue(1) gc begrenzt, das für eine bei einer Quarantäne-Stage zurückgehaltene Nachricht [pepsi-queue] QUARANTINE_MAX_AGE_DAYS (Standardwert 14) Tage nach ihrem Eintreffen einen Bounce erzeugt, wie bei jeder Quarantäne-Stage. Eine Stage mit MAX_HOLD beendet ihre Zurückhaltungen selbst, und gc lässt sie in Ruhe. Zurückgehaltene Mail liegt, solange sie zurückgehalten wird, als Klartext gespeichert vor (die Quarantäne einer Entschlüsselungs-Stage hält zurück, was diese entschlüsselt hat), weshalb standardmäßig eine Grenze gilt.
95.1.38.1.4. Konfiguration¶
Die Optionen stehen im eigenen [stage-<name>]-Abschnitt der Stage (PROGRAM = pepsi-stage-quarantine); alle sind optional, aber eine von RELEASE_STAGE und NEXT_STAGE muss gesetzt sein.
- RELEASE_STAGE = STAGE
Wohin eine freigegebene Nachricht geht. Standardwert ist NEXT_STAGE. Eine Nachricht, die Ingress in Quarantäne gestellt hat, hat jede Stage vor dieser übersprungen; für diesen Einsatz ist der Wert daher normalerweise
init. Er darf nicht diese Stage selbst sein.- MAX_HOLD = SPAN
Wie lange ein Zurückhalten höchstens dauert, zum Beispiel
14 days,2 weeksoder36 h(ein Tag zählt als 24 Stunden; Monate und Jahre werden abgelehnt). Ohne Wert dauert ein Zurückhalten, bis die Nachricht freigegeben oder gelöscht wird, innerhalb der Grenze von pepsi-queue(1)gc.- EXPIRE_STAGE = STAGE
Wohin eine Nachricht geht, wenn ihr Zurückhalten MAX_HOLD erreicht, zum Beispiel zu einer pepsi-stage-bounce(1)-Stage. Ohne Wert wird eine abgelaufene Nachricht gelöscht (festgehalten im Maillog, sofern aktiviert, wie jede gelöschte Nachricht). Abgelehnt ohne MAX_HOLD, da kein Zurückhalten sie erreichen könnte, und abgelehnt, wenn sie diese Stage selbst ist.
Der Worker verweigert den Start (Exit-Status 78), wenn sich der Abschnitt nicht parsen lässt oder eine darin genannte Stage nicht existiert; pepsi-setup(1) validate lehnt dasselbe ab. Alle Optionen sind in pepsi.conf(5) dokumentiert.
95.1.38.1.5. State¶
Eingaben: state.quarantine.reason und state.quarantine.by, sofern die Partei, die die Nachricht hierher geschickt hat, sie geschrieben hat; state.dsn und state.crypto.in beim Ablauf.
Ausgaben: der Eintrag state.quarantine, ein Objekt, dessen Schlüssel über Releases hinweg nur erweiterbar sind:
reason(Zeichenkette, optional)Warum die Nachricht zurückgehalten wird, so wie die Partei, die sie hierher geschickt hat, es formuliert hat (der
SMFIR_QUARANTINE-Text eines Milters).by(Zeichenkette, optional)Wer sie hierher geschickt hat:
milter:<MILTER_NAME>für einen Milter,stage:<name>für eine andere Stage.since(Zeichenkette, RFC 3339)Wann diese Stage begann, die Nachricht zurückzuhalten.
until(Zeichenkette, RFC 3339)Wann das Zurückhalten von selbst endet, mit MAX_HOLD.
released_at(Zeichenkette, RFC 3339)Wann die Nachricht freigegeben wurde.
expired(true)Das Zurückhalten hat
untilerreicht.
Der Aufbau ist in pepsi.state(7) beschrieben.
Übergänge:
erstes Eintreffen oder ein Eintrag, dessen früheres Zurückhalten beendet ist →
pausedbei dieser Stage,timeoutNULLoder das Ende von MAX_HOLD;während des Zurückhaltens erneut beansprucht, vor
until→ RELEASE_STAGE,pending;zum Zeitpunkt
untiloder danach beansprucht → EXPIRE_STAGE,pending, oder gelöscht.
95.1.38.1.6. Befehle¶
- worker
Läuft als persistenter pepsi-dispatch(1)-Worker, der Nachrichten-IDs von der Standardeingabe liest.
95.1.38.1.7. Globale Optionen¶
- -c FILE, –config FILE
Liest die Konfiguration aus FILE, statt die Standardorte zu durchsuchen.
- -L LOGLEVEL, –log LOGLEVEL
Setzt die Log-Ausführlichkeit (Standardwert
[pepsi] LOG, sonstinfo).- -v, –verbose
Zeigt Log-Meldungen aus allen Quellen.
- -h, –help; -V, –version
Gibt eine Verwendungsübersicht / die Version aus und beendet sich.
95.1.38.1.8. Exit-Status¶
Das Ergebnis jeder Nachricht wird pepsi-dispatch(1) auf der Statuszeile des Workers gemeldet, nicht als Exit-Status.
- 0
Der Worker lief, bis seine Standardeingabe geschlossen wurde.
- 1
Ein fataler Fehler ist aufgetreten (unlesbare Konfiguration, die Datenbank konnte nicht geöffnet werden, oder Standardein-/-ausgabe schlug fehl). Der Grund wird in das Journal geschrieben.
- 78
Der Abschnitt der Stage lässt sich nicht parsen, oder eine darin genannte Stage existiert nicht: Der Worker verweigert den Start, und pepsi-dispatch(1) hält die Nachrichten der Stage zurück, bis die Konfiguration korrigiert ist.
95.1.38.1.9. Beispiele¶
Eine Quarantäne für die Urteile eines Milters, freigegeben in den Rest der Pipeline:
[stage-quarantine]
PROGRAM = pepsi-stage-quarantine
RELEASE_STAGE = init
[stage-spamfilter]
PROGRAM = pepsi-stage-milter
SOCKET = unix:/run/rspamd/milter.sock
ALLOW_ACTIONS = addhdrs chghdrs chgbody quarantine
QUARANTINE_STAGE = quarantine
NEXT_STAGE = deliver
Eine Quarantäne, die ein Zurückhalten nach zwei Wochen mit einer DSN an den Absender beendet:
[stage-quarantine]
PROGRAM = pepsi-stage-quarantine
RELEASE_STAGE = init
MAX_HOLD = 2 weeks
EXPIRE_STAGE = bounce
Auflisten, was zurückgehalten wird, und dann eine Nachricht freigeben:
pepsi-queue -c /etc/pepsi/pepsi.conf quarantine list
pepsi-queue -c /etc/pepsi/pepsi.conf quarantine release TOKEN
95.1.38.1.10. Siehe auch¶
pepsi-queue(1), pepsi-stage-milter(1), pepsi-stage-decrypt(1), pepsi-ingress(1), pepsi-stage-bounce(1), pepsi-dispatch(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1)
95.1.38.1.11. Fehler¶
Melden Sie Fehler an den Pepsi-Issue-Tracker.