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).
--dateselects another UTC day;--dry-runprints 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-thanoverrides), sweeping days that were never reported (e.g. a domain advertising norua).pepsi-tlsrpt-prune.timerruns 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).