..
  This file is part of PEPSI.
  Copyright (C) 2026 Pepsi contributors

  PEPSI is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free
  Software Foundation; either version 3, or (at your option) any later version.

============
pepsi-tlsrpt
============

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

Role
====

``pepsi-tlsrpt`` is the sender side of SMTP TLS Reporting (RFC 8460). The relay
stages record every outbound TLS session outcome (success or a classified
failure) in the ``pepsi.tls_session`` aggregate-counter table when
``[pepsi-tlsrpt] SEND_REPORTS`` is on. Run once a day from cron, this tool
compiles a day's counters into one aggregate report per recipient domain, looks
up that domain's ``_smtp._tls`` ``rua`` reporting address and ships the
gzip-compressed JSON report there — by e-mail (``mailto:``, injected into the
pipeline at ``REPORT_STAGE`` so it is signed and relayed) or 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: :manpage:`pepsi-tlsrpt(1)`.

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

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``).

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.

See also
========

:doc:`pepsi-setup`, :doc:`pepsi-stage-relay-to-internet`,
:doc:`pepsi-stage-relay-to-smarthost`, :doc:`../architecture`,
:manpage:`pepsi-tlsrpt(1)`, :manpage:`pepsi.conf(5)`.