95.1.44. pepsi-queue

inspect and repair the pepsi-ingress message queue

Section du manuel:

1

95.1.44.1.1. Nom

pepsi-queue - lister, supprimer, réaffecter à une étape et débloquer les messages de la file d’attente, et libérer les messages en quarantaine.

95.1.44.1.2. Synopsis

pepsi-queue [GLOBAL-OPTIONS] [list] [–json] [–state-only] [–headers] [–body] [–limit N] [–stage STAGE] [–status STATUS] [WORKQUEUE-ID]

pepsi-queue [GLOBAL-OPTIONS] delete WORKQUEUE-ID

pepsi-queue [GLOBAL-OPTIONS] set-stage WORKQUEUE-ID STAGE

pepsi-queue [GLOBAL-OPTIONS] clear-all

pepsi-queue [GLOBAL-OPTIONS] quarantine list [–json] [–limit N]

pepsi-queue [GLOBAL-OPTIONS] quarantine show [–json] TOKEN

pepsi-queue [GLOBAL-OPTIONS] quarantine release TOKEN

pepsi-queue [GLOBAL-OPTIONS] quarantine delete [–yes] TOKEN

pepsi-queue [GLOBAL-OPTIONS] gc

Les options de list sont acceptées sans le mot list parce que le listage est l’action par défaut, mais seulement dans ce cas : données devant une autre sous-commande (pepsi-queue --stage relay delete 5), elles sont refusées, et non silencieusement ignorées, puisqu’elles se liraient comme un filtre que la commande n’applique pas.

95.1.44.1.3. Description

pepsi-queue est un outil de diagnostic et de réparation pour la table pepsi.workqueue partagée par le pipeline Pepsi. Chaque message accepté avance à travers un pipeline de filtres, et trois colonnes de chaque ligne suivent sa progression : un stage (la section de configuration du programme qui est actuellement responsable du message ; init pour un message fraîchement accepté), un status (pending, running, paused, failed ou timeout), et un state JSON facultatif (données de travail par étape). Voir pepsi.state(7) pour les clés que state peut porter.

L’outil se connecte à la même base de données que les autres composants, via la section partagée [pepsi-postgres] ; sa seule option propre est [pepsi-queue] QUARANTINE_MAX_AGE_DAYS, que lit gc. Démarré en tant que root, il poursuit sous le compte de service pepsi, qui possède la file d’attente ; voir Exécution en tant que root.

Avertissement

Les sous-commandes mutantes agissent immédiatement et ne sont pas réversibles. delete supprime un message définitivement, et set-stage / clear-all changent l’état de traitement sur place.

set-stage et clear-all émettent bien une notification de base de données : lorsqu’elles ont déplacé au moins une ligne, elles la remettent à pending puis réveillent pepsi-dispatch(1), pour que le changement prenne effet aussitôt plutôt qu’au prochain sondage. pepsi.workqueue ne porte aucun déclencheur notifiant, et pepsi-queue s’exécute en dehors de la boucle propre du dispatcher : rien d’autre ne le ferait ; quarantine release fait de même. delete et quarantine delete n’en émettent aucune : une ligne qui a disparu ne donne au dispatcher rien à revendiquer.

Cela rend clear-all dangereux sur un pipeline en fonctionnement : il réinitialise des lignes actuellement running, alors qu’un worker peut encore en traiter une, puis les rend directement au dispatcher, qui les revendique de nouveau. Le message est alors traité deux fois, ce qui, pour une étape de remise, signifie une remise en double et, pour une étape de rebond, un rebond en double. Arrêtez d’abord pepsi-dispatch, ou ne l’utilisez qu’après un plantage, quand il ne reste aucun worker avec lequel il pourrait entrer en collision.

95.1.44.1.4. Commandes

list [–json] [–state-only] [–headers] [–body] [–limit N] [–stage STAGE] [–status STATUS] [WORKQUEUE-ID]

Lister les messages en file d’attente, ordonnés par workqueue_id. C’est aussi l’action par défaut lorsqu’aucune sous-commande n’est donnée, de sorte que le mot-clé list peut être omis : pepsi-queue liste tout et pepsi-queue 5 n’affiche que le message ayant le workqueue_id 5.

