85.1.49. pepsi-tlsrpt

SMTP TLS Reporting (RFC 8460) daily reports

Handbuchabschnitt:

1

85.1.49.1.1. Name

pepsi-tlsrpt - tägliche Sammelberichte für SMTP TLS Reporting (RFC 8460).

85.1.49.1.2. Übersicht

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

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

85.1.49.1.3. Beschreibung

pepsi-tlsrpt ist die Absenderseite von SMTP TLS Reporting (RFC 8460). Während Pepsi ausgehende Mail zustellt, halten die Relay-Stages (pepsi-stage-relay-to-internet(1) und pepsi-stage-relay-to-smarthost(1)) das Ergebnis jeder TLS-Sitzung — einen Erfolg oder einen klassifizierten Fehler (starttls-not-supported, certificate-host-mismatch, certificate-expired, certificate-not-trusted, validation-failure, sts-policy-invalid) — als Aggregat-Zähler in der Tabelle pepsi.tls_session fest, geschlüsselt nach UTC-Tag, Richtliniendomain, angewandtem Richtlinientyp (tlsa/sts/no-policy-found), MX-Host und Ergebnis. Eine Sitzung ist ein Erfolg, wenn TLS ausgehandelt wurde, gleich was der SMTP-Austausch darüber dann ergab (eine SMTP-Ablehnung nach dem Handshake ist kein TLS-Fehler). Eine im Klartext zugestellte Nachricht ist keine TLS-Sitzung: Ohne Richtlinie (ein Smarthost mit MODE = plain oder ein MX, der kein STARTTLS anbietet) wird sie nicht festgehalten, und wo MTA-STS oder DANE TLS verlangten, wird sie als starttls-not-supported festgehalten. Ein Fehler, der sich nicht als TLS- oder Richtlinienproblem klassifizieren lässt (ein einfacher Verbindungsfehler), wird überhaupt nicht festgehalten. Die Richtliniendomain ist bei pepsi-stage-relay-to-internet(1) die Empfängerdomain; die Smarthost-Stage hält unter dem eigenen Hostnamen des Smarthosts fest, denn dieser — und nicht die Domain des Empfängers — ist die Gegenstelle, deren TLS beobachtet wurde. Dieses Festhalten wird durch [pepsi-tlsrpt] SEND_REPORTS eingeschaltet (standardmäßig aus) und für eine Berichtsnachricht selbst übersprungen (der Schleifenschutz state.tlsrpt), sodass ein Bericht, der auf einen TLS-Fehler stößt, nie einen Bericht über einen Bericht erzeugt.

Einmal täglich per Cron ausgeführt, stellt pepsi-tlsrpt report die Zähler eines Tages zu einem RFC-8460-Sammelbericht pro Richtliniendomain zusammen, schlägt die angekündigte Berichtsadresse dieser Domain nach (das rua-Feld ihres _smtp._tls-TXT-Eintrags) und verschickt den gzip-komprimierten JSON-Bericht dorthin: per E-Mail für ein mailto:-Ziel (der Bericht wird bei REPORT_STAGE in die Pipeline injiziert, sodass er DKIM-signiert und wie jede andere Nachricht weitergeleitet wird; ist REPORT_STAGE nicht gesetzt, wird das Ziel protokolliert und übersprungen) oder per HTTPS-POST (mit Content-Type: application/tlsrpt+gzip) für ein https:-Ziel. Eine Bericht-E-Mail trägt REPORT_FROM sowohl als Umschlagabsender als auch als From: — RFC 8460 §5.3 verlangt, dass ein Bericht per DKIM/DMARC ausrichtbar ist, er hat daher bewusst keinen Null-Absender, und es ist das Flag state.tlsrpt statt des Null-Absenders, das die Rekursion stoppt. Sobald der Bericht einer Domain verschickt ist, werden die Zähler dieses Tages für sie gelöscht, sodass ein erneuter Lauf für denselben Tag sicher ist.

