95.1.35. pepsi-stage-if¶
branch a message on a test of its stored state value
- Section du manuel:
1
95.1.35.1.1. Nom¶
pepsi-stage-if - l’étape de branchement conditionnel du pipeline Pepsi.
95.1.35.1.2. Synopsis¶
pepsi-stage-if [GLOBAL-OPTIONS] worker
95.1.35.1.3. Description¶
Cette étape a FUSION = yes par défaut : lorsque la fusion d’étapes est activée ([pepsi] ALLOW_FUSION, la valeur par défaut) et que cette étape est pliée dans le binaire pepsi unifié, un prédécesseur peut l’exécuter dans son propre processus worker plutôt que de la dispatcher séparément. Voir pepsi-dispatch(1) et pepsi.conf(5).
pepsi-stage-if est un programme d’étape exécuté par pepsi-dispatch(1) comme worker persistant lisant les identifiants de message sur l’entrée standard. Il charge la ligne pepsi.workqueue du message (refusant d’agir si son status n’est pas running), lit sa section [stage-<stage>], et teste l’égalité d’un membre du JSON state du message avec une valeur configurée : s’ils sont égaux, il fait avancer le message vers TRUE_STAGE, sinon vers FALSE_STAGE. C’est un branchement programmable : un opérateur peut acheminer selon n’importe quel verdict qu’une étape antérieure a noté (state.spam, state.auth.dkim, …) sans écrire de code.
L’étape ne fait jamais que déplacer la colonne stage. Elle ne réécrit jamais le message, ne le met jamais en pause ni ne le fait échouer, et laisse state intact, de sorte que state.dsn et chaque autre verdict sont préservés à travers la branche. Le corps du message n’est jamais chargé.
95.1.35.1.4. Condition¶
STATE_PATH est un chemin séparé par des points dans le JSON state. Un segment appliqué à un objet sélectionne le membre de ce nom (même numérique) ; appliqué à un tableau, il doit être un entier non négatif et sélectionne cette position. Par exemple, spam sélectionne l’indicateur spam de premier niveau, auth.dkim le membre dkim de l’objet auth, et dsn.rcpt.0.notify le champ notify de la première entrée de destinataire.
La valeur trouvée là est comparée à VALUE par sa forme textuelle naturelle :
une chaîne correspond à son propre texte (
passcorrespond àpass) ;un booléen correspond à
trueoufalse;un nombre correspond à son rendu décimal (
3,1.5) ;le null JSON correspond au littéral
null.
Un chemin absent n’est jamais égal, pas plus qu’un chemin qui se résout en un tableau ou objet, qui n’a pas de forme scalaire ; un tel chemin prend la branche FALSE_STAGE. VALUE est obligatoire et ne peut pas être vide (une option vide est lue comme non définie).
95.1.35.1.5. Configuration¶
Les options résident dans la section [stage-<name>] propre à l’étape (PROGRAM = pepsi-stage-if) : le STATE_PATH à tester, le VALUE auquel comparer, et les cibles de branche TRUE_STAGE/FALSE_STAGE. Toutes quatre sont obligatoires, et pepsi-setup vérifie en outre que les deux cibles de branche nomment des étapes existantes. L’étape n’a pas de NEXT_STAGE (les deux destinations sont nommées explicitement). Les options sont documentées dans pepsi.conf(5).
Les quatre options sont lues dans la section de l’étape après l’application des paramètres par adresse. Lorsque l’étape figure dans les EDITABLE_STAGES d’une étape pepsi-stage-edit-settings(1), un correspondant peut donc changer le test et les deux cibles de branchement pour son propre courrier. N’y inscrivez jamais une étape if qui protège une décision de sécurité (voir pepsi-settings(1) et la frontière des paramètres dans le chapitre Modèle de menace du manuel).
95.1.35.1.6. État¶
Entrées : l’unique membre de state sélectionné par STATE_PATH.
Sorties : aucune ; l’étape ne fait qu’avancer le message et laisse state inchangé. La disposition de l’état est décrite dans pepsi.state(7).
Transitions : avance vers TRUE_STAGE lorsque le membre sélectionné par STATE_PATH est égal à VALUE (comparé par sa forme textuelle scalaire), sinon vers FALSE_STAGE. Un chemin manquant ou une valeur non scalaire prend aussi la branche FALSE_STAGE. Ces deux avancées sont les seules transitions ; l’étape ne met jamais en pause, ne fait jamais échouer, ne réachemine ni ne termine.
95.1.35.1.7. Commandes¶
- worker
Exécuté comme un worker persistant de pepsi-dispatch(1), lisant les identifiants de message sur l’entrée standard.
95.1.35.1.8. Options globales¶
- -c FILE, –config FILE
Lit la configuration depuis FILE au lieu de parcourir les emplacements par défaut.
- -L LOGLEVEL, –log LOGLEVEL
Règle la verbosité de journalisation (par défaut
[pepsi] LOG, sinoninfo).- -v, –verbose
Affiche les messages de journal de toutes les sources.
- -h, –help ; -V, –version
Affiche un résumé d’utilisation / la version et quitte.
95.1.35.1.9. Code de sortie¶
Le résultat de chaque message est rapporté à pepsi-dispatch(1) sur la ligne de statut du worker, et non par le code de sortie.
- 0
Le worker s’est exécuté jusqu’à la fermeture de son entrée standard.
- 1
Une erreur fatale s’est produite (configuration illisible, la base de données n’a pas pu être ouverte, ou l’entrée/sortie standard a échoué). La raison est écrite dans le journal.
- 78
Le worker a refusé de démarrer : une section
[stage-*]qu’il sert ne s’analyse pas (par exemple un STATE_PATH/VALUE/TRUE_STAGE/FALSE_STAGE manquant). Le dispatcher remet en file ce qu’il lui avait confié et réessaie l’étape plus tard.
95.1.35.1.10. Exemples¶
Retraiter le message 42 avec un worker ponctuel (il doit être running)
echo 42 | pepsi-stage-if -c /etc/pepsi/pepsi.conf worker
Une section de pipeline qui envoie le courrier qu’une étape antérieure a marqué comme spam (state.spam == true) vers l’étape de rebond et tout le reste plus loin
[stage-if]
PROGRAM = pepsi-stage-if
STATE_PATH = spam
VALUE = true
TRUE_STAGE = bounce
FALSE_STAGE = srs
L’exemple suivant retient le courrier chiffré d’inconnus que personne ici ne peut lire. Un message chiffré pour une clé détenue seulement dans le client d’un destinataire passe tous les filtres de contenu sous forme de texte chiffré, de même qu’un message auquel aucune clé d’ici ne convient. Avec pepsi-stage-decrypt(1) en premier sur le chemin entrant et pepsi-stage-check-whitelist(1) après lui, deux branches retiennent le courrier qu’aucune clé d’ici n’a pu ouvrir lorsqu’il vient d’un expéditeur que la liste blanche n’a pas laissé passer
[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 est toute étape qui soustrait le message à l’utilisateur sans prévenir l’expéditeur : une remise dans une boîte aux lettres de quarantaine, ou pepsi-stage-discard(1). Deux règles ne sont pas négociables. Brancher uniquement sur no-decryption-key, qui signifie qu’aucune clé d’ici ne convient au message, et jamais sur decryption-failed ni sur crypto.in.decrypted = false : qu’un texte chiffré AES-CBC modifié se déchiffre dépend de son remplissage, de sorte qu’un acheminement qui diffère entre les deux livrerait la réponse à un attaquant dès qu’il peut l’observer. Et ne jamais acheminer le courrier retenu vers une étape de rebond, pour la même raison. Le courrier chiffré pour la propre clé de client de l’utilisateur (crypto.in.for_client) ne porte aucun échec et n’est pas retenu ; ajoutez une troisième branche sur crypto.in.for_client = true seulement si un tel courrier provenant d’inconnus est lui aussi indésirable.
95.1.35.1.11. Voir aussi¶
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. Bogues¶
Signalez les bogues au gestionnaire de tickets de Pepsi.