# PostSRSd example configuration file
# Copyright 2022-2023 Timo Röhling
# SPDX-License-Identifier: FSFUL
#
# The copyright holder gives unlimited permission to copy, distribute and modify
# this file.

# Local domains
# Your local domains need not be rewritten, so PostSRSd has to know about them.
#
# Example:
#     domains = { "example.com", "example.org", "example.net" }
#
domains = {}

# Local domains (file storage)
# Instead of listing your local domains directly, you can also write them to a
# file and have PostSRSd read it. This is particularly useful if you have a
# large number of domains for which you need to act as mail forwarder. PostSRSd
# reads this file before it chroots and drops root privileges. The file format
# is one domain per line.
#
# Example:
#     domains-file = "/usr/local/etc/postsrsd.domains"
#
#domains-file =

# Dedicated SRS rewrite domain.
# The local domain which is used to create the ephemeral SRS envelope
# addresses. It is recommended that you use a dedicated mail domain for SRS if
# you serve multiple unrelated domains (e.g. for your customers), to prevent
# privacy issues. If unset, the first configured local domain is used.
#
# Example:
#     srs-domain = "srs.example.com"
#
#srs-domain =

# Socketmap lookup table for Postfix integration.
# Traditionally, PostSRSd interacts with Postfix through the canonicalization
# lookup tables of the cleanup daemon. If you use a unix socket, be aware that
# most Postfix instances will jail their cleanup daemon in a /var/spool/postfix
# chroot, so no other path will be visible to them. Unix sockets are created
# before PostSRSd chroots and drops root privileges.
#
# Examples:
#     socketmap = unix:/var/spool/postfix/srs
#     socketmap = inet:localhost:10003
#
socketmap = unix:/var/spool/postfix/srs

# Socketmap connection keep-alive timeout.
# After PostSRSd has served a socketmap request, it will keep the connection
# open for a while longer, in case Postfix has additional queries. PostSRSd
# will close the connection after the configured time (in seconds) has expired.
#
# Examples:
#     keep-alive = 30
#
keep-alive = 30

# Milter endpoint for MTA integration.
# PostSRSd can act as a milter to rewrite envelope addresses if it has been
# built with milter support. Unix sockets are created before PostSRSd chroots
# and drops root privileges.
#
# Examples:
#     milter = unix:/var/spool/postfix/srs_milter
#     milter = inet:localhost:9997
#
#milter =

# Original envelope sender handling.
# When the envelope sender is rewritten, the original address can either be
# embedded in the rewritten address, or stored in a local database. Embedding
# makes PostSRSd work fully stateless, but the full sender address needs to fit
# into the localpart of the embedded address, effectively limiting the length
# of forwardable sender addresses to 51 octets. Storing the sender address in a
# database circumvents this problem, but makes PostSRSd vulnerable to an
# attacker sending vast amounts of emails with fake sender addresses, all of
# which need to be stored in the database.
#
# If you are unsure which option suits your use-case best, the vast majority of
# mail addresses will be relatively short, so you should pick "embedded".
#
# Examples:
#     original-envelope = embedded
#     original-envelope = database
#
original-envelope = embedded

# Database for envelope sender storage.
# If you decide to store envelope senders in a database, this database will be
# used. The option is ignored if original-envelope is set to "embedded". Also
# note that PostSRSd needs to be built with SQLite or Redis support for this.
#
# PostSRSd reads this database after it chroots and drops root privileges, so
# the actual filename is the chroot directory joined with this filename.
#
# Examples:
#     envelope-database = "sqlite:./senders.db"
#     envelope-database = "redis:localhost:6379"
#
#envelope-database = "sqlite:./senders.db"

# Secret keys for signing and verifying SRS addresses.
# Rewritten addresses are tagged with a truncated HMAC-SHA1 signature, to
# prevent tampering and forged envelope addresses. You can have more than
# one signing secret; each line of the secrets file is considered one secret
# key. If an incoming signature matches any key, it is accepted. Outgoing
# signatures will always be generated with the first configured secret.
#
# For security reasons, you should also make sure that the file is owned and
# only accessible by root (chmod 600). PostSRSd reads this file before it
# chroots and drops root privileges.
#
# Example:
#     secrets-file = "/usr/local/etc/postsrsd.secret"
#
secrets-file = "/usr/local/etc/postsrsd.secret"

# SRS tag separator
# This is the character following the initial SRS0 or SRS1 tag of a generated
# sender address. Valid separators are "=", "+", and "-". Unless you have a
# very good reason, you should leave this setting at its default.
#
separator = "="

# SRS hash signature length
# Any SRS address will be signed with a truncated hash to prevent tampering and
# ensure that only legitimate email bounces will be returned to sender. The
# default length provides adequate security without taking up too much valuable
# space. Unless you know what you are doing, you should leave this setting at
# its default.
#
# WARNING: You can break your mail server (or worse, turn it into a spam relay)
# if you mess up this setting.
#
hash-length = 4

# SRS minimum acceptable hash signature length
# This is the mininum signature length that PostSRSd considers valid. It is a
# separate setting because if you decide to increase the hash length, you may
# want to keep accepting the shorter hashes for a 24 hour grace period. Again,
# Unless you know what you are doing, you should leave this setting at its
# default.
#
# WARNING: You can break your mail server (or worse, turn it into a spam relay)
# if you mess up this setting.
#
hash-minimum = 4

# Always rewrite sender addresses
# You can force PostSRSd to rewrite any sender address, even if it has been
# rewritten already. You probably do not want to do this, though.
#
always-rewrite = off

# Execute PostSRSd as unprivileged user
# Drop root privileges and run as this user before entering the main loop and
# handling untrusted input. To prevent PostSRSd from changing users, set this to
# the empty string.
#
# Example:
#     unprivileged-user = "nobody"
#
unprivileged-user = "nobody"

# Execute PostSRSd in chroot jail
# PostSRSd will jail itself in the given directory, which adds an additional
# layer of protection against the exploitation of security bugs in PostSRSd. To
# prevent PostSRSd from chrooting, set this to the empty string.
#
# Example:
#     chroot-dir = "/usr/local/var/lib/postsrsd"
#
chroot-dir = "/usr/local/var/lib/postsrsd"

# Syslog
# PostSRSd writes log messages to stderr. If you enable this option, PostSRSd
# will also send all messages to the syslog mail facility.
#
syslog = off

# Debug
# This option makes PostSRSd more verbose in its logging, which can be useful
# to hunt down configuration problems.
#
debug = off