Beide Zielformen werden vor der Verwendung validiert, denn beide stammen aus einem DNS-Eintrag, den die Domain veröffentlicht, über die berichtet wird. Ein mailto:-Ziel muss eine einzelne schlichte Addr-Spec local@domain sein, sodass es weder Header noch zusätzliche Empfänger in die Berichtsnachricht einschleusen kann. An ein https:-Ziel wird über denselben gehärteten Client gesendet, den die Schlüsselentdeckung verwendet: Der Hostname wird aufgelöst und jede Kandidatenadresse geprüft, sodass ein rua, das auf eine Loopback-, private, Link-Local- oder CGNAT-Adresse zeigt, abgelehnt wird, statt aus dem Netz des Mailservers heraus angesprochen zu werden, und ein POST folgt keiner Umleitung, sodass eine öffentliche URL den Bericht nicht anderswohin lenken kann. Ein Ziel, das eine der beiden Prüfungen nicht besteht, wird protokolliert und übersprungen; die Zähler des Tages bleiben erhalten, sodass nichts verloren geht.

Es verbindet sich über den Abschnitt [pepsi-postgres] mit der gemeinsamen Datenbank und wird durch [pepsi-tlsrpt] konfiguriert (siehe pepsi.conf(5)). Es ist keine Stage. Als Cron-Job wird es normalerweise als root gestartet und läuft dann als Dienstkonto pepsi weiter; siehe Ausführung als root.

Die ankündigende Hälfte — unseren eigenen _smtp._tls-TXT-Eintrag veröffentlichen, sodass andere Absender ihre TLS-Ergebnisse zu unseren Domains an uns melden — wird von pepsi-setup(1) erledigt, das den Eintrag aus [pepsi-tlsrpt] RUA ausgibt.

85.1.49.1.4. Befehle

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

Stellt die Berichte für einen UTC-Tag zusammen und verschickt sie, standardmäßig für gestern.

–date YYYY-MM-DD

Berichtet über diesen UTC-Tag statt über gestern.

–dry-run

Gibt das JSON jedes Berichts auf die Standardausgabe aus, statt ihn zu senden, und behält die Zähler (nichts wird gelöscht). Nützlich zur Inspektion.

prune [–older-than DAYS]

Löscht pepsi.tls_session-Zähler, die älter als das Aufbewahrungsfenster sind. Ohne Flag ist das Fenster [pepsi-tlsrpt] RETAIN_DAYS (Standardwert 7). Berichtete Tage werden bereits von report geleert; dies räumt nur Tage ab, über die nie berichtet wurde (z. B. eine Domain, die kein rua ankündigt). Der mitgelieferte pepsi-tlsrpt-prune.timer führt es täglich aus, unabhängig von report — Zähler sammeln sich an, ob jemals Berichte gesendet werden oder nicht, daher darf die Aufbewahrung nicht davon abhängen, dass der Berichtsjob eingerichtet ist.

–older-than DAYS

Überschreibt das Aufbewahrungsfenster für diesen Lauf.

85.1.49.1.5. Konfiguration

Der Abschnitt [pepsi-tlsrpt] (siehe pepsi.conf(5)) wird als Ganzes gelesen: Er gilt nur dann als konfiguriert, wenn er entweder ein RUA ankündigt oder SEND_REPORTS setzt, und report verweigert andernfalls die Ausführung (prune, das nur Datensätze löscht, benötigt ihn nicht).

RUA

Die Berichts-URI(s), die wir in unserem eigenen _smtp._tls-TXT-Eintrag ankündigen, wörtlich (z. B. mailto:tls@example.org oder eine kommagetrennte mailto:-/https:-Liste). Nur pepsi-setup(1) liest sie, um den Eintrag auszugeben; beim Senden spielen sie keine Rolle. Nicht gesetzt bedeutet, dass wir nichts ankündigen.

SEND_REPORTS

Ob die Relay-Stages ausgehende TLS-Sitzungen überhaupt in pepsi.tls_session festhalten. Standardwert no.

REPORT_FROM

Umschlagabsender und From: ausgehender Bericht-E-Mails; seine Domain ist der Einreicher des Berichts (und Teil jeder report-id). Von report benötigt.

REPORT_STAGE

