47 lines
2.1 KiB
Markdown
47 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
|