85.1.49. pepsi-tlsrpt

SMTP TLS Reporting (RFC 8460) daily reports

Section du manuel:

1

85.1.49.1.1. Nom

pepsi-tlsrpt - rapports agrégés quotidiens de SMTP TLS Reporting (RFC 8460).

85.1.49.1.2. Synopsis

pepsi-tlsrpt [GLOBAL-OPTIONS] report [–date YYYY-MM-DD] [–dry-run]

pepsi-tlsrpt [GLOBAL-OPTIONS] prune [–older-than DAYS]

85.1.49.1.3. Description

pepsi-tlsrpt est le côté émetteur du SMTP TLS Reporting (RFC 8460). À mesure que Pepsi remet le courrier sortant, les étapes de relais (pepsi-stage-relay-to-internet(1) et pepsi-stage-relay-to-smarthost(1)) notent l’issue de chaque session TLS — un succès, ou un échec classifié (starttls-not-supported, certificate-host-mismatch, certificate-expired, certificate-not-trusted, validation-failure, sts-policy-invalid) — comme un compteur agrégé dans la table pepsi.tls_session, indexée par jour UTC, domaine de politique, type de politique appliquée (tlsa/sts/no-policy-found), hôte MX et résultat. Une session est un succès lorsque TLS a été négocié, quoi qu’ait ensuite renvoyé l’échange SMTP qui l’emprunte (un rejet SMTP après la poignée de main n’est pas un échec TLS). Un message remis en clair n’est pas une session TLS : sans politique (un smarthost MODE = plain, ou un MX qui n’offre pas STARTTLS), il n’est pas noté, et là où MTA-STS ou DANE exigeait TLS, il est noté comme starttls-not-supported. Un échec qui ne se classe ni comme problème TLS ni comme problème de politique (une simple erreur de connexion) n’est pas noté du tout. Le domaine de politique est le domaine destinataire pour pepsi-stage-relay-to-internet(1) ; l’étape smarthost enregistre sous le nom d’hôte du smarthost lui-même, puisque c’est lui — et non le domaine du destinataire — qui est le pair dont le TLS a été observé. Ce relevé est activé par [pepsi-tlsrpt] SEND_REPORTS (désactivé par défaut) et est ignoré pour un message de rapport lui-même (la protection contre les boucles state.tlsrpt), de sorte qu’un rapport qui rencontre une erreur TLS ne génère jamais un rapport sur un rapport.

Exécuté une fois par jour depuis cron, pepsi-tlsrpt report compile les compteurs d’une journée en un rapport agrégé RFC 8460 par domaine de politique, consulte l’adresse de rapport annoncée par ce domaine (le champ rua de son enregistrement TXT _smtp._tls) et y expédie le rapport JSON compressé en gzip : par e-mail pour une cible mailto: (le rapport est injecté dans le pipeline à REPORT_STAGE pour être signé en DKIM et relayé comme tout autre message ; si REPORT_STAGE n’est pas réglé, la cible est consignée et ignorée), ou par POST HTTPS (avec Content-Type: application/tlsrpt+gzip) pour une cible https:. Un e-mail de rapport porte REPORT_FROM à la fois comme expéditeur d’enveloppe et comme From: — la RFC 8460 §5.3 exige qu’un rapport puisse être aligné en DKIM/DMARC : il n’est donc délibérément pas à expéditeur nul, et c’est l’indicateur state.tlsrpt, et non l’expéditeur nul, qui arrête la récursion. Une fois le rapport d’un domaine expédié, les compteurs de ce jour le concernant sont supprimés, de sorte que réexécuter la commande pour le même jour est sans risque.

Les deux formes de cible sont validées avant usage, car toutes deux proviennent d’un enregistrement DNS que publie le domaine sur lequel porte le rapport. Une cible mailto: doit être un unique addr-spec local@domain simple, de sorte qu’elle ne puisse injecter ni en-têtes ni destinataires supplémentaires dans le message de rapport. Une cible https: reçoit le POST par le même client durci que celui qu’emploie la découverte de clés : le nom d’hôte est résolu et chaque adresse candidate est examinée, de sorte qu’un rua pointant sur une adresse de boucle locale, privée, lien-local ou CGNAT est refusé plutôt que sollicité depuis l’intérieur du réseau du serveur de messagerie, et un POST ne suit aucune redirection, de sorte qu’une URL publique ne peut pas renvoyer le rapport ailleurs. Une cible qui échoue à l’une ou l’autre vérification est journalisée et ignorée ; les compteurs du jour sont conservés, de sorte que rien n’est perdu.

Il se connecte à la base de données partagée via la section [pepsi-postgres] et est configuré par [pepsi-tlsrpt] (voir pepsi.conf(5)). Ce n’est pas une étape. Étant une tâche cron, il est normalement démarré en tant que root, auquel cas il poursuit sous le compte de service pepsi ; voir Exécution en tant que root.

La moitié d’annonce — publier notre propre enregistrement TXT _smtp._tls afin que d’autres expéditeurs nous rapportent leurs résultats TLS vers nos domaines — est gérée par pepsi-setup(1), qui imprime l’enregistrement à partir de [pepsi-tlsrpt] RUA.