Die Pipeline-Stage, bei der Bericht-E-Mails injiziert werden, sodass sie wie jede andere Nachricht signiert und weitergeleitet werden. Ohne sie kann ein mailto:-Ziel nicht verwendet werden. pepsi-setup(1) prüft, dass sie eine vorhandene Stage benennt.

ORGANIZATION

organization-name in ausgegebenen Berichten. Standardwert ist die Domain von REPORT_FROM.

CONTACT

contact-info (eine E-Mail-Adresse) in ausgegebenen Berichten. Nicht gesetzt, wird es im Bericht weggelassen.

RETAIN_DAYS

Wie viele Tage an pepsi.tls_session-Zählern prune behält (Standardwert 7), sofern --older-than es nicht für einen Lauf überschreibt.

85.1.49.1.6. Ausführung als root

Pepsi gibt jeder Komponente ihre eigene PostgreSQL-Rolle, die über den lokalen Socket durch das Betriebssystemkonto authentifiziert wird, unter dem sie läuft, und root gehört bewusst nicht dazu — was hier ins Gewicht fällt, weil der tägliche Auftrag normalerweise aus der Crontab von root läuft. Statt den Verbindungsaufbau scheitern zu lassen, erkennt das Werkzeug, dass es als root gestartet wurde, und wird zum unprivilegierten Dienstkonto pepsi — dem pepsi.tls_session gehört und das die Berichtsnachrichten injizieren darf —, bevor es sich verbindet. Ein Crontab-Eintrag braucht daher kein sudo -u pepsi.

Die Konfigurationsdatei (und jedes von ihr referenzierte @inline-secret@-Fragment) wird vor dem Wechsel gelesen, sodass eine nur für root lesbare Konfiguration weiterhin normal geladen wird.

Existiert das Konto pepsi nicht — ein nicht installierter Quellbaum, ein Testaufbau —, bleibt die Identität unangetastet, es wird eine Warnung protokolliert und die Verbindung als aufrufender Benutzer versucht, sodass eine Installation, in der root die Datenbank erreichen kann, weiterhin funktioniert.

85.1.49.1.7. Globale Optionen

Diese globalen Optionen stehen vor dem Unterbefehl (ein nachgestelltes Flag wird abgelehnt).

-c FILE, –config FILE

Liest die Konfiguration aus FILE, statt die Standardorte zu durchsuchen.

-L LOGLEVEL, –log LOGLEVEL

Setzt die Log-Ausführlichkeit. LOGLEVEL ist eines von error, warn, info, debug oder trace (Standardwert: info).

-v, –verbose

Zeigt Log-Meldungen aus allen Quellen, einschließlich Drittanbieter-Bibliotheken.

-h, –help

Gibt eine Verwendungsübersicht aus und beendet sich.

-V, –version

Gibt die Version aus und beendet sich.

85.1.49.1.8. Exit-Status

0

Erfolgreicher Abschluss. Zustellprobleme je Domain (ein Abfragefehler, ein unerreichbarer HTTPS-Endpunkt) werden protokolliert und der Lauf fährt fort; die Zähler des betroffenen Tages werden für den nächsten Lauf aufbewahrt.

1

Ein Fehler ist aufgetreten: eine fehlerhafte Konfiguration, ein [pepsi-tlsrpt]-Abschnitt, der weder ein RUA ankündigt noch SEND_REPORTS setzt (es gibt nichts zu berichten), eine fehlende erforderliche Option (REPORT_FROM), ein nicht parsebares --date oder eine fehlgeschlagene Datenbankverbindung oder -abfrage.

85.1.49.1.9. Beispiele

Die Berichte von gestern senden (typischer Cron-Aufruf):

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

Inspizieren, was für einen bestimmten Tag gesendet würde, ohne zu senden:

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

Zähler entfernen, die älter als 30 Tage sind:

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

Ein täglicher Crontab-Eintrag (nach Mitternacht UTC, der über den gerade beendeten Tag berichtet; das Aufräumen ist bereits durch pepsi-tlsrpt-prune.timer eingeplant):

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

85.1.49.1.10. Siehe auch

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

Melden Sie Fehler an den Pepsi-Issue-Tracker.