WORKQUEUE-ID

Un identifiant de message facultatif en fin de commande. Lorsqu’il est donné, un seul message au plus est affiché. --limit est alors sans objet, mais --stage et --status continuent de s’appliquer par-dessus : un message qui n’y correspond pas non plus n’est pas affiché. pepsi-queue 5 et pepsi-queue list 5 sont équivalents.

–json

Émettre un tableau JSON d’objets joliment formaté (workqueue_id, stage, status, mail_from, subject, received_at, state) au lieu de la table lisible par un humain. subject et state valent null lorsque le message n’en porte pas.

–state-only

Imprimer le state JSON complet et non tronqué de chaque message correspondant (la vue en table l’abrège), un bloc joliment formaté par message, chacun précédé d’une ligne de commentaire # workqueue_id. Avec un WORKQUEUE-ID explicite, cet en-tête est omis et la sortie n’est que l’état de ce message, de sorte que pepsi-queue --state-only 5 imprime le state complet du message 5, ce qui est pratique à passer dans un outil JSON. Un message sans state imprime null. Cette option a priorité sur –json.

–headers, –body

Écrit sur la sortie standard le bloc d’en-têtes stocké (–headers) ou le corps (–body) du message WORKQUEUE-ID, octet pour octet et sans rien afficher d’autre. Les deux ensemble écrivent le message entier (bloc d’en-têtes, ligne vide de séparation, corps), exactement comme le réassemble une étape qui charge le message complet. Les deux exigent un WORKQUEUE-ID et ne peuvent être combinées avec –json ou –state-only. La sortie est du courrier brut (fins de ligne CRLF, éventuellement 8 bits), destinée à un fichier ou à un tube, par exemple pepsi-queue --headers --body 5 | pepsi-detect-language.

–limit N

Afficher au plus N messages. Par défaut 100. Sans effet lorsqu’un WORKQUEUE-ID est donné, puisqu’une seule ligne au plus peut correspondre.

–stage STAGE

N’afficher que les messages dont l’étape est égale à STAGE.

–status STATUS

N’afficher que les messages ayant le statut donné.

delete WORKQUEUE-ID

Supprimer définitivement le message ayant le workqueue_id donné.

set-stage WORKQUEUE-ID STAGE

Réaffecter le message à STAGE et réinitialiser implicitement son statut à pending afin que la nouvelle étape le prenne. Le state du message est laissé inchangé.

clear-all

Réinitialiser à pending chaque message dont le statut est running ou paused. C’est le « déblocage » en masse que l’on utilise après un plantage ou une étape calée. Les messages en failed ou timeout sont laissés intacts, de même que les messages paused à une étape qui exécute pepsi-stage-quarantine(1) : ils ne sont pas bloqués mais retenus, et les réinitialiser les libérerait.

quarantine list [–json] [–limit N]

Lister les messages que retient une étape de quarantaine : les messages paused à chaque étape dont le PROGRAM est pepsi-stage-quarantine(1), du plus ancien au plus récent, au plus N (100 par défaut). La table montre pour chaque message son jeton, quand il est arrivé, depuis quand il est retenu, son expéditeur d’enveloppe et ses destinataires, ainsi que les champs by et reason de son enregistrement state.quarantine (qui l’a envoyé en quarantaine, et pourquoi). –json affiche à la place un tableau d’objets, avec workqueue_id, token, stage, status, received_at, mail_from, rcpt_to, from_header, subject, since, until, released_at, reason et by (null en cas d’absence). Les heures sont au format RFC 3339, en UTC.

quarantine show [–json] TOKEN

Afficher un message à une étape de quarantaine, quel que soit son statut, avec en plus son From: et son Subject:. Son contenu est accessible avec list --headers --body et le workqueue_id affiché ici.

quarantine release TOKEN

Libérer un message retenu : il est mis à pending à son étape de quarantaine et le dispatcher est réveillé, puis l’étape le fait suivre vers son RELEASE_STAGE. Seul un message paused à une étape de quarantaine est libéré.

quarantine delete [–yes] TOKEN

