86. pepsi-tlsrpt

Compile and send the daily SMTP TLS Reporting (RFC 8460) reports.

86.1. Role

pepsi-tlsrpt is the sender side of SMTP TLS Reporting (RFC 8460). When [pepsi-tlsrpt] SEND_REPORTS is on (it is off by default), the relay stages record the outcome of every outbound TLS session, a success or a classified failure, in the table of aggregate counters pepsi.tls_session. A cleartext delivery counts only when MTA-STS or DANE required TLS, as starttls-not-supported. A session that DANE = warn let through although the certificate matched no TLSA record counts as tlsa-invalid. An advertised MTA-STS policy that could not be fetched at first contact counts as sts-policy-fetch-error or sts-webpki-invalid and is reported without an MX host.

Run once a day from cron, this tool compiles a day’s counters into one aggregate report per policy domain, looks up that domain’s _smtp._tls rua reporting address and sends the gzip-compressed JSON report there, to at most the first five targets that the record lists. It sends the report by e-mail (mailto:, injected into the pipeline at REPORT_STAGE so that it is signed and relayed) or by HTTPS POST (https:). It connects through [pepsi-postgres] and is configured by [pepsi-tlsrpt]. It is not a stage. Being a cron job it normally starts as root, in which case it continues as the pepsi service account before connecting, so the crontab entry needs no sudo -u pepsi. Reference: pepsi-tlsrpt(1).

The advertising half (publishing our own _smtp._tls record from [pepsi-tlsrpt] RUA) is handled by pepsi-setup.

86.2. Features

  • report — compile and ship the day’s reports (default: yesterday, UTC). --date selects another UTC day; --dry-run prints each report’s JSON and retains the counters. A reported domain’s counters for that day are deleted, so re-runs are idempotent.

  • prune — delete counters older than the retention window ([pepsi-tlsrpt] RETAIN_DAYS, default 7; --older-than overrides), sweeping days that were never reported (e.g. a domain advertising no rua). pepsi-tlsrpt-prune.timer runs it daily, whether or not reports are sent.

A report message carries state.tlsrpt = true; the relay session recorder skips such messages, so a report that itself hits a TLS error never spawns a report about a report. It is sent from REPORT_FROM, not the null sender, because RFC 8460 §5.3 asks that a report be alignable under DKIM and DMARC.

86.3. Security

Both rua forms come out of a DNS record that the reported-on domain publishes, so both are treated as hostile input. A mailto: target must be a single plain local@domain addr-spec (no header or recipient injection into the report message). An https: target is posted to through the key-discovery HTTPS client with the system CA roots: every address the host name resolves to must be public (no loopback, RFC 1918, CGNAT or link-local target inside the mail server’s network), redirects are not followed, the response is capped at 64 KiB and the request at 30 s — see “Key-discovery SSRF” in Security model and A remote sender. Only the first five targets of a domain are used, so a record naming hundreds of third-party addresses cannot turn every reporting server into a mailer for it. Counter retention is in the availability table (Availability).

86.4. Configuration

[pepsi-tlsrpt]: SEND_REPORTS (default no — whether the relay stages record sessions at all), RUA (the reporting address we advertise, which pepsi-setup turns into the _smtp._tls TXT record), REPORT_FROM (required to send) and REPORT_STAGE (where a mailto: report is injected), the optional ORGANIZATION and CONTACT shown in the report, and RETAIN_DAYS (default 7). See pepsi.conf(5).

86.5. See also

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