feat: release v0.1.2

CHANGELOG.md

@@ -1,5 +1,19 @@
 # prometheus-tlsrpt-exporter Changelog
 
+<!-- BEGIN RELEASE v0.1.2 -->
+## Version 0.1.2
+
+Minor bugfix and documentation release.
+
+### Changes
+
+<!-- BEGIN CHANGES 0.1.2 -->
+- Fix typo in the Debian package's command line regarding the templates path.
+- Add README describing what this project actually does.
+<!-- END CHANGES 0.1.2 -->
+
+<!-- END RELEASE v0.1.2 -->
+
 <!-- BEGIN RELEASE v0.1.1 -->
 ## Version 0.1.1
 

README.md

@@ -0,0 +1,46 @@
+# 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

tlsrpt_exporter/__init__.py

@@ -1,2 +1,2 @@
 
-__version__ = '0.1.1'
+__version__ = '0.1.2'