Supprimer un message à une étape de quarantaine, sauf si un worker le traite à ce moment-là. La commande demande confirmation sur le terminal ; sans terminal, elle refuse sauf si –yes est donné. Le journal de courrier facultatif ([pepsi] MAIL_LOG) consigne la suppression comme il consigne chaque message qui quitte la file, avec l’étape de quarantaine comme étape finale.

gc

Nettoie la table des nonces de preuve d’origine (pepsi.origin_nonce), en supprimant chaque entrée dont l’expiration à deux semaines est passée. Un nonce expiré ne peut plus authentifier un rebond qui revient ; l’abandonner est donc sans risque. La même exécution supprime les lignes du cache d’adresses MX (pepsi.dns_address) dont le TTL DNS est passé : l’étape de relais ne lit jamais une ligne expirée et remplace les lignes d’un hôte lorsqu’elle résout cet hôte à nouveau, mais un hôte qu’elle ne résout plus jamais les garderait sinon pour toujours.

Ensuite, l’exécution rafraîchit les politiques MTA-STS en cache (pepsi.mta_sts_policy), indépendamment du flux de courrier (RFC 8461 section 10.2), avant de supprimer celles qui ont expiré. L’exécution récupère à nouveau chaque politique qui a consommé la moitié de sa durée de vie ou à laquelle il reste moins de trois heures. La récupération utilise les paramètres DNS et de délai de la première étape pepsi-stage-relay-to-internet dont MTA_STS est activé (si aucune n’est configurée, rien n’est rafraîchi), et elle suit les règles qu’applique l’étape de relais lors de l’utilisation. Un domaine qui continue de publier une politique ne retombe donc jamais au stade d’un premier contact, aussi rarement qu’il reçoive du courrier. Quand un rafraîchissement échoue, la ligne est conservée jusqu’à ce que son max_age soit passé, puis supprimée, puisque l’étape de relais n’applique jamais une politique expirée. Un rafraîchissement qui ne peut pas du tout s’exécuter est signalé, et l’exécution continue.

L’exécution supprime ensuite aussi les demandes de confirmation de listes de diffusion consignées (pepsi.list_confirmation) dont la fenêtre LIST_CONFIRMATION_DAYS est dépassée ; les lignes de liste blanche list-id qu’a apprises pepsi-stage-auto-whitelist(1) et dont last_seen + max_idle est passé, que pepsi-stage-check-whitelist(1) ignore déjà (les lignes sans last_seen n’expirent jamais) ; les seconds facteurs mis en place par e-mail et non confirmés dans le délai OTP_CONFIRM_WINDOW (pepsi.otp_pending, voir pepsi-stage-encrypt(1)) ; et les rapports agrégés DMARC qu’a stockés pepsi-stage-dmarc-report(1) (pepsi.dmarc_report, avec leurs enregistrements) dont la période s’est achevée il y a plus de [pepsi-dmarc-reports] RETAIN_DAYS (90) jours.

gc est destiné à s’exécuter périodiquement ; le paquet Debian livre un pepsi-origin-gc.timer qui l’invoque toutes les heures. Voir pepsi-stage-relay-to-internet(1) et pepsi-stage-relay-to-smarthost(1) (qui consignent les nonces en relayant) ainsi que pepsi-stage-anti-spam(1) et pepsi-stage-auto-pay(1) (qui les vérifient).

La même exécution revérifie aussi chaque login de l’enregistrement d’attribution de logins RFC 7293 (pepsi.login_assignment) contre passwd : un login sans entrée est marqué disparu, et un login qui est revenu ou a changé d’uid est consigné comme ayant un nouveau propriétaire, ce qui abandonne les paramètres, listes blanches, quota et enregistrements de réponse automatique du propriétaire précédent (voir pepsi-setup(1), The login assignment record). Une recherche passwd qui échoue ne décide de rien, et une vérification dans laquelle la plupart des logins consignés semblent disparus n’en marque aucun.

