diff --git a/README.rst b/README.rst index 444cf4a..271fac6 100644 --- a/README.rst +++ b/README.rst @@ -113,7 +113,7 @@ change the ``socketmap`` configuration of PostSRSd. If you prefer a TCP connection, e.g. ``inet:localhost:10003``, you need to change the mapping to something like ``socketmap:inet:localhost:10003:forward``. -.. _example: data/postsrsd.conf.in +.. _example: doc/postsrsd.conf Experimental Milter Support ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/postsrsd.conf b/doc/postsrsd.conf new file mode 100644 index 0000000..b1aee21 --- /dev/null +++ b/doc/postsrsd.conf @@ -0,0 +1,184 @@ +# PostSRSd example configuration file +# Copyright 2022 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. +# +# 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. +# +# 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. +# +# 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. +# +# Also note that you need to put the SQLite database into the chroot directory +# if you jail PostSRSd; otherwise, the database file will not be accessible. +# +# 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). +# +# 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 +# If you set this highly recommended option, PostSRSd will drop root +# privileges and switch to the configured user before it enters the main loop +# to handle untrusted input. +# +# Example: +# unprivileged-user = "nobody" +# +unprivileged-user = "nobody" + +# Execute PostSRSd in chroot jail +# If you set this highly recommended option, PostSRSd will jail itself +# in the given directory, which adds an additional layer of protection +# against the exploitation of security bugs in PostSRSd. +# +# 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