85.1.41. pepsi-status

summarise the health of the Pepsi mail pipeline

Section du manuel:

1

85.1.41.1.1. Nom

pepsi-status - imprimer un résumé de santé lisible par un humain de la file, des messages bloqués, des statistiques de remise et d’échec, et des issues TLS sortantes.

85.1.41.1.2. Synopsis

pepsi-status [GLOBAL-OPTIONS] [–json] [–limit N]

85.1.41.1.3. Description

pepsi-status imprime un rapport de santé ponctuel et en lecture seule du pipeline Pepsi, tiré entièrement de la base de données pepsi partagée. Il est destiné à être exécuté de façon interactive ou via SSH (par exemple depuis un hôte de surveillance) ; il ne modifie jamais une ligne et n’émet aucune notification de base de données, de sorte qu’on peut l’exécuter sans risque sur un déploiement en service à tout moment.

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 ; voir Exécution en tant que root.

Le rapport comporte six sections :

File d’attente

Le contenu actuel de la table pepsi.workqueue, ventilé par stage et status, avec l’âge du message le plus ancien de chaque groupe et un total général. C’est l’arriéré en direct : les lignes pending et running sont du travail en cours, les lignes paused attendent (par exemple un délai de paiement ou un réessai de relais), et les lignes failed/timeout demandent de l’attention.

Messages bloqués

Les messages individuels dont le statut est failed ou timeout, du plus ancien au plus récent. Pour chacun, le rapport montre le workqueue_id, le statut, l’étape, l’âge, l’expéditeur d’enveloppe et le sujet, et — lorsqu’une étape de relais en a noté une — la raison structurée pour laquelle le saut suivant a refusé le message (MTA distant, code SMTP, état étendu et texte de réponse, ou notre propre diagnostic, issus de state.bounce), le texte d’erreur que l’étape a noté lorsqu’elle a fait échouer ou différé le message (state.last_error, affiché sous la forme error:), et la raison donnée par pepsi-dispatch lorsqu’il a lui-même fait échouer ou expirer le message — un worker planté ou bloqué, ou une étape non configurée (state.dispatch_error, affiché sous la forme dispatch:). Dans la sortie –json, ces trois éléments sont les champs bounce, last_error et dispatch_error de chaque entrée problems. La liste est plafonnée par –limit ; la taille réelle de l’arriéré est toujours affichée.

Remises et échecs

Compteurs cumulatifs du pipeline : le nombre total de messages qui se sont achevés et ont quitté le pipeline, le total des exécutions d’étape, et par étape le nombre d’exécutions comptabilisées (la colonne MESSAGES, qui est le dénominateur de la moyenne), le temps de traitement moyen, les timeouts et les plantages de workers. Ce sont des totaux sur toute la durée de vie, accumulés depuis la création du schéma. Comme un message remis avec succès est supprimé de la file, il n’existe pas de journal de remise par message et donc pas de fenêtre temporelle glissante : les chiffres sont cumulatifs, ils ne portent pas « sur la dernière heure ».

TLS sortant

Issues des sessions TLS sortantes sur les sept derniers jours de rapport UTC (celui d’aujourd’hui, en UTC, et les six précédents, quel que soit le fuseau horaire du serveur), groupées par domaine de politique et type de résultat, avec les résultats non réussis marqués. Ces données ne sont présentes que lorsque [pepsi-tlsrpt] SEND_REPORTS est activé, et seulement aussi longtemps que pepsi-tlsrpt prune les conserve ([pepsi-tlsrpt] RETAIN_DAYS, également sept jours par défaut) : une rétention plus courte raccourcit donc cette section. La section liste ensuite toute adresse d’hôte MX que le cache du résolveur a actuellement marquée comme échouant à se connecter, avec l’heure de leur dernière connexion réussie (ou never).

Quotas de boîtes aux lettres

Une ligne par compte local dont Pepsi a tenu la comptabilité, mesure la plus ancienne d’abord : l’occupation, la limite effective, le taux de remplissage, d’où vient le chiffre (fsquota/maildirsize/scan) et depuis combien de temps la boîte aux lettres a été mesurée. Une ligne existe pour chaque compte auquel Pepsi a remis du courrier — c’est ce qui la crée — qu’il ait un quota ou non ; sur un déploiement qui n’utilise pas la fonctionnalité, la section liste donc quand même ces comptes, avec - dans les colonnes LIMIT et FULL. Elle n’est vide — et le dit — que lorsque aucune remise locale n’a été comptabilisée.