Elle met aussi fin à la rétention du courrier à une étape de quarantaine, c’est-à-dire à toute étape que nomme une option QUARANTINE_STAGE de pepsi-stage-decrypt(1) ou de pepsi-stage-milter(1). Si un message pending ou paused arrivé il y a [pepsi-queue] QUARANTINE_MAX_AGE_DAYS (par défaut 14) jours ou plus s’y trouve encore, gc le déplace vers le BOUNCE_STAGE propre à l’étape de quarantaine, sinon vers [pepsi-failure-bouncer] BOUNCE_STAGE, avec state.failure_class = quarantine-expired, et transforme en RET=HDRS un RET=FULL qu’a demandé son expéditeur. L’expéditeur apprend ainsi (selon NOTIFY) que le message a été retenu et non libéré, et récupère son bloc d’en-têtes mais jamais son contenu, qui est précisément ce qui a été retenu.

Deux sortes de messages sont supprimés à la place, et journalisés : la copie d’une contribution de liste destinée à un membre (son expéditeur d’enveloppe est le processeur de rebonds de la liste), et un message dont le contenu est issu d’un texte chiffré EnvelopedData S/MIME (AES-CBC), ou n’a pas pu en être ouvert, tel que pepsi-stage-decrypt(1) l’a consigné dans state.crypto.in. Qu’un texte chiffré CBC modifié s’ouvre ou non dépend de son remplissage, et cela décide si le message est retenu ou remis. Un DSN à l’expiration indiquerait donc à son expéditeur lequel des deux cas s’est produit. Un tel message va là où l’envoient les propres réglages de rebond de l’étape de déchiffrement, jamais vers un endroit que l’expéditeur pourrait observer (télémétrie decrypt-dropped).

Un message retenu est du texte en clair au repos aussi longtemps qu’il est retenu, car la quarantaine d’une étape de déchiffrement retient ce que celle-ci a déchiffré ; c’est pourquoi la rétention a une fin. 0 conserve le courrier retenu quel que soit son âge. Une étape de quarantaine qui n’a aucune destination de rebond, ou dont l’étape de rebond est elle-même, est laissée telle quelle et nommée dans la sortie. Pour libérer un message avant ce terme, utilisez quarantine release à une étape pepsi-stage-quarantine(1), et sinon set-stage.

Toute étape qui exécute pepsi-stage-quarantine(1) est aussi une étape de quarantaine, qu’un QUARANTINE_STAGE la nomme ou non (un milter avant la mise en file de pepsi-ingress(1) y envoie aussi du courrier), sauf une étape dotée d’un MAX_HOLD, qui met elle-même fin à ses rétentions.

95.1.44.1.5. Journal d’audit

Les sous-commandes modifiantes sont enregistrées dans le journal d’audit partagé, par le même utilitaire que l’API d’administration emploie pour les mêmes actions : delete sous queue.cancel, set-stage sous queue.set-stage (avec la nouvelle étape), clear-all sous queue.clear-all (avec le nombre de lignes réinitialisées), quarantine release sous queue.quarantine-release et quarantine delete sous queue.quarantine-delete (chacune avec le jeton) ; la page de quarantaine de la console et /api/v1/quarantine de pepsi-httpd(1) libèrent et suppriment par les mêmes fonctions et enregistrent les mêmes natures. Déplacer un message à la main est un acte d’administration quelle que soit l’interface qui l’accomplit, et un journal qui n’en verrait qu’une seule serait trompeur plutôt que simplement incomplet. list et gc ne sont pas enregistrées : lire n’est pas une action, et le ramasse-miettes est une minuterie, pas un opérateur.

95.1.44.1.6. Exécution en tant que root

Pepsi donne à chaque composant son propre rôle PostgreSQL, authentifié via la socket locale par le compte système sous lequel le composant s’exécute, et root n’en fait délibérément pas partie. Plutôt que d’échouer à se connecter et de vous obliger à penser à sudo -u pepsi pepsi-queue …, l’outil détecte qu’il a été démarré en tant que root et devient le compte de service non privilégié pepsi avant de se connecter. Le dispatcher s’exécute sous ce compte, et ce compte possède pepsi.workqueue. Le changement est définitif pour la durée de vie du processus ; l’outil n’a besoin d’aucun privilège propre.

