85.1.40. pepsi-queue¶

inspect and repair the pepsi-ingress message queue

Section du manuel:: 1

85.1.40.1.1. Nom¶

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

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

85.1.40.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 suivi par trois colonnes sur chaque ligne : un stage (la section de configuration du programme 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] ; il n’introduit aucune configuration propre. 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. delete n’en émet 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 — 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 qui entrer en collision.

85.1.40.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 — 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 chaque message dont le statut est running ou paused à pending — le « déblocage » en masse utilisé après un plantage ou une étape calée. Les messages en failed ou timeout sont laissés intacts.

gc

Passer le ramasse-miettes sur la table des nonces de preuve d’origine (pepsi.origin_nonce), en supprimant chaque entrée dont l’expiration de deux semaines est passée. Un nonce expiré ne peut plus authentifier un rebond de retour, de sorte que le supprimer est sûr. La même exécution supprime les lignes du cache d’adresses MX (pepsi.dns_address) dont le TTL DNS est dépassé : l’étape de relais ne lit jamais une ligne expirée et remplace les lignes d’un hôte lorsqu’elle le résout de nouveau, mais un hôte qu’elle ne résout plus jamais les conserverait sinon à tout jamais. 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 notent les nonces au moment du relais) ainsi que pepsi-stage-anti-spam(1) et pepsi-stage-auto-pay(1) (qui les vérifient).

85.1.40.1.5. Journal d’audit¶

Les trois 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) et clear-all sous queue.clear-all (avec le nombre de lignes réinitialisées). Déplacer un message à la main est un acte d’administration quelle que soit la surface 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.

85.1.40.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 il 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 — le compte sous lequel s’exécute le dispatcher, qui possède pepsi.workqueue — avant de se connecter. 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 — une arborescence source non installée, 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.

85.1.40.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 (par 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.

85.1.40.1.8. Code de sortie¶

0: Achèvement réussi. Un WORKQUEUE-ID qui ne correspond à aucune ligne n’est pas une erreur : list, delete et set-stage le signalent sur la sortie standard et sortent tout de même avec 0.
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.

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

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

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

85.1.40.1.11. Voir aussi¶

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

85.1.40.1.12. Bogues¶

Signalez les bogues au gestionnaire de tickets de Pepsi.