TLSRPT-REPORTD(1)

📦
version 0.6.0 · 2 versions
, in arch rolling

🌈 NAME 🌈

Okay so bestie, welcome to the tlsrpt-reportd(1) page — the manual for tlsrpt-reportd, aka the daemon that creates and delivers TLSRPT reports according to RFC 8460. It’s giving infrastructure main character energy, and we’re gonna get through it together. 💖

✨ SYNOPSIS ✨

tlsrpt-reportd [OPTION]

That’s the whole synopsis. One binary, some options, and a whole lot of report-slinging. Periodt. 💅

🦋 DESCRIPTION 🦋

tlsrpt-reportd is the final component in the TLSRPT framework. The pipeline is literally a relay race: an MTA (Mail Transfer Agent) reports successful delivery or encountered errors via libtlsrpt to a tlsrpt-collectd, which collects and pre-aggregates the data. Then the tlsrpt-fetcher associated with a tlsrpt-collectd transfers that pre-aggregated data over to tlsrpt-reportd.

And tlsrpt-reportd? She can retrieve data from multiple tlsrpt-fetchers and aggregates the pre-aggregated data into the final reports. Those reports are gzip-compressed and sent out to the destinations as specified in the TLSRPT DNS records of the domains that have received emails from the MTA. No cap, that’s the flow. 🫶

A simple data flow diagram visualizing the interaction of the components looks like this:

(MTA) v libtlsrt v tlsrpt-collectd v (storage) v tlsrpt-fetcher v tlsrpt-reportd v (report destination)

💅 OPTIONS 💅

🌸 Report creation and configuration options 🌸

  • --contact_info=addr — Use addr as the contact info in the TLSRPT report according to RFC 8460.
  • --organization_name=descr — Use descr as the name of the organization sending the TLSRPT report according to RFC 8460.
  • --sender_address=email — Use email as the "From:" address when sending reports via email.
  • --fetchers=list — List of fetcher commands to retrieve data. Multiple fetcher commands can be given separated by commas.
  • --dbname=path — Use the SQLite data base at location path.
  • --compression_level=n — Use compression level n to gzip-compress the TLSRPT reports.
  • --keep_days=n — Keep old data for n days before deleting from the database.

🎀 Report delivery options 🎀

  • --spread_out_delivery=sec — Spread out the delivery of TLSRPT reports over sec seconds. The minimum value is 1 and causes all reports to be sent out immediately. This setting should be set to several hours according to RFC8460, section 4.1. For example, set spread_out_delivery to 14400 to spread out the delivery of the reports over four hours.
  • --sendmail_script=path — Use the script path to send a TLSRPT report via email.
  • --sendmail_timeout=sec — Set timeout of sec seconds for email requests to deliver reports.
  • --http_script=path — Use the script path to upload a TLSRPT report via HTTP(S).
  • --http_timeout=sec — Set timeout of sec seconds for HTTP POST requests to deliver reports.
  • --max_retries_delivery=n — Give up after n failed attempts to deliver a report to its destination.
  • --min_wait_delivery=sec — Minimum time to wait before retrying a failed report delivery attempt.
  • --max_wait_delivery=sec — Maximum time to wait before retrying a failed report delivery attempt.
  • --http_upload_map=path — Load a transformation map for HTTPS report destinations from file path. Cannot be used in combination with --debug_send_http_dest!
  • --mail_destination_map=path — Load a transformation map for SMTP report destinations from file path. Cannot be used in combination with --debug_send_mail_dest!
  • --tlsrpt_record_map=path — Load a transformation map for all report destinations based on the TLSRPT domain from file path. Cannot be used in combination with --debug_send_file_dest!

🧚 Options controlling the interaction with one or more tlsrpt-collectd 🧚

  • --max_collectd_timediff=sec — Log a warning if the collectd clock reported by its fetcher differs by more than sec seconds from the reportd’s clock. The reportd starts querying the fetchers sec seconds after the UTC day change, so a clock difference bigger than sec seconds indicates the collectd might not yet be ready to provide the complete data for the previous day.
  • --max_collectd_timeout=sec — Wait at most sec seconds for a fetcher to finish a request for data from its collectd.
  • --max_retries_domaindetails=n — Give up after n failed attempts to retrieve report details for a domain.
  • --min_wait_domaindetails=sec — Minimum time to wait before retry after a failed attempt to get the report details for a domain from a tlsrpt-collectd.
  • --max_wait_domaindetails=sec — Maximum time to wait before retry after a failed attempt to get the report details for a domain from a tlsrpt-collectd.
  • --max_retries_domainlist=n — Give up after n failed attempts to retrieve the list of domains from a tlsrpt-collectd.
  • --min_wait_domainlist=sec — Minimum time to wait before retry after a failed attempt to get the list of domains from a tlsrpt-collectd.
  • --max_wait_domainlist=sec — Maximum time to wait before retry after a failed attempt to get the list of domains from a tlsrpt-collectd.
  • --interval_main_loop=sec — Wake up an idle main loop even if there are no tasks after sec seconds of inactivity.

🐛 Debug and development options 🐛

  • --debug_db=n — Control database debugging: 0 turns database debugging off, 1 activates logging of database statements.
  • --debug_send_file_dest=dir — Save reports into directory dir in addition to their delivery via email or HTTP POST requests. Cannot be used in combination with --tlsrpt_record_map!
  • --debug_send_mail_dest=path — Override the email destination to send out reports via email.
⚠️ Please note: with this option set, reports to email destinations will not be sent to the requested destination from the TLSRPT DNS record but to this replacement address instead! This option must not be used on production systems! Cannot be used in combination with --mail_destination_map!
  • --debug_send_http_dest=path — Override the HTTP POST destination to send out reports via HTTP POST requests.