LIMIT est la limite réellement en vigueur, résolue exactement comme le chemin de remise la résout : la limite propre au compte s’il en a une, sinon la valeur par défaut du site [pepsi] MAILBOX_QUOTA, un 0 explicite sur le compte signifiant illimité et non hériter, le quota propre au noyau resserrant celle qui l’a emporté.

USED est la dernière mesure plus tout ce qui a été remis depuis ; elle ne fait que croître, car rien n’indique à Pepsi qu’un utilisateur supprime du courrier par IMAP : c’est donc une borne supérieure plutôt qu’un fait. MEASURED est le temps écoulé depuis que quelqu’un a réellement regardé, et cela compte parce qu’un refus au RCPT repose sur la fraîcheur d’une mesure : un compte affiché « plein » face à une mesure très ancienne est un compte dont le reconcile de pepsi-quota(1) devrait s’occuper.

Changements de clé des correspondants

Combien de clés de chiffrement de correspondants la règle Autocrypt « le plus récent l’emporte » a remplacées au cours des 30 derniers jours (rotated), et combien de tels remplacements ACCEPT_ROTATION = expired a refusés (held), suivis des plus récents des deux — plafonnés par –limit — avec la date, l’adresse, le protocole, les anciennes et nouvelles empreintes, et l’indication que la nouvelle clé était celle du correspondant lui-même (inbound) ou présentée par un tiers (gossip). Une rotation est le seul moyen par lequel un message qui prétend simplement venir d’un correspondant peut changer la clé avec laquelle nous lui chiffrons le courrier, c’est pourquoi elle est montrée ici plutôt que laissée dans le journal d’audit. Les chiffres sont lus dans les lignes key.peer.rotate et key.peer.rotate.held de pepsi.event_log, que la base de données écrit en même temps que le changement lui-même, de sorte que la section remonte aussi loin que [pepsi-admin] EVENT_RETENTION les conserve. Voir pepsi-stage-autocrypt-learn(1).

Le texte libre du rapport lisible par un humain — la réponse d’un MTA distant, le sujet d’un message, un nom d’hôte issu du cache du résolveur — voit ses caractères de contrôle remplacés par des espaces avant d’être imprimé. Tout ce texte est choisi par quelqu’un d’autre, et cet outil est fait pour être exécuté via SSH sur un déploiement en service, c’est-à-dire précisément là où une séquence d’échappement de terminal repeindrait l’écran de l’opérateur. La sortie --json n’est pas concernée : l’échappement JSON s’en charge déjà.

85.1.41.1.4. Options

–json

Émettre tout le rapport sous forme d’un unique objet JSON (clés queue, problem_total, problems, global, stages, tls_report_days, tls, dns_failures, mailboxes, quota_default_bytes, key_change_days, key_changes_rotated, key_changes_held et key_changes) au lieu du texte lisible par un humain, pour le scripting et la surveillance.

–limit N

Lister au plus N messages bloqués (failed/timeout) individuels et au plus *N* comptes de quota de boîte aux lettres. Par défaut 50. L’arriéré total rapporté n’est pas affecté par ce plafond.

La section des messages bloqués indique « affichage de X sur Y » lorsqu’elle est tronquée ; la section des quotas de boîtes aux lettres ne le fait pas, de sorte que sur un hôte comptant plus de N comptes comptabilisés cette liste est silencieusement celle des N mesures les plus anciennes — ce qui en est le bout utile, mais augmentez –limit avant de conclure qu’un compte est absent.

85.1.41.1.5. 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-status, 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 rapport lui-même reste strictement en lecture seule.

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.41.1.6. Options globales

Ces options peuvent apparaître avant ou après les autres options.

-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.41.1.7. Code de sortie

0

Achèvement réussi.

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.41.1.8. 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.41.1.9. Exemples

Imprimer le rapport de santé complet

pepsi-status -c /etc/pepsi/pepsi.conf

Collecter le rapport en JSON pour un système de surveillance via SSH

ssh mail.example.com pepsi-status --json

Afficher jusqu’à 200 messages bloqués

pepsi-status -c /etc/pepsi/pepsi.conf --limit 200

85.1.41.1.10. Voir aussi

pepsi-queue(1), pepsi-tlsrpt(1), pepsi-quota(1), pepsi-dispatch(1), pepsi.conf(5), pepsi-setup(1)

85.1.41.1.11. Bogues

Signalez les bogues au gestionnaire de tickets de Pepsi.