Pre-generate proper example config

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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

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