95.1.38. pepsi-stage-quarantine¶
hold a message until an operator releases or deletes it
- Section du manuel:
1
95.1.38.1.1. Nom¶
pepsi-stage-quarantine - l’étape de quarantaine du pipeline Pepsi.
95.1.38.1.2. Synopsis¶
pepsi-stage-quarantine [GLOBAL-OPTIONS] worker
95.1.38.1.3. Description¶
pepsi-stage-quarantine est un programme d’étape exécuté par pepsi-dispatch(1) comme un worker persistant lisant les identifiants de message sur l’entrée standard. Il retient chaque message qui lui parvient jusqu’à ce qu’un opérateur le libère ou le supprime avec pepsi-queue(1) quarantine. Le courrier lui parvient partout où le pipeline l’y achemine : par la demande de quarantaine d’un milter (le QUARANTINE_STAGE de pepsi-stage-milter(1), ou d’un milter pré-file de pepsi-ingress(1)), par le QUARANTINE_STAGE de pepsi-stage-decrypt(1), ou par l’acheminement de toute autre étape.
L’étape voit un message au plus trois fois :
À l’arrivée, elle note
state.quarantine.sinceet laisse la lignepaused. Sans MAX_HOLD, la ligne n’a pas detimeout, de sorte que pepsi-dispatch(1) ne la réveille jamais de lui-même ; le message attend que quelqu’un agisse. Avec MAX_HOLD, letimeoutest la fin de la rétention, etstate.quarantine.untilla note.À la libération (
pepsi-queue quarantine release, ou unpepsi-queue set-stageou une remise en file administrative vers cette étape par un opérateur), la ligne revient à cette étape enpending. L’étape notereleased_atet fait suivre le message vers RELEASE_STAGE. Le webhookPOST /resumede pepsi-httpd(1), qui reprend un message dès qu’un paiement arrive, ne touche pas à un message retenu : son jeton est une notification de paiement, pas la décision d’un opérateur.À l’expiration, lorsque le dispatcher réveille la ligne à la fin de MAX_HOLD, l’étape note
expiredet achemine le message vers EXPIRE_STAGE, ou le supprime lorsque cette option n’est pas définie.
Une libération et une expiration se ressemblent pour l’étape, qui les distingue donc à son horloge : une revendication à until ou après est l’expiration. Une petite marge d’au plus cinq secondes, et d’au plus la moitié de la rétention, couvre un écart d’horloge entre l’hôte de la base de données et celui-ci ; une libération en ce dernier instant compte donc comme une expiration, jamais l’inverse. MAX_HOLD est lu au début d’une rétention : le modifier ensuite ne change ni la fin d’une rétention déjà notée, ni le fait que cette rétention prenne fin ou non.
Un message en route vers EXPIRE_STAGE est marqué comme pepsi-queue(1) gc marque une quarantaine expirée : state.failed_stage est cette étape, state.failure_class vaut quarantine-expired, un RET=FULL demandé par l’expéditeur devient RET=HDRS, et un state.bounce porté par le message est abandonné, afin que pepsi-stage-bounce(1) puisse dire à l’expéditeur que le message a été retenu et non libéré, sans renvoyer son contenu. Deux sortes de messages sont supprimées à l’expiration au lieu d’être acheminées, comme gc les supprime : la copie d’une contribution de liste destinée à un membre, dont l’expéditeur d’enveloppe est le gestionnaire de rebonds de la liste, et un message dont le contenu est sorti d’un texte chiffré sans protection d’intégrité, ou n’a pas pu en être ouvert (télémétrie decrypt-dropped). Pour la seconde sorte, le fait même que le message ait été retenu peut dépendre du remplissage d’un texte chiffré que son expéditeur a pu modifier, de sorte qu’un rapport à la fin de la rétention répondrait à la question du remplissage.
L’étape n’envoie aucun avis de son propre chef, ni à l’expéditeur ni aux destinataires.
Les options sont lues depuis la configuration de base, jamais depuis les paramètres par adresse : ce que retient une quarantaine, et pendant combien de temps, relève de la décision de l’hôte.
Un message libéré une fois d’une quarantaine et qui atteint plus tard de nouveau une étape de quarantaine est retenu à nouveau. L’émetteur d’une demande de quarantaine écrit un enregistrement neuf, et l’étape commence aussi une nouvelle rétention pour un enregistrement dont la rétention antérieure a pris fin.
Les rétentions sans MAX_HOLD restent bornées par pepsi-queue(1) gc, qui génère un rebond pour un message retenu à une étape de quarantaine [pepsi-queue] QUARANTINE_MAX_AGE_DAYS (14 par défaut) jours après son arrivée, comme il le fait pour toute étape de quarantaine. Une étape dotée de MAX_HOLD met fin elle-même à ses rétentions, et gc la laisse tranquille. Le courrier retenu est stocké en clair tant qu’il est retenu (la quarantaine d’une étape de déchiffrement retient ce que celle-ci a déchiffré), et c’est pourquoi une limite s’applique par défaut.
95.1.38.1.4. Configuration¶
Les options se trouvent dans la section [stage-<name>] propre à l’étape (PROGRAM = pepsi-stage-quarantine) ; toutes sont facultatives, mais l’une de RELEASE_STAGE et NEXT_STAGE doit être définie.
- RELEASE_STAGE = STAGE
Où va un message libéré. Vaut par défaut NEXT_STAGE. Un message que l’ingress a mis en quarantaine a sauté toutes les étapes précédant celle-ci ; pour cet usage, la valeur est donc normalement
init. Elle ne doit pas désigner cette étape elle-même.- MAX_HOLD = SPAN
Durée maximale d’une rétention, par exemple
14 days,2 weeksou36 h(un jour compte pour 24 heures ; les mois et les années sont refusés). Sans valeur, une rétention dure jusqu’à ce que le message soit libéré ou supprimé, dans la limite de pepsi-queue(1)gc.- EXPIRE_STAGE = STAGE
Où va un message lorsque sa rétention atteint MAX_HOLD, par exemple une étape pepsi-stage-bounce(1). Sans valeur, un message expiré est supprimé (noté dans le journal de courrier, s’il est activé, comme tout message supprimé). Refusée sans MAX_HOLD, puisque aucune rétention ne pourrait l’atteindre, et refusée lorsqu’elle désigne cette étape elle-même.
Le worker refuse de démarrer (code de sortie 78) lorsque la section ne s’analyse pas ou qu’une étape qu’elle nomme n’existe pas ; pepsi-setup(1) validate refuse la même chose. Toutes les options sont documentées dans pepsi.conf(5).
95.1.38.1.5. État¶
Entrées : state.quarantine.reason et state.quarantine.by, si la partie qui a envoyé le message ici les a écrits ; state.dsn et state.crypto.in à l’expiration.
Sorties : l’enregistrement state.quarantine, un objet dont les clés ne font que s’ajouter d’une version à l’autre :
reason(chaîne, facultative)Pourquoi le message est retenu, tel que l’a formulé la partie qui l’a envoyé ici (le texte
SMFIR_QUARANTINEd’un milter).by(chaîne, facultative)Qui l’a envoyé ici :
milter:<MILTER_NAME>pour un milter,stage:<name>pour une autre étape.since(chaîne, RFC 3339)Quand cette étape a commencé à retenir le message.
until(chaîne, RFC 3339)Quand la rétention prend fin d’elle-même, avec MAX_HOLD.
released_at(chaîne, RFC 3339)Quand le message a été libéré.
expired(true)La rétention a atteint
until.
La structure est décrite dans pepsi.state(7).
Transitions :
première arrivée, ou un enregistrement dont la rétention antérieure a pris fin →
pausedà cette étape,timeoutNULLou la fin de MAX_HOLD ;revendiqué de nouveau pendant la rétention, avant
until→ RELEASE_STAGE,pending;revendiqué à
untilou après → EXPIRE_STAGE,pending, ou supprimé.
95.1.38.1.6. Commandes¶
- worker
Exécuté comme un worker persistant de pepsi-dispatch(1), lisant les identifiants de message sur l’entrée standard.
95.1.38.1.7. 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.38.1.8. 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, base de données impossible à ouvrir, ou échec de l’entrée/sortie standard). La raison est écrite dans le journal.
- 78
La section de l’étape ne s’analyse pas, ou une étape qu’elle nomme n’existe pas : le worker refuse de démarrer, et pepsi-dispatch(1) retient les messages de l’étape jusqu’à ce que la configuration soit corrigée.
95.1.38.1.9. Exemples¶
Une quarantaine pour les verdicts d’un milter, libérée vers le reste du 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
Une quarantaine qui met fin à une rétention au bout de deux semaines par une DSN à l’expéditeur
[stage-quarantine]
PROGRAM = pepsi-stage-quarantine
RELEASE_STAGE = init
MAX_HOLD = 2 weeks
EXPIRE_STAGE = bounce
Lister ce qui est retenu, puis libérer un message
pepsi-queue -c /etc/pepsi/pepsi.conf quarantine list
pepsi-queue -c /etc/pepsi/pepsi.conf quarantine release TOKEN
95.1.38.1.10. Voir aussi¶
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. Bogues¶
Signalez les bogues au gestionnaire de tickets de Pepsi.