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.since fest und lässt den Datensatz paused stehen. Ohne MAX_HOLD hat der Datensatz kein timeout, sodass pepsi-dispatch(1) ihn nie von sich aus aufweckt; die Nachricht wartet, bis jemand handelt. Mit MAX_HOLD ist das timeout das Ende des Zurückhaltens, und state.quarantine.until hält es fest.

  • Bei der Freigabe (pepsi-queue quarantine release oder ein pepsi-queue set-stage oder administratives erneutes Einreihen eines Betreibers in diese Stage) kommt der Datensatz als pending zu dieser Stage zurück. Die Stage hält released_at fest und schickt die Nachricht an RELEASE_STAGE weiter. Der Webhook POST /resume von 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 expired fest 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 weeks oder 36 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 until erreicht.

Der Aufbau ist in pepsi.state(7) beschrieben.

Übergänge:

  • erstes Eintreffen oder ein Eintrag, dessen früheres Zurückhalten beendet ist → paused bei dieser Stage, timeout NULL oder das Ende von MAX_HOLD;

  • während des Zurückhaltens erneut beansprucht, vor until → RELEASE_STAGE, pending;

  • zum Zeitpunkt until oder 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, sonst info).

-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.