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élistpeut être omis :pepsi-queueliste tout etpepsi-queue 5n’affiche que le message ayant leworkqueue_id5.- WORKQUEUE-ID
Un identifiant de message facultatif en fin de commande. Lorsqu’il est donné, un seul message au plus est affiché.
--limitest alors sans objet, mais--stageet--statuscontinuent de s’appliquer par-dessus : un message qui n’y correspond pas non plus n’est pas affiché.pepsi-queue 5etpepsi-queue list 5sont é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.subjectetstatevalentnulllorsque le message n’en porte pas.- –state-only
Imprimer le
stateJSON 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 quepepsi-queue --state-only 5imprime lestatecomplet du message 5, ce qui est pratique à passer dans un outil JSON. Un message sansstateimprimenull. 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_iddonné.- set-stage WORKQUEUE-ID STAGE
Réaffecter le message à STAGE et réinitialiser implicitement son statut à
pendingafin que la nouvelle étape le prenne. Lestatedu message est laissé inchangé.- clear-all
Réinitialiser à
pendingchaque message dont le statut estrunningoupaused. C’est le « déblocage » en masse que l’on utilise après un plantage ou une étape calée. Les messages enfailedoutimeoutsont laissés intacts, de même que les messagespausedà 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 lePROGRAMest pepsi-stage-quarantine(1), du plus ancien au plus récent, au plus N (100par 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 champsbyetreasonde son enregistrementstate.quarantine(qui l’a envoyé en quarantaine, et pourquoi). –json affiche à la place un tableau d’objets, avecworkqueue_id,token,stage,status,received_at,mail_from,rcpt_to,from_header,subject,since,until,released_at,reasonetby(nullen 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 sonSubject:. Son contenu est accessible aveclist --headers --bodyet leworkqueue_idaffiché 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 sonRELEASE_STAGE. Seul un messagepausedà 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 étapepepsi-stage-relay-to-internetdontMTA_STSest 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 sonmax_agesoit 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êtreLIST_CONFIRMATION_DAYSest dépassée ; les lignes de liste blanchelist-idqu’a apprises pepsi-stage-auto-whitelist(1) et dontlast_seen + max_idleest passé, que pepsi-stage-check-whitelist(1) ignore déjà (les lignes sanslast_seenn’expirent jamais) ; les seconds facteurs mis en place par e-mail et non confirmés dans le délaiOTP_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.timerqui 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_STAGEde pepsi-stage-decrypt(1) ou de pepsi-stage-milter(1). Si un messagependingoupausedarrivé 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, avecstate.failure_class = quarantine-expired, et transforme enRET=HDRSunRET=FULLqu’a demandé son expéditeur. L’expéditeur apprend ainsi (selonNOTIFY) 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é
EnvelopedDataS/MIME (AES-CBC), ou n’a pas pu en être ouvert, tel que pepsi-stage-decrypt(1) l’a consigné dansstate.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étriedecrypt-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.
0conserve 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_STAGEla 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’unMAX_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,debugoutrace. En l’absence de l’option, l’option globale[pepsi] LOGs’applique, et à défautinfo.- -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.