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