README.exim.md
1PostSRSd integration with Exim
2==============================
3
4## SRS Return router
5
6If using a domain solely for SRS return addresses:
7
8 SRS_DOMAIN = srs.your.domain
9
10 begin routers
11
12 srs_return:
13 caseful_local_part
14 domains = SRS_DOMAIN
15 driver = redirect
16 allow_fail
17 data = ${if match {$local_part}{\N(?i)^srs[01]=\N} \
18 {${if match \
19 {${readsocket{inet:localhost:10002}{get ${quote_local_part:$local_part_prefix$local_part}@$domain}{3s}}} \
20 {\N^200 (.+)\N} \
21 {$1} \
22 {:fail: Invalid SRS bounce} \
23 }} \
24 {:fail: Invalid SRS bounce} \
25 }
26 no_more
27
28If your SRS domain is also used for other addresses:
29
30 SRS_DOMAIN = srs.your.domain
31
32 begin routers
33
34 srs_return:
35 caseful_local_part
36 domains = SRS_DOMAIN
37 local_part_prefix = srs0= : srs1=
38 driver = redirect
39 allow_fail
40 data = ${if match \
41 {${readsocket{inet:localhost:10002}{get ${quote_local_part:$local_part_prefix$local_part}@$domain}{3s}}} \
42 {\N^200 (.+)\N} \
43 {$1} \
44 {:fail: Invalid SRS bounce} \
45 }
46
47## Rewriting outgoing mail in the SMTP transport
48
49The following excludes locally submitted mail, or mail submitted by authenticated
50users from SRS rewriting. Of course, if the sender address is already in
51one of our local domains, there is no need to rewrite the address.
52
53 begin transports
54
55 remote_smtp:
56 debug_print = "T: remote_smtp for $local_part@$domain"
57 driver = smtp
58 return_path = ${if and { \
59 {!match_ip{$sender_host_address}{:@[]}} \
60 {!def:authenticated_id} \
61 {!match_address {$sender_address} { : *@+local_domains : *@+virtual_domains : SRS_DOMAIN}} \
62 } \
63 {${if match \
64 {${readsocket{inet:localhost:10001}{get $sender_address}{3s}}} \
65 {\N^200 (.+)\N} \
66 {$1} \
67 fail } \
68 } \
69 fail }
70
README.md
1PostSRSd
2========
3
4About
5-----
6
7PostSRSd provides the Sender Rewriting Scheme (SRS) via TCP-based
8lookup tables for Postfix. SRS is needed if your mail server acts
9as forwarder.
10
11
12Sender Rewriting Scheme Crash Course
13------------------------------------
14Imagine your server receives a mail from `alice@example.com`
15that is to be forwarded. If example.com uses the Sender Policy Framework
16to indicate that all legit mails originate from their server, your
17forwarded mail might be bounced, because you have no permission to send
18on behalf of example.com. The solution is that you map the address to
19your own domain, e.g.
20`SRS0+xxxx=yy=example.com=alice@yourdomain.org` (forward SRS). If the
21mail is bounced later and a notification arrives, you can extract the
22original address from the rewritten one (reverse SRS) and return the
23notification to the sender. You might notice that the reverse SRS can
24be abused to turn your server into an open relay. For this reason, `xxxx`
25and `yy` are a cryptographic signature and a time stamp. If the signature
26does not match, the address is forged and the mail can be discarded.
27
28Building
29--------
30
31PostSRSd requires a POSIX compatible system and CMake to build.
32Optionally, help2man is used to create a manual page.
33
34For convenience, a Makefile fragment is provided which calls CMake with
35the recommended command line options. Just run `make`.
36
37Alternatively, you can control many aspects of the build manually:
38
39 mkdir build
40 cd build
41 cmake .. <options>
42 make
43 make install
44
45The CMake script defines a number of options in addition to the
46standard CMake flags. Use `-D<option>=<value>` to override the defaults.
47
48* `GENERATE_SRS_SECRET` (default: `ON`). Generate a random secret on install.
49* `USE_APPARMOR` (default: `OFF`): Install an AppArmor profile for the daemon.
50* `USE_SELINUX` (default: `OFF`): Install an SELinux policy module for
51 the daemon.
52* `INIT_FLAVOR` (default: auto-detect). Select the appriopriate startup
53 script type. Must be one of (`systemd`, `upstart`,`sysv-lsb`,`sysv-redhat`)
54 or `none`.
55* `CHROOT_DIR` (default: `${CMAKE_INSTALL_PREFIX}/lib/postsrsd`). Chroot jail
56 for the daemon.
57* `SYSCONF_DIR` (default: `/etc`). Location of system configuration files.
58* `CONFIG_DIR` (default: `${SYSCONF_DIR}/default`). Install destination for
59 the postsrsd settings.
60* `DOC_DIR` (default: `${CMAKE_INSTALL_PREFIX}/share/doc/postsrsd`). Install
61 destination for documentation files.
62* `SYSD_UNIT_DIR` (default: `${SYSCONF_DIR}/systemd/system`). Install
63 destination for systemd startup files.
64
65Installing
66----------
67
68Run `make install` as root to install the daemon and the configuration
69files.
70
71Configuration
72-------------
73
74The configuration is located in `/etc/default/postsrsd` by default. On many
75systems, the default configuration will work out-of-the-box, but please take
76the two minutes to check the settings for yourself. Also, please make sure
77that Postfix has the correct domain name configured, i.e.
78`postconf -h mydomain` returns the correct value.
79
80You must store at least one secret key in `/etc/postsrsd.secret`. The installer
81tries to generate one from `/dev/urandom`. Be careful that no one can guess
82your secret, because anyone who knows it can use your mail server as open
83relay! Each line of `/etc/postsrsd.secret` is used as secret. The first secret
84is used for signing and verification, the others for verification only.
85
86PostSRSd exposes its functionality via two TCP lookup tables. The
87recommended Postfix configuration is to add the following fragment to
88your main.cf:
89
90 sender_canonical_maps = tcp:localhost:10001
91 sender_canonical_classes = envelope_sender
92 recipient_canonical_maps = tcp:localhost:10002
93 recipient_canonical_classes= envelope_recipient,header_recipient
94
95This will transparently rewrite incoming and outgoing envelope addresses,
96and additionally undo SRS rewrites in the To: header of bounce notifications
97and vacation autoreplies.
98
99Run `service postsrsd start` and `postfix reload` as root, or reboot. For Debian and Ubuntu you need to run `systemctl enable postsrsd` first.
100
101Known Issues
102------------
103
104- Due to the way PostSRSd is integrated with Postfix, sender addresses
105 will always be rewritten even if the mail is not forwarded at all. This
106 is because the canonical maps are read by the cleanup daemon, which
107 processes mails at the very beginning before any routing decision is made.
108
109 Where piping into an external command is not a problem,
110 [Postforward](https://github.com/zoni/postforward) offers an alternative
111 way to integrate PostSRSd with Postfix which avoids this problem.
112
113- The Postfix package in CentOS 6 lacks the required support for TCP
114 dictionaries. Please upgrade your distribution or build Postfix yourself.
115
116Use with Exim
117-------------
118
119Exim configuration examples can be found in [README.exim.md](README.exim.md)
120
README_UPGRADE.md
1PostSRSd Upgrade Note
2=====================
3
4/etc/default/postsrsd
5---------------------
6
7The shipped configuration file has changed from previous versions.
8However, the installer will not automatically overwrite existing
9configuration files to prevent data loss.
10
11Please review the changes after the installation and update your
12configuration file accordingly. Note in particular, that most options
13may no longer remain commented out, since it was cumbersome to maintain
14all the default values in the various startup scripts.
15
16