README.md
1postfix-mta-sts-resolver
2========================
3
4[](https://travis-ci.org/Snawoot/postfix-mta-sts-resolver) [](https://travis-ci.org/Snawoot/postfix-mta-sts-resolver) [](https://pypistats.org/packages/postfix-mta-sts-resolver) [](https://pypi.org/project/postfix-mta-sts-resolver/) [](https://pypi.org/project/postfix-mta-sts-resolver/) [](https://pypi.org/project/postfix-mta-sts-resolver/) [](https://snapcraft.io/postfix-mta-sts-resolver) 
5
6Daemon which provides TLS client policy for Postfix via socketmap, according to domain MTA-STS policy. Current support of RFC8461 is limited - daemon lacks some minor features:
7
8* Fetch error reporting
9* Fetch ratelimit (but actual fetch rate partially restricted with `cache_grace` config option).
10
11Server has configurable cache backend which allows to store cached STS policies in memory (`internal`), file (`sqlite`) or in Redis database (`redis`).
12
13---
14
15:heart: :heart: :heart:
16
17You can say thanks to the author by donations to these wallets:
18
19- ETH: `0xB71250010e8beC90C5f9ddF408251eBA9dD7320e`
20- BTC:
21 - Legacy: `1N89PRvG1CSsUk9sxKwBwudN6TjTPQ1N8a`
22 - Segwit: `bc1qc0hcyxc000qf0ketv4r44ld7dlgmmu73rtlntw`
23
24---
25
26## Requirements
27
28* Postfix 3.4+ (or Postfix 2.10+ if missing Postfix SNI feature is tolerable. In that case you have to set zone option `require_sni` to `false` in MTA-STS daemon config)
29* Python 3.5.3+ (see ["Systems without Python 3.5+"](#systems-without-python-35) below if you haven't one, or use Docker installation method)
30* aiodns
31* aiohttp
32* aiosqlite
33* aioredis
34* PyYAML
35* (optional) uvloop
36
37All dependency packages installed automatically if this package is installed via pip.
38
39
40## Installation
41
42### Method 1. System-wide install from PyPI (recommended for humans)
43
44Run:
45
46```bash
47sudo python3 -m pip install postfix-mta-sts-resolver[redis,sqlite]
48```
49
50If you don't need `redis` or `sqlite` support, you may omit one of them in square brackets. If you don't need any of them and you plan to use internal cache without persistence, you should also omit square brackets.
51
52Package scripts shall be available in standard executable locations upon completion.
53
54#### pip user install
55
56All pip invocations can be run with `--user` option of `pip` installer. In this case superuser privileges are not required and package(s) are getting installed into user home directory. Usually, script executables will appear in `~/.local/bin`.
57
58### Method 2. System-wide install from project source
59
60Run in project directory:
61
62```bash
63sudo python3 -m pip install .[redis,sqlite]
64```
65
66If you don't need `redis` or `sqlite` support, you may omit one of them in square brackets. If you don't need any of them and you plan to use internal cache without persistence, you should also omit square brackets.
67
68Package scripts shall be available in standard executable locations upon completion.
69
70
71### Method 3. Install into virtualenv
72
73See ["Building virtualenv"](#building-virtualenv)
74
75### Method 4. Docker
76
77Run
78
79```bash
80docker volume create mta-sts-cache
81docker run -d \
82 --security-opt no-new-privileges \
83 -v mta-sts-cache:/var/lib/mta-sts \
84 -p 127.0.0.1:8461:8461 \
85 --restart unless-stopped \
86 --name postfix-mta-sts-resolver \
87 yarmak/postfix-mta-sts-resolver
88```
89
90Daemon will be up and running, listening on local interface on port 8461. Default configuration baked into docker image uses SQLite for cache stored in persistent docker volume. You may override this configuration with your own config file by mapping it into container with option `-v my_config.yml:/etc/mta-sta-daemon.yml`.
91
92### Method 5. Snap Store
93
94[](https://snapcraft.io/postfix-mta-sts-resolver)
95
96```bash
97sudo snap install postfix-mta-sts-resolver
98```
99
100NOTE: in snap layout `mta-sta-daemon` program is named `postfix-mta-sts-resolver.daemon` and `mta-sts-query` is named `postfix-mta-sts-resolver.query`.
101
102### Common installation notes
103
104See also [contrib/README.md](https://github.com/Snawoot/postfix-mta-sts-resolver/tree/master/contrib/README.md) for RHEL/OEL/Centos and FreeBSD notes.
105
106See [contrib/](https://github.com/Snawoot/postfix-mta-sts-resolver/tree/master/contrib) for example of systemd unit file suitable to run daemon under systemd control.
107
108## Running
109
110This package provides two executables available after installation in respective locations.
111
112
113### mta-sts-query
114
115`mta-sts-query` is a command line tool which fetches and outputs domain MTA-STS policies. Intended to be used for debug purposes.
116
117Synopsis:
118
119```
120$ mta-sts-query --help
121usage: mta-sts-query [-h] [-v {debug,info,warn,error,fatal}]
122 domain [known_version]
123
124positional arguments:
125 domain domain to fetch MTA-STS policy from
126 known_version latest known version (default: None)
127
128optional arguments:
129 -h, --help show this help message and exit
130 -v {debug,info,warn,error,fatal}, --verbosity {debug,info,warn,error,fatal}
131 logging verbosity (default: warn)
132```
133
134### mta-sts-daemon
135
136`mta-sts-daemon` is a daemon which provides external [TLS policy for Postfix SMTP client](http://www.postfix.org/TLS_README.html#client_tls_policy) via [socketmap interface](http://www.postfix.org/socketmap_table.5.html).
137
138You may find useful systemd unit file to run daemon in [contrib/](https://github.com/Snawoot/postfix-mta-sts-resolver/tree/master/contrib).
139
140Synopsis:
141
142```
143$ mta-sts-daemon --help
144usage: mta-sts-daemon [-h] [-v {debug,info,warn,error,fatal}] [-c FILE]
145 [-l FILE] [--disable-uvloop]
146
147optional arguments:
148 -h, --help show this help message and exit
149 -v {debug,info,warn,error,fatal}, --verbosity {debug,info,warn,error,fatal}
150 logging verbosity (default: info)
151 -c FILE, --config FILE
152 config file location (default: /etc/mta-sts-
153 daemon.yml)
154 -l FILE, --logfile FILE
155 log file location (default: None)
156 --disable-uvloop do not use uvloop even if it is available (default:
157 False)
158```
159
160#### Seamless restart/upgrade/reload and load balancing
161
162By default mta-sts-daemon allows its multiple instances to share same port (on Linux/FreeBSD/Windows). Therefore, restart or upgrade of daemon can be performed seamlessly. Set of unit files for systemd in [contrib/](contrib/) directory implements "reload" by mean of running backup instance when main instance is getting restarted.
163
164Also on Linux and FreeBSD, load distribited across all processes (with SO\_REUSEPORT and SO\_REUSEPORT\_LB respectively).
165
166
167## MTA-STS Daemon configuration
168
169See [configuration man page](https://github.com/Snawoot/postfix-mta-sts-resolver/blob/master/man/mta-sts-daemon.yml.5.adoc) and [config\_examples/](https://github.com/Snawoot/postfix-mta-sts-resolver/tree/master/config_examples) directory. Default config location is: `/etc/mta-sts-daemon.yml`, but it can be overriden with command line option `-c FILE`.
170
171All options is self-explanatory, only exception is `strict_testing` option. If set to `true`, STS policy will be enforced even if domain announces `testing` MTA-STS mode. Useful for premature incorporation of MTA-STS against domains hesistating to go `enforce`. Please use with caution.
172
173
174## Postfix configuration
175
176SMTP client of your Postfix instance must be able to validate peer certificates. In order to achieve that, you have to ensure [`smtp_tls_CAfile`](http://www.postfix.org/postconf.5.html#smtp_tls_CAfile) or [`smtp_tls_CApath`](http://www.postfix.org/postconf.5.html#smtp_tls_CApath) points to system CA bundle. Otherwise you'll get `Unverified TLS connection` even for peers with valid certificate, and delivery failures for MTA-STS-enabled destinations. Also note: even enabled [`tls_append_default_CA`](http://www.postfix.org/postconf.5.html#tls_append_default_CA) will not work alone if both `smtp_tls_CAfile` and `smtp_tls_CApath` are empty.
177
178Once certificate validation is enabled and your Postfix log shows "Trusted TLS connection ... " for destinations with valid certificates signed by public CA, you may enable MTA-STS by adding following line to `main.cf`:
179
180```
181smtp_tls_policy_maps = socketmap:inet:127.0.0.1:8461:postfix
182```
183
184If your configuration already has some TLS policy maps, just add MTA-STS socketmap to list of configured maps accordingly to [`smtp_tls_policy_maps`](http://www.postfix.org/postconf.5.html#smtp_tls_policy_maps) syntax. TLS policy tables are searched in the specified order until a match is found, so you may have table with local overrides of TLS policy prior to MTA-STS socketmap. This may be useful for skipping network lookup for well-known destinations or relaxing security for broken destinations, announcing MTA-STS support.
185
186Reload Postfix after reconfiguration.
187
188
189## Operability check
190
191Assuming default MTA-STA daemon configuration. Following command:
192
193```bash
194/usr/sbin/postmap -q dismail.de socketmap:inet:127.0.0.1:8461:postfix
195```
196
197should return something like:
198
199```
200secure match=mx1.dismail.de
201```
202
203Postfix log should show `Verified TLS connection established to ...` instead of `Untrusted ...` or `Trusted TLS connection established to ...` when mail is getting sent to MTA-STS-enabled domain.
204
205
206## Special cases of deployment
207
208
209### Systems without Python 3.5+
210
211Some people may find convenient to install latest python from source into `/opt` directory. This way you can have separate python installation not interferring with system packages by any means. Download latest python source from [python.org](https://www.python.org/), unpack and run in unpacked source directory:
212
213```bash
214./configure --prefix=/opt --enable-optimizations && make -j $[ $(nproc) + 1 ] && make test && sudo make install
215```
216
217Python binaries will be available in `/opt/bin`, including `pip3`. You may install `postfix-mta-sts-resolver` using `/opt/bin/pip3` without interference with any system packages:
218
219```bash
220sudo /opt/bin/pip3 install postfix-mta-sts-resolver[sqlite,redis]
221```
222
223Executable files of `postfix-mta-sts-resolver` will be available in `/opt/bin/mta-sts-query` and `/opt/bin/mta-sts-daemon`
224
225
226### Building virtualenv
227
228Run `make` in project directory in order to build virtualenv. As result of it, new directory `venv` shall appear. `venv` contains interpreter and all required dependencies, i.e. encloses package with depencencies in separate environment. It is possible to specify alternative path where virtualenv directory shall be placed. Specify VENV variable for `make` command. Example:
229
230```bash
231make VENV=~/postfix-mta-sts-resolver
232```
233
234Such virtual environment can be moved to another machine of similar type (as far python interpreter is compatible with new environment). If virtualenv is placed into same location on new machine, application can be runned this way:
235
236```bash
237venv/bin/mta-sts-daemon
238```
239
240Otherwise, some hacks required. First option - explicitly call virtualenv interpreter:
241
242```bash
243venv/bin/python venv/bin/mta-sts-daemon
244```
245
246Second option - specify new path in shebang of scripts installed in virtualenv. It is recommended to build virtualenv at same location which app shall occupy on target system.
247
248
249## Credits
250
251Inspired by [this forum thread](http://postfix.1071664.n5.nabble.com/MTA-STS-when-td95086.html).
252
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}