95.1.35. pepsi-stage-if

branch a message on a test of its stored state value

Handbuchabschnitt:

1

95.1.35.1.1. Name

pepsi-stage-if - die Bedingte-Verzweigungs-Stage der Pepsi-Pipeline.

95.1.35.1.2. Übersicht

pepsi-stage-if [GLOBAL-OPTIONS] worker

95.1.35.1.3. Beschreibung

Diese Stage hat den Standardwert FUSION = yes: Wenn Stage-Fusion aktiviert ist ([pepsi] ALLOW_FUSION, der Standardwert) und diese Stage in das vereinheitlichte pepsi-Binärprogramm eingefaltet ist, kann ein Vorgänger sie in seinem eigenen Worker-Prozess ausführen, statt sie separat zu dispatchen. Siehe pepsi-dispatch(1) und pepsi.conf(5).

pepsi-stage-if ist ein Stage-Programm, das von pepsi-dispatch(1) als persistenter Worker ausgeführt wird, der Nachrichten-IDs von der Standardeingabe liest. Es lädt den pepsi.workqueue-Datensatz der Nachricht (und weigert sich zu handeln, sofern sein status nicht running ist), liest seinen [stage-<stage>]-Abschnitt und testet ein Mitglied des state-JSON der Nachricht auf Gleichheit gegen einen konfigurierten Wert: Sind sie gleich, schaltet es die Nachricht zu TRUE_STAGE weiter, andernfalls zu FALSE_STAGE. Es ist eine programmierbare Verzweigung: Ein Betreiber kann nach jedem Urteil routen, das eine frühere Stage festgehalten hat (state.spam, state.auth.dkim, …), ohne Code zu schreiben.

Die Stage verschiebt immer nur die stage-Spalte. Sie schreibt die Nachricht nie um, pausiert oder lässt sie nie fehlschlagen und lässt state unberührt, sodass state.dsn und jedes andere Urteil über die Verzweigung hinweg erhalten bleiben. Der Nachrichtentext wird nie geladen.

95.1.35.1.4. Bedingung

STATE_PATH ist ein punktgetrennter Pfad in das state-JSON. Ein Segment, das auf ein Objekt angewendet wird, wählt das Mitglied dieses Namens aus (auch ein numerisches); auf ein Array angewendet muss es eine nicht-negative Ganzzahl sein und wählt diese Position aus. Zum Beispiel wählt spam das oberste spam-Flag, auth.dkim das dkim-Mitglied des auth-Objekts und dsn.rcpt.0.notify das notify-Feld des ersten Empfängereintrags.

Der dort gefundene Wert wird mit VALUE in seiner natürlichen Textform verglichen:

  • eine Zeichenkette passt auf ihren eigenen Text (pass passt auf pass);

  • ein Boolean passt auf true oder false;

  • eine Zahl passt auf ihre Dezimaldarstellung (3, 1.5);

  • JSON-null passt auf das literale null.

Ein Pfad, der fehlt, ist nie gleich, und ebenso wenig ein Pfad, der auf ein Array oder Objekt auflöst, denn diese haben keine Skalarform; ein solcher Pfad nimmt den FALSE_STAGE-Zweig. VALUE ist erforderlich und kann nicht leer sein (eine leere Option gilt als nicht gesetzt).

95.1.35.1.5. Konfiguration

Die Optionen liegen im eigenen [stage-<name>]-Abschnitt der Stage (PROGRAM = pepsi-stage-if): das zu testende STATE_PATH, der Vergleichswert VALUE und die Verzweigungsziele TRUE_STAGE/FALSE_STAGE. Alle vier sind erforderlich, und pepsi-setup prüft zusätzlich, dass beide Verzweigungsziele bestehende Stages benennen. Die Stage hat kein NEXT_STAGE (beide Ziele werden ausdrücklich benannt). Die Optionen sind in pepsi.conf(5) dokumentiert.

Alle vier Optionen werden aus dem Abschnitt der Stage gelesen, nachdem die adressbezogenen Einstellungen angewendet wurden. Ist die Stage also in den EDITABLE_STAGES einer pepsi-stage-edit-settings(1)-Stage aufgeführt, kann ein Korrespondent den Test und beide Verzweigungsziele für seine eigene Mail ändern. Führen Sie dort nie eine if-Stage auf, die eine Sicherheitsentscheidung absichert (siehe pepsi-settings(1) und die Einstellungsgrenze im Kapitel Threat model des Handbuchs).

95.1.35.1.6. State

Eingaben: das einzelne von STATE_PATH ausgewählte Mitglied von state.

