prometheus-tlsrpt-exporter/README.md
s3lph c1588633cf
All checks were successful
/ test (push) Successful in 1m6s
/ codestyle (push) Successful in 1m5s
/ build_wheel (push) Successful in 1m7s
/ build_debian (push) Successful in 1m28s
feat: release v0.1.2
2023-12-18 01:16:22 +01:00

46 lines
2.1 KiB
Markdown

# prometheus-tlsrpt-exporter
Prometheus exporter for MTA-STS TLS report metrics.
## Description
When using [MTA-STS][mtasts] to enforce TLS transport encryption for e-mail traffic, regular automated reports can be requested from supporting servers. These JSON-formatted TLSRPT reports contain information regarding the success rate of TLS connections.
This piece of software exposes an HTTP endpoint where such reports can be submitted, and a Prometheus metrics endpoint where aggregated statistics are exposed.
## Endpoints
By default, this exporter binds to `localhost:9123`. It is intended to be used behind a TLS-terminating reverse proxy. There are the following endpoints:
- `/reports`: This is where the TLSRPT reports are submitted to. This endpoint must be world-accessable, and the POST-method must be permitted.
- `/metrics`: This is the Prometheus metrics endpoint. Access should be restricted to your prometheus server.
- `/ui`: At this endpoint a (very simple) user interface is presented where the recently received reports can be viewed. Access should be restricted to your mail administrators.
## Metrics
The following metrics are exposed, each labelled with the domain for which a report was received:
```metrics
# TYPE tlsrpt_successful counter
# HELP tlsrpt_successful Number of successful sessions
# TYPE tlsrpt_failed counter
# HELP tlsrpt_failed Number of failed sessions
# TYPE tlsrpt_count counter
# HELP tlsrpt_count Number of reports
```
## Setup
1. Install the `prometheus-tlsrpt-exporter`.
- I recommend installing the [Debian package][deb].
1. Set up a TLS-terminating reverse proxy that forwards e.g. `https://mail.example.org/report` to the `/report` endpoint.
1. Publish a DNS record `_smtp._tls.example.org. TXT "v=TLSRPTv1; rua=https://mail.example.org/report"`, where `example.org` is your mail domain.
- The same TLSRPT endpoint can be used for multiple mail domains.
[mtasts]: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol#SMTP_MTA_Strict_Transport_Security
[deb]: https://git.kabelsalat.ch/s3lph/-/packages/debian/prometheus-tlsrpt-exporter