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.since et laisse la ligne paused. Sans MAX_HOLD, la ligne n’a pas de timeout, 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, le timeout est la fin de la rétention, et state.quarantine.until la note.

  • À la libération (pepsi-queue quarantine release, ou un pepsi-queue set-stage ou une remise en file administrative vers cette étape par un opérateur), la ligne revient à cette étape en pending. L’étape note released_at et fait suivre le message vers RELEASE_STAGE. Le webhook POST /resume de 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 expired et 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 weeks ou 36 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_QUARANTINE d’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, timeout NULL ou la fin de MAX_HOLD ;

  • revendiqué de nouveau pendant la rétention, avant until → RELEASE_STAGE, pending ;

  • revendiqué à until ou 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, sinon info).

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