95.1.57. pepsi-failure-bouncer¶
Funnel failed/timeout messages to the bounce stage
- Section du manuel:
1
95.1.57.1.1. Nom¶
pepsi-failure-bouncer - déplacer les messages bloqués (failed/timeout) vers l’étape de rebond.
95.1.57.1.2. Synopsis¶
pepsi-failure-bouncer [GLOBAL-OPTIONS] [–failed-only | –timeout-only]
pepsi-failure-bouncer [GLOBAL-OPTIONS] –once [–failed-only | –timeout-only]
95.1.57.1.3. Description¶
Un message qui traverse le pipeline d’étapes après l’ingress (voir pepsi-dispatch(1)) atterrit dans l’un des deux états terminaux lorsque son étape courante abandonne :
failedUne étape a appelé
fail()ou renvoyé une erreur qu’elle a marquée permanente, le worker a renoncé à réessayer une erreur à une étape sansBOUNCE_STAGE, le message a fait planter son worker trois fois, ou le dispatcher l’a trouvé en attente à une étape que la configuration ne nomme plus.timeoutLe message a retenu son worker au-delà de MAX_RUNTIME trois fois ou, dans une étape
pepsi-stage-relay-to-*, était encore tué à MAX_LIFETIME.
La plupart des erreurs n’arrivent jamais ici : le worker les réessaie jusqu’au MAX_LIFETIME de l’étape, puis remet lui-même le message au BOUNCE_STAGE de l’étape (voir pepsi-dispatch(1)).
Le dispatcher ne remet jamais en file une ligne failed ou timeout, de sorte que, sans ce programme, de tels messages s’accumulent dans pepsi.workqueue et l’expéditeur d’origine n’est jamais informé que son courrier n’a pas été remis. C’est pourquoi pepsi.target l’exécute (voir Systemd ci-dessous).
pepsi-failure-bouncer déplace chaque message bloqué vers le [pepsi-failure-bouncer] BOUNCE_STAGE configuré et réinitialise son statut à pending. Le dispatcher exécute alors l’étape de rebond (pepsi-stage-bounce(1)), qui transforme le message en une notification d’état de remise et la relaie vers l’expéditeur, en honorant le NOTIFY RFC 3461 de l’expéditeur.
Il attend d’abord : un message n’est déplacé qu’une fois en échec depuis [pepsi-failure-bouncer] MIN_AGE (par défaut une heure). Ce temps est mesuré depuis state.failed_at, que la base de données horodate lorsque la ligne devient failed/timeout. L’opérateur dispose ainsi d’une fenêtre pour remarquer l’échec et remettre le message en circulation avec pepsi-queue(1) avant que son expéditeur n’en soit informé. Chaque message qu’il déplace est journalisé comme un avertissement avec son expéditeur, l’étape où il a échoué et l’erreur enregistrée, car l’étape de rebond remplace cet enregistrement par le DSN. L’étape est aussi conservée dans state.failed_stage, que pepsi-stage-bounce(1) nomme dans le DSN.
La copie d’une contribution de liste destinée à un membre (un message portant state.list.member) est au contraire supprimée, avec la même ligne de journal. Son expéditeur d’enveloppe est l’adresse de rebond propre à la liste, de sorte qu’un DSN atteindrait le traitement des rebonds de la liste et imputerait au membre une faute de cet hôte. Une contribution en route vers une liste, qui porte aussi state.list, a pour expéditeur d’enveloppe son auteur et rebondit comme tout autre message. Un message est aussi supprimé lorsque son contenu est issu d’un texte chiffré sans protection d’intégrité, ou n’a pas pu en être ouvert (un EnvelopedData S/MIME, AES-CBC ; consigné par pepsi-stage-decrypt(1) dans state.crypto.in). La clé de télémétrie decrypt-dropped compte ces cas. Qu’une étape ait échoué sur un tel message peut dépendre d’un contenu qui dépend du remplissage CBC d’un texte chiffré, que l’expéditeur a pu modifier ; un DSN indiquerait donc à l’expéditeur si le remplissage était valide.
Un message qui est déjà à l’étape de rebond est laissé intact, de sorte qu’un rebond qui échoue lui-même à cette étape ne boucle pas. Un rebond qui échoue en aval de l’étape de rebond (un DSN à expéditeur nul qui n’a pas pu être relayé) est tout de même ramené à l’étape de rebond, qui le supprime simplement — un rebond n’est jamais rebondi à nouveau.
La première règle n’est que la protection à un pas ; la seconde met fin à toute chaîne plus longue, car une véritable étape de rebond réécrit le message avec un expéditeur nul, et un message à expéditeur nul est abandonné plutôt que rebondi à nouveau. BOUNCE_STAGE doit donc mener à une étape de rebond. S’il pointe vers une étape qui ne fait qu’avancer, il n’y a plus aucun point fixe : le message avance, échoue à nouveau plus loin et est réinitialisé à nouveau, dans une boucle que la notification d’échec entretient à la vitesse de la base de données. pepsi-setup(1) échoue purement et simplement lorsque BOUNCE_STAGE ne nomme aucune étape configurée, et avertit lorsqu’il en nomme une qui n’exécute pas directement pepsi-stage-bounce(1) ; le second cas n’est qu’un avertissement, car l’option peut délibérément nommer une étape d’acheminement qui atteint l’étape de rebond sur une branche.
Ayant fait passer des lignes à pending, le bouncer notifie lui-même le canal workqueue, de sorte que le dispatcher traite le rebond immédiatement plutôt qu’à son prochain balayage POLL_INTERVAL. Il le doit : il s’exécute hors de la boucle du dispatcher, et aucun déclencheur sur pepsi.workqueue ne notifie le canal workqueue du dispatcher. L’unique déclencheur de notification de la table alimente le canal workqueue_failed décrit ci-dessous, et seul cet outil écoute ce canal (voir pepsi-dispatch(1)).
Il se connecte à la base de données partagée via la section [pepsi-postgres] et est configuré par [pepsi-failure-bouncer] (voir pepsi.conf(5)). Lorsqu’il est démarré en tant que root (depuis un shell root, une tâche cron ou une unité sans User=), il poursuit sous le compte de service non privilégié pepsi avant de se connecter ; c’est le rôle qui possède la file d’attente. root n’a pas de rôle PostgreSQL propre, de sorte que sans ce basculement la connexion serait refusée. La configuration est lue en premier, et si le compte pepsi n’existe pas, l’identité est laissée intacte et un avertissement est journalisé. Ce n’est pas une étape.
95.1.57.1.4. Modes¶
Sans l’indicateur --once, pepsi-failure-bouncer s’exécute comme un service de longue durée. Il fait un LISTEN sur le canal PostgreSQL workqueue_failed, que le déclencheur workqueue_failed_notify active chaque fois qu’un écrivain fait passer une ligne à failed ou timeout. Il fait rebondir chaque message une fois qu’il a atteint l’âge MIN_AGE, et lorsqu’aucune notification n’arrive avant, il se réveille pour le plus ancien échec en attente. Au démarrage, et à nouveau à chaque reconnexion, il balaie d’abord tous les messages déjà bloqués, afin de ne rien manquer de ce qui a été validé avant que l’écouteur ne s’attache (ou pendant une connexion perdue). Il s’exécute jusqu’à recevoir SIGINT ou SIGTERM.
Avec –once, il effectue ce balayage une seule fois sur tous les messages actuellement bloqués et quitte. C’est la forme adaptée à une exécution manuelle par l’opérateur et au timer livré.
95.1.57.1.5. Systemd¶
pepsi-failure-bouncer.timer exécute pepsi-failure-bouncer.service, un balayage –once sous le compte pepsi, dix minutes après le démarrage puis toutes les dix minutes. pepsi.target requiert le timer, de sorte qu’activer la cible active le balayage. Un message en échec reste donc dans la file entre MIN_AGE et MIN_AGE plus dix minutes avant de rebondir (ou, pour un expéditeur que le message n’a pas authentifié, d’être abandonné avec un avertissement ; voir BOUNCE_UNAUTHENTICATED dans pepsi.conf(5)). Pour réessayer plutôt un message, utilisez pepsi-queue(1) set-stage dans ce délai.
Les développeurs et testeurs qui veulent conserver les messages en échec pour le diagnostic désactivent le balayage avec
systemctl mask --now pepsi-failure-bouncer.timer
Le masquage est nécessaire parce que pepsi.target redémarrerait un timer simplement désactivé ou arrêté. systemctl unmask pepsi-failure-bouncer.timer suivi de systemctl start pepsi-failure-bouncer.timer le réactive ; le balayage suivant fait alors rebondir tout ce qui a échoué entre-temps. Ne le laissez pas masqué sur une machine qui traite du vrai courrier.
Aucune unité n’exécute le mode service de longue durée. Un site qui le préfère (un échec rebondit alors en quelques instants plutôt qu’en quelques minutes) masque le timer et lance le service depuis sa propre unité.
95.1.57.1.6. Options¶
- –once
Balayer les messages qui sont bloqués maintenant, et le sont depuis MIN_AGE, et quitter, au lieu de s’exécuter comme un service qui écoute les nouveaux échecs.
- –failed-only
N’agir que sur les messages
failed, en ignoranttimeout.- –timeout-only
N’agir que sur les messages
timeout, en ignorantfailed. Mutuellement exclusif avec –failed-only.
95.1.57.1.7. Options globales¶
Ces options peuvent apparaître avant ou après les autres indicateurs.
- -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 cette option, c’est l’option globale[pepsi] LOGqui s’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.57.1.8. Code de sortie¶
- 0
Achèvement réussi (un balayage
--onces’est terminé, ou le service s’est arrêté proprement sur un signal).- 1
Une erreur s’est produite : une configuration malformée, l’absence de l’option obligatoire
BOUNCE_STAGE, ou l’échec de la connexion à la base de données. En mode service, une connexion à la base de données perdue n’est pas fatale : elle est journalisée et réessayée avec un backoff.- 78
Le schéma de la base de données ne correspond pas à cette version (non installé, plus ancien, plus récent ou modifié) ; exécutez d’abord
schemade pepsi-setup(1).
95.1.57.1.9. Exemples¶
Exécuter comme service, depuis votre propre unité
pepsi-failure-bouncer -c /etc/pepsi/pepsi.conf
Faire rebondir tout ce qui est actuellement bloqué, une fois, à la main
pepsi-failure-bouncer -c /etc/pepsi/pepsi.conf --once
Ne faire rebondir que les messages qui ont expiré
pepsi-failure-bouncer -c /etc/pepsi/pepsi.conf --once --timeout-only
95.1.57.1.10. Voir aussi¶
pepsi-dispatch(1), pepsi-stage-bounce(1), pepsi-queue(1), pepsi-status(1), pepsi.conf(5), systemd.timer(5)
« Loops and amplification » dans le chapitre modèle de menace du manuel de Pepsi (pourquoi un échec ne rebondit jamais en boucle), et « Unknown recipients and backscatter » dans son chapitre sécurité (pourquoi l’étape de rebond abandonne un rapport d’échec destiné à un expéditeur que le message n’a pas authentifié).
95.1.57.1.11. Bogues¶
Signalez les bogues au gestionnaire de tickets de Pepsi.