⚠️ Please note: with this option set, reports to HTTP POST destinations will not be sent to the requested destination from the TLSRPT DNS record but to this replacement URL instead! This option must not be used on production systems! Cannot be used in combination with --http_upload_map!

🌟 General options 🌟

  • --config_file=filename — Read options from the section tlsrpt_reportd of the INI-style configuration file filename. Environment variables override settings from the configuration file and command line options override both.
  • --help — Print a help message describing all options.
  • --pidfilename=path — Specifies the file that contains the process ID of the tlsrpt-reportd daemon. An empty string will cause no PID file to be created.

🍓 Logging options 🍓

  • --logfilename=filename — Use filename as log file.
  • --log_level=level — Set log level to level, allowed values: debug, info, warn, error.

🌈 ENVIRONMENT 🌈

All config options except --help and --config_file can also be set via environment variables. The environment variable for a configuration option is the prefix TLSRPT_REPORTD_ followed by the configuration setting name in all caps. For example the --log_level option can instead be configured using the TLSRPT_REPORTD_LOG_LEVEL environment variable. Cute, consistent, very “set it and forget it” of her. 💜

🔥 DESTINATION MAPPING 🔥

The --tlsrpt_record_map, --http_upload_map and --mail_destination_map options allow a mapping of the report destinations retrieved from the TLSRPT record based on the domain the report is created for. It’s giving “we see the destination, and we have opinions.” 👑

All maps are processed on a "first match wins" manner. No further rules are processed after a rule has matched. So order matters, bestie — first rule to match takes the crown. 👑

The --tlsrpt_record_map is used first to transform the whole set of destinations. The --http_upload_map and --mail_destination_map options allow for further modifications to report destinations matching the mailto: or https: URI scheme and they inspect the report destination to determine if the rule applies, not the domain for which the report is created.

Each map line has the format: match action [parameters]

match is of the form matchtype:pattern. Supported match types are: domain: and regexp:.

The domain: prefix can be omitted, i.e. without a match type specified the domain: match style is the default. A domain: match matches the domain part of a mailto: URI in the --mail_destination_map and the domain part of an https: URI in the --http_upload_map. A domain: match can match a complete domain name or if it starts with a . it matches all subdomains. A single . matches every domain name. A trailing . after a domain name is ignored.

The domain name many.sub.domains.example.com would not be matched by sub.domains.example.com or sub.domains.example.com. without a leading dot, but it would be matched by these domain match expressions:

  • many.sub.domains.example.com.
  • many.sub.domains.example.com
  • .sub.domains.example.com.
  • .sub.domains.example.com
  • .domains.example.com.
  • .domains.example.com
  • .example.com.
  • .example.com
  • .com.
  • .com
  • .

A regexp: style match in the --tlsrpt_record_map matches against the domain name the report is created for. A regexp: style match in the --http_upload_map and --mail_destination_map maps matches against the whole report destination, not just the extracted domain part.

The action can be one of ACCEPT, DISCARD, APPEND, REPLACE and REGEXP. ACCEPT actions just accept the report destinations as they are. DISCARD actions return an empty set of report destinations, no report will be sent out. APPEND actions supply additional report destinations. REPLACE actions replace the report destinations with other destinations. REGEXP actions transform each matching report destination according to their two parameters: a matching regexp and a substitution.

APPEND and REPLACE and REGEXP actions can introduce other URI schemes. tlsrpt-reportd understands in addition to the mailto: and https: URI schemes defined in RFC 8460 the additional URI scheme directory: as a directory in the filesystem where reports are to be saved as files to allow inspection and debugging.

Rules in the --mail_destination_map can also introduce https: and directory: URIs as report destinations. Rules in the --http_upload_map can also introduce https: and directory: URIs as report destinations. No further processing is done with those destinations, i.e. a https: URI introduced in the --mail_destination_map is not put through the transformations from --http_upload_map and vice versa.

The results from --tlsrpt_record_map which is processed first, however, are put through the transformations of --http_upload_map and --mail_destination_map even if --tlsrpt_record_map already had actions modify the report destinations.

✨ EXAMPLES ✨

Okay bestie, this is the part where it gets real — actual commands you can type. Let's go 💅

Say you wanna pull data from a local fetcher running the standard config, and from another local fetcher that's using a whole different storage backend. You literally just do this:

tlsrpt-reportd --fetchers "tlsrpt-fetcher, tlsrpt-fetcher --storage sqlite:///tmp/test.sqlite"

See how the second one gets its own extra args tucked inside the quotes? Yeah — each fetcher spec gets parsed on its own, so you can totally mix and match. Iconic. 🎀

And if you're feeling a little more adventurous — like, remote-server energy 🌈 — you can hit a local fetcher and a remote one over ssh in the same run:

tlsrpt-reportd --fetchers "tlsrpt-fetcher, ssh user@remote tlsrpt-fetcher"

Two fetchers, one reportd, zero drama. No cap, that's the whole vibe. 🔥

💀 EXIT STATUS 💀

  • 0 — Success. Everything worked, you ate, periodt. 💖
  • 1 — Failure. Something went sideways, bestie. 😭

🦋 SEE ALSO 🦋

Go give these queens some love too:

  • tlsrpt-collectd[1]
  • tlsrpt-fetcher[1]

👑 AUTHOR 👑

This whole thing was written by Boris Lohner. Respect the main character. 🫶

And that's the page, bestie! 🧚 This lil' icon of a manual is tlsrpt-reportd, dated 2026-09-01 (that's the TLSRPT-REPORTD(1) you'd see stamped in the footer). Go forth, fetch your reports, and slay. 💜🌸

📦 where this page comes from