Le fichier de configuration (et tout fragment @inline-secret@ qu’il référence) est lu avant le basculement, de sorte qu’une configuration lisible par root seul est toujours chargée normalement.

Si le compte pepsi n’existe pas (dans une arborescence source non installée ou un banc de test), l’identité est laissée intacte, un avertissement est journalisé et la connexion est tentée en tant qu’utilisateur appelant, de sorte qu’une installation où root peut atteindre la base de données continue de fonctionner.

95.1.44.1.7. Options globales

Ces options globales précèdent la sous-commande (un indicateur placé à la fin est rejeté).

-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. LOGLEVEL est l’un de error, warn, info, debug ou trace. En l’absence de l’option, l’option globale [pepsi] LOG s’applique, et à défaut info.

-v, –verbose

Affiche les messages de journal de toutes les sources, y compris les bibliothèques tierces.

-h, –help

Affiche un résumé d’utilisation et quitte.

-V, –version

Affiche la version et quitte.

95.1.44.1.8. Code de sortie

0

Achèvement réussi. Un WORKQUEUE-ID ou un TOKEN qui ne correspond à aucune ligne n’est pas une erreur : list, delete, set-stage et les sous-commandes quarantine le signalent sur la sortie standard et sortent tout de même avec 0, de même qu’un quarantine delete qui n’a pas été confirmé.

1

Une erreur s’est produite : un fichier de configuration malformé ou une connexion ou requête de base de données échouée. La raison est écrite dans le journal.

2

La ligne de commande elle-même était erronée, y compris une option de list donnée devant une autre sous-commande.

78

Le schéma de la base de données appartient à une autre version de Pepsi (non installé, plus ancien, plus récent ou modifié) ; exécutez pepsi-setup schema (voir pepsi-setup(1)).

95.1.44.1.9. Fichiers

Lorsque –config n’est pas fourni, le premier fichier existant de la liste suivante est utilisé. Chaque composant Pepsi partage le même fichier de configuration, c’est donc la même liste que chacun parcourt :

  • $XDG_CONFIG_HOME/pepsi.conf

  • $HOME/.config/pepsi.conf

  • /etc/pepsi/pepsi.conf

  • /etc/pepsi.conf

95.1.44.1.10. Exemples

Lister les 20 premiers messages en file d’attente sous forme de table

pepsi-queue -c /etc/pepsi/pepsi.conf list --limit 20

Afficher, en JSON, chaque message actuellement détenu par l’étape spamfilter

pepsi-queue -c /etc/pepsi/pepsi.conf list --json --stage spamfilter

Inspecter uniquement le message 5, puis vider son state JSON complet

pepsi-queue -c /etc/pepsi/pepsi.conf 5
pepsi-queue -c /etc/pepsi/pepsi.conf --state-only 5

Enregistrer le message 5 tel qu’il est stocké, puis examiner son seul bloc d’en-têtes

pepsi-queue -c /etc/pepsi/pepsi.conf --headers --body 5 > msg5.eml
pepsi-queue -c /etc/pepsi/pepsi.conf --headers 5

Confier de nouveau le message 42 à l’étape spamfilter

pepsi-queue -c /etc/pepsi/pepsi.conf set-stage 42 spamfilter

Voir ce que retient une quarantaine, examiner un message, puis le libérer

pepsi-queue -c /etc/pepsi/pepsi.conf quarantine list
pepsi-queue -c /etc/pepsi/pepsi.conf quarantine show TOKEN
pepsi-queue -c /etc/pepsi/pepsi.conf quarantine release TOKEN

Supprimer un message retenu sans confirmation interactive, depuis un script

pepsi-queue -c /etc/pepsi/pepsi.conf quarantine delete --yes TOKEN

Récupérer après un plantage en remettant en file tout ce qui était en vol

pepsi-queue -c /etc/pepsi/pepsi.conf clear-all

95.1.44.1.11. Voir aussi

pepsi-status(1), pepsi-config(1), pepsi-ingress(1), pepsi-dispatch(1), pepsi-failure-bouncer(1), pepsi-stage-quarantine(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1)

95.1.44.1.12. Bogues

Signalez les bogues au gestionnaire de tickets de Pepsi.