..
  This file is part of PEPSI.
  Copyright (C) 2026 GNUnet e.V.

  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; a cleartext delivery counts only when MTA-STS or DANE required TLS,
as ``starttls-not-supported``) in the ``pepsi.tls_session`` aggregate-counter
table when
``[pepsi-tlsrpt] SEND_REPORTS`` is on (it is **off** by default). 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 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``).
  ``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.

Configuration
=============

``[pepsi-tlsrpt]``: ``SEND_REPORTS`` (default ``no`` — whether the relay stages
record sessions at all), ``RUA`` (the reporting address *we* advertise, which
:doc:`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 :manpage:`pepsi.conf(5)`.

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