7. Configuration¶
All Pepsi components read one INI-style configuration file (the format is shared with the GNU Taler tools). The exhaustive option reference lives in the single man page pepsi.conf(5) and in the per-program chapters under Programs.
7.1. File format¶
A file is a sequence of [SECTION] headers, each followed by
OPTION = VALUE assignments. Section and option names are case-insensitive
(conventionally upper case); # or % begins a comment; a value may be
double-quoted to preserve surrounding whitespace.
Three directives combine several files into one configuration. This matters for keeping secrets out of the world-readable configuration file:
@inline@ FILEInclude another file, relative to the current one.
@inline-matching@ GLOBInclude every file matching a shell glob.
@inline-secret@ SECTION FILEMerge one section from a mode-restricted file (typically credentials). A directive ends the section it appears in, so write it after that section’s last option; an option below it would belong to no section and the file would not load. A fragment that cannot be read only causes a warning, and the options that it carries then look unset.
pepsi-setup rungives each fragment to the service account that is meant to read it. A credential written directly intopepsi.confinstead is readable by every local account (Mail appliances store secrets world-readable or unprotected).
Path-valued options undergo $-expansion from the [PATHS] section or the
environment ($VAR, ${VAR}, ${VAR:-default}). Value types are
boolean (YES/NO), number, duration (h/m/s units only —
see the caveat below), path and unix mode (octal).
Warning
duration values are parsed by jiff::SignedDuration, which accepts only
hours/minutes/seconds and below. A calendar unit such as 5 d or 2 weeks
does not parse. For day-or-longer windows write the equivalent in hours
(120 h) or use an integer option where one is provided (e.g.
[pepsi-srs] MAX_AGE_DAYS).
7.1.1. Packaged defaults: config.d¶
Below the operator’s file there is one more layer. Every *.conf in
${DATADIR}/config.d (/usr/share/pepsi/config.d on a packaged install) is
parsed before pepsi.conf, so those files supply defaults that
pepsi.conf overrides option by option. They belong to the package: redefine
what you want in pepsi.conf rather than editing them, or an upgrade will
discard the change.
One ships:
vacation.confConfiguration that ships as wording rather than as a value: the
[pepsi-vacation-default-message]notices in ten languages, which pepsi-stage-vacation falls back to. RedefiningENinpepsi.confleaves the other nine in place.
No config.d file lowers the cryptographic policy for a whole class of
correspondents. Which S/MIME container a correspondent gets is decided per peer
by the S/MIME capability record (The per-peer S/MIME capability record,
Which S/MIME container a correspondent gets). Only a correspondent recorded as unable to read
AuthEnvelopedData gets AES-256-CBC. A correspondent who has never sent a
signed message (a Thunderbird user, say) is asked once, in a plaintext part
beside the first ciphertext, to reply with a signed message
(What a correspondent on an unmeasured client sees); alternatively, the operator configures the record
(pepsi-keys peer capability set ADDRESS cbc).
7.3. Ingress and listeners¶
[pepsi-ingress] holds message-acceptance policy (HOSTNAME,
ACCEPTED_DOMAINS, MAX_MESSAGE_SIZE, MAX_CONNECTIONS,
DMARC_ENFORCE, DNS settings). Each [pepsi-ingress-listener-<name>] section
binds one socket:
SERVE = tcp(withBIND_TO/PORT),unix(withUNIXPATH) orsystemd(socket activation,FD_INDEX).MODE = plain|starttls|tlsselects the transport security;starttls/tlsrequireTLS_CERTandTLS_KEY.
Declare as many listeners as needed — e.g. an MX listener on 25 with opportunistic STARTTLS and a submissions listener on 465 with implicit TLS.
7.4. The stage pipeline¶
The pipeline is wired entirely from [stage-<name>] sections. The stage
name is an operator-chosen label; the section’s PROGRAM selects the
binary, and NEXT_STAGE/BOUNCE_STAGE connect the graph:
PROGRAM(required) The stage binary (found on
PATHunless absolute). One binary may serve several stages: it reads its options from whichever section the message is currently at.NEXT_STAGE(optional) Where a message advances on success. A terminal stage with no
NEXT_STAGEremoves the delivered message.BOUNCE_STAGE(optional) Where a message that failed permanently is routed so that a DSN is generated; with
ORIGINATE_SUCCESS_DSN, this also applies to a message that was delivered successfully. This is usually apepsi-stage-bouncestage.PARALLELISM/MAX_MESSAGES/QUEUE_LIMIT(optional) How the dispatcher sizes the worker pool for this stage: the cap on concurrent worker processes (
PARALLELISM, default 4, started on demand and reaped when idle), the number of messages that a worker handles before it is recycled (MAX_MESSAGES, default 1000), and how many messages are pipelined to one worker at once (QUEUE_LIMIT, default 4). The stage can thus haveQUEUE_LIMIT × PARALLELISMmessages in flight, whilePARALLELISMalone sets the number of processes and connections. See pepsi-dispatch.FUSION(optional) Whether a predecessor may run this stage in its own worker process instead of handing the row back to the dispatcher. Defaults to
YESwhenPROGRAMis one of the fast body-free stages (pepsi-stage-+if,discard,auto-whitelist,block-language,check-whitelist,srs,list,edit-settings,dmarc-reportordefang) andNOotherwise;[pepsi] ALLOW_FUSION = NOdisables fusion globally.
New messages always enter at [stage-init], which must exist. Each
program reads its own options from its section; those are documented per program
under Programs.
7.4.1. Ordering constraints¶
The pipeline graph is yours to draw, but six orderings are not free choices,
and getting any of them wrong produces mail that looks right. pepsi-setup
warns about four of them: a DKIM-signing stage that leads to an encrypt stage,
a decrypt stage that leads to an ARC stage, a decrypt stage with no local
delivery downstream, and a re-encryption stage that has no decrypt stage
upstream or leads to a stage that reads or forwards the content.
Encryption comes before DKIM signing. The recommended outbound chain is:
submission → … → encrypt → srs → dkim-sign → relay
pepsi-stage-encrypt rewrites the body, and DKIM must sign the bytes that are actually transmitted. Signing first yields a message whose DKIM signature does not verify at the recipient — which is worse than no signature, because a broken signature is a stronger negative signal to a receiving MTA than an absent one.
Anything that reads the body comes before encryption. The pay-to-send gate (pepsi-stage-anti-spam) and language detection (pepsi-stage-detect-language) both want cleartext, and both get it, because encryption is last on the outbound path — which is the reason for the ordering above.
SRS is for forwarded mail, and harmless on the outbound relay tail. It
rewrites a sender in somebody else’s domain, that is, on mail that this host
forwards, so that SPF passes at the next hop. The null sender and a sender
already in the SRS domain are left alone. SRS_DOMAIN is a dedicated domain,
not aligned with any served one. pepsi-setup refuses an aligned one unless
[pepsi-srs] ALLOW_ALIGNED_DOMAIN says so, because forwarded forgeries of a
served domain would otherwise pass DMARC at the next hop on SPF alone (see the
threat model’s A remote sender). On a relay tail that forwarded and
submitted mail share, our own users’ mail is therefore rewritten too. That
costs SPF alignment for their domain, but DMARC still passes on the aligned DKIM
signature that dkim-sign adds afterwards, in the order that pepsi-setup
checks for: encrypt → srs → dkim-sign → relay. A copy produced by an alias
or ~/.forward gets a forward return address rather than an SRS one. A
remote report about such a copy is answered through the bounce stage (the SRS
stage’s BOUNCE_STAGE, else a stage named bounce), so a pipeline that
forwards off-site should have one.
ARC comes before decryption. The recommended inbound chain is:
init = arc → decrypt → aliases → (anti-spam / language / …) → local delivery
An ARC set seals the message as it arrived.
pepsi-stage-decrypt rewrites the body, so decrypting first would
make the sealed AMS describe bytes that nobody else ever saw: a claim about
a message that never existed.
Decryption needs local delivery downstream. Decrypting invalidates the
sender’s DKIM signature. This is harmless for a message that is about to be
filed in a mailbox on this host, but not for one that is relayed onward. The
stage therefore runs only for recipients that this host serves, and it splits a
message that has both kinds of recipient. pepsi-setup warns when no
pepsi-stage-relay-to-maildir or
pepsi-stage-relay-to-lmtp is reachable from a decrypt stage,
because such a stage is either pointless or harmful.
Re-encryption comes last, immediately before local delivery.
pepsi-stage-reencrypt seals what the decrypt stage opened to the
recipient’s own mail-client key. It must therefore come after decryption
(before it, nothing that it sees was opened). It must also come after every
stage that reads the content or may forward a copy, because those stages would
otherwise see ciphertext that only the user’s client can open
(End-to-end encryption: two custody modes): language detection and blocking, the spam gate, the
whitelist check, pepsi-stage-autocrypt-learn, the vacation
responder, ~/.forward processing and alias expansion.
The mirror image of the outbound rule applies too: anything that reads the
body comes after decryption, which is why the content stages sit where they
do. Peer-key learning (pepsi-stage-autocrypt-learn) also comes
after the spam verdict, so that a key is never learnt from spam. Note that the
decrypt stage loads the whole message body for every message that passes
through it (its Load is fixed per stage, and whether a message
is protected cannot be told from the envelope columns), so placement is a
performance matter as well as a correctness one.
7.5. Worked examples¶
Each example below is a complete, minimal pipeline for one job, with no language classification, ARC/DKIM signing or spam filtering: only the shared sections, one listener, and the stages that do the work. They all have the same basic sections in common:
[pepsi-postgres]for the database, and[pepsi-ingress]plus one[pepsi-ingress-listener-*]socket.
The listeners set MODE = starttls/tls but no TLS_CERT/TLS_KEY:
pepsi-setup auto-fills the certbot paths (see Installation). Set them
explicitly, or pass --no-certbot, to manage the certificate yourself.
Each is a real, self-contained configuration. To add ARC, SRS, DKIM signing or
spam filtering on top, insert the corresponding stages between init and
the delivery stage as the sample pepsi.conf shows.
7.5.1. Minimal inbound (relay to a smarthost)¶
An edge MX that accepts mail for our domains and hands every message to one
authenticated upstream smarthost. init is the relay stage; the smarthost
authenticates us, so no SRS rewrite is needed here:
[pepsi-postgres]
CONFIG = postgres:///pepsi
[pepsi-ingress]
HOSTNAME = mail.example.org
ACCEPTED_DOMAINS = example.org
[pepsi-ingress-listener-mx]
SERVE = tcp
BIND_TO = 0.0.0.0
PORT = 25
MODE = starttls
# init: relay every accepted message to the upstream smarthost. A successful
# delivery is terminal (no NEXT_STAGE).
[stage-init]
PROGRAM = pepsi-stage-relay-to-smarthost
SERVER_NAME = mail.example.org
# The upstream smarthost (one [...-mta-*] section per route; CATCH_ALL takes
# everything not matched by a DOMAINS list).
[pepsi-stage-relay-to-smarthost-mta-upstream]
HOST = smtp.relay.example.net
PORT = 587
MODE = starttls
AUTH = plain
USERNAME = relayuser
PASSWORD = changeme
CATCH_ALL = yes
7.5.2. Minimal outbound (relay direct to the internet)¶
A submission/relayhost that accepts our own users’ mail and delivers it directly
to each recipient’s MX. The listener trusts a local network (MYNETWORKS) so
those submissions are marked locally-originated and allowed to relay to any
domain; outbound mail keeps its own envelope sender, so there is no SRS stage:
[pepsi-postgres]
CONFIG = postgres:///pepsi
[pepsi-ingress]
HOSTNAME = mail.example.org
ACCEPTED_DOMAINS = example.org
[pepsi-ingress-listener-submission]
SERVE = tcp
BIND_TO = 0.0.0.0
PORT = 587
MODE = starttls
# Trust submissions from this network without authentication (use SASL_TYPE /
# TLS_AUTH_CLIENT instead for roaming users).
MYNETWORKS = 10.0.0.0/8
# init: deliver directly to each recipient's mail exchanger. Terminal.
[stage-init]
PROGRAM = pepsi-stage-relay-to-internet
SERVER_NAME = mail.example.org
# Read by pepsi-setup to build the SPF record listing our sending hosts, and
# to check each address's PTR against SERVER_NAME above. PUBLIC_IP belongs in
# the relay *stage's* section: pepsi-setup finds it by walking [stage-*] and
# keeping the sections whose PROGRAM is a relay, never by the program's own
# section name.
PUBLIC_IP = 203.0.113.7 2001:db8::25
7.5.3. Minimal local delivery (relay to Maildir)¶
An MX that delivers mail for our domain into local users’ Maildir/new/. Every
recipient is in ACCEPTED_DOMAINS (so ingress accepts it) and resolves to a
local account, so no NEXT_STAGE is needed. Add one (a smarthost or bounce
stage) if a recipient in our domain may have no local mailbox:
[pepsi-postgres]
CONFIG = postgres:///pepsi
[pepsi-ingress]
HOSTNAME = mail.example.org
ACCEPTED_DOMAINS = example.org
[pepsi-ingress-listener-mx]
SERVE = tcp
BIND_TO = 0.0.0.0
PORT = 25
MODE = starttls
# init: write each local recipient's copy into their Maildir via the setuid
# helper. Terminal for local recipients.
[stage-init]
PROGRAM = pepsi-stage-relay-to-maildir
SERVER_NAME = mail.example.org
A staging deployment that never touches the network swaps the delivery stage for
pepsi-stage-discard (see pepsi-stage-discard).
7.6. Configuration in the database¶
The file described above is the base layer. On top of it, Pepsi reads a set of
administrator-managed overrides from the pepsi.config_override table, so a
running deployment can be reconfigured without editing files and without a
restart.
Nothing about this is on by default. With no rows in that table a deployment behaves exactly as its configuration file says — there is no implicit configuration hiding in the database, and deleting every override returns the system to the file’s behaviour.
7.6.1. The scope chain¶
Five layers, lowest precedence first:
Layer |
Written by |
Applies to |
|---|---|---|
the configuration file |
the operator, with a text editor |
everything |
|
|
everything |
|
|
messages whose relevant address is at that domain |
|
|
messages whose relevant address is exactly that one |
|
the account owner, by e-mail |
messages to/from that one address |
Higher layers override lower ones option by option, never section by section. An option that no layer mentions keeps its file value, so an override is always a targeted amendment rather than a replacement of a whole section.
The “relevant address” is the same one that the per-address settings layer
uses: the envelope sender for a locally-originated message, otherwise each
envelope recipient. When one message’s recipients resolve to different
configurations for the stage that is about to run, the message is split into one row per
distinct configuration, exactly as for pepsi.settings.
The domain: and address: layers hold [stage-*] sections only: a
stage consults them for the section it is running, per message. Every other
section is read once per process and sees the file plus the global layer, so
pepsi-config refuses to store a scoped override of one and pepsi-setup
run reports any such row as an error.
7.6.2. Why pepsi.settings is a separate table¶
The two have different write authorities:
pepsi.settingsis written by account owners, from their own mailbox, through pepsi-stage-edit-settings, restricted to the stage sections that the operator listed inEDITABLE_STAGES;config_overridedefines the pipeline and is writable only through thepepsi-configdatabase role.
Merging them would put user-writable rows in the same table as the definition of
the mail server. There, a single bug in a namespace check would no longer just
let an override leak; it would let a user reconfigure the MTA. PostgreSQL enforces the separation:
pepsi-setup grants INSERT/UPDATE/DELETE on config_override to
the pepsi-config role alone, revokes them from every service account, and
verifies both against the live database after each install. A stage
worker’s job is to parse hostile mail; it may read the configuration but may not
change it.
7.6.3. What stays in the configuration file¶
Some sections are never read from the database, whatever rows exist. An override naming one of them is ignored at run time and refused at write time:
[pepsi],[pepsi-postgres],[PATHS]Needed to find and open the database in the first place.
[pepsi]is also the home of the administrator-only cryptographic policy.[pepsi-httpd],[pepsi-httpd-listener-*],[pepsi-httpd-cert-*]The server that serves the configuration interface must always be able to start, whatever the database says.
[pepsi-ingress-listener-*]Listening sockets are bound at start-up, often under socket activation and before privileges are dropped.
[pepsi-secure-link]Its
PEPPERis the server-side secret that makes a stolen database useless (see The secure-link fallback portal). If the database could replace it, an attacker could quietly arrange for the next stored message to be one that the attacker can open. That is the same kind of attack as lowering the crypto policy. Keeping it out of the database is also what denies a stolen dump any offline guessing of PINs (Offline guessing of weak password hashes, key passphrases and derived keys).[pepsi-admin]Decides who may administer the server and how the administrative surface reaches the database. If the database could set it, writing to the database would be a way to grant yourself the console.
[pepsi-crypto],[pepsi-srs],[pepsi-origin]Each holds a server-side key that exists so that the database alone is not enough: the key-encryption keys (and which of them wraps new private keys), the SRS key that authorises relaying to any address, and the key for proofs of origin, against which a returning bounce or payment demand is checked. If the database could replace one of these keys, an attacker could arrange for the next wrapped key to be one that the attacker can open, or for a forged bounce to be relayed or paid. The rest of each section stays in the file together with the key.
[pepsi-wizard]Listed here for a third reason: it is not configuration at all, but the setup wizard’s record of the answers that it was given. The browser interview stages these answers as draft rows in this very table. Drafts are invisible to every reader, but a hand-written row that is not a draft would otherwise end up in the effective configuration of every process. Nothing reads the section at run time, so the safe answer is that the database never supplies it either.
The line is “needed before a database connection exists, a security boundary, or the home of a server-side secret”. Listeners are on the second side of it deliberately: if the database could move a listening socket or change its TLS material, a database compromise would become a compromise of the mail server’s own ports.
Which programs run is decided by the file as well. Options that name an
executable are refused in any section and at any scope: HELPER (what a
delivery stage, running setgid, executes), [pepsi-whitelist] SCAN_HELPER,
[pepsi] MAILBOX_HELPER and [pepsi-secure-link] PIN_COMMAND. A stage’s
PROGRAM is accepted only as a bare pepsi-stage-* command, which the
dispatcher finds on its PATH. A stage can therefore still
be added, removed or rewired through the overlay, but a principal allowed to
write it cannot make the pipeline run an executable of its choosing
(Command injection and XXE in mail gateway management interfaces, Mail appliances store secrets world-readable or unprotected).
Important
Adding a submission port is a text-editor-and-restart operation. So is
changing a listener’s TLS certificate, the database connection, or the
[pepsi] crypto policy. No administrative interface can change these, and
none should imply that it can.
Credentials are never stored in the database, whatever section they are in. An
option whose name marks it as a credential is refused by pepsi-config set
and by the administrative API, and ignored if a row for one exists anyway. Such
a name has PASS, PASSWORD, PASSPHRASE, SECRET, TOKEN,
CREDENTIAL(S), CLIENT_ID, PEPPER or SYSTEM_ID among the words
its underscores separate (API_PASS, KEY_WRAP_SECRET, but not
SECRETARY); the same rule masks a value wherever a
configuration is shown. The rule also covers the file that a credential is read
from and the endpoint that it is sent to (TOKEN_FILE, TOKEN_ENDPOINT),
since a database able to change those can
redirect the credential. Put them in the file or in a secrets.d fragment.
Likewise a domain: or address: override is accepted for a [stage-*]
section only (see above: nothing else reads those layers), and refused for any
other section rather than stored where nothing will read it.
Two further options are file-only for a plainer reason: they are read to open
the database itself, before an overlay can exist: [pepsi-ingress]
DB_POOL_SIZE and [pepsi-dispatch] DB_POOL_SIZE.
7.6.4. Hot reload, and what needs a restart¶
Every write to the table fires a config_changed notification. What happens
next depends on the section:
[stage-*]— applied without a restart.When the notification arrives,
pepsi-dispatchdoes two things. It rebuilds its own view of the pipeline from the overlay: which stages exist, and each one’sPROGRAM,PARALLELISM,MAX_MESSAGESandQUEUE_LIMIT. And it retires its stage workers, so that their replacements read the new values. No message is interrupted: a retired worker is given no further work and exits once its current messages are done. The next message is routed and run with the new configuration, which is what makes adding, editing and removing a stage take effect live. There is one hard edge: if the reloaded graph does not parse, the dispatcher shuts down and exits withEX_CONFIG, rather than route by a pipeline that its workers no longer share. The shipped unit restarts it (Restart=always, backing off to once a minute), so it resumes on its own once the configuration is fixed. An overlay that cannot be read (a database error) is different: the dispatcher keeps its current stage graph and retries the reload, rather than dropping every stage defined only in the database.- Everything else — needs a restart of the component that reads it.
[pepsi-ingress],[pepsi-srs],[pepsi-tlsrpt]and the rest are read once at start-up. The value is stored, and takes effect when that program is next started.pepsi-configsays which applies after every write.
An edit to the configuration file takes the same path for the pipeline:
pepsi-dispatch looks at the file’s modification time and size every two
seconds. When they change, it re-reads the file, rebuilds its stage table and
retires its workers, so a security setting changed there applies to the
messages handed out a few seconds later
(Clients silently send mail unencrypted). A file that does not parse changes
nothing: the running configuration is kept and the error logged.
[pepsi-dispatch]’s own options, and every section the other services read,
still need that service restarted.
If a component misses a notification because its listener was disconnected, it re-reads the overlay when the listener reconnects. A lost notification thus costs latency, not correctness.
7.6.5. Secrets stay in files¶
The database stores only the @inline-secret@ reference, never a secret
value, so each fragment under secrets.d stays owned by the single reader that
needs it: an unprivileged stage can read its own secret and nothing else.
Encrypted values in the database would hand every reader one key that opens
everything.
7.6.6. Editing the overlay¶
pepsi-config set stage-relay MAX_LIFETIME '48 h'
pepsi-config set --scope domain:example.org stage-relay DELAY_DSN_AFTER '4 h'
pepsi-config unset stage-relay MAX_LIFETIME
pepsi-config list
Every write is validated first: Pepsi builds the configuration that the change would produce and runs the owning stage’s real parser over it. This is the same check that pepsi-stage-edit-settings applies to an override sent by e-mail. A value that would stop a program from starting is refused with that program’s own error message, and nothing is stored.
Should a bad row reach the table anyway, what happens depends on how bad it is.
A row that cannot be represented in the configuration (an unknown scope, a
file-only section, a malformed name) is logged loudly and skipped; an overlay
that cannot be read at all, or whose merged text does not parse, is logged and
the program runs on the configuration file alone. A value that is well-formed
but rejected by the program itself, such as an unparseable duration or a
NEXT_STAGE that names no stage, is not skipped: it is part of the effective configuration, and the program fails on it exactly
as it would on the same value in the file. pepsi-setup run checks for both
(see Validating).
7.6.7. Where a value came from¶
pepsi-config dump --origin
pepsi-config dump --origin --scope address:user@example.org
annotates every effective value with the layer that set it (file, or the
database scope), and each section with whether a change to it is applied live or
needs a restart.
7.6.8. Backing it up¶
The two halves are backed up by different tools, on purpose:
the overrides, which are in the database, are covered by
pg_dumpalong with the rest of the schema;the configuration file and the
secrets.dfragments cannot be in the database, because they must exist before a database connection does. They are covered bypepsi-config export, which writes a single password-encrypted archive. Its key is derived with salted Argon2id (Offline guessing of weak password hashes, key passphrases and derived keys) from a password of at least 12 characters that is not on the list of common passwords.
The archive records each file’s mode, owner and group by name, and
pepsi-config import restores them; it refuses rather than guesses when a
named account does not exist on the target machine. An archive that lost
ownership would either break every unprivileged reader or silently make a secret
world-readable.
7.7. Validating¶
Always validate a configuration before relying on it:
pepsi-setup -c /etc/pepsi/pepsi.conf check # against live DNS
pepsi-config -c /etc/pepsi/pepsi.conf dump # effective values
pepsi-setup run refuses to change anything if the configuration is invalid:
it checks that [stage-init] exists, that every NEXT_STAGE/BOUNCE_STAGE
resolves, that each stage’s PROGRAM configuration parses, and that domains and
PUBLIC_IP values are well-formed.
It validates the database overlay too: a stored override must name a real scope,
must not name a file-only section (which would be silently ignored), must not put
anything but a [stage-*] section in a domain: or address: scope, and
must name a stage section that exists, either in the file or defined by the
overlay itself, since the dispatcher loads a stage added with pepsi-config set
without a restart. The configuration it produces must then still satisfy every
affected stage’s own parser: the global layer over the file, and each
domain:/address: scope’s chain over that, each running the parsers of
the stages that it touches.