Ausgaben: keine; die Stage schaltet die Nachricht nur weiter und lässt state unverändert. Das State-Layout wird in pepsi.state(7) beschrieben.

Übergänge: schaltet zu TRUE_STAGE weiter, wenn das von STATE_PATH ausgewählte Mitglied gleich VALUE ist (nach Skalar-Textform verglichen), andernfalls zu FALSE_STAGE. Auch ein fehlender Pfad oder ein nicht-skalarer Wert nimmt den FALSE_STAGE-Zweig. Diese beiden Weiterschaltungen sind die einzigen Übergänge; die Stage pausiert, schlägt fehl, leitet um oder schließt nie ab.

95.1.35.1.7. Befehle

worker

Läuft als persistenter pepsi-dispatch(1)-Worker, der Nachrichten-IDs von der Standardeingabe liest.

95.1.35.1.8. 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.35.1.9. 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 Worker hat den Start verweigert: Ein [stage-*]-Abschnitt, den er bedient, lässt sich nicht parsen (z. B. ein fehlendes STATE_PATH/VALUE/TRUE_STAGE/FALSE_STAGE). Der Dispatcher reiht erneut ein, was er übergeben hatte, und versucht die Stage später wieder.

95.1.35.1.10. Beispiele

Nachricht 42 über einen einmaligen Worker erneut verarbeiten (sie muss running sein):

echo 42 | pepsi-stage-if -c /etc/pepsi/pepsi.conf worker

Ein Pipeline-Abschnitt, der Mail, die eine frühere Stage als Spam markiert hat (state.spam == true), zur Bounce-Stage sendet und alles andere weiter:

[stage-if]
PROGRAM = pepsi-stage-if
STATE_PATH = spam
VALUE = true
TRUE_STAGE = bounce
FALSE_STAGE = srs

Das nächste Beispiel hält verschlüsselte Mail von Fremden zurück, die hier niemand lesen kann. Eine Nachricht, die an einen nur im Client eines Empfängers gehaltenen Schlüssel verschlüsselt ist, passiert jeden Inhaltsfilter als Chiffrat, und ebenso eine Nachricht, zu der kein Schlüssel hier passt. Mit pepsi-stage-decrypt(1) zuerst auf dem eingehenden Pfad und pepsi-stage-check-whitelist(1) danach halten zwei Zweige Mail zurück, die kein Schlüssel hier öffnen konnte, wenn sie von einem Absender kommt, den die Whitelist nicht durchgelassen hat:

[stage-whitelist]
PROGRAM = pepsi-stage-check-whitelist
WHITELIST_NAME = default
NEXT_STAGE = known-sender

# Whitelisted senders (state.spam = false) go on unchecked.
[stage-known-sender]
PROGRAM = pepsi-stage-if
STATE_PATH = spam
VALUE = false
TRUE_STAGE = deliver
FALSE_STAGE = undecryptable

# Mail no key here could open waits in a quarantine.
[stage-undecryptable]
PROGRAM = pepsi-stage-if
STATE_PATH = crypto.in.failure
VALUE = no-decryption-key
TRUE_STAGE = hold
FALSE_STAGE = deliver

hold ist jede Stage, die die Nachricht vom Benutzer fernhält, ohne es dem Absender mitzuteilen: eine Zustellung in ein Quarantäne-Postfach oder pepsi-stage-discard(1). Zwei Regeln sind nicht verhandelbar. Verzweigen Sie nur nach no-decryption-key, was bedeutet, dass kein Schlüssel hier zu der Nachricht passt, und nie nach decryption-failed oder nach crypto.in.decrypted = false: Ob sich ein verändertes AES-CBC-Chiffrat entschlüsseln lässt, hängt von seinem Padding ab, sodass ein Weg, der sich zwischen beiden unterscheidet, einem Angreifer die Antwort verriete, sobald er ihn beobachten kann. Und leiten Sie die zurückgehaltene Mail aus demselben Grund nie zu einer Bounce-Stage. Mail, die an den eigenen Client-Schlüssel des Benutzers verschlüsselt ist (crypto.in.for_client), trägt keinen Fehler und wird nicht zurückgehalten; fügen Sie einen dritten Zweig nach crypto.in.for_client = true nur hinzu, wenn auch solche Mail von Fremden unerwünscht ist.

95.1.35.1.11. Siehe auch

pepsi-config(1), pepsi-stage-check-whitelist(1), pepsi-stage-bounce(1), pepsi-dispatch(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1)

95.1.35.1.12. Fehler

Melden Sie Fehler an den Pepsi-Issue-Tracker.