PostSRSd Documentation

PostSRSd is a Sender Rewriting Scheme (SRS) daemon for Postfix. SRS is used to forward emails from domains that use SPF (Sender Policy Framework) without being rejected by the recipient's MTA.

When you forward an email from alice@example.com, your server might not have permission to send on behalf of example.com. PostSRSd circumvents this by rewriting the envelope sender to a temporary address on a domain you control, such as SRS0=xxxx=yy=example.com=alice@yourdomain.org (forward SRS).

• xxxx: A cryptographic signature to prevent abuse.
• yy: A timestamp to ensure the address expires.

If a bounce occurs, PostSRSd can perform 'reverse SRS' to extract the original sender and relay the notification correctly.

When migrating from version 1.x to 2.x, note that most configuration options must now be set in postsrsd.conf rather than via command-line arguments.

Mapping old environment variables to new config keys:

• SRS_DOMAIN $\rightarrow$ srs-domain
• SRS_EXCLUDE_DOMAINS $\rightarrow$ domains
• SRS_SECRET $\rightarrow$ secrets-file
• RUN_AS $\rightarrow$ unprivileged-user
• CHROOT $\rightarrow$ chroot-dir

Postfix Compatibility: PostSRSd 2.x uses socketmap: tables, which are not compatible with tcp: tables. Ensure your Postfix version is at least 2.10 and update your main.cf accordingly.

To build PostSRSd from source, you need CMake (3.24+), a C99 capable compiler (like gcc), and libConfuse.

Optional dependencies:

• sqlite3: Enable with -DWITH_SQLITE=ON to store envelope senders.
• hiredis: Enable with -DWITH_REDIS=ON to store envelope senders in Redis.
• libseccomp & gperf: Enable with -DWITH_SECCOMP=ON for sandboxing.
• check: Required for unit tests (disable with -DBUILD_TESTING=OFF).

Build steps:

cd path/to/source
mkdir _build && cd _build
cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local
make -j
sudo make install

PostSRSd 2.1+ can automatically reload if the domains-file is modified by enabling the domains-file-watch option in postsrsd.conf.

Best Practice for Updates: To avoid race conditions or issues with non-atomic updates, always update the domains file using an atomic move:

1. Create a temporary file (e.g., postsrsd.domains.tmp.XXXXXX) in the same directory.
2. Populate the temporary file.
3. Rename the temporary file to replace the actual domains file.

Do not delete the existing file and create a new one in-place, as this is not atomic and may cause PostSRSd to miss the event.

The recommended way to integrate PostSRSd with Postfix is using canonical maps of the cleanup daemon.

Add the following to your /etc/postfix/main.cf:

sender_canonical_maps = socketmap:unix:srs:forward
sender_canonical_classes = envelope_sender
recipient_canonical_maps = socketmap:unix:srs:reverse
recipient_canonical_classes = envelope_recipient, header_recipient

Note on socket paths: The srs part in the socketmap refers to the path to the unix socket relative to /var/spool/postfix. If you change the socketmap configuration in PostSRSd, you must update this path. If using TCP, use a format like socketmap:inet:localhost:10003:forward.

PostSRSd 2.x supports the Milter protocol. This is considered experimental and not yet ready for production.

1. In postsrsd.conf, set the milter option.
2. In /etc/postfix/main.cf, add:

smtpd_milters = unix:srs_milter

PostSRSd uses the CMake FetchContent module to manage external dependencies. By default, it attempts to find installed system libraries first; if they are not found, it downloads the source code, builds it, and links it statically.

For self-contained builds where you want to ensure no network access is attempted during the configuration phase, use the following CMake options:

cmake -DFETCHCONTENT_FULLY_DISCONNECTED -DFETCHCONTENT_TRY_FIND_PACKAGE_MODE=ALWAYS ..

PostSRSd is configured via postsrsd.conf, which is typically located in /usr/local/etc.

Key configuration options:

• domains (or domains-file): Defines your local domains so PostSRSd knows which ones are local.
• secrets-file: Path to a file containing the secret passphrase used for authentication.
• milter: Enables experimental Milter support.
• domains-file-watch: Enables inotify support to automatically reload the configuration when the domains-file is modified.

An example configuration can be found in /usr/local/share/postsrsd.

PostSRSd can act as a Milter (Mail Filter) to automatically rewrite sender and recipient addresses during mail transactions. The daemon implements the standard Milter protocol and handles the following lifecycle:

• OPTNEG: Negotiates milter options.
• MAIL: Receives the sender address. The daemon may rewrite this address using postsrsd_forward.
• RCPT: Receives recipient addresses. The daemon can use postsrsd_reverse to check if recipients are already SRS-encoded and use MILTER_DO_DELRCPT/MILTER_DO_ADDRCPT to replace them if necessary.
• EOM: End of message. At this stage, the daemon finalizes the rewriting of the sender and recipients.
• QUIT: Ends the session.

Configuration Note: The milter-rewrite-local setting determines whether the daemon attempts to rewrite addresses even if they belong to local domains.

The Socketmap interface allows external applications to query SRS mappings using a netstring-based protocol. It supports two primary query types:

1. forward <address>: Rewrites a given address using the configured SRS domain. If always-rewrite is not set, it will only rewrite addresses that are not in the local-domains list.
2. reverse <address>: Reverses an SRS-encoded address back to its original form.

Response Formats:

• Success: OK <rewritten_address>
• Permanent Error: PERM <error_message> (e.g., PERM Invalid query., PERM Too big., PERM Invalid map.)
• Not Found: NOTFOUND <info>