85.1.49.1.4. Commandes

report [–date YYYY-MM-DD] [–dry-run]

Compiler et expédier les rapports pour un jour UTC, par défaut hier.

–date YYYY-MM-DD

Faire le rapport pour ce jour UTC au lieu d’hier.

–dry-run

Imprimer le JSON de chaque rapport sur la sortie standard au lieu de l’envoyer, et conserver les compteurs (rien n’est supprimé). Utile pour l’inspection.

prune [–older-than DAYS]

Supprimer les compteurs pepsi.tls_session plus anciens que la fenêtre de rétention. Sans indicateur, la fenêtre est [pepsi-tlsrpt] RETAIN_DAYS (par défaut 7). Les jours rapportés sont déjà effacés par report ; ceci ne balaie que les jours qui n’ont jamais été rapportés (par exemple un domaine qui n’annonce aucun rua). Le pepsi-tlsrpt-prune.timer livré l’exécute quotidiennement, indépendamment de report — les compteurs s’accumulent que des rapports soient envoyés ou non, de sorte que la rétention ne doit pas dépendre de la mise en place de la tâche de rapport.

–older-than DAYS

Redéfinir la fenêtre de rétention pour cette exécution.

85.1.49.1.5. Configuration

La section [pepsi-tlsrpt] (voir pepsi.conf(5)) est lue comme un tout : elle n’est considérée comme configurée que lorsqu’elle annonce un RUA ou règle SEND_REPORTS, et report refuse de s’exécuter dans le cas contraire (prune, qui ne fait que supprimer des lignes, n’en a pas besoin).

RUA

Le ou les URI de rapport que nous annonçons dans notre propre enregistrement TXT _smtp._tls, verbatim (par exemple mailto:tls@example.org, ou une liste mailto:/https: séparée par des virgules). Seul pepsi-setup(1) le lit, pour imprimer l’enregistrement ; il ne joue aucun rôle dans l’envoi. Non réglé, cela signifie que nous n’annonçons rien.

SEND_REPORTS

Détermine si les étapes de relais notent les sessions TLS sortantes dans pepsi.tls_session. Par défaut no.

REPORT_FROM

Expéditeur d’enveloppe et From: des e-mails de rapport sortants ; son domaine est le déclarant du rapport (et fait partie de chaque report-id). Requis par report.

REPORT_STAGE

L’étape du pipeline à laquelle les e-mails de rapport sont injectés, afin qu’ils soient signés et relayés comme tout autre message. Sans elle, une cible mailto: ne peut pas être utilisée. pepsi-setup(1) vérifie qu’elle nomme une étape existante.

ORGANIZATION

organization-name dans les rapports émis. Par défaut, le domaine de REPORT_FROM.

CONTACT

contact-info (une adresse e-mail) dans les rapports émis. Omis du rapport lorsqu’il n’est pas réglé.

RETAIN_DAYS

Le nombre de jours de compteurs pepsi.tls_session que prune conserve (par défaut 7), sauf si --older-than le remplace pour une exécution donnée.

85.1.49.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 — ce qui compte ici, car la tâche quotidienne s’exécute normalement depuis la crontab de root. Plutôt que d’échouer à se connecter, l’outil détecte qu’il a été démarré en tant que root et devient le compte de service non privilégié pepsi — qui possède pepsi.tls_session et peut injecter les messages de rapport — avant de se connecter. Une entrée de crontab n’a donc pas besoin de sudo -u pepsi.

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

0

Terminé avec succès. Les problèmes de remise par domaine (un échec de résolution, un point de terminaison HTTPS injoignable) sont journalisés et l’exécution continue ; les compteurs du jour concerné sont conservés pour la prochaine exécution.

1

Une erreur s’est produite : une configuration malformée, une section [pepsi-tlsrpt] qui n’annonce pas de RUA et ne règle pas SEND_REPORTS (il n’y a rien à signaler), une option requise manquante (REPORT_FROM), un --date inanalysable, ou l’échec d’une connexion ou d’une requête à la base de données.

85.1.49.1.9. Exemples

Envoyer les rapports d’hier (invocation cron typique)

pepsi-tlsrpt -c /etc/pepsi/pepsi.conf report

Inspecter ce qui serait envoyé pour un jour spécifique sans envoyer

pepsi-tlsrpt -c /etc/pepsi/pepsi.conf report --date 2026-06-14 --dry-run

Élaguer les compteurs plus anciens que 30 jours

pepsi-tlsrpt -c /etc/pepsi/pepsi.conf prune --older-than 30

Une entrée crontab quotidienne (après minuit UTC, rapportant le jour qui vient de se terminer ; l’élagage est déjà planifié par pepsi-tlsrpt-prune.timer)

17 1 * * *  pepsi  pepsi-tlsrpt -c /etc/pepsi/pepsi.conf report

85.1.49.1.10. Voir aussi

pepsi-setup(1), pepsi.conf(5), pepsi-stage-relay-to-internet(1), pepsi-stage-relay-to-smarthost(1), pepsi-config(1)

85.1.49.1.11. Bogues

Signalez les bogues au gestionnaire de tickets de Pepsi.