95.2.1. pepsi.conf

configuration file for the Pepsi pipeline

Manual section:

5

95.2.1.1.1. Name

pepsi.conf - configuration file shared by all Pepsi components.

95.2.1.1.2. Description

Every Pepsi component — pepsi-ingress(1), pepsi-dispatch(1), every pepsi-stage-* program, pepsi-httpd(1), pepsi-queue(1), pepsi-tlsrpt(1), pepsi-setup(1) and the rest — reads the same INI-style configuration file, conventionally pepsi.conf. The format is shared with the GNU Taler components that Pepsi builds upon.

Because there is one file, each setting is documented once, under the section that owns it. A component reads only the sections relevant to it: the shared [pepsi] and [pepsi-postgres] sections are read by everything; the [stage-<name>] pipeline sections are read by the dispatcher and the stage programs; component-specific sections ([pepsi-ingress], [pepsi-httpd], [pepsi-dispatch], [pepsi-payments], [pepsi-tlsrpt] …) by the component named.

An option that nothing reads is ignored, so a misspelt one silently takes its default; pepsi-setup(1) warns about every such option in a section it knows, naming the closest real option.

Renamed options. When a release renames an option, the old name keeps working for at least one more release: every program reads it under the new name and logs a warning saying so, and pepsi-setup(1) warns too. When both names are set, the new one wins. NEWS lists every rename.

95.2.1.1.3. File Format

A configuration file is a sequence of [SECTION] headers, each followed by OPTION = VALUE assignments:

[pepsi-ingress]
HOSTNAME = mail.example.org
ACCEPTED_DOMAINS = example.org example.com

Section and option names are case-insensitive and are conventionally written in upper case. Blank lines are ignored. A # or % at the start of a line introduces a comment. A value may be wrapped in double quotes to preserve leading or trailing whitespace.

95.2.1.1.3.1. Directives

@inline@ FILE

Include another configuration file, resolved relative to the current file.

@inline-matching@ GLOB

Include every file matching the shell glob GLOB.

@inline-secret@ SECTION FILE

Merge section SECTION from FILE (typically a mode-restricted file holding credentials) into the configuration. A file that cannot be read is ignored with a warning. This keeps secrets out of the world-readable main file.

A directive is a top-level line: like @inline@, it ends the section it appears in. Write it after the last option of the section that it feeds. An option placed below it belongs to no section, and the whole file then fails to load with expected section header or directive. pepsi-setup(1) always emits its directives last within a section for this reason:

[pepsi-srs]
SRS_DOMAIN = srs.example.net
MAX_AGE_DAYS = 21
@inline-secret@ pepsi-srs secrets.d/pepsi-ingress.secret

Because an unreadable fragment causes only a warning, an option that it should have supplied simply looks unset. Whatever needs the value then reports the permission problem, typically as “… is not configured”. Pepsi detects that case and says so explicitly, naming the fragment, its owner and mode; run pepsi-setup run as root to give each fragment to its reader account.

95.2.1.1.3.2. Value Substitution

Options read as paths undergo $-expansion: $VAR and ${VAR} are replaced with the value of VAR from the [PATHS] section or, failing that, the environment. The form ${VAR:-default} supplies a fallback. The [PATHS] section is pre-populated with the usual installation directories (PREFIX, BINDIR, DATADIR and so on).

95.2.1.1.3.3. Value Types

boolean

YES or NO (case-insensitive).

number

A decimal integer. A few options documented as such take a fractional value instead, and each says so where it is described (the ingress connection-rate options and the relay stages’ RETRY_FACTOR).

duration

A span such as 5 s or 2 h. See the caveat below.

path

A filesystem path subject to $-expansion as described above.

unix mode

A file permission written in octal, e.g. 660.

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 a span of a day or longer, write the equivalent in hours (120 h) or use an integer option where one is provided (e.g. [pepsi-srs] MAX_AGE_DAYS).

95.2.1.1.4. The Database Overlay

This file is the base layer. On top of it, every component reads a set of administrator-managed overrides from the pepsi.config_override table of the shared schema, so a deployment can be reconfigured without editing files and, for the stage sections, without a restart. With no rows in that table a deployment behaves exactly as this file says; deleting every override returns it to that state.

The scope chain, lowest precedence first:

  1. this file;

  2. database scope global;

  3. database scope domain:DOMAIN;

  4. database scope address:ADDRESS;

  5. the per-address pepsi.settings table (pepsi-settings(1)).

Higher layers override lower ones option by option, never section by section: an option that no layer mentions keeps the value written here. The address a domain:/address: scope is matched against is the envelope sender for a locally-originated message, otherwise each envelope recipient.

The last layer is a different table with a different write authority. pepsi.settings is written by account owners themselves, by e-mail, within the EDITABLE_STAGES allowlist; config_override defines the pipeline and is writable only through the pepsi-config PostgreSQL role. pepsi-setup(1) grants that role INSERT/UPDATE/DELETE on the table, revokes them from every service account, and verifies both against the live database after each install. A stage worker parses hostile mail all day long, so it must not be able to rewrite the configuration that defines its own stage.

95.2.1.1.4.1. Sections That Are Never Read From the Database

An override naming one of these is ignored at run time and refused at write time:

[pepsi], [pepsi-postgres], [PATHS]

Read before a database connection can exist – and [pepsi] additionally holds 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.

[pepsi-ingress-listener-*]

Listening sockets are bound at start-up, often under socket activation and before privileges are dropped.

[pepsi-secure-link]

Its PEPPER is the server-side secret that makes a stolen database useless. A database that could replace it could arrange for the next stored message to be one that an attacker can open. The other options of the section stay in the file with it.

[pepsi-admin]

Decides who may administer the server and how the administrative interface reaches the database. If the database could set it, anyone who can write the database could grant themselves access to 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 proof-of-origin key against which Pepsi checks a returning bounce or payment demand. A database that could replace one of them could arrange for the next wrapped key to be one that an attacker can open, or for a forged bounce to be relayed or paid. The other options of each section stay in the file with it.

[pepsi-wizard]

Not configuration at all, but pepsi-setup(1)’s record of the answers it was given, which the browser console stages as draft rows in this very table. Nothing reads it at run time, so the database never supplies it either.

Three further rules apply in every other section:

  • No credential is ever stored in the database. In every section, an option is refused at write time and ignored at run time when its name marks it as a credential, that is, when the name contains PASS (PASSWORD, PASSPHRASE, API_PASS), SECRET, TOKEN, CREDENTIAL, CLIENT_ID, PEPPER or SYSTEM_ID. (The same rule masks a value wherever a configuration is shown.) This includes the file that a credential is read from and the endpoint that it is sent to (SECRET_FILE, TOKEN_FILE, TOKEN_ENDPOINT), because a database that could set those could redirect the credential. Credentials live in this file or its secrets.d fragments, each readable only by the account that needs it.

  • No program is chosen by the database. HELPER, SCAN_HELPER, MAILBOX_HELPER and PIN_COMMAND name an executable, and a setgid stage or a setuid tool runs several of them. In every section, they are refused at write time and ignored at run time. A stage’s PROGRAM is accepted only as a bare pepsi-stage-* command (no path component), so a stage can still be added through the database but only ever runs an installed stage binary.

  • The domain: and address: scopes take [stage-*] sections only. Those layers are consulted by a stage, per message, for the section it is running; nothing reads any other section per domain or per address, so such an override is refused rather than stored and never read.

Consequently, to add a submission port or to change a listener’s TLS material, the database connection or the crypto policy, you edit this file and restart; no administrative interface can do it. [pepsi-ingress] DB_POOL_SIZE and [pepsi-dispatch] DB_POOL_SIZE are file-only for the same bootstrap reason: the pool must exist before the overlay can be read.

95.2.1.1.4.2. Hot Reload

Every write to the table fires a config_changed notification.

Every [stage-*] change is applied without a restart, in both halves of the pipeline, the dispatcher and the stage workers. On the notification, pepsi-dispatch(1) rebuilds its own stage table from the overlay and retires its stage workers, so that the replacements re-read the overlay. A stage may therefore be added, edited or removed while the pipeline runs, and an edited PROGRAM/PARALLELISM/MAX_MESSAGES/QUEUE_LIMIT takes effect. No message is interrupted: a worker is given no further work and its slot is dropped once its in-flight messages report back.

A reload never routes mail by a pipeline that the workers no longer share. A reloaded stage graph that does not parse ends the dispatcher (exit EX_CONFIG, through the ordinary shutdown, so nothing is stranded) rather than leaving the previous table in place.

Every other section is read once at start-up by the component that owns it and therefore needs that component restarted – including [pepsi-dispatch]’s own options, which are deliberately not reloaded. pepsi-config set prints which case applies.

An edit to this file reaches the pipeline the same way: pepsi-dispatch(1) checks the file’s modification time and size every two seconds and, when they change, re-reads it, rebuilds its stage table and retires its workers. A file that does not parse is not applied; the dispatcher logs the error and keeps the configuration it has.

A component that misses a notification re-reads the overlay when its database listener reconnects, so a lost notification costs latency, not correctness.

Secrets are never stored in the database: the overlay refuses a credential (see above), and the @inline-secret@ reference lives in this file. Each fragment stays owned by the single reader that needs it.

A broken value in the database cannot stop a program from starting: an overlay that cannot be read or does not produce a usable configuration is logged loudly and this file is used unchanged.

See pepsi-config(1) for set/unset/list, for dump --origin (which annotates every effective value with the layer that it came from), and for the encrypted export/import of this file and its secrets.d fragments.

95.2.1.1.5. The [pepsi] Section

Cross-cutting identity and policy settings shared across the Pepsi tools. This section is never read from the database overlay.

KEY_DIR = PATH

Directory that may hold per-domain DKIM key files left by an older installation (<domain>/dkim.rsa.key and <domain>/dkim.ed25519.key). Nothing signs with them: the DKIM and ARC keys belong to pepsi-dkim(1). Once that daemon answers, pepsi-setup run deletes those files and lists their selectors (<DKIM_SELECTOR> and <DKIM_SELECTOR>-ed25519) as records that can be removed from DNS. Optional; defaults to /var/pepsi/keys.

DKIM_SELECTOR = NAME

Prefix of the DKIM selectors that pepsi-dkim(1) gives its keys: each generation of keys of a domain is published at <NAME>-YYYYMM._domainkey.<domain> (RSA) and <NAME>-YYYYMM-ed25519._domainkey.<domain> (Ed25519), where YYYYMM is the month in which the keys were made (with a letter appended when that name is taken). Optional; defaults to pepsi.

DKIM_ALGORITHMS = LIST

The DKIM signatures that pepsi-stage-dkim-sign(1) adds: a whitespace- or comma-separated list of rsa and ed25519. Optional; defaults to both. Gmail, Microsoft 365 and Yahoo do not verify Ed25519 (RFC 8463) signatures; they ignore them, and Google’s DMARC aggregate reports list the Ed25519 selector as fail. That is harmless — DMARC needs one aligned pass and the RSA signature supplies it — but rsa alone removes the noise. Leaving out rsa is permitted and warned about by pepsi-setup(1): those receivers would then see no verifiable signature at all. pepsi-setup publishes and checks only the selectors in use (plus the one that the ARC seal needs when this is the ARC_DOMAIN), and pepsi-dkim(1) makes keys only for them.

ARC_DOMAIN = DOMAIN

Domain whose identity pepsi-stage-arc(1) uses to ARC-seal inbound mail (RFC 8617). The seal is made with this domain’s DKIM key of ARC_ALGORITHM. pepsi-setup(1) therefore adds the domain to the signing domains that it hands to pepsi-dkim(1), which makes that key for it, and to the DKIM DNS records that it prints; ARC needs no separate record. Optional; if unset, authentication results are recorded but not sealed.

ARC_ALGORITHM = rsa | ed25519

Algorithm that signs the single ARC seal (ARC permits only one per hop, unlike DKIM, which by default is signed with both — see DKIM_ALGORITHMS). Optional; defaults to rsa for the widest interoperability.

ORIGINATE_SUCCESS_DSN = yes | no

Whether Pepsi may originate a positive (Action: delivered) delivery-status notification when a delivery succeeds and the sender requested NOTIFY=SUCCESS. Optional; defaults to no — Pepsi normally emits only failure bounces. When yes, the delivery stages (pepsi-stage-relay-to-internet(1), pepsi-stage-relay-to-smarthost(1), pepsi-stage-relay-to-maildir(1), pepsi-stage-relay-to-lmtp(1)) and pepsi-stage-discard(1) route a successful delivery to their BOUNCE_STAGE (for LMTP, its NOTIFY_STAGE) to emit the report.

It governs SUCCESS reports only. DELAY reports have their own, per-stage switch (a delivery stage’s DELAY_DSN_AFTER, unset by default) and FAILURE bounces need no switch at all – they are the default when a recipient’s NOTIFY says nothing. SUCCESS and DELAY alike are emitted only when the sender’s NOTIFY asked for them by name; neither has an implicit default.

MAILBOX_QUOTA = SIZE

Default limit on how much mail a local account may hold, applied by pepsi-stage-relay-to-maildir(1). A plain byte count or a K/M/G/ T suffix in powers of 1024 (2G, 500M, 1048576), or none. Optional; defaults to none — no quota. A single account’s limit is set with pepsi-quota(1) set, which overrides this; the kernel’s own limit tightens whichever applies.

The quota covers the whole Maildir++ tree — the INBOX plus every folder (.Sent, .Trash, …) — because that is what the user calls their mailbox, and counting only the INBOX would let anyone keep unlimited mail in another folder, one drag-and-drop away from it.

MAILBOX_QUOTA_COUNT = N

Default limit on the number of messages that an account may hold; 0 or absent for none. A very large number of very small messages is a denial of service against a mailbox in its own right, and a byte limit alone does not prevent it.

MAILBOX_OVER_QUOTA = defer | bounce

What happens to a recipient whose mailbox is full. Optional; defaults to defer.

defer keeps the message queued and retries it until the delivery stage’s MAX_LIFETIME, then bounces, which gives the account time to make room. bounce refuses at once with an RFC 3463 5.2.2, routing the recipient to the delivery stage’s QUOTA_LIMIT_STAGE (else its BOUNCE_STAGE), so the sender is not left waiting for days. A kernel EDQUOT counts as a full mailbox and gets the same treatment. At delivery time this governs pepsi-stage-relay-to-maildir(1) only; pepsi-stage-relay-to-lmtp(1) routes the MDA’s own x.2.2 refusal to its QUOTA_LIMIT_STAGE, whatever this option says.

The same choice decides the reply that pepsi-ingress(1) gives when it refuses an over-quota recipient at RCPT: 452 4.2.2 for defer, 552 5.2.2 for bounce.

MAILBOX_QUOTA_MAX_AGE = DURATION

How long a mailbox measurement may be trusted for a RCPT-time refusal. Optional; defaults to 15 m. Units are h/m/s.

pepsi-ingress(1) refuses an over-quota recipient only on a measurement younger than this, and never on the running usage estimate. That is a correctness bound, not a performance one: the estimate only ever grows (nothing tells Pepsi when a user deletes mail over IMAP), so refusing on it would close a mailbox whose owner has since emptied it. It would stay closed for good, because with every message refused, no delivery would run to measure the mailbox again. This bound and pepsi-quota(1) reconcile keep that from happening.

MAILBOX_QUOTA_RCPT_CHECK = yes | no

Whether pepsi-ingress(1) consults the quota table at RCPT time. Optional; defaults to yes. Refusing there costs one indexed lookup and saves a bounce: the sending MTA is still on the line, so it tells its user, and Pepsi generates no backscatter to an envelope sender that may well be forged. Turning it off moves all enforcement to delivery time.

MAILBOX_HELPER = PATH

The privileged helper that pepsi-quota(1) runs to measure a mailbox — for its measure subcommand and its reconcile sweep. Optional; defaults to pepsi-helper-maildir-writer, resolved on the invoking process’s PATH.

It is the same binary that the local-delivery stage uses, invoked in its measure mode: a Maildir is 0700, so this is the one process that can become the user and read it. Set this only when the helper is not on pepsi-quota’s PATH under its name — chiefly a --prefix-ed source install. Keep it in step with the delivery stage’s own HELPER option in its [stage-<name>] section (see pepsi-stage-relay-to-maildir(1)): the two name the same program for two callers, and only the stage’s is per-stage. Like every option that names a program, it cannot be set from the database overlay.

MAILBOX_FS_QUOTA = yes | no

Whether the filesystem holding home directories enforces kernel disk quotas, in which case Pepsi consults quotactl(2) as well and lets the kernel’s limit tighten the effective one. Optional; defaults to no.

Normally set for you. This is a fact about the host’s mounts, not a preference, so pepsi-setup(1) probes for it and records the answer without asking. An explicit value is never overwritten. Have it on where it applies: the kernel’s accounting is the only layer of the three that the account owner cannot tamper with (the Maildir++ maildirsize file lives in their own directory), and it counts everything they own on that filesystem rather than only their mail.

RECIPIENT_DELIMITER = CHARACTER | none

The site-wide sub-address separator (alice+lists is account alice). Optional; defaults to +. A [stage-<name>] section may override it for its own delivery decisions, but prefer setting it here. pepsi-ingress(1) uses this value to work out which mailbox quota applies to a recipient, and it has no stage section to read. If a stage uses a different delimiter, sub-addressed mail therefore escapes the RCPT-time refusal; pepsi-setup(1) warns when a stage does so.

Mailing lists use this value, and only this one, for every sub-address they write and read: the VERP envelope sender of each copy (announce-bounces+alice=example.net=<code>@…), a bounce probe’s sender, the -confirm+token address, and pepsi-stage-list(1)’s router that recognises them when they come back. none leaves lists on +, since a VERP sender cannot be written without a delimiter.

MAX_QUEUE_ROWS = N | none

Queue admission control: the largest number of messages (pepsi.workqueue rows) that the queue may hold before pepsi-ingress(1) stops accepting mail. Optional; defaults to 1000000; none (or 0) for no limit. A row is one recipient group, so a mailing-list fan-out multiplies this figure, and so does a relay stage that splits a message into one row per recipient.

At the limit, pepsi-ingress(1) answers 452 4.3.1 at RCPT, at DATA/the first BDAT chunk, and after the end of data. That is a temporary refusal: the sending MTA keeps the message and retries, while the queue that is already there drains. pepsi-stage-list-post(1) holds a fan-out back for QUEUE_THROTTLE_DELAY instead of emitting its next batch. Nothing already queued is affected: bounces, DSNs and auto-replies that the pipeline itself originates are never refused.

MAX_QUEUE_BYTES = SIZE | none

The largest number of octets that the queue may hold: every queued header block plus every queued body, each body counted once however many recipient rows share it (it is stored once — see STORED DATA below). A plain byte count or a K/M/G/T suffix as for MAILBOX_QUOTA. Optional; defaults to none. After the end of data the check includes the size of the message being offered, so one oversized message is refused on its own merits. Refusals are as for MAX_QUEUE_ROWS.

MIN_FREE_SPACE = SIZE | none

The free space that must remain on the filesystem holding FREE_SPACE_PATH for mail to be accepted; a message is refused when accepting it would leave less. Optional; defaults to 1G; none disables the probe. This limit also sees what is not the queue, such as the write-ahead log, other databases and logs. That matters because PostgreSQL does not degrade when its filesystem fills: it stops, and every stage, the console and the submission socket stop with it. Refusals are as for MAX_QUEUE_ROWS.

FREE_SPACE_PATH = PATH

Where MIN_FREE_SPACE is measured (statvfs(3), the space available to an unprivileged writer). Optional; defaults to /var/lib/postgresql, the parent of the Debian clusters’ data directories – a data directory itself is 0700 postgres, but statvfs needs only to reach a path, and its parent lies on the same filesystem in a default layout. Set it to the data directory (or its mount point) when PostgreSQL keeps its data elsewhere. When the database is on another host the default path usually does not exist and the probe is silently off; a path set here that cannot be probed is logged once, and the limit is then not enforced.

QUEUE_CHECK_INTERVAL = DURATION

How long a measurement of the queue is reused. Optional; defaults to 10 s. Measuring is two sequential scans (the pepsi.queue_usage() function), so each process takes at most one per interval and every RCPT in between is answered from the cached figure; the limits are therefore approximate by up to one interval’s worth of admissions. When a measurement fails, Pepsi logs it and admits mail: a brief database problem must not become an outage of its own, and Pepsi still answers 451 when it genuinely cannot store a message.

QUEUE_THROTTLE_DELAY = DURATION

How long pepsi-stage-list-post(1) holds back a fan-out after finding the queue full, before it looks again. Optional; defaults to 60 s.

CT_CHECK = warn | off

Whether the TLS clients check Certificate Transparency: the Signed Certificate Timestamps (SCTs) embedded in a server certificate that chains to the system roots. This covers MTA-STS and verified smarthost delivery, the DANE stage’s PKIX fallback, and the WKD/VKS fetches of key discovery (including those under [pepsi-keydiscovery] TLS_CA_BUNDLE). A certificate passes with at least two valid SCTs (three if it is valid for more than 180 days) from logs of two different operators. Optional; defaults to warn.

warn logs a warning for a certificate that does not pass and connects all the same: a certificate that a CA issued without logging it shows up in Pepsi’s own log, but the check cannot stop mail. There is deliberately no mode that refuses. A connection verified against TLS_CA or a smarthost’s TLS_CA_BUNDLE (an operator’s private CA, whose certificates are not logged) is never checked. off checks nothing.

CT_LOG_LIST = PATH

The list of Certificate Transparency logs against which the SCTs are checked, in the JSON format of Google’s v3 log list. pepsi-keys(1) ct-logs update, run daily by pepsi-keys-ct-logs.timer, keeps it current. The file is public and must be readable by every Pepsi program. Without it, or when its log_list_timestamp is more than 70 days old, nothing is checked (logged at debug level). Optional; defaults to /var/lib/pepsi/ct-log-list.json.

CT_LOG_LIST_URL = URL

Where pepsi-keys ct-logs update fetches the list from. Optional; defaults to https://www.gstatic.com/ct/log_list/v3/log_list.json. An operator may point it at a mirror; a list older than the one in place is refused unless --force is given.

DNS_SERVERS = LIST

The resolvers for every program that makes DNS lookups and whose own section names none: the DNS_SERVERS of pepsi-ingress(1), pepsi-stage-arc(1) and both relay stages, and the lookups that have no option of their own (DANE key discovery, pepsi-tlsrpt(1), pepsi-reputation(1) check, pepsi-setup(1), pepsi-status(1)). Optional; when unset, /etc/resolv.conf is used.

Entries are separated by white space or commas, each one of:

  • an IP address (IPv4 or IPv6): plain DNS on port 53, UDP and then TCP when a reply is truncated;

  • tls://ADDRESS[:PORT]#NAME: DNS over TLS (RFC 7858), port 853 by default;

  • https://ADDRESS[:PORT][/PATH]#NAME: DNS over HTTPS (RFC 8484), an HTTP/2 POST to PATH (default /dns-query), port 443 by default.

An IPv6 ADDRESS is written in brackets in the two URL forms (tls://[2001:db8::53]#dns.example.net). The address is required, so no lookup is needed to reach the resolver, and so is NAME: the resolver’s certificate must be valid for it and chain to the system roots. One list holds either plain or encrypted entries, never both (a failing encrypted resolver would otherwise fall back to plain DNS), and there is no fallback to plain DNS when the encrypted resolvers cannot be reached: the lookup fails as a temporary failure. A list that does not parse makes the stages that read it refuse to start and every lookup that would use it fail.

An encrypted entry protects the path to the resolver, so Pepsi trusts the DNSSEC AD bit from a resolver reached over it, as it does for a resolver on loopback (see pepsi-stage-relay-to-internet(1), DANE). The resolver must still validate DNSSEC itself.

DNS_TIMEOUT = DURATION

The DNS timeout per query for every program whose own section sets no DNS_TIMEOUT. Optional; each program’s own default applies when unset (5 s for most). Like a section’s DNS_TIMEOUT, it bounds a query only where the resolvers come from a DNS_SERVERS list; with /etc/resolv.conf the system’s options timeout: applies.

MAIL_LOG = off | summary | full

Whether to keep a per-message record. Optional; defaults to off.

Pepsi deletes a message’s row when the pipeline is finished with it, so there is normally no per-message success log: an ordinary deployment does not accumulate a record of its users’ correspondence, and cannot be compelled to produce one that it does not have.

Setting this option changes that. summary writes one pepsi.mail_log row as a message leaves the pipeline, carrying the envelope sender and recipients, the direction (outbound for locally-submitted mail, inbound otherwise), the stage at which it ended, the outcome (completed/failed) and what the pipeline decided about it (a closed list of state keys: the authentication verdict, the spam and paid decisions, any next-hop failure detail, and the cryptography and language findings). full additionally records the Subject: line. Message content is never recorded at any setting.

Warning

Turning this on means the deployment keeps a record of who corresponds with whom. Some deployments genuinely need that evidence; make sure yours is one of them, and that keeping it is lawful where you operate.

Rows are readable through GET /api/v1/mail-log by a principal holding logs:read, are append-only for every component that processes mail, and are pruned after [pepsi-admin] MAIL_LOG_RETENTION_DAYS days. The row is written by the same statement that removes the message or marks it failed, so enabling the log costs no extra database round-trip. See the manual’s “The administrative API” chapter.

ALLOW_FUSION = yes | no

Whether stage fusion is permitted. A stage fuses with the successor that it advances to when the successor is marked FUSION = yes (see the per-stage option below), its PROGRAM is folded into the same unified pepsi binary, and it needs no message column that the predecessor has not already loaded. The predecessor then runs the successor’s body in its own worker process. This skips both the advancing UPDATE and the successor’s loading SELECT, and the dispatcher receives a single completion for the whole fused chain. Optional; defaults to yes. Set it to no to force every stage transition back through the database and the dispatcher (the benchmark of the cost of each stage does this, so that each stage is measured as its own dispatched worker). Fusion never happens in a per-program (multibin) build, where a successor is always a separate process. See pepsi-dispatch(1) for the full model.

REFLECTION_HOLD_MAX

(duration, optional) The longest random hold on reflected mail — a DSN written by pepsi-stage-bounce(1), a copy that an alias (pepsi-stage-aliases(1)) or a ~/.forward (pepsi-stage-dot-forward(1)) resends, a mailing list’s fan-out (pepsi-stage-list-post(1)). Each such message is held, before the next stage sees it, for a time drawn afresh and uniformly from zero to this value: the producing stage hands it on paused with that timeout instead of pending, and the dispatcher’s paused-retry sweep releases it. If reflected mail left after the pipeline’s own, predictable latency, whoever sent the original could time it so that the reflections from many hosts reach one victim in a single pulse. Spreading the reflections of each host over a random window flattens that pulse. Defaults to 30 s; 0 s disables the hold; at most 10 m (s/m units). Automatic replies (the vacation notice, a payment request, a challenge) are not held — they are rate-limited per sender instead.

MTA_STS_MODE = enforce | testing | none

Mode of the MTA-STS policy published for our domains. enforce and testing cause pepsi-setup(1) to emit a _mta-sts.<domain> TXT record (and pepsi-httpd(1) to serve the corresponding policy file); none disables MTA-STS publishing. Optional; defaults to enforce. MTA_STS_MX sets which hosts the policy permits.

MTA_STS_MX = ENTRY[, ENTRY…]

The hosts published as mx: lines in the MTA-STS policy, that is, every MX that a sender may deliver to (RFC 8461 §3.2: mx “must appear at least once and may appear more than once”). Each ENTRY is either

HOST

a host pattern applying to every served domain, or

DOMAIN:HOST

a host pattern applying to that one served domain.

A domain’s mx set is the unqualified entries plus the entries qualified with its own name; qualified entries add to the shared set rather than replacing it, so a site whose domains share a primary MX writes it once and cannot lose it by qualifying one domain’s backup. A host pattern may use a single leading-label wildcard (*.example.net), and : is unambiguous as the separator because a hostname cannot contain one.

The policy is therefore per domain, which is what a host serving several domains needs: each domain’s MX records name its own hosts, and there is no reason for those hosts to agree. Each domain’s policy gets its own id in its own _mta-sts.<domain> TXT record, so senders cache them independently:

MTA_STS_MX = example.org:mx.example.org, example.net:mail.example.net

Optional. When the option is absent entirely, every domain’s policy names the [pepsi-ingress] HOSTNAME. That fallback is a last resort, not a good default: HOSTNAME is the EHLO greeting name, which need not be a name that any MX record points at. When it is not, an enforce policy tells every compliant sender not to deliver to the domain at all. So set this option to the hosts your MX records actually name. The pepsi-setup(1) wizard reads them out of DNS and writes the option for you, and every pepsi-setup run re-checks the resolved set against live MX records and prints the option to set when they disagree (see pepsi-setup(1), MTA-STS cross-checks).

Under the default enforce mode a policy that omits a host tells every compliant sender that it must not deliver there, so a backup MX left out of this list receives no mail while the primary is down.

Each host named must also present a TLS certificate valid for its own name (RFC 8461 §4.1), and pepsi-setup(1) provisions that: the hosts listed here become Subject Alternative Names on the ingress listeners’ certificate, which is expanded through certbot on the next pepsi-setup run if it does not cover them yet. Pepsi uses one certificate rather than one per host, because pepsi-ingress(1) serves a single certificate per listener and does not select on SNI. A wildcard entry is the exception: HTTP-01 cannot obtain one, so that certificate has to be supplied with TLS_CERT/TLS_KEY.

MTA_STS_MAX_AGE = SECONDS

The max_age published in the MTA-STS policy (how long senders may cache it). Optional; defaults to 604800 (one week). RFC 8461 §3.2 bounds it to 1..``31557600``, and a value outside that is refused – in particular 0, which would publish an immediately-expiring policy and so disable MTA-STS while looking like it was configured.

TEMPLATE_DIR = PATH

Directory holding message templates (<name>.<lang>.body) expanded at runtime — for example the pepsi-stage-anti-spam(1) payment-request reply and the pepsi-stage-bounce(1) BOUNCE_MESSAGE body. Optional; defaults to ${DATADIR}/templates, where make install places the bundled templates. ${DATADIR} is resolved from the install prefix of the running binary, so the default is /usr/share/pepsi/templates for a --prefix=/usr installation and follows the prefix for any other; set this option only if the templates live somewhere that the prefix does not imply.

LOG_JSON = yes | no

Emit logs as structured JSON lines (one JSON object per record) on standard error instead of the default human-readable text format, so a log aggregator such as Loki can ingest them without extra parsing. Applies to every Pepsi binary except pepsi-setup(1), which sets up logging before it loads a configuration. Optional; defaults to no (text). The -L/--log log-level option and -v/--verbose apply in both formats.

LOG = error | warn | info | debug | trace

Default maximum log level for every Pepsi binary. All components load this same configuration, including the stage workers that the dispatcher spawns, which receive no command-line log flag of their own. This option is therefore the single setting that lowers or raises logging across the whole pipeline at once; the benchmark scripts, for instance, set it to warn so that per-message logging does not skew their measurements. Optional; defaults to info. The -L/--log flag, when given, overrides it for that one process. pepsi-setup(1) ignores this option, since it sets up logging before it loads a configuration; pass -L there.

PUBLIC_RESOLVERS = IP … | none

The public recursive resolvers through which pepsi-setup(1) re-checks, as the Internet sees them, the DNS records that this host depends on: the reverse DNS of every PUBLIC_IP, each served domain’s MX and TXT records, and the ingress HOSTNAME’s addresses (see DNS as the Internet sees it in pepsi-setup(1)). A list of IP addresses separated by spaces or commas. Optional; defaults to Google (8.8.8.8, 2001:4860:4860::8888), Cloudflare (1.1.1.1, 2606:4700:4700::1111) and Quad9 (9.9.9.9, 2620:fe::fe). none disables the check.

The check exists because a lookup from this host cannot tell when a zone is reachable only from this host’s network: a nameserver behind NAT whose port 53 is not forwarded looks healthy from inside. The names that the check sends to these resolvers are names that this host publishes for anybody to query; set none anyway if you prefer that no third-party resolver be asked, and verify from a machine outside your network instead. Read only by pepsi-setup.

SHARE_TELEMETRY = yes | no

Whether this deployment shares anonymous feature-usage telemetry with the Pepsi project. Opt-in: optional, and defaults to no, so an installation that never sets it shares nothing. When set to yes, pepsi-setup(1) generates a random SYSTEM_ID (below) and the pepsi-telemetry-client(1) daemon aggregates feature-usage events from the stage workers and pepsi-ingress(1) and submits per-feature counts to TELEMETRY_SERVER under that anonymous id (no addresses, message data, host names or IP addresses). Left at no, a running daemon stays dormant (no socket, nothing submitted), no SYSTEM_ID is generated, and the in-process telemetry calls are no-ops that open no socket. An unparseable value is read as no. Whoever changes this option in the file notifies the daemon (telemetry_changed); the daemon also re-reads the file every minute. The browser setup console can switch it on only while the daemon is running with a SYSTEM_ID.

SYSTEM_ID = 64-HEX

Anonymous 256-bit identifier (64 hexadecimal characters) submitted with every telemetry report. Generated and written here by pepsi-setup(1) only once SHARE_TELEMETRY has been turned on, so a deployment that has not opted in never gets one. Required by pepsi-telemetry-client(1). An operator may add one by hand while telemetry is off, which is what lets the browser console offer to switch telemetry on; a console save keeps it. Do not reuse it across deployments.

TELEMETRY_SERVER = HOST | URL

The central telemetry collector. Optional; defaults to telemetry.pepsi.taler.net. pepsi-telemetry-client(1) submits to https://<server>/telemetry/{usage,features}; a value containing an explicit scheme:// is honoured verbatim (e.g. http://localhost:18080 for local testing).

The following CRYPTO_* options govern end-to-end message cryptography (OpenPGP and S/MIME) — not the DKIM/ARC keys above. They are deliberately system-administrator settings and live in [pepsi] rather than in a [stage-*] section, which puts them structurally out of reach of the per-address override layer (pepsi.settings overrides only stage sections) and therefore of pepsi-stage-edit-settings(1): algorithm selection, downgrade permission, weak-digest acceptance and minimum key sizes are security decisions with a secure default, not per-user preferences. Every one is optional; a deployment that does no end-to-end cryptography can ignore them all. The key store that holds those keys is configured in [pepsi-crypto] (below) and managed with pepsi-keys(1).

CRYPTO_ALLOW_DOWNGRADE = no | negotiate | yes

Whether Pepsi may emit a downgraded container (S/MIME AES-256-CBC EnvelopedData, OpenPGP SEIPDv1-with-MDC) and accept 3DES on decryption. Optional; defaults to negotiate, which downgrades per recipient and only when that recipient can do no better. That matters, because much of the installed base cannot read an RFC 9580 AEAD message at all. Reading SEIPDv1 and AES-CBC is always permitted and is not gated by this option.

For OpenPGP the recipient’s own certificate says whether it reads SEIPDv2. For S/MIME, whose certificates advertise no content-encryption capability, the answer is the recipient’s S/MIME capability record: learnt from the RFC 8551 SMIMECapabilities attribute of the correspondent’s signed mail (by pepsi-stage-autocrypt-learn(1)), or configured with pepsi-keys peer capability set ADDRESS aead|cbc. Under negotiate only a recipient recorded as unable to read AES-256-GCM AuthEnvelopedData gets AES-256-CBC EnvelopedData; a recipient with no record gets AEAD. Thunderbird 140.12.0esr cannot read AuthEnvelopedData and fails silently — no error, an empty plaintext — so a Thunderbird user who has never sent a signed message needs a configured record. no refuses a recipient recorded as unable to read AEAD (the encrypt stage’s no-key policy decides); yes sends EnvelopedData to every S/MIME recipient whatever its record, for an operator who wants the global downgrade. The measurement is in pepsi-crypto/tests/thunderbird.rs; the client matrix is in the manual’s interoperability chapter.

yes does not coarsen OpenPGP: the encrypt stage requests the container auto, which both negotiate and yes resolve per recipient — AEAD for a certificate that advertises SEIPDv2, SEIPDv1+MDC only for one that does not. The difference between the two values is the S/MIME container and the acceptance of an inbound 3DES S/MIME message, which is never emitted under any setting. Inbound OpenPGP 3DES is accepted under negotiate as well as yes, and refused only under no: an OpenPGP certificate states its own cipher capabilities, so negotiate has something to negotiate with, whereas X.509 advertises none and therefore gets the stricter rule. Inbound OpenPGP Blowfish, the other 64-bit-block cipher, follows the 3DES rule exactly.

pepsi-setup does not write this option unless asked: the per-recipient default needs no line in pepsi.conf, so a deliberate setting is made by editing pepsi.conf by hand or with pepsi-setup --wizard --expert=CRYPTO_ALLOW_DOWNGRADE. It warns when the value is yes.

CRYPTO_ALLOW_WEAK_DIGESTS = yes | no

Accept SHA-1 signatures on verification. Optional; defaults to no. A signature under a weak digest is reported as such, never silently counted as valid. An ECDSA signature with SHA-1 is verified on P-256 only; on P-384 it is reported as unsupported whatever this option says. An MD5 signature is refused whatever this option says: MD5 collisions take seconds to compute, so such a signature says nothing about what was signed. pepsi-setup(1) warns when it is yes.

CRYPTO_MIN_RSA_BITS = BITS

Smallest RSA modulus accepted on inbound verification and outbound encryption. For S/MIME it applies to the leaf certificate and to every intermediate certificate of the chain, but not to a configured trust anchor. Optional; defaults to 2048. Values below 1024 are refused outright. When the floor is lowered, a key between it and 2047 bits is accepted for verifying a signature, logged as a warning, and pepsi-setup(1) warns about the lowered floor itself. Such a key still cannot be encrypted to, sign or decrypt, since AWS-LC, which does every RSA operation, takes 2048 to 8192 bits for those; and a SHA-384 signature by it is reported as unsupported, since AWS-LC verifies keys below 2048 bits with SHA-1, SHA-256 and SHA-512 only. Whatever the floor, an RSA key whose private key follows from its modulus (the ROCA fingerprint, or primes close enough for Fermat’s method) is refused like a key below it, and so is a key of any type on the known-compromised list (pepsi.compromised_key, see [pepsi-keydiscovery] BADKEYS_URL).

CRYPTO_GENERATE_RSA_BITS = 2048 | 3072 | 4096 | 8192

Modulus size used when this deployment generates an RSA key. Optional; defaults to 2048. These are the four sizes that AWS-LC generates, in constant time; any other value is refused when the configuration is read (by pepsi-setup, pepsi-keys and the crypto stages alike), because a key of another size would have to come from a key generator that is not constant time. It may not be below CRYPTO_MIN_RSA_BITS, because a deployment must not generate keys that it then refuses to accept. OpenPGP key generation accepts only 2048, 3072 or 4096. Every later use of the private key (signing, decryption) is AWS-LC’s too.

CRYPTO_INLINE_PGP = accept | reject

How to treat inline (non-MIME) PGP. Optional; defaults to accept, because real senders still emit it. Pepsi never generates it.

CRYPTO_OPENPGP_ALGORITHM = ed25519 | rsa

Algorithm used when generating a new OpenPGP identity. Optional; defaults to ed25519 — generation is instantaneous, which matters because an identity may have to be created while a message waits. rsa uses CRYPTO_GENERATE_RSA_BITS.

CRYPTO_SMIME_ALGORITHM = p256 | p384 | rsa

Algorithm used when generating a new S/MIME identity. Optional; defaults to p256, ECDSA/ECDH over NIST P-256; p384 is the same over P-384, and rsa is RSA at CRYPTO_GENERATE_RSA_BITS.

The choice decides how inbound S/MIME reaches our private key, which is why the default is a curve. Mail to an EC identity arrives as ECDH key agreement (KeyAgreeRecipientInfo) and never reaches an RSA private-key operation on a ciphertext the sender chose; the key agreement, ECDSA signatures and key generation are AWS-LC’s, in constant time, and generating the identity takes milliseconds. Mail to an RSA identity arrives as RSA key transport (PKCS#1 v1.5 or OAEP, as the sender chooses), which pepsi-stage-decrypt unwraps with AWS-LC’s constant-time, blinded RSA, with RFC 8017 implicit rejection and a randomised minimum duration; one branch on AWS-LC’s PKCS#1 v1.5 or OAEP decoding verdict remains, which its interface cannot avoid. AWS-LC accepts RSA keys of 2048 to 8192 bits. An RSA identity outside that range can neither decrypt nor sign, and is refused with a warning; Pepsi generates none, so in practice this is an imported key below 2048 bits under a lowered CRYPTO_MIN_RSA_BITS. RSA signatures, and the self-signatures of the certificates and requests Pepsi generates, are AWS-LC’s too.

Choose rsa for a site whose correspondents’ clients cannot encrypt to an elliptic-curve certificate, or when you want CRYPTO_SMIME_SHARED_KEY = yes, which is RSA only. OpenSSL 3.5 has been measured to encrypt to such a certificate; Thunderbird 140 has been measured only reading ECDH ciphertext, and Outlook and Apple Mail have not been measured at all (see the manual’s interoperability chapter). The option shapes newly generated identities only: an existing RSA identity, generated or imported, keeps signing and decrypting, since every lookup resolves by capability rather than by algorithm, and the remaining RSA caveats above still apply to it until a new identity supersedes it (pepsi-keys(1) identity generate makes the new material primary).

CRYPTO_SMIME_SHARED_KEY = yes | no

Issue one S/MIME certificate carrying both digitalSignature and keyEncipherment instead of a separate signing and encryption certificate. Optional; defaults to no.

The default splits them because a separate signing certificate can be destroyed at expiry or revocation — nothing legitimate ever re-signs old mail, so a retired signing key is only a forgery risk — while the decryption half is retained so that archived and in-flight ciphertext stays readable. Turning this on halves the number of certificates that an operator buys per identity, and gives up that separation: a shared key follows the decryption rule, so revoking a compromised signing key also ends the ability to receive new encrypted mail at that certificate.

The option decides only what newly created identities look like. Both shapes are supported permanently and may coexist for one address, so every lookup resolves by capability rather than by shape. Combined with an elliptic-curve CRYPTO_SMIME_ALGORITHM it is refused by pepsi-setup(1): using one EC key for both ECDSA and ECDH is cross-algorithm key reuse, which several S/MIME clients reject.

95.2.1.1.6. The [pepsi-postgres] Section

Shared database connection settings. Every Pepsi component connects to the same database and the shared pepsi schema, so these settings live in one section rather than being repeated per component.

Note

Connection budget. Each Pepsi process opens its own connection pool. The stage workers and the operator CLIs do their database work strictly serially, so each of them uses a single connection. The dispatcher runs up to one worker process per stage slot (the sum of the stages’ PARALLELISM), so this rule of one connection per worker keeps the bulk of the connection count predictable and minimal. The concurrent components keep a small bounded pool sized by their own DB_POOL_SIZE option: the pepsi-dispatch(1) coordinator (default 8, because it processes the results of many workers concurrently) and the pepsi-ingress(1) and pepsi-httpd(1) servers (default 1 each). When tuning, ensure Σ PARALLELISM (one connection per live worker) + the dispatcher pool + the two servers’ pools stays below the server’s max_connections. A stage’s QUEUE_LIMIT does not enter this budget: pipelining more messages onto a worker raises its in-flight count, not the number of worker processes (or connections), so it is the safe setting to raise for throughput when max_connections is the limiting factor.

CONFIG

(string, required) PostgreSQL connection string or URI, e.g. postgres:///pepsi. The server sets the schema search path to pepsi and uses READ COMMITTED transactions (at most one writer ever touches a given queue row, so serializable isolation is unnecessary).

This file is world-readable, so the string must not carry a password; every component refuses to start with one.

Local database (the canonical setup). Each component connects over the UNIX socket as the role named after its own system account (pepsi, pepsi-ingress, pepsi-httpd, pepsi-crypto, …) and PostgreSQL’s peer authentication checks the uid. No password exists anywhere, and the database grants of each role are the privilege boundary between the components.

Remote database (recommended setup). Keep the same model: one role per account, each with credentials of its own that no other account can read. When a component connects, the placeholder {role} in the connection string is replaced by the role that it connects as, so one string names a different file for every role. With client certificates (the database’s pg_hba.conf using cert):

CONFIG = postgres://db.example.org/pepsi?sslmode=verify-full&sslcert=/etc/pepsi/postgres/{role}.crt&sslkey=/etc/pepsi/postgres/{role}.key

or with passwords, one libpq password file (.pgpass format, e.g. the single line *:*:*:*:<password>) per role:

CONFIG = postgres://db.example.org/pepsi?sslmode=verify-full&passfile=/etc/pepsi/postgres/{role}.pgpass

sslmode=verify-full checks the server certificate against the system root store, as every other TLS connection of Pepsi does (SSL_CERT_FILE and SSL_CERT_DIR replace the store), so a certificate from a local CA verifies once that CA is installed there (on Debian: a file in /usr/local/share/ca-certificates and update-ca-certificates). Unlike libpq, sslrootcert=FILE adds the CA certificates of FILE to the system store rather than replacing it.

Each key or password file belongs to its role’s account and has mode 0600 or 0400; a password file that anybody else can read is refused, as libpq refuses it, and pepsi-setup run reports every role whose account exists on the host but whose file is missing, owned by another account or open to others. Leave the user name out of the string (or write {role} there): each component supplies its own. Because the file is read when the connection is opened, by the account that opens it, a setuid stage such as pepsi-stage-encrypt reads the pepsi-crypto file, which the dispatcher that started it cannot read. The string itself then holds no secret and stays in this file.

Environment override. The environment variable PEPSI_POSTGRES_CONFIG, when set and not empty, replaces this option and may carry a password. Every shipped systemd unit reads it from EnvironmentFile=-/etc/pepsi/postgres.env (the leading - makes the file optional; keep it root-owned 0600, since systemd reads it as root before starting the service). The setuid and setgid programs keep the variable only when root or the pepsi dispatcher account started them, so the stages reach the dispatcher’s database while an ordinary user cannot point a privileged program at another one. A password in it is one password for every role, which gives up the separation between the components; prefer the per-role files above and use the variable for what differs between hosts. When it is set, CONFIG may be omitted; a password in CONFIG is refused even then. A tool run from a shell (pepsi-setup run, pepsi-queue, …) needs the variable exported the same way, e.g. set -a; . /etc/pepsi/postgres.env; set +a.

SQL_DIR

(path, optional) Directory containing the SQL migration files. Only pepsi-setup(1) reads this, when installing the schema; the serving components ignore it. Defaults to ${DATADIR}/sql (i.e. <install-prefix>/share/pepsi/sql, where make install places the files). Override it when running from a source checkout.

WORKER_SYNCHRONOUS_COMMIT

(boolean, optional) Whether a stage worker’s database connection keeps PostgreSQL’s synchronous_commit on. Defaults to no.

With it off, a worker’s COMMIT returns before the write-ahead log record has reached stable storage, which lets the pipeline’s writes group-commit instead of each paying its own flush. Nothing else changes: isolation, atomicity and visibility are unaffected, and a crash can never expose a partial transaction. What can be lost is the last few hundred milliseconds of durability — and only for stage transitions, never for message acceptance, because pepsi-ingress(1) always commits synchronously. A 250 still means the message is on disk.

If a machine crash loses a stage advance, the message is found still at the previous stage and runs through it a second time. Exactly the same happens when a worker is killed after doing its work but before committing. Set this to yes if a stage in your pipeline has side effects that must not be repeated even across a power loss, and accept the throughput cost.

95.2.1.1.7. The [pepsi-dkim] Section

Options for pepsi-dkim(1), the signing daemon that holds the DKIM and ARC private keys, rotates them and reports their DNS records. Its man page describes each option in full; here are the names and defaults. The section is read by the daemon, by pepsi-setup(1) (validate, run, check), by the signing stages (SOCKET only) and by pepsi-status(1) and pepsi-httpd(1) (PUBLIC_DIR only).

SOCKET = PATH

The signing socket. Default /run/pepsi-dkim/sign.sock.

STATE_DIR = PATH

The private keys and the daemon’s private state (mode 0700, owner pepsi-dkim). Default /var/lib/pepsi-dkim. Not backed up: after a restore the daemon makes fresh keys.

PUBLIC_DIR = PATH

The world-readable status document status.json and, with PUBLISH_RETIRED_KEYS, the published retired keys. Default /var/lib/pepsi-dkim-public.

RSA_BITS = 2048 | 3072 | 4096

Modulus size of each new RSA key. Default 2048.

ROTATION_DAYS = DAYS

How long a generation of keys signs before the next one takes over. Default 0: no automatic rotation (pepsi-dkim rotate still rotates on demand).

ROTATION_LEAD_DAYS = DAYS

How long before the switch the next generation is made, so that its records can be published. Default 28; must be shorter than ROTATION_DAYS.

RETIRE_AFTER_DAYS = DAYS

How long a replaced key’s record must stay in DNS before the key is retired. Default 14; at least 1, and it must exceed the SIGNATURE_EXPIRATION_DAYS of every pepsi-stage-dkim-sign(1) and pepsi-stage-arc(1) stage.

WAIT_FOR_DNS = yes | no

Whether a scheduled or requested switch waits until every authoritative server of the zone serves the next generation’s records. Default yes.

DNS_CHECK_INTERVAL = DURATION

How often each record is looked up at the authoritative servers. Default 1 h; at least one minute.

DNS_UPDATE = none | rfc2136

Whether the daemon publishes and withdraws its records itself, by RFC 2136 UPDATE signed with TSIG. Default none: the operator publishes them.

DNS_UPDATE_SERVER = HOST

Where the updates go. Default: the MNAME of the zone’s SOA record.

DNS_UPDATE_TTL = SECONDS

TTL of the records that the daemon adds. Default 3600.

TSIG_KEY_NAME = NAME

Name of the TSIG key. Required with DNS_UPDATE = rfc2136.

TSIG_ALGORITHM = hmac-sha256 | hmac-sha384 | hmac-sha512

Default hmac-sha256.

TSIG_SECRET = BASE64

The TSIG key. Required with DNS_UPDATE = rfc2136. A secret: pepsi-setup(1) keeps it in secrets.d/pepsi-dkim.secret, readable by the pepsi-dkim account alone.

PUBLISH_RETIRED_KEYS = yes | no

Publish a retired private key under /.well-known/pepsi-dkim-retired/<domain>/<selector>.pem instead of deleting it, once DNS no longer serves its records, so old signatures lose their value as evidence. Default no; meaningful with rotation.

NOTIFY = yes | no

Mail the postmaster, at most once a day per pending change, when a record must be added or removed, a rotation waits for DNS, or the DNS server refused an update. Default yes.

NOTIFY_ADDRESS = ADDRESS

Who gets those notices. Default postmaster@ the first served domain.

95.2.1.1.8. The [pepsi-srs] Section

The Sender Rewriting Scheme parameters, shared by pepsi-stage-srs(1) (the forward rewrite) and pepsi-ingress(1) (the reverse decode at RCPT time), so the secret and domain match in both directions. Omitting the section disables SRS: the stage refuses to run and ingress treats SRS-looking recipients as ordinary addresses.

SRS_DOMAIN

(string, required to enable SRS) The domain of the rewritten envelope senders. It must be a domain that you control: its MX must point at the Pepsi ingress (so bounces return) and its SPF must authorise Pepsi’s sending IPs. pepsi-setup(1) provisions keys and DNS for it. It cannot provision the MX, since you decide where mail for a domain is routed, so it checks the MX instead: with a stage running pepsi-stage-srs(1), a SRS_DOMAIN with no MX and no address record is reported on every run. An SRS address is a return path, and a domain that cannot receive mail loses every bounce for the mail that this host forwards.

It must be a dedicated domain that is not DMARC-aligned with any domain that this host serves: not an ACCEPTED_DOMAINS entry or other sending identity, not a subdomain or parent of one, and not sharing its last two labels with one (Pepsi has no public-suffix list, so it errs towards calling two domains aligned). Forwarded mail leaves with its envelope sender rewritten into this domain from Pepsi’s own addresses, so SPF passes for it at the next hop. If the SRS domain were aligned with a served domain, a message forged as coming from that domain, received from outside and forwarded, would pass DMARC at the next hop on SPF alone. With a dedicated domain SPF still passes, but DMARC rests on the author’s own DKIM signature. pepsi-setup(1) refuses an aligned SRS_DOMAIN unless ALLOW_ALIGNED_DOMAIN is set. For this domain, publish an MX record pointing at this host and the SPF record that pepsi-setup(1) prints; since nobody sends mail from it, a DMARC record with p=reject is appropriate too. pepsi-ingress(1) decodes an SRS local-part at this domain whether or not it is an accepted domain.

ALLOW_ALIGNED_DOMAIN

(boolean, default no) Accept an SRS_DOMAIN that is DMARC-aligned with a served domain, with a warning instead of an error. Only for a host that cannot have a dedicated domain: forwarded forgeries of the aligned served domain then pass DMARC at the next hop. Publishing p=quarantine or p=reject for the served domain together with [pepsi-ingress] DMARC_ENFORCE = yes refuses such forgeries at ingress instead; for an SRS domain that is a subdomain (or any name other than the served domain itself), aspf=s in the served domain’s DMARC record keeps the SRS envelope from aligning. The warning names both, and pepsi-setup check reports the served domain’s DMARC record as an SRS alignment [MISMATCH] until one of them is in place.

SECRET_FILE / SECRET

(required when SRS_DOMAIN is set) The secret key of the HMAC that signs SRS addresses, given as a file path (preferred; store it mode 0600) or inline. The keys that seal the forward return addresses of forwarded copies (pepsi-stage-srs(1)) are derived from it under labels of their own. It must stay stable over time, because a bounce returned days later must still verify, and it must be identical across all instances. To replace it, move the old secret to PREVIOUS_SECRET_FILE (see “Rotating the SRS key” in the operations chapter of the manual).

PREVIOUS_SECRET_FILE

(path list, optional) One file, or several separated by whitespace, each holding a retired SRS secret. These secrets are verify only: a returning address whose signature matches one of them is accepted, nothing new is signed with them, and MAX_AGE_DAYS still bounds every address. A missing or empty file is an error; a file holding the current secret is ignored with a warning. Each file gets the ownership and mode of the current secret’s fragment (pepsi-ingress, 0640) from pepsi-setup run, and pepsi-setup(1) warns when one was last changed more than MAX_AGE_DAYS ago: every address that it signed has expired, so it verifies nothing and can be removed.

MAX_AGE_DAYS

(integer, optional) How many days a rewritten address stays valid for returning bounces (SRS timestamps are day-granular), and for how many days pepsi-ingress(1) answers a report sent to a forward return address. Default 21, which covers a remote host’s retries (typically five days) on top of this host’s own MAX_LIFETIME. Clamped to 1..``1021``: the day counter wraps after 1024 days, so a window at or above it would make every timestamp verify and disable expiry altogether.

The signature in a rewritten address is 8 base32 characters — 40 bits — and no shorter one is ever accepted. A forged signature would do real harm: pepsi-ingress(1) treats a verified SRS recipient as authorisation to relay to the decoded address even when its domain is not one that this deployment serves, so a forged token makes this host an open relay and a source of arbitrary backscatter in its name. There is no option to accept a narrower signature: it would leave the deployment only as strong as the narrower MAC for as long as it was set. The per-connection cap on failed SRS recipients (pepsi-ingress(1) drops a connection with 421 after three) bounds the online search separately; neither bound substitutes for the other.

95.2.1.1.9. The [pepsi-origin] Section

Proof-of-origin keying, shared by both relay stages (pepsi-stage-relay-to-internet(1) and pepsi-stage-relay-to-smarthost(1), which stamp the Pepsi-Origin header on outbound mail and record its nonce) and pepsi-stage-anti-spam(1) (which verifies the header on a returning bounce). The feature is on by default: when no secret is configured, pepsi-setup(1) generates a random one on first run (provided [pepsi-ingress] HOSTNAME is set). The secret is not stored inline in this world-readable file; it is written to a secrets.d/pepsi-origin.secret fragment beside the configuration (owned by the pepsi dispatcher account, mode 0640) and pulled into this section with an @inline-secret@ directive. Re-running setup reuses the existing fragment rather than rotating the key. ENABLED = no disables the feature — outbound mail is unstamped and every bounce is then unverifiable (routed by the stage’s BOUNCE_TARGET_STAGE, else forwarded). Removing the section does not: the next pepsi-setup(1) run would provision a new secret.

ENABLED

(boolean, optional) Default YES. NO switches proof-of-origin off for every component that reads this section, whatever secret is configured, and stops pepsi-setup(1) from generating one. An existing secret fragment is left in place, so switching back on resumes with the same key.

The header carries the version, our HOSTNAME (the [pepsi-ingress] option), the originating sender account, a 128-bit nonce and a timestamp, plus an HMAC-SHA256 over all of them. Each stamped nonce is recorded in pepsi.origin_nonce for two weeks; a bounce is trusted only if its embedded header’s MAC verifies and its nonce is still tracked. See pepsi-stage-anti-spam(1).

SECRET_FILE / SECRET

The secret key of the HMAC, given as a file path (preferred; store it mode 0600) or inline. Like the SRS secret, it must stay stable over time, because a bounce returned days later must still verify, and it must be identical across all instances. When neither is set, pepsi-setup(1) provisions a random SECRET in a secrets.d/pepsi-origin.secret fragment referenced by @inline-secret@ (see above), keeping it out of the world-readable main configuration. The feature requires [pepsi-ingress] HOSTNAME (bound into the MAC).

95.2.1.1.10. The [pepsi-crypto] Section

Custody and lifecycle of the end-to-end key store — the pepsi.crypto_identity, pepsi.peer_key and pepsi.ca_trust tables managed by pepsi-keys(1). Like the [pepsi] CRYPTO_* options above this is administrator-only, but it is about storage rather than about cryptographic strength. Omit the whole section if the deployment does no end-to-end cryptography; as soon as it says anything, pepsi-setup(1) insists on a usable KEY_WRAP_SECRET, because a key store that cannot store keys is a configuration mistake rather than a choice.

Private key material is kept in the database, sealed with AES-256-GCM under a key-encryption key derived from KEY_WRAP_SECRET. The database alone therefore never yields a private key: a dump, a replica or a backup tape produces ciphertext, and the key that opens it is a separate artefact guarded by file permissions. The other half of the boundary is a database grant — crypto_identity.private_wrapped is granted to the pepsi-crypto role alone; see pepsi-setup(1).

KEY_WRAP_SECRET

(string, required once the section exists) The key-encryption key that wraps private key material at rest. Keep it out of this world-readable file: put it in a secrets.d/pepsi-crypto.secret fragment and reference it with an @inline-secret@ directive, exactly as the SRS and proof-of-origin secrets are handled. Every pepsi-setup(1) run re-asserts mode 0640 on that fragment and hands it to the pepsi-crypto account. A secret of fewer than 16 characters is refused.

Back it up separately from the database. If it is lost, every stored private key is gone: mailboxes hold plaintext, so nobody’s mail becomes unreadable, but in-flight and archived ciphertext is lost, every published identity is invalidated and the organisation must re-key.

KEY_WRAP_KEY_ID

(string, optional) Identifier of the key-encryption key under which new material is wrapped. Default k1. Must be a non-empty run of ASCII letters, digits and underscores, because it becomes part of the option name KEY_WRAP_SECRET_<ID>, from which a retired key is read. Each row records the id of the key that sealed it, so a rotation can proceed row by row instead of all at once.

KEY_WRAP_SECRET_<ID>

(string, optional) A retired key-encryption key, kept until every row wrapped under it has been rotated. <ID> is the wrap_key_id that it names, upper-cased (so KEY_WRAP_SECRET_K0 for key k0). Between introducing a new key and running pepsi-keys wrap rotate the deployment keeps working: new material is sealed under the new key while old material still opens under this one. Remove it once the rotation reports everything re-wrapped.

AUTO_CREATE_IDENTITY

(boolean, optional) Whether an identity may be generated automatically for a served address. Default YES. pepsi-stage-encrypt(1) acts on it, and only for an address in a [pepsi-ingress] ACCEPTED_DOMAINS domain that has no crypto_identity row of any kind yet (a revoked key or the user’s own registered key counts), under CRYPTO_OPENPGP_ALGORITHM / CRYPTO_SMIME_ALGORITHM and IDENTITY_VALIDITY_DAYS. When it takes effect depends on that stage’s ENABLE_PEP:

  • ENABLE_PEP = yes (the default): eagerly, on the sender’s first locally submitted message, whether or not it asked for protection. Every sender at a served domain therefore ends up with a wrapped private key on this server, and the deployment’s WKD serves its public half.

  • ENABLE_PEP = no: lazily, the first time a local sender explicitly asks for protection (to sign or only to encrypt), or on every message under that stage’s SIGN = always; never merely because an address appeared in an envelope, so a user who never uses the feature never has key material.

This option is the operator’s veto over both: it lives in an administrator-only section, so no per-address pepsi.settings override can turn automatic creation back on. With it off, every identity is created on request – pepsi-keys(1), the web console, or the e-mail generate command.

Because the trigger is on the outbound path, an address that only ever receives stays keyless and is never published — outsiders therefore have nothing to encrypt to it with. Pre-provision such addresses with pepsi-keys identity generate.

IDENTITY_VALIDITY_DAYS

(number, optional) Lifetime of a generated identity, in days. Default 730 (two years); must be positive. An integer count of days rather than a duration because the parser rejects calendar units (see the warning at the top of this page). pepsi-keys identity generate --days overrides it for one identity.

ENCRYPTION_ROTATION_DAYS

(number, optional) The forward-secrecy profile. 0 (the default) turns it off. A positive number of days makes pepsi-keys identity rotate-due (run daily by pepsi-keys-rotate.timer) replace every encryption key that the server holds (custody = local) once it is that old, and retire the old one; a user’s own MUA key is never rotated. What it costs: a correspondent who cached the old key encrypts to a retired one until they fetch the new one (Autocrypt, WKD). Once the retired key’s private half is destroyed (below), mail that still arrives encrypted to it can no longer be opened, for example late mail, mail from a correspondent’s stale cache, or a copy redelivered from a backup. See the manual’s key-management chapter.

RETIRED_PRIVATE_GRACE_DAYS

(number, optional) With ENCRYPTION_ROTATION_DAYS set, how many days a retired (revoked or expired) server-held decryption key keeps its private half before pepsi-keys identity rotate-due destroys it. Default 30; 0 destroys at the first run after retirement. A key that a message in the queue is still encrypted to is kept until that message has left the queue. Ignored while rotation is off.

LOCAL_DOMAINS, TARGETS, RECIPIENT_DELIMITER

(string, optional) Which domains and accounts an address is attributed to when deciding who owns an identity, whether pepsi-keys(1), the setup applier or pepsi-stage-encrypt(1) creates it — the same option names, meanings and defaults as the local-delivery stages’ options (pepsi-stage-relay-to-maildir(1)). LOCAL_DOMAINS defaults to [pepsi-ingress] ACCEPTED_DOMAINS, TARGETS to the /etc/login.defs UID_MIN..``UID_MAX`` range and RECIPIENT_DELIMITER to +. An address that resolves to a local account has that login recorded with its identity and may be managed by that user; one that does not (a role address, a hosted domain) is operator-only.

95.2.1.1.11. The [pepsi-keydiscovery] Section

How Pepsi finds a correspondent’s public key or certificate — the input to pepsi.peer_key, as distinct from [pepsi-crypto] above, which is about custody of our own key material. Read by the pepsi-keydisc(1) discovery services, by pepsi-keys(1) (whose peer refresh --address runs the same fan-out in one process), and by any stage that must park a message on a key that it does not yet have.

The whole section is optional: with none of it, discovery runs with the default source set.

Discovery is asynchronous. A stage that needs a key that it does not have in its cache performs no network I/O of its own: it commits its work, pauses the message and enqueues a request in pepsi.key_request, and a discovery service answers the request and releases every message parked on that address. See pepsi-keydisc(1) for the service side and pepsi.state(7) for the keydisc key that a parked message carries.

SOURCES

(string, optional) Which discovery methods this deployment runs, as a comma- or whitespace-separated list of dane, wkd-advanced, wkd-direct, ldap and vks (wkd is accepted for wkd-advanced, hkp for vks; duplicates are ignored). Default dane wkd-advanced wkd-direct vks. ldap is deliberately absent, because it needs a compile-time feature and is useless until configured.

This list is also the set of methods that the stop rule waits for, which has two consequences. A pepsi-keydisc@<method> instance whose method is not listed refuses to start; and a listed method with no instance running makes every request wait the full TIMEOUT before it settles. Keep the list and the running units in step: pepsi.target starts exactly the four default methods, so leave the option unset unless you also mask or start instances. inbound, inbound-signed and gossip (and their aliases harvested/autocrypt, autocrypt-signed/signed and autocrypt-gossip) are rejected. Learning a key from a message is not a service, so nothing would ever answer for it: it runs inline in pepsi-stage-autocrypt-learn(1), from material already in the message. An empty list is refused too; remove the option to take the default.

MIN_TRUST

(string, optional) The trust floor — a key from a worse-ranked source is not used. Named by its source: manual (also api or operator), dane, wkd-advanced (also wkd), wkd-direct, ldap, vks (also hkp), inbound-signed (also autocrypt-signed or signed), harvested (also inbound or autocrypt), or gossip (also autocrypt-gossip, any, none). Default any — accept anything.

One further spelling, owner-confirmed (owner_confirmed), names a rung by what the evidence is rather than by the method that produced it: it resolves to vks, the weakest rung at which somebody who could prove control of the mailbox or the domain published the key on purpose. It exists so that inserting a rung between vks and harvested cannot silently move that line. It is also the default of [stage-encrypt] GOSSIP_MIN_TRUST.

The alternative to encrypting to a trust-on-first-use key is not a better key, it is cleartext. Raising the floor is how a deployment says that it would rather send nothing than send to an unauthenticated key. The ranking still matters at the default: it decides conflicts, and it is recorded per key.

any/none name the bottom rung, whatever it currently is, while every other spelling names one rank exactly. The distinction matters for the three that look alike. inbound-signed (rank 7) is what a correspondent said about their own address in a message that their domain’s DKIM signature covered; harvested (rank 8) is the same claim in a message that nothing signed; and gossip (rank 9) is one correspondent’s introduction of another (Autocrypt Level 1 §5.3). MIN_TRUST = harvested is therefore the useful middle setting: it keeps opportunistic encryption but refuses third-party introductions. inbound-signed keeps it only for correspondents whose domain signs their mail. Gossiped and unsigned keys are still stored either way; the floor decides only whether they may be used.

The floor does not apply to an address for which this deployment holds an identity. Our own key is not a discovered key: it pre-empts the lookup, so no peer_key row for that address is consulted whatever its rank, and no floor can exclude it. own (also local) is accepted as a spelling for completeness — every rank has a name and state.crypto renders this one — but as a floor it means “encrypt only to addresses for which we hold our own key”, i.e. no external correspondent ever receives ciphertext. See pepsi-stage-encrypt(1) and pepsi-stage-decrypt(1).

TIMEOUT

(duration, optional) Whole-request deadline: how long a request may stay outstanding before it settles with whatever has been found. Default 60 s. Uses h/m/s units only (see the duration note above).

INBOUND_TIMEOUT

(duration, optional) The same deadline for a message parked on the inbound path — waiting for the key that verifies a signature — defaulting to TIMEOUT. It is separate so that it can be lowered on its own: a message parked on the inbound path is mail that somebody is waiting for, so an operator who notices the delay can lower this to seconds without shortening the outbound deadline. pepsi-setup(1) warns above five minutes.

RANK_GRACE

(duration, optional) Trades speed against thoroughness. When a lookup succeeds, every method still running that ranks better is granted RANK_GRACE × (how many ranks better it is) of extra time; when that expires, the best answer in hand wins. Default 5 s, so one rank up gets 5 s and three ranks up gets 15 s.

This one option covers the whole range. 0 means the first usable answer wins outright. With the default, a slow WKD server cannot hold up a message once a key server has already answered, but a better source that is nearly as fast still wins. A value at or above TIMEOUT means every method is waited for and the ranking applies in full (pepsi-setup(1) notes that case rather than treating it as an error — it is a legitimate choice).

METHOD_TIMEOUT

(duration, optional) One method’s own network deadline, covering connect, handshake and every read. Default 15 s. Setting it above TIMEOUT makes a slow method unable to finish inside the whole-request deadline, which pepsi-setup(1) warns about.

CACHE_TTL

(duration, optional) How long a stored key is used before pepsi-keys peer refresh re-checks it (it becomes the row’s refresh_after) — through the method that found it, and only if that is a network method still in SOURCES. Default 24 h.

NEGATIVE_TTL

(duration, optional) How long an authoritative “this address has no key” is remembered. Default 24 h. While the entry is fresh a message for that address takes the no-key path immediately and never parks: pausing 60 s to re-learn a known answer only delays every message to that correspondent. The accepted cost is that a key published five minutes ago stays invisible until the entry ages out — lower this if that matters more than the delay. The same interval paces the lookups that pepsi-stage-encrypt(1) raises in the background for an address whose only key was harvested from its own mail or gossiped: at most one request per address per NEGATIVE_TTL, so a key that the owner later publishes is found within that time.

ERROR_TTL

(duration, optional) The same, after a method failed rather than answering “nothing here”. Default 1 h: “the server was down” is worth re-trying sooner than “there is no key”.

MAX_RESPONSE_BYTES

(number, optional) Cap on a fetched WKD or VKS response body, enforced while streaming rather than afterwards, so a 10 MB body costs the cap and not 10 MB. Default 262144 (256 KiB). Must be greater than zero.

VKS_SERVERS

(string, optional) Verifying key servers to query, in order, as a comma- or whitespace-separated list. Default https://keys.openpgp.org. Every entry must be an https:// URL, because there is no reason to believe a key fetched over an unauthenticated channel; a trailing / is stripped.

TLS_CA_BUNDLE

(path, optional) A PEM file of CA certificates that replaces the system root store for the WKD and VKS HTTPS fetches — those of the discovery services, of pepsi-keys peer refresh and identity publish --vks, and of pepsi-stage-vks-confirm(1). Absent (the default), the system roots are used. A WKD host or key server whose certificate does not chain to a certificate in the file is refused, as any untrusted one is. LDAP and DANE are unaffected, and the https:// revocation-list fetches (CRL_FETCH) keep the system roots, since a CRL is authenticated by its issuer’s signature. Narrowing the store shrinks the set of certificate authorities that could mis-issue a certificate for a correspondent’s WKD host. The cost is that Pepsi no longer finds the WKD keys of correspondents whose WKD host uses a CA that the file does not hold. The file is read when a fetcher is built: a file that cannot be read or holds no PEM certificate makes pepsi-keydisc(1) refuse to start, and is never silently replaced by the system roots.

ALLOW_DOMAINS, DENY_DOMAINS

(string, optional) Recipient-domain lookup policy, comma- or whitespace-separated and matched case-insensitively on the domain part. A non-empty ALLOW_DOMAINS is exclusive (only those domains are ever looked up); DENY_DOMAINS always wins over it. Both empty by default, so every domain may be looked up. An address with no @ is never looked up.

This is the recipient-side privacy control, and it is the operator’s. The per-user switch below is the sender side; the two are not interchangeable.

LDAP_URL, LDAP_BASE, LDAP_FILTER, LDAP_ATTRIBUTE, LDAP_BIND_DN, LDAP_BIND_PASSWORD

(string, optional) The directory that pepsi-keydisc@ldap queries. LDAP_URL must be an ldap:// or ldaps:// URL and, with LDAP_BASE, is required once ldap is in SOURCES. LDAP_FILTER defaults to (mail={address}) and must contain the {address} placeholder (the address is RFC 4515-escaped before substitution, so a local part containing * or ( cannot become filter syntax); LDAP_ATTRIBUTE defaults to userCertificate;binary. An absent LDAP_BIND_DN means an anonymous bind; a present one requires an ldaps:// URL, because a simple bind sends the password verbatim and the lookup is refused rather than performed in the clear (the same rule that the LMTP and SMTP clients apply to AUTH).

LDAP support is a compile-time cargo feature. On a build without it, ldap in SOURCES is rejected by pepsi-setup(1) and the pepsi-keydisc@ldap instance refuses to start.

CRL_FETCH

(boolean, optional) Whether the discovery services fetch the certificate revocation lists that cached S/MIME peer certificates name in their cRLDistributionPoints (http:// and https:// only) into pepsi.crl_cache, for pepsi-stage-decrypt(1) to check signer certificates against. Default YES. Each distribution point is fetched when its list’s nextUpdate arrives, but at least daily, so the CA learns that this host holds some certificate that it issued – never which one, and never when a message arrives (no OCSP responder is ever queried; what a TLS server staples is evaluated on that session alone). A fetched list is stored only if it is current and not older than the one already cached. With NO nothing is fetched and S/MIME revocation reads “not checked”. See pepsi-keydisc(1).

CRL_MAX_BYTES

(number, optional) Cap on one fetched CRL, enforced while streaming. Default 1048576 (1 MiB). A list larger than this is not stored, and the certificates it would have covered stay “not checked”. Must be greater than zero.

CA_ISSUERS_FETCH

(boolean, optional) Whether the discovery services follow the caIssuers pointers (authorityInfoAccess, http:// and https:// only, never LDAP) of the cached S/MIME peer certificates, and of the certificates fetched from them up to three levels, into pepsi.ca_issuer_cache. pepsi-stage-decrypt(1) hands the stored CA certificates to the verifier as intermediates, so a correspondent who sends their certificate without its intermediates can still be validated up to a pepsi-keys(1) ca anchor. A fetched certificate is never an anchor and never names a signer. Default NO: each fetch tells a CA that this host corresponds with one of its subscribers. Answers are capped at 64 KiB and refetched weekly. See pepsi-keydisc(1).

BADKEYS_URL

(URL, optional) Where pepsi-keys blocklist update fetches the list of known compromised keys; pepsi-keys-blocklist.timer runs that command daily. Default https://update.badkeys.info/v0: the badkeys blocklist (https://badkeys.info), which includes every RSA and EC key that the Debian OpenSSL bug (CVE-2008-0166) could produce, keys published in RFCs, test suites and documentation, and keys extracted from firmware and software packages. badkeysdata.json below this URL names the current list, which must lie below the URL too; it is fetched over verified TLS (the roots of TLS_CA_BUNDLE when that is set), conditionally, so an unchanged list costs one small request. Must be https://. A mirror of your own may be named instead, and a mirror that never changes keeps the list fixed.

The list lives in the database (pepsi.compromised_key, about 240 MB for the 2026 list of three million keys), beside the moduli that pepsi-keys peer screen factored. It only grows: an update adds new entries and removes none. A correspondent’s key on the list is refused wherever a key below [pepsi] CRYPTO_MIN_RSA_BITS is refused (for encryption, for signature verification and in an S/MIME chain), and key discovery, harvesting and pepsi-keys peer import never store it. Until the first update only the screen’s own findings apply. To stop the updates, systemctl mask --now pepsi-keys-blocklist.timer (pepsi.target starts a merely disabled timer again); pepsi-keys blocklist dismiss takes wrong entries out of service. See pepsi-keys(1).

95.2.1.1.11.1. The per-sender switch: [stage-encrypt] DISCOVERY

A stage that consumes the key store reads one option of its own, in its [stage-<name>] section, so it can be overridden per address through the pepsi.settings layer (pepsi-settings(1)):

DISCOVERY

(boolean, optional) Whether a cache miss may trigger a network lookup. Default YES. With NO the cached keys are still used, but a miss goes straight to the stage’s no-key path instead of parking the message, since there would be nothing to wait for.

Important

What the per-address override actually means. The settings layer resolves an outbound message on its envelope sender, so an override of DISCOVERY for an address means “this user’s mail never triggers a lookup” — not “never look this correspondent up”. Recipient-side suppression is the operator’s ALLOW_DOMAINS/DENY_DOMAINS above; there is deliberately no per-address recipient denylist, which would need its own column and a second list to stay consistent with this one.

DISCOVERY is read by pepsi-stage-encrypt(1) and pepsi-stage-decrypt(1) from that stage’s effective section, so a pepsi.settings override applies. Their other options are documented under pepsi-stage-encrypt Options and pepsi-stage-decrypt Options.

95.2.1.1.12. The [pepsi-keys] Section

The mirror image of the section above: how other people find our users’ keys. Read by pepsi-keys(1) and by pepsi-stage-vks-confirm(1). The whole section is optional, and a configuration that omits it publishes nothing to any key server.

Web Key Directory publication needs no options at all. It follows each identity’s published flag (on by default, cleared with pepsi-keys identity unpublish) and is served by pepsi-httpd(1) from our own domain, so it takes effect on the next request and is undone by clearing the flag. What this section configures is the other channel, which behaves nothing like it: a key server accepts a key permanently: it can later be told that the key is revoked, but never told to forget it.

VKS_PUBLISH

(boolean, optional) Whether an identity created or imported by hand (pepsi-keys identity generate/import, the web console’s or the API’s generate, the e-mail generate command) starts with its key-server upload requested (crypto_identity.vks_wanted). Default NO.

Each identity records whether its upload was asked for, and the retry job (pepsi-keys identity publish --retry) uploads exactly the published, active OpenPGP identities that have vks_wanted set, retrying until verified. It is not gated by this option. Two consequences:

  • automatically generated keys ([stage-encrypt] ENABLE_PEP) and MUA keys registered from a user’s own mail are never uploaded unasked, whatever this option says – Autocrypt and the deployment’s own WKD are how they are found;

  • a user’s explicit request to upload (pepsi-keys identity publish <ID> --vks, the web console’s Upload to the key server, PATCH /api/v1/identities/{id} with vks_wanted, or the e-mail publish command) is honoured whatever this option says.

“Not uploaded” is therefore recorded state rather than an absence, and pepsi-keys identity show prints it. An upload cannot be withdrawn, which is why the default for keys made by hand stays an operator’s decision.

VKS_SERVER

(string, optional) The key server that uploads go to; https:// only, and a plaintext URL is refused rather than downgraded. Defaults to the first [pepsi-keydiscovery] VKS_SERVERS entry, so a deployment that already chose a key server to read from does not name it twice.

One server, not a list: publishing the same key to several servers repeats an act that cannot be undone, and every one of them then has to be kept up to date with revocations.

Its host is also the default VKS_HOST of pepsi-stage-vks-confirm(1): the only host from which that stage accepts a verification mail and to which it follows a link.

VKS_MAX_ATTEMPTS

(integer, optional) How many attempts one identity gets before pepsi-keys identity publish --retry leaves it alone. Default 5. The row keeps its last error, so an abandoned identity says why.

VKS_RETRY_INTERVAL

(duration, optional) Minimum spacing between attempts for one identity. Default 6 h. Calendar units are rejected: 6 h parses, 1 d does not.

VKS_BATCH

(integer, optional) How many identities one --retry run works on, so that the first run over a large deployment does not send one enormous burst of requests to a third party. Default 50.

95.2.1.1.13. The [pepsi-mpki] Section

Read by pepsi-keys(1) mpki, which orders S/MIME certificates for the users of a domain from a commercial certificate authority (a managed PKI). The section is optional and every option has a default. It holds only what the host needs to reach the CA and to mail its notices: whether a domain takes part, from which CA account and under which rules, is set per domain in the database with pepsi-keys mpki domain set, and the account’s API key is a file of its own.

CREDENTIAL_DIR

(path, optional) The directory that holds one mpki-DOMAIN.secret file per managed domain, with that domain’s CA API key. Default: the secrets.d directory beside the configuration file (/etc/pepsi/secrets.d). pepsi-keys mpki credential set writes the files, with mode 0640 and group pepsi-crypto.

TIMEOUT

(duration, optional) The deadline of one request to the CA’s API. Default 60 s. A request that runs out of time is a temporary failure, retried by a later pass.

NOTIFY_STAGE

(string, optional) The stage at which the notices of a pass are injected as one mail per domain to the domain’s notify address (pepsi-keys mpki domain set DOMAIN --notify ADDRESS), with the null sender and Auto-Submitted: auto-generated. Name a stage of the path that outbound mail takes, for example the stage that DKIM-signs it. Without it no notice is mailed, and pepsi-keys mpki notices still lists them all.

NOTIFY_FROM

(string, optional) The From: address of a notice mail. Default postmaster@DOMAIN, for the domain that the notices concern.

95.2.1.1.14. The [pepsi-ingress] Section

Global options governing message acceptance, read by pepsi-ingress(1).

HOSTNAME

(string, required) Host name announced in the SMTP greeting and the EHLO response, e.g. mail.example.org.

ACCEPTED_DOMAINS

(string, required) Whitespace- or comma-separated list of domains for which mail is accepted. Recipients in any other domain are rejected as relaying with 550 5.7.1, unless the session is authenticated (see the listener sections). Matching is case-insensitive and by IDNA form: an internationalised domain may be written as its U-label (münchen.example) or its A-label (xn--mnchen-3ya.example), and mail to either spelling is accepted. At least one domain must be given.

USERNAME_MAP

(path, optional) File mapping each SASL authentication id to the e-mail addresses that it may use as the envelope sender and From: identity (RFC 6409 §6/§8.1). Each non-blank, non-comment line is username: addr… — a # begins a comment, the key is the SASL username, and the value is the whitespace/comma separated list of allowed addresses (which may be empty). A username listed with addresses is allowed exactly those (the first concrete one being the canonical identity used for the Sender: fixup); an address may be a * wildcard such as *@example.org (any address at the domain) or a bare * (any address). A username listed with no addresses is denied any address (its AUTH is refused even though the credentials are valid); a username not listed falls back to the default username@HOSTNAME. The file is re-read whenever its modification time changes (checked on each authentication); a missing/unreadable file is treated as empty. When unset, every authenticated user is mapped to its default username@HOSTNAME. See pepsi-ingress(1).

SENDER_MAP

(path, optional) File naming the addresses that a MYNETWORKS network or a TLS client certificate may send as. Each non-blank, non-comment line holds a key followed by at least one address in the USERNAME_MAP syntax (exact, a *@example.org wildcard, or * for any address). The key is a CIDR network or bare address, or cert: followed by the 64-hex-digit SPKI pin of a TLS_AUTH_CLIENT key or of a TLS_AUTH_CLIENT_CA certificate. An address that one key names exactly is claimed: no other key’s wildcard reaches it. A MYNETWORKS session is bound by the most specific network containing the peer, a certificate session by the key or CA under which it was recognised; a bound session is subject to the MAIL FROM/From: checks of USERNAME_MAP (550 5.7.1), and a CA-issued certificate that names a mailbox is confined to it. A certificate that no key matches authenticates nothing, and a MYNETWORKS entry outside loopback that no single key covers whole is refused: pepsi-ingress does not start and pepsi-setup(1) validate fails, naming the entry, since every host in it could otherwise send as any address and have it signed for every served domain. A bare * binds a network to every address, as an explicit decision; loopback (127.0.0.0/8, ::1) needs no binding. pepsi-ingress (at every start) and pepsi-setup validate warn about a MYNETWORKS entry that is wider than one host and whose most specific key is a bare *: every machine in that network may send signed mail as any address of every served domain, the configuration that the EchoSpoofing campaign abused. Read once at start-up; an error in the file stops pepsi-ingress from starting. See pepsi-ingress(1), Client certificates and Sender bindings for networks and certificates.

POSTMASTER

(string, optional) Routable address to which the reserved <Postmaster> mailbox without a domain is rewritten. RFC 5321 §4.5.1 requires <Postmaster> (with no domain) to be accepted regardless of ACCEPTED_DOMAINS; on acceptance Pepsi rewrites it to this address so that the normal pipeline (aliases, local delivery, relay) can route it. When unset it is rewritten to postmaster@HOSTNAME — add an alias for that address in a pepsi-stage-aliases ALIASES map to deliver postmaster mail to a real person, or set POSTMASTER to that person directly. See pepsi-ingress(1).

MAX_MESSAGE_SIZE

(number, optional) Maximum accepted message body size in bytes — the size of the DATA payload. The value is advertised through the ESMTP SIZE extension; messages exceeding it are rejected with 552. Defaults to 26214400 (25 MiB).

MAX_HEADER_FIELDS

(number, optional) The largest number of fields that the top-level header block of a message may carry; a message with more is refused at the end of data with 552 5.3.4, on every listener. Defaults to 1000 (ordinary mail carries 20 to 150); 0 is unlimited. Together with MAX_HEADER_FIELD_SIZE, this is the limit that the Dovecot advisories CVE-2024-23184 and CVE-2024-23185 ask the MTA in front of the MDA to enforce. Header blocks of attached messages (message/rfc822 parts) are not counted; they stay bounded by MAX_MESSAGE_SIZE.

MAX_HEADER_FIELD_SIZE

(number, optional) The largest size of one header field, in octets, unfolded: its name, colon and value with every continuation line, line breaks not counted. A message with a larger field is refused at the end of data with 552 5.3.4. Defaults to 102400 (100 KiB, Postfix’s header_size_limit; a To: naming a thousand recipients is about 40 KiB); 0 is unlimited.

MAX_CONNECTIONS

(number, optional) Maximum number of SMTP connections served concurrently across all listeners. The effective admission ceiling is the smaller of this and MAX_OPEN_SOCKETS. Defaults to 1024.

DB_POOL_SIZE

(number, optional) Maximum number of PostgreSQL connections in the ingress database pool. Ingress serves many SMTP sessions concurrently, each briefly calling workqueue_add, so unlike the single-connection stage workers it can use more than one. Defaults to 1; raise it only if the single connection limits how fast ingress accepts mail, and keep the sum of every component’s pool below PostgreSQL’s max_connections.

MAX_OPEN_SOCKETS

(number, optional) Hard ceiling on concurrently open client connections, guarding against file-descriptor exhaustion. When unset, it is derived from the process’s soft RLIMIT_NOFILE minus RESERVED_SOCKETS. When the ceiling is reached and a new connection arrives, the server makes room by closing the longest-idle connection in the source range (one IPv4 address, or an IPv6 /32) whose total idle time is largest (a 421, then close).

RESERVED_SOCKETS

(number, optional) File descriptors held back from the RLIMIT_NOFILE-derived budget (for the database pool, listeners, stdio and DNS sockets). Defaults to 64. Ignored when MAX_OPEN_SOCKETS is set.

CONN_RATE_PER_SECOND

(number, optional) Token-bucket refill rate limiting accepted new connections per source range, in connections per second. A connection over the rate is answered with a best-effort 421 and closed; the connection holds a slot only while that reply is written, and none at all (and gets no reply) when the descriptor ceiling is already reached. Defaults to 1. A fractional value is accepted (0.2 is one connection every five seconds). Local (UNIX-socket) connections are never rate-limited.

CONN_RATE_BURST

(number, optional) Token-bucket burst allowance per source range, likewise fractional. Defaults to 1.

MAX_CONNECTIONS_PER_IP

(number, optional) How many concurrent connections one source range (one IPv4 address, or an IPv6 /32) may hold. A connection over it is refused like a rate-limited one. Defaults to 16; 0 disables the cap.

MAX_LOCAL_CONNECTIONS

(number, optional) How many concurrent connections all UNIX-socket peers together may hold. Local connections are exempt from the rate limit and from the server-wide eviction, so this limit keeps local submitters from holding every slot. One peer uid may hold at most half of it (at least one), so a single local account cannot lock the others out; root and the service accounts are not exempt. When local connections fill it, a new connection from a uid that holds fewer of them than the heaviest uid evicts the heaviest uid’s longest-idle connection, provided that connection has sent no complete command line for 5 seconds; the evicted session is answered 421 4.3.2. So colluding accounts cannot fill it either; pepsi-sendmail writes its whole message without pausing and is never the one evicted. Defaults to 32; 0 leaves them bounded only by MAX_CONNECTIONS, with no per-uid share.

MAX_MESSAGES_PER_SESSION

(number, optional) How many mail transactions one session may start; the next MAIL is answered 421 and the session closed. Defaults to 100; 0 is unlimited.

VERIFY_RECIPIENTS

(``auto`` or ``off``, optional) Whether an address at a served domain that nothing on this host would accept is refused at RCPT time with 550 5.1.1. Default auto. The sending MTA then tells its own user at once. If the message were accepted, it would bounce later to its envelope sender. Spam forges that sender, so the bounce reaches an innocent third party (backscatter) and gets this host blocklisted.

Nothing needs to be listed by hand. For each served domain, the sources that can vouch for an address are derived from the [stage-*] sections:

  • the local accounts that a pepsi-stage-relay-to-maildir(1) or pepsi-stage-dot-forward(1) resolves for its LOCAL_DOMAINS, TARGETS and RECIPIENT_DELIMITER included;

  • the MDA behind a pepsi-stage-relay-to-lmtp(1), asked for its LOCAL_DOMAINS with RCPT TO and no message;

  • the backend behind a pepsi-stage-route(1), as its RECIPIENT_CHECK says;

  • every pepsi-stage-aliases(1) map, with the stage’s own matching;

  • the mailing lists, when a pepsi-stage-list(1) router is configured;

  • postmaster@ and abuse@, and the control addresses of the stages that answer one (pepsi@, pepsi-keys@, pepsi-wallet@, secretary@, dmarc-reports@).

An address that any of them vouches for is accepted. So is every address at a domain that cannot be checked:

  • an alias catch-all covers the domain;

  • a stage runs a program that Pepsi does not know;

  • the domain is routed to a backend with RECIPIENT_CHECK = none;

  • the domain is relayed onward by a smarthost stage with nothing here holding its mailboxes.

Every uncertainty accepts too: an unreadable file, a database error, a probe that fails or times out. pepsi-setup run prints the result for every domain. off accepts every address at a served domain. Read at start-up: a changed stage graph needs an ingress restart, while edits to an alias map, a recipient list or the mailing lists apply at once.

Whatever this option says, a local part containing % (the percent hack) or ! (a bang path) at a served domain is refused 550 5.1.3 unless one of the sources above vouches for the address, so a backend that still honours those forms is never handed a route to a third party.

MAX_INVALID_RECIPIENTS

(number, optional) How many unknown recipients one session may name. At the limit the session is closed with 421, which turns a dictionary attack (harvesting valid addresses, or making the MDA answer guess after guess) into a stream of connections that the connection limits meter. Defaults to 10; 0 is unlimited.

MAX_SELF_HOPS

(number, optional) How many times a message may already have passed through this host’s ingress before it is refused as a routing loop, with 554 5.4.6. Counted from the Received: fields that ingress itself writes (by HOSTNAME (pepsi-ingress)). Legitimate mail re-enters a few times at most: an alias to another served domain, a ~/.forward, or a report to one of our own users each leave over SMTP and come back in. A loop, by contrast, would otherwise run until the generic hop limit of the relay stages, dozens of passes. Defaults to 5; 0 disables the check.

AUTH_FAILURES_PER_HOUR

(number, optional) How many failed AUTH attempts one source range may make per hour across all of its sessions (a token bucket). Once spent, AUTH from the range is refused with 421 without consulting the SASL backend until the bucket refills. Defaults to 20; 0 is unlimited.

ACCOUNT_AUTH_FAILURES_PER_HOUR

(number, optional) How many failed AUTH attempts one account (its authentication id, compared case-insensitively) may collect per hour from all sources together (a token bucket). Once spent, an AUTH for the account from a source range from which it has not authenticated in the last 30 days waits ACCOUNT_AUTH_DELAY before the SASL backend is asked, and such attempts are checked one at a time, so a guesser spread over many addresses gets one guess per delay. The account is never locked: its owner with the right password still signs in, after the delay. An attempt that would have to queue longer than three delays is answered 454 4.7.0 without being checked. Defaults to 10; 0 turns the delay off.

ACCOUNT_AUTH_DELAY

(duration, optional) The wait described under ACCOUNT_AUTH_FAILURES_PER_HOUR, and so the least time between two checked guesses at one account past its budget. Defaults to 20 s; 0 s turns the delay off.

LOCAL_MESSAGES_PER_MINUTE

(number, optional) How many messages one local uid may submit per minute across its sessions; the uid is identified by SO_PEERCRED on a UNIX-socket session. A MAIL over the rate gets 451 4.7.1. Defaults to 60; 0 is unlimited.

LOCAL_MESSAGE_BURST

(number, optional) The burst allowed on top of LOCAL_MESSAGES_PER_MINUTE. Defaults to 120.

USER_RECIPIENTS_PER_HOUR

(number, optional) How many recipients one SASL account (its authentication id, compared case-insensitively) may submit to per hour across all of its sessions; a RCPT over the rate gets 450 4.7.1. Only accepted recipients count. This limits how much mail a stolen password can send. Defaults to 500; 0 is unlimited.

USER_RECIPIENT_BURST

(number, optional) The burst allowed on top of USER_RECIPIENTS_PER_HOUR. Defaults to 500.

COMMAND_TIMEOUT

(duration, optional) The longest time that a session waits for the next command (or AUTH continuation, or the start of a DATA/BDAT body) before the connection is closed with 421 (RFC 5321 §4.5.3.2). Defaults to 300 s.

TLS_HANDSHAKE_TIMEOUT

(duration, optional) The longest time that a TLS handshake may take, on an implicit-TLS listener and after STARTTLS, before the connection is closed (without a reply). Separate from COMMAND_TIMEOUT: a handshake takes a working client a few round trips, and each one costs the server a private-key operation, so a peer that stalls or sends a ClientHello a few bytes at a time should not hold a connection for a whole command timeout. Defaults to 30 s; must be greater than zero.

DATA_TIMEOUT

(duration, optional) The longest time that a session waits for the next block of payload octets while receiving a DATA/BDAT body before closing with 421. Defaults to 180 s.

SESSION_TIMEOUT

(duration, optional) The longest one session may last, from the moment it connects; past it the next read — a command, an AUTH continuation, a block of a body — is answered 421 4.4.2 Session time limit exceeded and the connection closed, whatever the per-read timeouts say. Every byte that the client sends resets those timeouts, so without this limit a client could hold a transaction open indefinitely at a point of its choosing: just before the end of DATA, for example, at thousands of hosts at once, in order to complete them all in the same instant. Defaults to 30 m, far above what a session needs (a MAX_MESSAGE_SIZE body still fits at 15 KB/s); a bulk sender whose session is cut simply reconnects. 0 s disables the deadline.

DMARC_ENFORCE

(boolean, optional) When YES, reject at SMTP time (550) a message from an unauthenticated session whose DMARC evaluation fails and whose published policy is quarantine or reject; submitted mail is never rejected on DMARC’s account. The compiled-in default is NO, so a configuration that does not mention the option keeps accepting such mail with the failing result recorded (and pepsi-stage-arc(1) seals it) for a downstream receiver to decide; pepsi-setup(1) --wizard writes YES for a new installation, and an existing pepsi.conf keeps whatever it says. pepsi-setup(1) warns about a configuration with accepted domains that does not set the option, and about one with the option off while a served domain’s DMARC record asks receivers to quarantine or reject. Other authentication failures never reject a message. A From: naming several domains is evaluated, and can be rejected, for each of them (up to 10). With YES, a message from an unauthenticated session to which DMARC cannot be applied is rejected as well: one with no From: address (550 5.6.0) and one whose From: names more than 10 domains (550 5.7.1). A failing message is accepted instead when a sealer listed in ARC_TRUSTED_SEALERS vouches for its ARC chain.

EXTERNAL_SUBJECT_TAG

(boolean, optional, default ``YES``) Put TAG_EXTERNAL at the front of the Subject of a message from an unauthenticated session when its From: claims a served domain without a DMARC, aligned DKIM or aligned SPF pass, when its Sender: claims one without an aligned DKIM or SPF pass, when its From: cannot be read one way only or names several domains, or when its DMARC fail was not acted on. Before that, remove copies of the tag from the front of every inbound subject, judged as a mail client renders it, so that a sender cannot write the tag. A message without a Subject gets one. The X-Pepsi-Warning fields (from-ambiguous, served-domain-not-authenticated, served-sender-not-authenticated, dmarc-fail-not-enforced) and state.auth.warnings are written either way. See pepsi-ingress(1), Marking mail from outside.

TAG_EXTERNAL

(string, optional, default ``[external]``) The tag that EXTERNAL_SUBJECT_TAG writes, trimmed. The documented [external] is removed from inbound subjects even when this is something else, since a sender forging the documented tag is forging an indicator that a reader may have seen elsewhere. An empty value turns the tag off.

ARC_TRUSTED_SEALERS

(string, optional) Whitespace- or comma-separated domains whose ARC chain (RFC 8617) overrides a DMARC failure under DMARC_ENFORCE. List the mailing-list hosts and forwarders that you know to break DMARC for the mail that they relay, and that you trust to have authenticated that mail when they received it. A message that fails DMARC is accepted when its ARC chain validates (cv=pass, recomputed from the signatures, never read from the chain’s own cv= tag) and the d= of the ARC-Seal with the highest instance is listed here (compared lower-cased, without a trailing dot). That seal comes from the ADMD that sealed last, the only one whose signature covers the message as received. The sealer is recorded as state.auth.arc_override; state.auth.dmarc still reads fail. A chain sealed last by anyone else, one that does not validate, or none at all leaves the rejection in place. Default empty: an unknown sealer proves nothing. The chain of every message refused under DMARC_ENFORCE is checked whatever the list holds, and the refusal is logged with its last sealer — arc-sealer=<domain> for a chain that validates, a claimed sealer for one that does not — so the log names the forwarders and lists to consider for this option. Has no effect without DMARC_ENFORCE, which pepsi-ingress(1) warns about at start.

MIME_ANOMALIES

(string, optional) What to do with a message whose MIME structure is ambiguous, or whose message header carries differing copies of a field that RFC 5322 allows only once. An ambiguous structure is a shape whose reading RFC 2045/2046 leave to the parser, so that a filter scans something other than what the client shows. enforce (the default) refuses the hard classes with 554 5.6.0: an empty boundary=, a NUL in a MIME header, conflicting duplicate Content-Type or Content-Transfer-Encoding fields, an RFC 2047 encoded-word as boundary, and differing Date, Subject, To, Reply-To or Sender fields. It marks differing Cc fields with X-Pepsi-Warning: duplicate-header-cc. It rewrites the soft classes to the one reading that the standards mandate: an unknown transfer encoding, whitespace after a quoted-printable soft break, non-alphabet base64 characters, a missing close delimiter, a delimiter line of the multipart’s boundary after its close delimiter (the epilogue, which RFC 2046 says to ignore, is dropped), and identical duplicate fields. The rewrite happens before the message is stored, never inside a signed or encrypted part, after SPF/DKIM/DMARC and before the ARC seal (a message carrying an ARC chain is rewritten by pepsi-stage-arc(1) instead, once it has verified the chain). log counts and logs the classes and stores the message as received, marking every differing header field X-Pepsi-Warning: duplicate-header-<field>. Both record the classes as state.mime_anomalies. See pepsi-ingress(1), “Ambiguous MIME structure”, for the classes and the measured base rate.

IPREV_ACTION

(``none`` or ``reject``, optional) How ingress treats a client whose reverse DNS definitely fails to validate (RFC 8601 iprev=fail: its address has a PTR name that does not resolve back to it, or none at all). none (the default) records the verdict in state.origin.iprev and the Received: header only: broken reverse DNS is evidence about the sender’s DNS, not about its message, and small sites have it. reject refuses every recipient but postmaster with 550 5.7.25 (RFC 7372) on an unauthenticated session of a listener that is not a submission listener; a temperror or permerror never refuses.

DNS_SERVERS

(string, optional) The resolvers used for the SPF/DKIM/DMARC lookups, in the syntax of [pepsi] DNS_SERVERS (plain addresses, or tls:// / https:// entries). If unset, [pepsi] DNS_SERVERS applies, and without that the system resolver configuration (/etc/resolv.conf).

DNS_TIMEOUT

(duration, optional) Per-query timeout for those lookups. Defaults to [pepsi] DNS_TIMEOUT, else 5 s. Because verification runs synchronously while receiving DATA, a slow resolver delays the 250 acceptance.

It applies only when a DNS_SERVERS list names the resolvers (this section’s or [pepsi]’s). Without one the system resolver configuration is used whole, timeout included, so this option has no effect and the options timeout:/attempts: lines of /etc/resolv.conf are what bound a query.

MAX_DKIM_SIGNATURES

(number, optional) How many DKIM-Signature fields of one inbound message are verified; the ones whose d= is the From: domain or a parent or child of it are taken first. Defaults to 10.

VERIFY_TIMEOUT

(duration, optional) Deadline on inbound verification: SPF and the selected DKIM signatures are checked concurrently under it, then DMARC under a second one. A check that misses it is recorded as temperror for that check only. Defaults to 20 s.

DISPATCH_WAKE_INTERVAL

(duration, optional) Minimum spacing between two NOTIFYs telling pepsi-dispatch(1) that new mail has arrived. Defaults to 5 ms; 0 disables coalescing and notifies once per accepted message.

Ingress does not notify from inside the transaction that stores the message. PostgreSQL holds a database-wide lock from the moment a transaction queues a notification until it commits, so notifying transactions cannot group-commit — under concurrent load they serialise, each paying its own disk flush. Admissions are therefore notified out of band, once per interval, after the rows have committed; because the dispatcher answers any wake-up with a full scan of the queue, one notification serves an arbitrary number of newly accepted messages.

The limit is trailing: the first wake-up after an idle period is sent immediately, so a lone message is not delayed at all, and only notifications behind it are merged. Raising it means fewer notifications under sustained load, at the cost of a little worst-case queue latency; there is rarely a reason to do so.

MILTERS

(optional) The milters consulted during the SMTP session, by the names of their [pepsi-ingress-milter-*] sections, separated by spaces or commas, in the order they are asked. It applies to every listener that is not a submission listener; a listener section’s own MILTERS replaces it for that listener. none (the default) consults none. See The [pepsi-ingress-milter-*] Sections below and pepsi-ingress(1), Milters.

The ARC sealing identity and algorithm are configured in the shared [pepsi] section (ARC_DOMAIN and ARC_ALGORITHM) above and used by pepsi-stage-arc(1), not by ingress.

95.2.1.1.15. The [pepsi-ingress-listener-*] Sections

Each section whose name begins with pepsi-ingress-listener- defines one listening socket. The suffix is a free-form name used in log messages, e.g. [pepsi-ingress-listener-mx]. Declare as many listeners as required.

SERVE

(required) The kind of socket to bind. One of:

tcp

Bind a TCP socket. Requires BIND_TO and PORT.

unix

Bind a UNIX-domain socket. Requires UNIXPATH; honours UNIXPATH_MODE and UNIXPATH_GROUP.

systemd

Adopt a socket passed by a systemd parent through socket activation; see FD_INDEX.

BIND_TO

(string) IP address to listen on when SERVE = tcp, e.g. 0.0.0.0 or ::. Required for tcp.

PORT

(number) TCP port to listen on when SERVE = tcp. Required for tcp.

UNIXPATH

(path) Filesystem path of the socket when SERVE = unix. Required for unix.

UNIXPATH_MODE

(unix mode, optional) Permission bits of the UNIX-domain socket, in octal. Defaults to 660.

UNIXPATH_GROUP

(string, optional) Group to which the UNIX-domain socket is chgrped after binding (the owner is unchanged). Combined with the default 0660 mode this lets a specific peer reach the socket while it stays non-world-accessible — used when pepsi-httpd runs behind a front web server (e.g. www-data) that reverse-proxies to it. The group must exist; an unknown group is a startup error.

FD_INDEX

(number, optional) Zero-based index of the systemd-passed file descriptor to adopt when SERVE = systemd. Index 0 is the first descriptor (SD_LISTEN_FDS_START). Defaults to 0.

It is a position, not a name: it counts ListenStream= entries in the owning .socket unit, so inserting one renumbers every listener after it while appending one renumbers nothing. The unit and these sections are two halves of one statement and nothing checks that they agree at configuration time, so a mismatch is reported where the descriptors actually are: the server logs a warning at start-up naming every index that no listener claimed. Take the warning seriously: a socket on which the server never accepts is worse than an absent one, because systemd still queues the connection and the client blocks until its own read timeout expires instead of being refused at once.

A descriptor may be a UNIX-domain socket as readily as a TCP one; the unit decides which it is, not this file. Options that depend on the socket’s family are therefore resolved once the descriptor is in hand rather than while parsing: AUTH_PEERCRED must be stated explicitly (it cannot be inferred as it is for SERVE = unix), and a plaintext SUBMISSION listener that turns out to have inherited a network socket makes pepsi-ingress(1) refuse to start rather than carry credentials in the clear.

MODE

(optional) Transport security of the listener. One of:

plain

Cleartext only; STARTTLS is not advertised. This is the default.

tls

Implicit TLS: the connection is wrapped in TLS from the first byte (e.g. the submissions port 465). Requires TLS_CERT and TLS_KEY.

starttls

Cleartext that may be upgraded with the STARTTLS command. Requires TLS_CERT and TLS_KEY.

TLS_CERT

(path) PEM file containing the server certificate chain. Required when MODE is tls or starttls — but may be omitted, in which case pepsi-setup(1) auto-fills the certbot path /etc/letsencrypt/live/<HOSTNAME>/fullchain.pem and can obtain the certificate (see pepsi-setup(1) and its –no-certbot option).

TLS_KEY

(path) PEM file containing the private key for TLS_CERT. Required when MODE is tls or starttls; like TLS_CERT it may be omitted for pepsi-setup(1) to auto-fill (…/privkey.pem).

MYNETWORKS

(optional) Whitespace/comma separated list of trusted IPv4/IPv6 CIDR networks (a bare address is a /32 or /128 host). A connection from any of these is authenticated without further proof, and may relay and send as the addresses to which [pepsi-ingress] SENDER_MAP binds the network. Every entry outside loopback (127.0.0.0/8, ::1) must be covered by a SENDER_MAP network key, or pepsi-ingress refuses to start and pepsi-setup(1) validate fails; a loopback entry is unrestricted. Empty by default. pepsi-setup(1) warns about an entry wider than a single host that is not loopback.

AUTH_PEERCRED

(optional, default ``yes`` on a ``SERVE = unix`` listener, ``no`` elsewhere) Authenticate the client by its kernel-reported UNIX-socket peer credentials (SO_PEERCRED): the connecting process’s user id is resolved to a login through the passwd database, and that login is looked up in USERNAME_MAP exactly as a SASL username would be. The session is then authenticated and carries a submission identity, so the RFC 6409 §6/§8.1 rules apply: a local program can only use an envelope sender and From: that its own account is mapped to, and an account mapped to no address is refused.

This is the mechanism behind pepsi-sendmail(1) and the reason the socket may safely be world-writable: being able to open it decides nothing about who you can send as. Unlike MYNETWORKS, which trusts a network position and therefore lets any local process send as anyone, the identity here is supplied by the kernel and cannot be forged by the client.

Rejected on a SERVE = tcp listener, where there are no peer credentials to read. Set it to no for an unauthenticated local socket (for instance behind a proxy) — but such a listener cannot then also be a SUBMISSION listener, since nothing would authenticate.

With SERVE = systemd it is accepted but not inferred, and so must be written out: whether the inherited descriptor is a UNIX socket or a TCP one is a property of the .socket unit rather than of this file, and the shipped pepsi-ingress.socket passes both kinds. If the descriptor turns out to be a TCP socket, the option authenticates nobody, because SO_PEERCRED has no meaning there and every session stays anonymous. That failure is safe but silent, so pepsi-ingress(1) warns at start-up, naming the listener.

SASL_TYPE

(optional) SASL backend for the AUTH command: none (default) or dovecot. AUTH (mechanisms PLAIN and LOGIN) is advertised and accepted only on a TLS-protected session; a cleartext AUTH is refused with 504 5.5.4 (RFC 4954 §4 – the 538 of RFC 2554 is deprecated), and AUTH on a listener with no backend with 503 5.5.1. Any value other than none requires MODE tls or starttls.

SASL_PATH

(path) Path of the Dovecot auth-client socket. Required when SASL_TYPE is dovecot — there is no default, and a listener that asks for dovecot without it fails to parse. The path that pepsi-setup proposes, /run/dovecot/auth-client-pepsi, is a Pepsi-private listener rather than Dovecot’s shared auth-client socket: the latter is 0600 dovecot and unreachable by the unprivileged pepsi-ingress user, so pointing this at it gives a submission listener whose AUTH always fails with a permission error. pepsi-setup run probes this socket as the service user and, if it is missing or unreadable, offers to install a /etc/dovecot/conf.d/10-pepsi.conf that adds a dedicated listener owned by pepsi-ingress (or prints it for you to deploy).

TLS_AUTH_CLIENT

(optional) Whitespace/comma separated list of SHA-256 hashes (64 hex characters) of the DER SubjectPublicKeyInfo of authorised client keys. When set, the listener requests a client certificate: a session is authenticated if the presented leaf’s key hash is listed and [pepsi-ingress] SENDER_MAP binds that pin to the addresses that it may send as; the pin is the key, and the certificate around it is not consulted. A hash that names a CA in the presented chain authorises nothing (a CA goes in TLS_AUTH_CLIENT_CA, whose constraints can be checked). An unrecognised certificate does not abort the handshake. A certificate is requested only from a client that can negotiate TLS 1.3 (see TLS_AUTH_CLIENT_TLS12). Requires MODE tls or starttls. Compute a hash with openssl x509 -in cert.pem -noout -pubkey | openssl pkey -pubin -outform DER | openssl dgst -sha256.

TLS_AUTH_CLIENT_CA

(path, optional) PEM file of CA certificates whose client certificates authenticate. A presented certificate is accepted when it builds a full RFC 5280 path to one of them (validity, basicConstraints and path length, the CA’s own included, key usage, name and policy constraints, key strength); when it carries an extendedKeyUsage naming id-kp-clientAuth and the digitalSignature bit; when it is not revoked, with every certificate of the path that names a distribution point covered by a current list (the lists that pepsi-keydisc(1) keeps in pepsi.crl_cache; with no list at hand the certificate is not accepted, and a submission listener answers 451 4.7.0 at MAIL FROM until the list is fetched); and when [pepsi-ingress] SENDER_MAP binds the CA’s key hash (logged at start-up) to the addresses that its certificates may send as. A certificate that names a mailbox is confined to those of its mailboxes that the binding permits. Each certificate in the file must be a currently valid CA permitted to sign certificates, or the configuration is refused. Requires MODE tls or starttls. See pepsi-ingress(1), Client certificates.

MILTERS

(optional) The milters this listener consults during the SMTP session, separated by spaces or commas, in order; none consults none. When unset, a listener that is not a submission listener runs [pepsi-ingress] MILTERS and a submission listener (the local submission socket included) runs none. A name without a [pepsi-ingress-milter-*] section stops ingress from starting.

TLS_AUTH_CLIENT_TLS12

(boolean, optional, default ``no``) On a listener with TLS_AUTH_CLIENT or TLS_AUTH_CLIENT_CA, a client certificate is requested only when the client offers TLS 1.3, which encrypts the certificate; TLS 1.2 sends it in the clear, and with it the person or device that it names. A TLS 1.2 client is still served, without a certificate request (logged at info), so it can authenticate with SASL or not at all. yes requests the certificate under TLS 1.2 as well, for a device that speaks nothing newer.

SUBMISSION

(optional, default ``no``) When yes, the listener is an RFC 6409 message submission agent: authentication becomes mandatory (an unauthenticated MAIL FROM is refused with 530 5.7.0), and every accepted message gets the submission fixups — a missing Date: and Message-ID: are added. Requires at least one authentication mechanism (SASL_TYPE, TLS_AUTH_CLIENT, TLS_AUTH_CLIENT_CA, MYNETWORKS or AUTH_PEERCRED); a submission listener with none is rejected. Leave it off for an MX listener (port 25). A submission listener also withholds the submitting client from the trace header by default (RECEIVED_PRIVACY).

A TLS MODE is required too, except on a SERVE = unix listener (or a SERVE = systemd one that inherits a UNIX socket, checked at start-up): a filesystem socket has no transport that an attacker could observe or interpose on, and its authentication comes from the kernel rather than from the wire, so requiring a certificate there would protect nothing.

RECEIVED_PRIVACY

(optional, default: the value of **SUBMISSION*)* When yes, the Received: trace header written for every message accepted on this listener carries no from clause, and the client’s User-Agent and X-Mailer header fields are removed. The header then holds neither the client’s IP address and reverse name nor the name that it announced in EHLO, which is usually the user’s machine name. Every recipient, and every list archive, would otherwise learn the submitter’s address and software from a message they sent; this is the privacy-sensitive convention of draft-josefsson-email-received-privacy, which large providers follow on submission. The by clause, the RFC 3848 protocol keyword, the TLS parameters, the for clause and the date stay, so loop detection (MAX_SELF_HOPS, which counts the by clause) and the transport record are unaffected, and the journal of pepsi-ingress(1) still records the client for abuse handling. On by default for a submission listener, the implicit local submission socket included; off for an MX listener, where the trace of a remote peer is what abuse handling at the next hop needs. Set it explicitly to turn either around.

A session accepted by any of MYNETWORKS, AUTH_PEERCRED, SASL AUTH or a client certificate (TLS_AUTH_CLIENT, TLS_AUTH_CLIENT_CA) is recorded with state.local_origin = true (otherwise false) and may relay to any domain, not only the served domains.

95.2.1.1.16. The [pepsi-ingress-exchange-online-*] Sections

Each section whose name begins with pepsi-ingress-exchange-online- names one Microsoft 365 (Exchange Online) tenant whose outbound mail this host relays, for example [pepsi-ingress-exchange-online-example]. The suffix is a free-form name used in log messages and recorded in state.exchange_tenant.

Exchange Online sends through an outbound connector to port 25, from addresses that every Microsoft 365 customer shares, and it cannot authenticate to the smart host. MYNETWORKS cannot tell this tenant from any other, so it would let every customer send as the served domains. Instead, a client in SENDER_NETWORKS whose envelope sender is empty or at one of DOMAINS may name recipients outside the served domains on an MX listener (one that is not a submission listener). At the end of the data the message is relayed only if all of the following hold, and refused with 550 5.7.1 otherwise:

  • the header carries exactly one X-MS-Exchange-CrossTenant-Id field, and its value is TENANT_ID. Exchange Online adds that field to every message, naming the tenant that sends it, but it keeps a copy that the sender wrote, so a message from another tenant that claims this one has two;

  • the message has exactly one From: mailbox, at one of DOMAINS;

  • a DKIM signature by that From: domain verified. This needs DKIM signing for the domain in Microsoft 365 (the selector1 and selector2 records).

A proven message is treated like a submission from then on (state.local_origin = true, state.origin.auth_method = exchange-online). It does not speak for its From: address, so it cannot register or operate keys by e-mail. Mail that the tenant forwards for an outside sender carries no signature by the tenant’s domains and is not relayed. A message whose recipients are all in served domains is ordinary inbound mail and needs no proof.

TENANT_ID

(required) The tenant id, as shown in the Microsoft Entra admin centre (eight, four, four, four and twelve hexadecimal digits).

DOMAINS

(required) The domains the tenant may send as, separated by spaces or commas. Each must be one of [pepsi-ingress] ACCEPTED_DOMAINS.

SENDER_NETWORKS

(optional) The networks from which the tenant’s mail arrives, separated by spaces or commas. The default is the list of Exchange Online outbound addresses that Microsoft publishes in the SPF record spf.protection.outlook.com: 40.92.0.0/15, 40.107.0.0/16, 52.100.0.0/15, 52.102.0.0/16, 52.103.0.0/17, 104.47.0.0/17, 2a01:111:f400::/48, 2a01:111:f403::/49, 2a01:111:f403:8000::/51, 2a01:111:f403:c000::/51 and 2a01:111:f403:f000::/52. The proof rests on this list: only mail that really arrives from Exchange Online carries the tenant field that Microsoft writes, so never add an address that anybody else can send from.

95.2.1.1.17. The [pepsi-ingress-milter-*] Sections

Each section whose name begins with pepsi-ingress-milter- names one milter (a mail filter speaking the sendmail/Postfix milter protocol) that pepsi-ingress(1) consults during the SMTP session, for example [pepsi-ingress-milter-greylist]. The suffix is the name that MILTERS lists. Because the milter answers while the client is still connected, its refusal is the SMTP reply: a 5xx refusal is reported by the sending MTA to its own user, and a 4xx refusal is retried by it, which is how greylisting works. Nothing is accepted that would later have to be bounced. How the session is presented to a milter, and what each verdict does, is described in pepsi-ingress(1), Milters. A milter that runs after the message was accepted is a pepsi-stage-milter stage instead (pepsi-stage-milter(1)), which sees the message after decryption.

SOCKET

(required) Where the milter listens, in the syntax that sendmail’s S= and Postfix’s smtpd_milters use: unix:/path (or local:/path), inet:host:port, inet:port@host, or inet6:[address]:port.

MILTER_NAME

(optional) The value of the {daemon_name} macro; defaults to the section’s suffix.

ALLOW_ACTIONS

(optional) The modifications the milter may make, as for pepsi-stage-milter(1): addhdrs, chghdrs, chgbody, addrcpt, addrcpt_par, delrcpt, chgfrom, quarantine, or all / none. The default is addhdrs chghdrs chgbody quarantine: everything a content filter needs, and no change to the envelope. A milter that needs an action it was not offered fails its negotiation, which ON_FAILURE then handles, and the log names the missing action. A recipient that a milter adds is subject to the rule every RCPT is: an address at a served domain that something on this host would accept, or any address on an authenticated session; anything else is dropped and logged, so a filter cannot turn the host into an open relay. quarantine is offered only when a quarantine stage exists (QUARANTINE_STAGE). Some filters ask for more than they use: rspamd, for one, asks for addrcpt, delrcpt and quarantine as well as the header and body actions, and is refused without them. pepsi-setup writes what a detected filter asks for.

QUARANTINE_STAGE

(optional) The stage at which a message the milter quarantines is stored, instead of init. The default is the one stage running pepsi-stage-quarantine(1), when there is exactly one; without such a stage, quarantine is not offered to the milter. The message records state.quarantine.reason (the milter’s text) and state.quarantine.by (milter:<name>).

ON_FAILURE

(optional, default ``accept``) What a milter that cannot be reached, times out or breaks the protocol costs: accept consults it no more for the rest of the session, and the mail is accepted as if it were not configured (logged, and counted in telemetry); tempfail answers the current command and every later MAIL of the session with 451 4.7.1; reject answers them with 550 5.7.1. accept follows the stance of ingress everywhere else: a filter that has crashed must not stop all inbound mail. Choose tempfail for a filter whose verdict must never be skipped; the sending MTAs then keep the mail until the filter is back.

CONNECT_TIMEOUT, COMMAND_TIMEOUT, CONTENT_TIMEOUT

(durations, optional, defaults ``30 s``, ``30 s`` and ``300 s``) As for pepsi-stage-milter(1): connecting and negotiating, waiting for the reply to one command, and waiting for the end-of-message verdict (SMFIR_PROGRESS restarts the wait, up to ten times the timeout). The SMTP client waits as long; RFC 5321 gives it ten minutes for the reply to the end of the data, so keep CONTENT_TIMEOUT well below that.

PROTOCOL_VERSION

(optional, default ``6``) The highest milter protocol version offered.

MACROS_CONNECT, MACROS_HELO, MACROS_MAIL, MACROS_RCPT, MACROS_DATA, MACROS_EOH, MACROS_EOM

(optional) The macros sent at each phase, defaulting to Postfix’s lists (milter_connect_macros and the others); none sends none at that phase. A milter that asks for its own list with SMFIF_SETSYMLIST is sent that instead. Ingress knows j, _, v, i (the token of the row the message will be stored as), {daemon_name}, {daemon_addr}, {if_addr}, {if_name}, {client_addr}, {client_port}, {client_name}, {client_ptr}, {tls_version}, {cipher}, {auth_type}, {auth_authen}, {auth_author}, {auth_ssf}, {mail_addr}, {mail_host}, {mail_mailer}, {rcpt_addr}, {rcpt_host} and {rcpt_mailer}; any other is not sent.

95.2.1.1.18. The [pepsi-greylist] Section

Read by pepsi-greylist(1), the greylisting milter, by pepsi-status(1) and by pepsi-setup(1) validate. Every option and its default is described in pepsi-greylist(1): SOCKET, SOCKET_MODE, SOCKET_GROUP, DELAY, RETRY_WINDOW, PASSED_TTL, AUTO_WHITELIST_PASSES, AUTO_WHITELIST_TTL, IDENTITY, IPV4_MASK, IPV6_MASK, DNS_TIMEOUT, DNS_CACHE_TTL, DNS_SERVERS, EXEMPT_RECIPIENTS, RECIPIENT_DOMAINS, WHITELIST_BYPASS, WHITELIST_NAME (with LOCAL_DOMAINS, RECIPIENT_DELIMITER and TARGETS, as a whitelist stage reads them), BIG_SENDERS, SPF_BYPASS, REPLY, DB_POOL_SIZE and MAX_CONNECTIONS. Durations there may be written in days and weeks.

95.2.1.1.19. The [pepsi-greylist-senders-*] Sections

One section per group of senders that is never greylisted, [pepsi-greylist-senders-NAME], with DOMAINS (the client’s identity domain or forward-confirmed PTR name), NETWORKS (the client address) and ENABLED. The groups that ship are in ${DATADIR}/config.d/greylist.conf; see pepsi-greylist(1).

95.2.1.1.20. The [pepsi-reputation] Section

Read by pepsi-reputation(1), which downloads the IP blocklists against which inbound mail is checked and checks whether this host is on one, and by pepsi-setup(1).

CACHE_DIR

(path, optional) Where rsync keeps its copy of each rsync list, so that the next download transfers only the difference. Defaults to /var/lib/pepsi-reputation, the state directory of pepsi-reputation-iplists.service.

CHECK_IP_ZONES

(string, optional) The DNS blocklists that pepsi-reputation check asks about this host’s own addresses. Defaults to zen.spamhaus.org bl.spamcop.net b.barracudacentral.org psbl.surriel.com bl.mailspike.net dnsbl-1.uceprotect.net ix.dnsbl.manitu.net; none asks none.

CHECK_DOMAIN_ZONES

(string, optional) The domain blocklists that it asks about the served domains. Defaults to dbl.spamhaus.org multi.surbl.org.

CHECK_ADDRESSES

(string, optional) Addresses to check besides the PUBLIC_IP of every pepsi-stage-relay-to-internet stage and the addresses of [pepsi-ingress] HOSTNAME.

GOOGLE_SITE_VERIFICATION

(string, optional) DOMAIN:TOKEN pairs, the tokens that Gmail Postmaster Tools hands out per domain. pepsi-setup(1) prints each as a google-site-verification=TOKEN TXT record for the domain and checks that it is published.

95.2.1.1.21. The [pepsi-reputation-list-*] Sections

One section per IP blocklist, [pepsi-reputation-list-NAME]; NAME is lower-case letters, digits and -. pepsi-reputation iplists update downloads each enabled list whole into the database; pepsi-ingress(1) looks the client of every unauthenticated session up there, records the lists naming it under state.origin.ip_blocklist (see pepsi.state(7)) and, for a list with ACTION = reject, refuses the session’s recipients. No list operator is asked about a client while it is connected.

${DATADIR}/config.d/reputation.conf defines spamhaus-drop-v4, spamhaus-drop-v6 and blocklist-de-mail (enabled) and uceprotect-1 (rsync, disabled), all with ACTION = mark. Change one of their options by naming the section in pepsi.conf; the later definition wins option by option.

URL

(string) https://…, or rsync://HOST/MODULE/FILE (one file, printable ASCII). Required, except in the section of a shipped list, where it and FORMAT default to the shipped values, so that a section that only sets ENABLED works even where config.d is not installed. An rsync list needs the rsync program, an optional dependency: on a host without it the list is not used, its entries are removed, and pepsi-setup(1) warns.

FORMAT

(string, optional) ip-list (default): one entry per line, as rbldnsd’s ip4set/ip6trie datasets or a plain address list have it – an address, a network, a range (a.b.c.d-e.f.g.h or a.b.c.d-h) or rbldnsd’s short form (a.b.c for a /24), an exclusion with a leading !. spamhaus-drop: Spamhaus DROP’s JSON lines. Entries wider than a /8 (IPv4) or a /16 (IPv6) are dropped, and a file of which more than a tenth is not entries is refused.

ENABLED

(boolean, optional) Whether the list is downloaded and consulted. Defaults to YES.

ACTION

(string, optional) mark (default) records the listing for the pipeline; pepsi-stage-if(1) can route on origin.ip_blocklist.listed or origin.ip_blocklist.lists.NAME. reject also refuses the recipients with 554 5.7.1, except <postmaster>.

MIN_INTERVAL

(duration, optional) The least time between two downloads of the list. Defaults to 45 m. List operators lock out hosts that download too often (UCEPROTECT: more than four files an hour).

MAX_AGE

(duration, optional) How long after its last successful check ingress still consults the list. Defaults to 12 h. An older list is treated as unknown, which admits mail and records nothing.

MAX_SIZE

(integer, optional) The largest list file accepted, in bytes. Defaults to 67108864 (64 MiB).

95.2.1.1.22. The Stage Pipeline and [stage-*] Sections

After ingress, a message is advanced by a chain of stage programs. pepsi-dispatch(1) claims a pending row, sets it running and hands the message id to a persistent worker process of that stage. The worker is started as PROGRAM [-c FILE] worker, reads ids on its standard input, one per line, and answers each with one status line; it does its work and advances the row (or finishes it). There is no positional-id invocation: a PROGRAM that is a wrapper script must therefore forward its arguments and its standard input. New messages enter at the initial stage, [stage-init], which must exist.

Each section whose name begins with stage- describes one stage. The suffix is the stage name, e.g. [stage-init]. The stage name is an operator-chosen label, independent of the binary that it runs.

PROGRAM

(string, required) The stage binary to run, e.g. pepsi-stage-relay-to-smarthost. It is located on the PATH unless given as an absolute path. The same binary may serve several stages (it reads its options from whichever section the message is currently at).

NEXT_STAGE

(string, optional) The stage that a message advances to on success. With none, a successful terminal stage removes the message.

BOUNCE_STAGE

(string, optional) The stage to which a message is routed so that a delivery-status notification is generated. For delivery stages (pepsi-stage-relay-to-smarthost(1), pepsi-stage-relay-to-internet(1)) and pepsi-stage-discard(1) it receives a permanently-failed (non-bounce) message for a bounce, and — when [pepsi] ORIGINATE_SUCCESS_DSN is enabled — a successfully-delivered message for a positive report. With none, a permanently-failed message is marked failed (delivery stages) or simply dropped (pepsi-stage-discard(1)).

PARALLELISM

(number, optional) Upper bound on the number of concurrent worker processes pepsi-dispatch(1) runs for this stage. Workers are started on demand and stopped when idle, so this is a ceiling, not a fixed pool size. Each worker holds one database connection, so this also bounds the stage’s share of the connection budget (see the [pepsi-postgres] note above). Default 4. The dispatcher temporarily lowers a stage below this value when the database reports that its connection limit is exhausted (see pepsi-dispatch(1)).

MAX_RUNTIME

(duration, optional) Maximum real time a worker of this stage may spend on a single message. It replaces [pepsi-dispatch] MAX_RUNTIME for this stage, so that a slow hop gets time without loosening every other stage. The pepsi-stage-relay-to-* stages end a delivery a little earlier, by a tenth of this time (between 1 s and 30 s), to keep the time to store its outcome: the replies already read stand, and the rest is deferred like any transient failure. pepsi-setup(1) refuses a CONNECT_TIMEOUT, COMMAND_TIMEOUT or DATA_TIMEOUT that does not fit into that time, including one that is left at its default.

MAX_MESSAGES

(number, optional) Number of messages that a worker of this stage handles before the dispatcher retires it and starts a fresh process (bounding memory growth). Default 1000.

QUEUE_LIMIT

(number, optional) Upper bound on the number of messages pepsi-dispatch(1) pipelines to a single worker process of this stage at once. The worker still processes them strictly one at a time, but having the next ids already queued on its standard input removes a coordinator round-trip per message, so the stage’s total in-flight capacity is QUEUE_LIMIT × PARALLELISM. Because the worker count (and thus the connection budget) is unchanged, raising this gains throughput without spending more database connections, at the cost of a little head-of-line latency (a message can wait behind a slower pipelined sibling on the same worker); lower it (e.g. to 1) for a stage whose per-message work is long and uneven, such as a network relay. Default 4.

MAX_LIFETIME

(duration, optional) How long a message may keep failing at this stage before the worker gives up, counted from when the message was queued (for a DSN, from when pepsi-stage-bounce(1) built it). This covers any error that the stage does not mark permanent, which is to say a fault of the host rather than of the message, such as an unreadable resolver configuration, a helper that cannot be started or a template that cannot be read. Until then the message is paused and retried, after one minute and then twice as long each time, up to an hour, with the error in state.last_error. Then it is rerouted to this stage’s BOUNCE_STAGE, or failed when there is none or the message is a member’s copy of a list post (see pepsi-dispatch(1)). The delivery stages and pepsi-stage-milter(1) read the same option for their own retries. Default 120 h.

FUSION = yes | no

(optional) Whether a predecessor stage may run this stage in its own worker process instead of writing the row pending and waiting for the dispatcher to claim it (stage fusion; see [pepsi] ALLOW_FUSION above and pepsi-dispatch(1)). Fusion happens only when it is also globally enabled, this stage’s PROGRAM is folded into the unified pepsi binary, and this stage needs no message column that the predecessor has not already loaded. When any of these does not hold, fusion is refused and the advance falls back to a normal dispatched hop, which is always safe. Defaults to no for every program except the fast, body-free routing and classification stages, for which it defaults to yes: pepsi-stage-if(1), pepsi-stage-discard(1), pepsi-stage-srs(1), pepsi-stage-check-whitelist(1), pepsi-stage-auto-whitelist(1), pepsi-stage-block-language(1), pepsi-stage-list(1), pepsi-stage-edit-settings(1) (which is body-free for every message that is not a control message, i.e. effectively all of them), pepsi-stage-dmarc-report(1) (body-free for all mail not addressed to its report address) and pepsi-stage-defang(1) (body-free for every recipient who has not turned it on). Two of those need the header block rather than the envelope alone, so each fuses only into a predecessor that has already loaded it: pepsi-stage-block-language(1), whose ENFORCEMENT = soft path rewrites the Subject:, and pepsi-stage-check-whitelist(1), which reads List-Id:. Listing a program here only sets the default of its FUSION option; whether a particular pair may actually fuse is decided per pair, at run time.

The remaining options in a [stage-<name>] section depend on its PROGRAM. The subsections below document the options that each stage program reads from its own section; a section reads only the keys listed for its PROGRAM plus the general keys above.

Some programs are the exception and are documented only in their own man pages, because their option sets are large and change with the delivery mechanism that they drive: pepsi-stage-relay-to-maildir(1) (whose SERVER_NAME is required — the stage refuses to start without it — plus HELPER, UNKNOWN_MAILBOX_STAGE, QUOTA_LIMIT_STAGE, the RETRY_* family, MAX_LIFETIME and the locality options LOCAL_DOMAINS, TARGETS and RECIPIENT_DELIMITER), pepsi-stage-relay-to-lmtp(1) (SOCKET or HOST/PORT, TLS, TLS_VERIFY, TLS_CA, TLS_CLIENT_CERT/TLS_CLIENT_KEY, AUTH, USERNAME, PASSWORD, SERVER_NAME, QUOTA_LIMIT_STAGE, SIEVE_REJECT_STAGE, UNKNOWN_MAILBOX_STAGE, LOCAL_DOMAINS, NOTIFY_STAGE, the timeouts and the RETRY_* family with MAX_LIFETIME and DELAY_DSN_AFTER), pepsi-stage-dot-forward(1) (HELPER, RESTART_STAGE, ALLOW_PIPE, ALLOW_FILE and the locality options) and the mailing-list stages pepsi-stage-list(1) (POST_STAGE, COMMAND_STAGE), pepsi-stage-list-post(1) (DELIVERY_STAGE, RESPONSE_STAGE, REMOVE_DKIM_HEADERS, SITE_HEADER_MATCH_CHAIN, SENDER_POSTS_PER_HOUR, MAX_HELD_MESSAGES), pepsi-stage-list-deliver(1), pepsi-stage-list-command(1) (RESPONSE_STAGE, MAX_COMMAND_LINES, REQUIRE_AUTHENTICATED) and pepsi-stage-list-bounce(1) (RESPONSE_STAGE), whose site-wide options are in [pepsi-list] below. Everything on this page about [stage-<name>] in general still applies to them. The shared sections that these programs also draw on are documented elsewhere on this page: [pepsi] (signing identity), [pepsi-srs] (the SRS engine), [pepsi-payments] (the merchant backend) and the smarthost [pepsi-stage-relay-to-smarthost-mta-*] sections.

95.2.1.1.22.1. pepsi-stage-arc Options

A stage with PROGRAM = pepsi-stage-arc reads, besides a required NEXT_STAGE, its DNS settings and the signature parameters of the ARC set it adds (these apply to the ARC-Message-Signature; the ARC-Seal is always relaxed-canonicalized over a fixed header set, per RFC 8617):

DNS_SERVERS

(string, optional) Resolvers, in the syntax of [pepsi] DNS_SERVERS, for the key lookups that validate the inbound ARC chain (SPF, DKIM and DMARC were verified by pepsi-ingress(1) and are not re-run here). When unset, [pepsi] DNS_SERVERS applies, and without that the system resolv.conf.

DNS_TIMEOUT

(duration, optional) Per-query DNS timeout. Default [pepsi] DNS_TIMEOUT, else 5 s.

HEADER_CANONICALIZATION

(``relaxed`` | ``simple``, optional) Header canonicalization of the AMS (the left half of c=). Default relaxed.

BODY_CANONICALIZATION

(``relaxed`` | ``simple``, optional) Body canonicalization of the AMS (the right half of c=). Default relaxed. ARC supports any combination of the two.

SIGNATURE_EXPIRATION_DAYS

(integer, optional) When set to a positive number of days, the AMS carries an expiration (x=) that many days after signing. Unset (the default) emits no expiration. The ARC-Seal has no x= tag in RFC 8617 and never carries one, whatever this option says.

SIGNED_HEADERS

(string, optional) Whitespace/comma-separated list of headers that the AMS covers (h=). Must include From. Defaults to the built-in originator/MIME header set plus DKIM-Signature, so the DKIM signatures whose results the AAR records cannot be stripped or replaced behind the seal. Every field but DKIM-Signature is listed twice, so a copy of it added after the seal breaks the set. DKIM-Signature is listed once and signed only on a message that carries one: naming an absent field in h= would over-sign it, and a DKIM signature added after the seal (by pepsi-stage-dkim-sign on a forwarded message, say) would then break the set.

The ARC signing identity and algorithm come from the shared [pepsi] section (ARC_DOMAIN, ARC_ALGORITHM); the key is held, and the seal signed, by pepsi-dkim(1). The hash is always SHA-256; the signature algorithm (a=) is the single [pepsi] ARC_ALGORITHM choice, since ARC permits one signature per hop.

95.2.1.1.22.2. pepsi-stage-srs Options

A stage with PROGRAM = pepsi-stage-srs needs only a NEXT_STAGE in its own [stage-<name>] section; all its parameters (SRS_DOMAIN, SECRET/SECRET_FILE, MAX_AGE_DAYS, ALLOW_ALIGNED_DOMAIN) live in the shared [pepsi-srs] section documented above, so they are identical to ingress’s reverse-decode.

95.2.1.1.22.3. pepsi-stage-encrypt Options

A stage with PROGRAM = pepsi-stage-encrypt signs locally submitted mail as its From: author and encrypts it to each recipient. It reads, besides a required NEXT_STAGE and an optional BOUNCE_STAGE:

Warning

Place this stage before the DKIM-signing stage, not after: … → encrypt → srs → dkim-sign → relay. DKIM must sign the bytes that are actually transmitted, and this stage rewrites the body. Signing first yields mail that looks valid but whose signature does not verify. That is worse than no signature, because a broken one is a stronger negative signal to a receiver than an absent one. pepsi-setup(1) warns when it finds a DKIM-signing stage that leads to this one.

The pay-to-send gate and language detection both read the message body and both want cleartext; on the outbound path they run before this stage, which is why encryption is last.

Every option below is behavioural and is per-address overridable through the pepsi.settings table (pepsi-settings(1)), keyed for outbound mail on the envelope sender. The cryptographic policy — algorithms, downgrade permission, minimum key sizes — is in [pepsi]’s CRYPTO_* options and [pepsi-crypto], is system-administrator-only, and is deliberately not reachable from here.

ENABLE_PEP

(boolean, optional) Behave like the pretty Easy privacy (pEp) project: every local sender at a served domain gets a key on their first message, mail is encrypted whenever a recipient key is known or discoverable, and the sender’s key goes out with every message. Default YES.

A preset of defaults, not a forcing mode: it changes the default of SIGN to encrypted-only and turns on eager key creation. Any option written out explicitly still wins. With ENABLE_PEP = no, SIGN defaults to opportunistic and keys are created only on an explicit request (signing or encrypting) or under SIGN = always. Eager creation additionally needs [pepsi-crypto] AUTO_CREATE_IDENTITY (the operator’s veto, which no per-address override reaches) and a KEY_WRAP_SECRET, and happens only for an address at a [pepsi-ingress] ACCEPTED_DOMAINS domain that has no crypto_identity row of any kind. A user may opt out with ENABLE_PEP = no in their own pepsi.settings override where EDITABLE_STAGES allows. No pEp wire format is produced: no X-pEp-Version header, no pEp 2.x wrapping, no trustwords and no key sync. See pepsi-stage-encrypt(1).

SIGN

(``no`` | ``encrypted-only`` | ``opportunistic`` | ``always``, optional) Whether to sign with the From: author’s key. Default encrypted-only under ENABLE_PEP, else opportunistic.

encrypted-only signs only a message that this stage encrypts, inside the ciphertext; cleartext mail carries the sender’s key but no signature, so a recipient who does not use cryptography never sees a signature.asc. An explicit request (X-Pepsi-Sign: yes, a [sign] subject keyword) still signs cleartext. opportunistic signs when the author has usable material, otherwise sends unsigned. always signs the same way and additionally has an identity created for an author who has none, under the same conditions as the eager creation of ENABLE_PEP (AUTO_CREATE_IDENTITY, a KEY_WRAP_SECRET, a served domain, no identity of any kind), unless X-Pepsi-Sign: no refused the signature. None of these values is a guarantee: an author that this deployment does not serve is sent unsigned rather than bounced. A message that the submitting client already signed gets no second signature from Pepsi, and one that the client already encrypted is left alone entirely.

ENCRYPT

(``no`` | ``opportunistic`` | ``required``, optional) Default opportunistic: encrypt to a recipient for whom we have a usable key, and send ordinary mail to one for whom we do not. required means a recipient with no usable key gets the secure link or a bounce, never cleartext.

PREFER

(``openpgp`` | ``smime``, optional) Which protocol to reach for when a correspondent has usable keys of both on the same rung of the trust ladder. A better-ranked key of the other protocol always wins, so a key harvested from unsigned mail never overrides a directory’s, DANE’s, the operator’s or an authenticated message’s certificate of the other protocol. Default openpgp; pgp is accepted as a synonym for it.

ON_NO_KEY

(``cleartext`` | ``secure-link`` | ``bounce``, optional) What happens to a recipient with no usable key. Defaults from ENCRYPT: cleartext for no/opportunistic, and for required either secure-link (when SECURE_LINK_STAGE is set) or bounce. Setting it explicitly overrides that — except that a message whose own request raised the policy to required never falls back to cleartext.

Caution

ON_NO_KEY = cleartext together with [pepsi] CRYPTO_ALLOW_DOWNGRADE = no sends plaintext to a correspondent who cannot read an authenticated container. That is strictly worse than the SEIPDv1+MDC or AES-256-CBC EnvelopedData that the option was set to avoid. Most of the OpenPGP installed base (GnuPG 2.4 and older) is in that position, and so is every S/MIME correspondent whose capability record says it cannot read AuthEnvelopedData. pepsi-setup(1) warns about the pair. Leave the option at its default negotiate, which downgrades rather than refuses, and only when the recipient’s own key (OpenPGP) or capability record (S/MIME) shows they must.

ON_OVERSIZE

(``cleartext`` | ``secure-link`` | ``bounce``, optional) What happens to a message larger than MAX_SIZE. Defaults exactly like ON_NO_KEY, so required does not become cleartext because an attachment was large.

PADDING

(boolean, optional) Pad what this stage encrypts to a Padmé length, so the ciphertext’s size says less about the message: an observer learns the length only to within a bucket that grows with it, at most 12 % of overhead. Inside a SEIPDv2 container this is an RFC 9580 padding packet after the signature; SEIPDv1 and S/MIME, which have no padding that a reader skips, carry a Pepsi-Padding: filler header field on the encrypted MIME entity instead. Default yes. Turn it off only for a reader that has been measured to mishandle one of the two.

MAX_SIZE

(number, optional) The largest message, in bytes, that this stage encrypts. Default 25000000 (25 MB). Neither the CMS builder nor the OpenPGP paths stream, so the whole message is resident while it is encrypted, once per recipient; a visible cap keeps the memory ceiling of each worker predictable instead of letting PARALLELISM workers each hold a multi-hundred-megabyte message.

MIN_TRUST

(``own`` | ``manual`` | ``dane`` | ``wkd-advanced`` | ``wkd-direct`` | ``ldap`` | ``vks`` | ``owner-confirmed`` | ``inbound-signed`` | ``harvested`` | ``gossip`` | ``any``, optional) The lowest-ranked key source that this stage encrypts to. Defaults to [pepsi-keydiscovery] MIN_TRUST, so a deployment has one floor unless it deliberately wants two. See The [pepsi-keydiscovery] Section for the ranking, for why the default floor accepts anything, and for the difference between harvested and gossip.

SUBJECT_KEYWORDS_SIGN, SUBJECT_KEYWORDS_ENCRYPT, SUBJECT_KEYWORDS_BOTH

(comma-separated list, optional) Keywords that a sender may put anywhere in the Subject to ask for protection. Defaults [sign], [encrypt] and [secure]. Matched case-insensitively; the matched keyword is removed from the outgoing Subject. An encryption keyword raises the policy to required for that message — reading a deliberate human request as “try, and quietly give up” would make the feature a lie. Commas, not spaces, separate the list, because a keyword may legitimately contain a space.

STRIP_REQUEST_HEADERS

(boolean, optional) Remove every X-Pepsi-* field from the outgoing message. Default YES. The two headers that this stage acts on (X-Pepsi-Sign, X-Pepsi-Encrypt) are removed unconditionally, whatever this option says: a control channel that survives onto the wire is one that the next hop can be told to obey. This option decides only the fate of the other X-Pepsi-* fields that an add-in may have added. Pepsi-Origin is not in that namespace and is never touched.

PROTECT_HEADERS

(boolean, optional) Copy the RFC 5322 header fields (From, Sender, To, Cc, Reply-To, Subject, Date, Message-ID, In-Reply-To, References; never Bcc) into the protected part with a protected-headers="v1" parameter (RFC 9788 injected headers) and, on an encrypted message, replace the outer Subject with ... (which is what Thunderbird implements for PGP/MIME); a message that is only signed keeps its outer Subject. The protected From: is what lets pepsi-stage-decrypt(1) at the receiving end notice a signed message re-sent under another author, and the protected To: and Cc: put the recipients inside the signature for a client that does not read Pepsi’s own recipient attribute. Default NO: an encrypted message’s subject reads ... in a client that cannot look inside the protected part.

AUTOCRYPT

(boolean, optional) Advertise the From: author’s own OpenPGP key in an Autocrypt: header. Default YES, and on every locally submitted message — signed, encrypted or plain cleartext — because a correspondent has to learn the key from ordinary mail before there is anything to encrypt with.

The key is reduced to the minimal five-packet form of Autocrypt Level 1 §2.1.1. Only OpenPGP is advertised (Autocrypt has no S/MIME form), only for an identity that still holds its private material, and never on a message that already carries an Autocrypt: field: a real client’s own header names the key with which it can decrypt, and a second field makes Level 1 parsers discard both. prefer-encrypt=mutual is claimed only when the effective ENCRYPT is required; see pepsi-stage-encrypt(1).

Nothing is advertised when the address’s public face is the user’s own MUA key (custody = client), or on a message the client already encrypted: the mail client advertises its own key.

Turn it off to keep key publication to the Web Key Directory and DNS, which is a defensible choice for a deployment that does not want its users’ keys travelling on every message that they send.

ATTACH_KEYS_AS_FILES

(boolean, optional) Also attach the sender’s public key as an application/pgp-keys file named OpenPGP_0x<long key ID>.asc, the classic OpenPGP way, in addition to the Autocrypt: header. Default NO, independent of ENABLE_PEP; an operator who wants the file only sets AUTOCRYPT = no as well.

On an encrypted message the file goes inside the ciphertext; on cleartext the message is wrapped in a multipart/mixed (or the key is added to an existing one). It is attached until every recipient provably holds the key – they sent back a message encrypted to it and signed by them, recorded in pepsi.peer_has_own_key – and starts again for a new key. Never when the public face is the user’s own MUA key, never on mail the client encrypted, and not on cleartext the client signed.

KEYS_CONTROL_LOCAL_PART

(string, optional) Local part of the address at which a user operates their own keys by e-mail: a locally submitted message whose only recipient is <KEYS_CONTROL_LOCAL_PART>@<served domain> is a command (status, generate, register, publish [FPR], retire FPR, pin FPR, otp enroll, otp confirm CODE, otp remove in the Subject:), consumed and answered at RESPONSE_STAGE. Every command but status is refused under a reply or forward prefix (Re:, Fwd:, AW:, …). Default pepsi-keys; none switches the surface off. Needs RESPONSE_STAGE.

OTP_CONFIRM_WINDOW

(duration, optional) How long a second factor set up by e-mail (otp enroll) waits for its owner to confirm it with a code (otp confirm) before it lapses; until then a second factor already in force stays in force. The enrolment reply’s Expires: header names the end of this window. Default 1h.

RESPONSE_STAGE

(stage name, optional) Where the replies to the e-mail key commands and the “a new key was registered for your address” notices are injected, as new null-sender messages. Normally the outbound DKIM-signing stage, which is what pepsi-setup –wizard writes (dkim-sign). Unset means no notices and no e-mail commands (control mail is then sent on like any other message); pepsi-setup(1) warns about that, refuses a name that is not a stage, and requires the key-registered.en.body and keys.en.body fallback templates when it is set.

AUTOCRYPT_GOSSIP

(boolean, optional) Advertise the other recipients’ OpenPGP keys in Autocrypt-Gossip: fields (Autocrypt Level 1 §5.3), so that two correspondents who have never written to each other can nevertheless answer each other encrypted after one message. Default NO.

Off by default because it is not the same kind of act as AUTOCRYPT: that one publishes a key that its owner asked this deployment to hold, while this one redistributes third parties’ keys, material that is merely cached here, to correspondents who did not ask for them.

It applies only to a message this stage actually encrypts, and the fields go inside the ciphertext, never on the outer header block: their whole purpose is to introduce the recipients to each other without disclosing the recipient set to the network. There is therefore no gossip on the cleartext pass-through, on a signed-but-unencrypted message, or on an S/MIME container (Autocrypt is defined over OpenPGP and has no S/MIME form). One field is emitted per introduced recipient (unlike Autocrypt:, where a second field makes a Level 1 parser discard the message), and prefer-encrypt never appears, since it states the sender’s own policy and this field speaks for somebody else.

Warning

Blind carbon copies are never gossiped. The addresses advertised are read from the message’s parsed To: and Cc: fields and from nowhere else; the envelope recipient list is consulted only to remove an address from the set. A Bcc recipient is on the envelope and in neither field, so no copy of the message can carry a header naming them. This is the property to rely on, because a gossip header for a blind recipient would tell every other recipient that a hidden one exists and who it is. This holds even if a Bcc: field was left on the message by a broken submitting client, because the field is not read.

The converse is deliberate: a blind recipient’s own copy does carry gossip about the To:/Cc: recipients. They received those header fields like everyone else, so it discloses nothing they cannot already read, and it is what lets them reply encrypted.

A recipient for whom this deployment holds no cached key is simply left out: the stage performs no key discovery on their behalf and never delays a message to fetch a third party’s key. A message with more than 50 visible recipients gets no gossip at all: at that size it is a broadcast rather than a conversation, each introduced key is repeated in every recipient’s own ciphertext, and introducing an arbitrary subset would be worse than introducing none.

GOSSIP_MIN_TRUST

(``own`` | ``manual`` | ``dane`` | ``wkd-advanced`` | ``wkd-direct`` | ``ldap`` | ``vks`` | ``owner-confirmed`` | ``inbound-signed`` | ``harvested`` | ``gossip`` | ``any``, optional) The lowest-ranked key source whose key may be republished in an Autocrypt-Gossip: field. Default owner-confirmed — the weakest rung at which somebody entitled to the address took a deliberate step to publish the key.

It is a real tightening over MIN_TRUST, and deliberately so: encrypting to a trust-on-first-use key is a good trade, because the alternative is cleartext, but handing that key to third parties is a different act. Everyone who receives a gossiped key stores it at a rung that they judge by our word, not by how we obtained the key, so passing on a guess turns it into something that looks like knowledge.

The floor actually applied is the stricter of this and MIN_TRUST: introducing a correspondent to a key that this stage would not itself encrypt to would be recommending something that the stage declined. So raising either option tightens gossip and lowering either cannot loosen it past the other, and an operator who hardens MIN_TRUST need not remember that a second option exists. GOSSIP_MIN_TRUST = any gossips every key that may be encrypted to. Has no effect unless AUTOCRYPT_GOSSIP is on.

SECURE_LINK_STAGE

(stage name, optional) Where a recipient taking the secure-link route is sent. Required if ON_NO_KEY/ON_OVERSIZE resolves to secure-link.

DISCOVERY

(boolean, optional) Whether a cache miss may trigger a network lookup; documented under The per-sender switch: [stage-encrypt] DISCOVERY.

DISCOVERY_TIMEOUT

(duration, optional) Override [pepsi-keydiscovery] TIMEOUT for the messages that this stage parks. Note that Section::duration() rejects calendar units: 90 s and 2 h parse, 1 d does not.

SUBJECT_KEYWORDS_CLEAR_OK

(comma-separated list, optional) Keywords with which a local sender accepts cleartext for a recipient whose key lookup failed in the DNS (see “Recipient DNS failures” in pepsi-stage-encrypt(1)). Default [clear-ok]. Matched and removed like the other keywords, honoured only for state.local_origin mail, and it never weakens ENCRYPT = required.

CLEAR_ON_DNS_FAILURE

(boolean, optional) The same acceptance as a standing setting, normally given per sender through pepsi.settings. Default NO: a recipient whose domain’s DNS does not answer is deferred and bounced at MAX_LIFETIME, and one whose key records keep failing while the domain answers goes to SECURE_LINK_STAGE or bounces, instead of being sent in clear.

DELAY_DSN_AFTER

(duration, optional) While a message is deferred on a recipient DNS failure, send its sender one “delayed” DSN once it has waited this long, but only if the sender asked for NOTIFY=DELAY and a BOUNCE_STAGE is set. Default 4 h.

NOTIFY_CLEARTEXT

(``no`` | ``author``, optional) Whether the author of a locally submitted message is told when it left unencrypted although encryption was wanted: a recipient with no usable key under ON_NO_KEY = cleartext, or a message over MAX_SIZE under ON_OVERSIZE = cleartext. With author, the stage injects one notice per such copy at RESPONSE_STAGE (null sender, to the From: address), naming the recipients and the reason; never for a message with a null sender or a list post. The keyless recipients of a message share one copy, so they share one notice. Default no; normally switched on per sender through pepsi.settings. Set here, it needs RESPONSE_STAGE (the worker refuses to start without it). Templates cleartext-notice.<lang>.body. Independently of this option, a subject that starts with a near miss of one of the SUBJECT_KEYWORDS_* (a misspelling, a look-alike letter, [encrypted]) is answered at RESPONSE_STAGE with a warning naming the keyword that it resembled (keyword-near-miss.<lang>.body).

NOTICE_SIGNER

(e-mail address, optional) The identity that signs every message that Pepsi composed itself, that is, the rows carrying state.notice (see pepsi.state(7)): sign-in and portal links, secretary challenges, payment requests, command replies, key-change and out-of-office notices. Signed only, never encrypted, in the first PREFER protocol the identity has, and sent From: that address (the previous From: becomes Reply-To: unless the notice set one). Unset (the default): such messages take the stage’s ordinary path, which changes nothing on mail without local_origin. Read from the configuration file only, never through pepsi.settings. Needs [pepsi-crypto] KEY_WRAP_SECRET (the worker refuses to start without it) and an identity created with pepsi-keys(1) identity generate, at a served domain so that the Web Key Directory publishes it; without one the notices wait and are retried. Usually set in a stage section of its own, at which the programs that emit notices point with their RESPONSE_STAGE, BLOCK_RESPONSE_STAGE, [pepsi-admin] ENROL_STAGE and [pepsi-secure-link] NOTIFY_STAGE options; see “Signing Pepsi’s own notices” in pepsi-stage-encrypt(1).

An author identity that this stage creates or registers is attributed to a passwd login through [pepsi-crypto]’s LOCAL_DOMAINS, TARGETS and RECIPIENT_DELIMITER, as pepsi-keys(1) attributes one, so the ownership rule of The [pepsi-crypto] Section does not depend on which program made the key. An address that resolves to no local account is a legitimate state (a role address or a hosted domain), not a failure. [pepsi-crypto] AUTO_CREATE_IDENTITY decides whether an identity may be created at all, and creation is offered only for an author in a [pepsi-ingress] ACCEPTED_DOMAINS domain.

The binary is installed setuid pepsi-crypto, mode 4750 pepsi-crypto:pepsi, because it must be the one database role that is granted crypto_identity.private_wrapped (peer authentication goes by the effective uid), and it must read the 0640 fragment that holds the key-encryption key and is owned by the same account. See pepsi-stage-encrypt(1).

95.2.1.1.22.4. pepsi-stage-decrypt Options

A stage with PROGRAM = pepsi-stage-decrypt decrypts mail addressed to recipients that this host serves and verifies whatever signature it carries. It reads, besides a required NEXT_STAGE and an optional BOUNCE_STAGE:

ENABLED

(boolean, optional) Whether to do any cryptography at all. Default YES. NO still removes the X-Pepsi-* header namespace from inbound mail: a disabled stage must not become a channel for a forged indicator.

LOCAL_DOMAINS, TARGETS, RECIPIENT_DELIMITER

(optional) Which recipients this host serves — the same options, with the same defaults, as pepsi-stage-relay-to-maildir(1) and pepsi-stage-dot-forward(1). LOCAL_DOMAINS defaults to [pepsi-ingress] ACCEPTED_DOMAINS.

REQUIRE_ACCOUNT

(boolean, optional) Whether a local recipient must additionally resolve to a passwd account permitted by TARGETS. Default NO, which is the difference from the delivery stages: they must know whose mailbox to write, while this stage only has to know whether the message is ours. A hosted domain whose users hold crypto identities but no shell accounts is an ordinary deployment.

ON_DECRYPT_FAILURE

(``passthrough`` | ``quarantine`` | ``bounce-if-unproblematic``, alias ``bounce``, optional) What to do with a message that this host could not open. Default passthrough: the user may hold the key in their own client, and bouncing mail we merely could not open helps nobody. quarantine needs QUARANTINE_STAGE; bounce-if-unproblematic needs BOUNCE_STAGE.

bounce-if-unproblematic bounces only a message whose failed ciphertext is integrity-protected (OpenPGP, S/MIME AuthEnvelopedData, judged from the ciphertext itself, not its label), where every modification fails alike, and its diagnostic names no reason (the reason is logged). Any other failed message is dropped without a trace that the sender could see: for an AES-CBC S/MIME message, which has no integrity protection, a DSN would be a padding oracle (an attacker who captured a ciphertext re-sends modified copies and learns from each DSN, or its absence, whether the modified padding was valid; about 2,000 such messages decrypt a 16-byte block). The value bounce is an alias for the longer but unambiguous bounce-if-unproblematic: the bounce is only sent on messages where the CBC oracle does not apply because the message is not encrypted with CBC; the worker and pepsi-setup(1) warn when the short spelling is used. pepsi-stage-decrypt(1) explains the choice.

ON_BAD_SIGNATURE

(``record`` | ``quarantine`` | ``bounce``, optional) What to do with a message whose signature did not verify. Default record: mailing lists that rewrite bodies, forwarders and clients with broken canonicalisation all produce bad signatures on entirely legitimate mail. Only the invalid verdict counts as bad here — valid-untrusted and unverifiable are the normal state of mail from an unknown correspondent and are never routed. bounce needs BOUNCE_STAGE, and drops rather than bounces a message whose signature came out of an S/MIME EnvelopedData container: whether a modified CBC ciphertext yields a plaintext that looks signed depends on its padding.

ON_MISSING_SIGNATURE

(``record`` | ``tag`` | ``quarantine``, optional) What to do with a message that arrives without a valid signature (unsigned, unverifiable, valid-untrusted or partial) from a From: address whose mail carried a valid signature by an anchored key within the last MISSING_SIGNATURE_WINDOW_DAYS. The stage records, per address, when such a signature last verified (pepsi.signed_sender); a forged From: of a correspondent who always signs then stands out even where DMARC is not enforced. Default record: the fact goes to X-Pepsi-Crypto (usually-signed=<date>) and state.crypto.in.usually_signed, for Sieve rules and the client extensions, and nothing else changes, because a correspondent writing from a phone or a new client produces exactly this shape. tag also prepends TAG_MISSING_SIGNATURE to the Subject; quarantine routes the message to QUARANTINE_STAGE. ON_BAD_SIGNATURE handles an invalid signature, and a message that was not opened here (a decryption failure, mail for the user’s own client key) is not judged.

MISSING_SIGNATURE_WINDOW_DAYS

(integer, optional) How long, in days, a valid signature from an address makes its unsigned mail stand out (ON_MISSING_SIGNATURE). Default 90. 0 turns the check off; signatures are still recorded.

MAX_SIGNATURE_AGE_DAYS

(integer, optional) How many days before the message’s arrival a signature may have been made and still earn valid. A signature made earlier, or more than a day after the arrival, verifies but is reported valid-untrusted (withheld=old-signature / future-signature): no [verified] tag, no state.signature_verified. This catches a captured signed message that is replayed under fresh outer headers. The arrival time is the one that this host recorded, never the sender-written Date:; a signature without a creation time (CMS without signingTime) is not judged. Default 7; 0 turns the check off. A site whose mail is often delivered late (a moderated list, an archive re-injected) raises it.

UNAUTHENTICATED_PLAINTEXT

(``text`` | ``require-signature`` | ``open``, optional) What becomes of a plaintext recovered from an S/MIME EnvelopedData container (AES-CBC, or 3DES where [pepsi] CRYPTO_ALLOW_DOWNGRADE admits it) when no valid signature inside the container covers it. Such a ciphertext has no integrity protection: whoever holds a copy can rewrite its plaintext block by block (EFAIL’s CBC gadgets) into HTML that sends the rest of the plaintext to their server as soon as a client renders it. Default text: the plaintext is delivered with every part that a client would render as markup (text/html, text/enriched, XHTML, inside attached messages too) relabelled text/plain, a multipart/alternative reduced to its plain alternative, and the Subject tagged TAG_UNAUTHENTICATED in place of TAG_DECRYPTED; the text arrives, nothing renders, and the HTML formatting of such mail is lost. require-signature passes such a message on unopened, still encrypted, for the user’s own mail client, which then sees the S/MIME container and applies its own EFAIL defences; unsigned CBC mail to a user without a client key arrives unreadable. It is not a decryption failure: ON_DECRYPT_FAILURE is not consulted. open delivers the plaintext as it came out of the container, markup included, tagged all the same. A signature over the plaintext counts whatever its key is worth (valid or valid-untrusted); one around the ciphertext does not, since an attacker re-signs a rewritten ciphertext with a key of their own. Content from an AEAD container (AuthEnvelopedData, every OpenPGP container Pepsi accepts) is never affected. See pepsi-stage-decrypt(1).

OPEN_ENVELOPED_DATA

(boolean, optional) Whether S/MIME EnvelopedData (AES-CBC, 3DES) is opened at all. Default YES: most S/MIME clients send nothing else. NO passes every such message on unopened for the user’s own mail client, as require-signature does with an unsigned one, without applying any private key to it: the container’s algorithm identifier is not authenticated, so the content key of a captured AES-GCM message sent without RFC 9709 key derivation can be re-submitted under a synthetic AES-CBC container, and with this off it is never applied to one. This is not a decryption failure: ON_DECRYPT_FAILURE is not consulted. A container using RFC 9709 id-alg-cek-hkdf-sha256 is key-separated by construction but is still an EnvelopedData and left unopened too. Set it per recipient address or domain with an address:/domain: overlay (pepsi-config(1)) to leave CBC to the clients of users whose correspondents send AuthEnvelopedData.

DECRYPTED_MARKUP

(``keep`` | ``text``, optional) What becomes of markup in a plaintext that this stage decrypted when UNAUTHENTICATED_PLAINTEXT has not already reduced it. Default keep: the plaintext is delivered as it came out of an authenticated container, HTML included, and remote content in it is left to the client’s own settings (see the manual’s chapter on mail clients). text relabels every markup part text/plain exactly as UNAUTHENTICATED_PLAINTEXT = text does (sanitised=text in X-Pepsi-Crypto), so no client fetches remote content for a decrypted message, at the price of its formatting; a signature over a relabelled part does not verify in the client.

QUARANTINE_STAGE

(stage name, optional) Where a quarantine route leads. Required if any policy above is set to quarantine.

SUBJECT_TAGS

(boolean, optional) Prepend the earned tags to the Subject in nesting order: encrypted(signed(body)) gives [decrypted][verified] … and signed(encrypted(body)) would give [verified][decrypted] …. Default YES: for most users this is the only signal that they will ever see. The cost is a mutated user-visible field, which affects search, threading and quoted subjects in replies. (Both shapes open. The second earns [verified] only from a signature inside the ciphertext: an outer signature covers ciphertext and never reaches the valid verdict for which the tag is written; see pepsi-stage-decrypt(1).)

TAG_DECRYPTED, TAG_VERIFIED, TAG_UNAUTHENTICATED

(string, optional) The tag wording. Defaults [decrypted], [verified] and [decrypted, unauthenticated]; none writes no tag (an empty value reads as unset). TAG_VERIFIED is written for the valid verdict only, and the address to which the signer is bound goes inside its closing bracket ([verified: alice@example.org]; a spelling without a closing bracket gets the address appended after a colon); TAG_UNAUTHENTICATED replaces TAG_DECRYPTED on a plaintext from a container without integrity protection that no signature covers (UNAUTHENTICATED_PLAINTEXT).

TAG_VERIFIED_EXCEPT_REPLY_TO

(string, optional) Written instead of TAG_VERIFIED when the signature is valid but the outer Reply-To: was added by a mailing list (List-Id present, no signed Reply-To:) and is covered by nothing. Default [verified (except reply-to)], the address inside as above.

TAG_BAD_SIGNATURE

(string, optional) The tag for the invalid verdict on a signature outside a ciphertext. Empty by default: a bad signature is a routine property of legitimate mail, so a default-on tag would decorate a large part of a user’s inbox with an accusation.

TAG_BAD_SIGNATURE_ENCRYPTED

(string, optional) The tag for the invalid verdict on a signature inside a ciphertext. Default [bad signature]: a mailing list cannot rewrite a body that it cannot read, so the reason why TAG_BAD_SIGNATURE is empty by default does not apply inside a ciphertext, and a replayed ciphertext would otherwise read [decrypted] as if it came from its signer. none turns it off (an empty value reads as unset).

TAG_UNVERIFIED_SIGNER

(string, optional) The tag for a signature inside a ciphertext that is sound but not valid: valid-untrusted, unverifiable or partial. Default [unverified signer], for the same reason. none turns it off. Outside a ciphertext those verdicts earn no tag.

TAG_MISSING_SIGNATURE

(string, optional) The tag that ON_MISSING_SIGNATURE = tag prepends to a message from a usually-signing address that arrived without a valid signature. Default [unsigned, usually signed].

STRIP_SUBJECT_TAGS

(boolean, optional) Remove anything that would display as a security indicator from the front of an inbound Subject before prepending ours. Default YES, and effectively mandatory: without it an external sender simply writes [verified] themselves. The vocabulary is derived from the TAG_* options plus their built-in defaults, the [verified: …] address form included whole however long the address, so renaming a tag cannot reopen the hole, and the comparison is made on the decoded subject with look-alike characters folded, so encoded-words, full-width brackets, Cyrillic letters and zero-width characters do not hide a tag either. Any leading bracketed group naming a security property ([secure], (signature OK)) is removed as well. pepsi-stage-decrypt(1) gives the full rule.

STRIP_SUBJECT_KEYWORDS

(comma-separated list, optional) Extra inbound subject tags to remove. Commas rather than whitespace, because a keyword may contain a space.

ADD_RESULT_HEADER

(boolean, optional) Add the X-Pepsi-Crypto result header to a message that carried protection. Default YES. Its grammar is documented in pepsi-stage-decrypt(1). Every X-Pepsi-* field is removed from inbound mail first, unconditionally and whatever this option says — that removal is what makes the header believable.

ISOLATE_ENCRYPTED

(boolean, optional) When a message carries ciphertext next to other content, make its first encrypted unit the message and move every other part into an inert attachment (application/octet-stream, disposition attachment), before anything is decrypted. Default YES. This avoids EFAIL direct exfiltration, both by this stage and by a recipient’s client that decrypts the message itself. Moved ciphertexts are opened into attachments too; beside a signed plaintext, only those signed by the same key are kept, and beside a PGP/MIME or S/MIME container that is not opened, the moved parts are dropped (see pepsi-stage-decrypt(1)). Switching it off delivers the message as it arrived.

ISOLATE_SIGNED

(boolean, optional) When a message without ciphertext carries signed content next to unsigned content, reduce it to its signed units. Default YES. A signature verdict then applies to everything that the user sees. Switching it off keeps mailing-list footers appended outside a signature, at the price that a stranger’s text beside a validly signed part reaches the user under the same [verified] tag.

MAX_LAYERS

(integer, optional) How many nested encrypted layers are unwrapped. Default 4. A message with more is delivered with the remainder unopened.

TRUST_ANCHOR_TTL

(duration, optional) How long a worker process reuses the ca_trust anchors that it last read. Default 5 m. An anchor added or disabled becomes effective within this window; restart the workers to apply it at once. Calendar units are rejected (5 m and 2 h parse, 1 d does not).

DISCOVERY

(boolean, optional) Whether a cache miss may trigger a network lookup; documented under The per-sender switch: [stage-encrypt] DISCOVERY. Read from this section by the same reader, so the two crypto stages cannot disagree about its name or its default.

DISCOVERY_TIMEOUT

(duration, optional) Override [pepsi-keydiscovery] INBOUND_TIMEOUT for the messages that this stage parks.

[pepsi] CRYPTO_ALLOW_DOWNGRADE does not gate this direction. OpenPGP SEIPDv1+MDC and CMS AES-CBC EnvelopedData are readable whatever the emission policy says (OPEN_ENVELOPED_DATA above is this stage’s own switch): refusing them inbound would make this host unable to receive mail from most of the world while protecting nobody. Only 3DES (with OpenPGP Blowfish beside it) and the weak signature digests are gated inbound, and each refusal produces its own verdict. UNAUTHENTICATED_PLAINTEXT decides what a plaintext from such a container may do once read.

The binary is installed setuid pepsi-crypto, mode 4750 pepsi-crypto:pepsi, for exactly the reasons given for pepsi-stage-encrypt(1) above. See pepsi-stage-decrypt(1).

95.2.1.1.22.5. pepsi-stage-reencrypt Options

A stage with PROGRAM = pepsi-stage-reencrypt takes a message that the decrypt stage opened and, before local delivery, seals it to the recipient’s own mail-client (MUA) key. It acts only on rows whose state.crypto.in says the message arrived encrypted and was decrypted. NEXT_STAGE is mandatory.

ON_NO_CLIENT_KEY

(string, optional) What happens to a local recipient with no usable MUA key: plaintext (default) files the plaintext; bounce refuses the message through BOUNCE_STAGE with a 5.7.5 DSN that carries only the addressing header fields and no body (RET=HDRS is forced). A message that the decrypt stage opened from an S/MIME EnvelopedData container (no integrity protection) is dropped instead: the bounce would go out only because the ciphertext opened, which for a modified AES-CBC ciphertext says whether its padding was valid. pepsi-setup refuses bounce without a BOUNCE_STAGE. Per-recipient overrides through pepsi.settings apply.

PROTECT_HEADERS

(boolean, optional) Copy the RFC 5322 fields inside the ciphertext and replace the outer Subject with .... Default NO, as for the encrypt stage: the copy is for the mailbox, whose server lists and searches by the outer subject.

ENABLED

(boolean, optional) When off, the stage passes every message through. Default YES.

LOCAL_DOMAINS, TARGETS, RECIPIENT_DELIMITER, REQUIRE_ACCOUNT

Which recipients are served here, as for pepsi-stage-decrypt Options. Other recipients are neither sealed nor refused.

The container follows [pepsi] CRYPTO_ALLOW_DOWNGRADE and the per-peer S/MIME capability record as for outbound encryption. The binary is unprivileged and folded into the multi-call pepsi binary: it seals to public keys and reads only the public columns of pepsi.crypto_identity. See pepsi-stage-reencrypt(1).

95.2.1.1.22.6. pepsi-stage-defang Options

A stage with PROGRAM = pepsi-stage-defang removes the remote references (images, style sheets, fonts, frames, url(), @import) from the HTML and CSS parts of a message outside any signature, keeping links, cid: parts and inline data: images, and marks a changed message X-Pepsi-Warning: remote-content-defanged. NEXT_STAGE is mandatory.

DEFANG

(string, optional) on or off (default off). Meant to be set per address through pepsi.settings; while it is off the stage passes the message on untouched. See pepsi-stage-defang(1).

95.2.1.1.22.9. pepsi-stage-dkim-sign Options

A stage with PROGRAM = pepsi-stage-dkim-sign reads, besides a required NEXT_STAGE and an optional BOUNCE_STAGE (where a message for a domain without keys here, or without a usable From:, is reported; without one such a message is failed):

HEADER_CANONICALIZATION, BODY_CANONICALIZATION

(``relaxed`` | ``simple``, optional) The two halves of the c= canonicalization. Both default to relaxed and may be set independently; all four combinations are valid for both DKIM signing and ARC sealing.

SIGNATURE_EXPIRATION_DAYS

(integer, optional) The signatures carry an expiration (x=) this many days after signing. Default 7: a replayed copy of the message, or one signed with a stolen key, stops verifying a week after signing, which still outlasts every receiver’s retry schedule. 0 emits no expiration.

SIGNED_HEADERS

(string, optional) Whitespace/comma-separated list of headers that the signatures cover (h=). Must include From. Defaults to the built-in originator/MIME header set plus List-Unsubscribe and List-Unsubscribe-Post, which RFC 8058 requires a DKIM signature to cover before a receiver may offer one-click unsubscription. Every field is listed twice in the default, so each is over-signed: a copy of one added later breaks the signature.

SIGNING_DOMAIN

(string, optional) Force the signing domain (d=). When unset, the domain is taken from the first mailbox of each message’s From: header, read strictly: a field that does not parse as an RFC 5322 mailbox-list in full yields no domain, and the message is refused rather than signed (see pepsi-stage-dkim-sign(1)). A fixed SIGNING_DOMAIN is a sending identity, so pepsi-setup(1) provisions its keys and DNS.

The keys are held, and the signatures made, by pepsi-dkim(1), whose selectors start with [pepsi] DKIM_SELECTOR; [pepsi] DKIM_ALGORITHMS picks the algorithms. The hash is always SHA-256; an RSA (rsa-sha256) and an Ed25519 (ed25519-sha256) signature are emitted, or only those that [pepsi] DKIM_ALGORITHMS names.

95.2.1.1.22.10. pepsi-stage-relay-to-internet Options

A stage with PROGRAM = pepsi-stage-relay-to-internet reads (a NEXT_STAGE and BOUNCE_STAGE are the general keys above):

SERVER_NAME

(string, required) Our own host name, announced in EHLO and written into the Received: trace header, e.g. mail.example.org.

EHLO_FROM_PTR

(boolean, optional, default no) With yes, the stage takes the name that it announces in EHLO from the reverse DNS of each connection’s local address. It asks for the PTR record of that address and announces the first name that is a host name and resolves back to the same address (forward-confirmed reverse DNS). When there is no such name, or the lookup fails, it announces SERVER_NAME, as without the option. Receivers such as Gmail and Microsoft compare the EHLO name with the PTR of the connecting address, and a fixed SERVER_NAME can agree with only one PTR. The option is meant for a host whose addresses have names that the address owner chose, for a host with several addresses, and for an IPv4 and an IPv6 address with different names. Each address is looked up once an hour (a failed lookup again after five minutes), through DNS_SERVERS. SERVER_NAME stays the name in the Received: header.

POSTMASTER

(string, optional) Address that receives a double bounce — a bounce (null sender) that is itself undeliverable. The row stays in the queue until a copy is delivered there: it is retried while the copy is deferred, and marked failed when the copy is refused or MAX_LIFETIME runs out. With none, such double bounces are discarded.

PUBLIC_IP

(string, optional) The public addresses from which this relay sends, read by pepsi-setup(1) to build the SPF record (and, for this stage, to check reverse DNS). This option of the relay stages is documented under The Egress Identity Option: PUBLIC_IP below.

CONNECT_TIMEOUT / COMMAND_TIMEOUT / DATA_TIMEOUT

(duration, optional) Per-connection timeouts for, respectively, establishing the TCP connection, an SMTP command/response, and the DATA transfer. Defaults 300 s / 300 s / 600 s.

RETRY_INITIAL / RETRY_MAX_INTERVAL / RETRY_FACTOR

(duration / duration / number, optional) Exponential-backoff schedule between delivery attempts of a transiently-failing message: the first wait, the cap on the wait, and the multiplier applied each attempt. Defaults 300 s / 2 h / 2.

MAX_LIFETIME

(duration, optional) How long a message may stay in the pipeline before a transient failure becomes permanent (it is then bounced or failed). Default 5 d of wall-clock, but the value must be written with h/m/s units — the duration parser rejects the d calendar unit (so write 120 h, not 5 d).

DELAY_DSN_AFTER

(duration, optional) When set, a one-shot Action: delayed DSN is sent to the sender once a still-undelivered message has been queued at least this long and the sender requested NOTIFY=DELAY. Must use h/m/s units. Unset (the default) disables delay warnings.

MAX_HOP_COUNT

(number, optional) Maximum number of Received: headers tolerated before the message is treated as a mail loop and permanently failed. Default 30.

DNS_SERVERS

(string, optional) Resolvers, in the syntax of [pepsi] DNS_SERVERS, for the MX, address and DANE lookups. When unset, [pepsi] DNS_SERVERS applies, and without that the system resolv.conf.

DNS_TIMEOUT

(duration, optional) Per-query DNS timeout. Default [pepsi] DNS_TIMEOUT, else 5 s.

MTA_STS

(boolean, optional) Whether to discover and enforce recipient-domain MTA-STS policies (RFC 8461). Default yes.

MTA_STS_TIMEOUT

(duration, optional) Timeout for fetching an MTA-STS policy file over HTTPS. Default 10 s.

ADDRESS_FAMILY

(optional) Which IP address families to use when connecting to mail exchangers: any (default), ipv4 (also spelled v4/v4only) or ipv6 (v6/v6only). The configured value is intersected with what the local host can actually route, so pinning a family the host has no route for leaves nothing to connect to. pepsi-stage-relay-to-smarthost(1) has the same option, additionally settable per MTA entry.

DANE

(optional) DANE/TLSA (RFC 7672) enforcement for the destination MX: off (no TLSA lookups), warn (an explicit opt-out: validate but, on a mismatch, log and deliver over TLS with the unverified certificate check that applies without DANE) or strict (the default, as RFC 7672 section 2.2 requires: a usable-but-mismatching record, or a failed TLSA or MX-security lookup, defers delivery — so a host whose resolver cannot answer TLSA queries needs warn or off). Requires a DNSSEC-validating resolver (Pepsi trusts the response AD bit; see DNS_SERVERS; a worker started with DANE on warns when that resolver is neither a loopback address nor reached over tls:// or https://); usable TLSA records take precedence over MTA-STS, except that warn never replaces the PKIX validation of an enforce MTA-STS policy. Where one usage and selector are published under both SHA-256 and SHA-512, only the SHA-512 records are matched (RFC 7671 section 9). In either mode a secure TLSA RRset makes STARTTLS mandatory for that MX (RFC 7672 section 2.2): a host that does not offer it defers the message.

95.2.1.1.22.11. pepsi-stage-relay-to-smarthost Options

A stage with PROGRAM = pepsi-stage-relay-to-smarthost reads the operational options below; the upstream smarthosts themselves are defined once in the shared [pepsi-stage-relay-to-smarthost-mta-*] sections (see The Smarthost (MTA) Sections below). A NEXT_STAGE and BOUNCE_STAGE are the general keys above.

SERVER_NAME

(string, required) Our own host name, announced in EHLO (unless an MTA overrides it with HELO_NAME) and written into the Received: header.

EHLO_FROM_PTR

(boolean, optional, default no) As for pepsi-stage-relay-to-internet: each connection announces the forward-confirmed PTR name of its local address, and SERVER_NAME when there is none. An MTA section that sets its own HELO_NAME keeps that name, because the operator chose it for that smarthost.

CONNECT_TIMEOUT / COMMAND_TIMEOUT / DATA_TIMEOUT

(duration, optional) Per-connection timeouts for the TCP connect, an SMTP command/response and the DATA transfer. Defaults 300 s / 300 s / 600 s.

RETRY_INITIAL / RETRY_MAX_INTERVAL / RETRY_FACTOR

(duration / duration / number, optional) Exponential-backoff schedule between relay attempts. Defaults 300 s / 2 h / 2.

MAX_LIFETIME

(duration, optional) How long a message may stay in the pipeline before a transient failure becomes permanent. Default 5 d of wall-clock, but write it with h/m/s units — the parser rejects the d calendar unit.

DELAY_DSN_AFTER

(duration, optional) When set, a one-shot Action: delayed DSN is sent once a still-undelivered message has been queued at least this long and the sender requested NOTIFY=DELAY. Must use h/m/s units. Unset disables it.

MAX_HOP_COUNT

(number, optional) Maximum number of Received: headers before the message is treated as a loop and permanently failed. Default 30.

POSTMASTER

(string, optional) Address that receives a double bounce, as for pepsi-stage-relay-to-internet(1) above. The copy has the null sender and takes the route of the address’s domain, so one of the [pepsi-stage-relay-to-smarthost-mta-*] sections must serve that domain.

ADDRESS_FAMILY

(optional) The address family every MTA entry inherits unless its own [pepsi-stage-relay-to-smarthost-mta-*] section overrides it: any (default), ipv4 (also v4/v4only) or ipv6 (v6/v6only). Same option, same spellings, as pepsi-stage-relay-to-internet(1)’s above.

PUBLIC_IP

(string, optional) The public addresses from which this relay sends, read by pepsi-setup(1) to build the SPF record. This option of the relay stages is documented under The Egress Identity Option: PUBLIC_IP below.

DNS_SERVERS

(string, optional) Resolvers, in the syntax of [pepsi] DNS_SERVERS, for the DANE TLSA lookups. When unset, [pepsi] DNS_SERVERS applies, and without that the system resolv.conf.

Consulted for every encrypting MTA entry whose DANE is not off (the default is strict); the resolver must validate DNSSEC, and a worker started with DANE on warns when it is neither a loopback address nor reached over tls:// or https://.

DNS_TIMEOUT

(duration, optional) Per-query timeout for the DANE TLSA lookups. Default [pepsi] DNS_TIMEOUT, else 5 s.

95.2.1.1.22.12. Bounce Stage Options

A [stage-<name>] section with PROGRAM = pepsi-stage-bounce additionally reads, from its own section:

SERVER_NAME

(string, required) Host name used in the generated bounce’s From: and Reporting-MTA fields and in its Message-ID domain, e.g. mail.example.org.

POSTMASTER

(string, optional) From: address of generated bounces (Mail Delivery Subsystem <POSTMASTER>) and the DKIM signing identity — the bounce is signed as this address’s domain, whose keys pepsi-setup(1) provisions. Defaults to postmaster@<SERVER_NAME>.

NEXT_STAGE

(string, required for this stage) The stage to which the rewritten bounce is advanced. Because the bounce is left unsigned, this is normally a pepsi-stage-dkim-sign(1) stage (which signs it as the postmaster’s domain), which in turn points at a delivery stage such as pepsi-stage-relay-to-internet(1).

BOUNCE_MESSAGE

(string, optional) Name of the template that renders the human-readable (text/plain) part of the bounce. The template file is bounce-<NAME>.<lang>.body under the [pepsi] TEMPLATE_DIR, and it is a Mustache template. <lang> follows the message’s state.language (the language detected in the original message, whose sender the bounce goes to) in its q order, falling back to bounce-<NAME>.en.body, which must exist. When the option is unset, or when rendering fails, a built-in English notice is used instead, so a bounce is always produced. Three template families are installed by make install: bounce-default, bounce-language (the language policy of pepsi-stage-block-language(1)) and bounce-payment (the unpaid gate of pepsi-stage-anti-spam(1)).

The whole message state except what the inbound crypto stages recorded (state.crypto, state.encrypted, state.signature_verified) is passed to the template as the rendering context, augmented with the convenience variables server_name, postmaster, bounce_to, failed_recipient, diagnostic, action and the booleans failed / delayed / delivered. In particular the delivery stage records structured next-hop detail under state.bounce — remote_mta, smtp_code, enhanced_status, phase and reply_text — so the template can state precisely why the next MTA refused the message. When a state.bounce.enhanced_status (RFC 3463) is present it is also used for the DSN’s machine-readable Status: field.

RET_FULL_MAX_SIZE

(integer, optional) The largest original message, in bytes, that a RET=FULL bounce returns in full. Default 262144 (256 KiB); 0 removes the limit.

RFC 3461 §6.2 says the full message “SHOULD be returned” when the sender set RET=FULL on MAIL FROM, and explicitly permits returning the headers alone when the message “exceeds some implementation-specified size” — so the limit is part of conforming behaviour, not an escape from it. Without one, a failed 40 MB message would become a 40 MB bounce sent to a sender who is already having a bad day. Above the limit the DSN falls back to text/rfc822-headers, exactly as a RET=HDRS (or absent-RET) bounce does, and the fallback is logged.

The body is fetched from the database only for a message whose sender asked for it and which is within the limit; an ordinary bounce still loads nothing but the header block.

A message that arrived encrypted is never returned in full, whatever RET says: the DSN quotes only its From, Sender, To, Cc, Date and Message-ID fields. See pepsi-stage-bounce(1).

BOUNCE_UNAUTHENTICATED

(``drop`` or ``send``, optional) What to do with a report addressed to an envelope sender that the inbound message did not authenticate. Default drop.

Spam forges its envelope sender, so a bounce for it goes to an innocent third party. That is backscatter: the recipients complain, and this host’s IP ends up on blocklists. Under drop a report is sent only when:

  • the message came from one of our own users (state.local_origin);

  • SPF passed for the envelope sender’s domain; or

  • an aligned DKIM signature passed for a From: domain that is the envelope sender’s domain, or a parent or child of it; or

  • a temporary DNS error stopped a check that could have shown one of these, and neither SPF nor DMARC failed outright. Only an error about the envelope sender’s own domain counts: SPF ending in temperror, or, with a From: at that domain, DMARC or a signature by that domain doing so.

Anything else is dropped and logged as a warning. A message that a stage created, rather than one that arrived over SMTP, carries no authentication record and is always reported. send reports to every sender, authenticated or not.

The failed recipient and diagnostic quoted in the bounce are taken from the state left on the row by the delivery stage that routed the message here (see BOUNCE_STAGE above). When there is no such state.bounce, because the message failed on this host (a stage error past MAX_LIFETIME or marked permanent, a crashed or hung worker, or a row that pepsi-failure-bouncer(1) moved here), the row is split into one row per recipient, each recipient’s own NOTIFY/ORCPT/RET from state.dsn is honoured, and the DSN carries a generic diagnostic chosen by state.failure_class; state.last_error is never copied into it. The DSN replaces the message’s state with retry_since, so the stages after this one count their MAX_LIFETIME from when the DSN was built.

95.2.1.1.22.13. pepsi-stage-discard Options

A stage with PROGRAM = pepsi-stage-discard deletes the message (a staging / test sink). It ignores NEXT_STAGE — a discard is always terminal — and reads:

DISPOSITION

(optional) The simulated outcome: success (default) treats the message as delivered; failure treats it as a permanent delivery failure.

BOUNCE

(boolean, optional) Whether the discard may emit a DSN at all. Default no.

BOUNCE_STAGE

(string, optional) The stage that generates the DSN, to which a reportable discard is routed (normally a pepsi-stage-bounce(1) stage). Without one, nothing is emitted and the row is just deleted.

The success path also consults the shared [pepsi] ORIGINATE_SUCCESS_DSN flag; a null-sender message is never bounced.

95.2.1.1.22.14. pepsi-stage-anti-spam Options

A stage with PROGRAM = pepsi-stage-anti-spam reads (besides a NEXT_STAGE):

BOUNCE_STAGE

(string, optional) The stage to which a message that is still unpaid at the deadline is routed: normally a pepsi-stage-bounce(1) stage (a rejection DSN, honouring the sender’s NOTIFY) or a pepsi-stage-discard(1) stage (silent drop). Without one, an unpaid message is just deleted.

BOUNCE_TARGET_STAGE

(string, optional) Where a returning bounce that carries no valid ``Pepsi-Origin`` proof is routed, that is, a message with the null sender that claims to report on mail of ours, although we cannot show that we originated that mail (see The [pepsi-origin] Section). Without one such a message takes the ordinary NEXT_STAGE path, past the payment gate: a null-sender message is never gated, since a bounce must not be bounced, so a forged bounce reaches the mailbox. pepsi-setup(1) --wizard therefore writes BOUNCE_TARGET_STAGE = discard-rejected, a pepsi-stage-discard(1) sink that it also emits, whenever it configures the stage (it always writes [pepsi-origin]): the forged bounce is dropped, with the verdict in the log. Point it at a quarantine or review stage instead to keep such messages for inspection: a legitimate bounce that quotes little of the original, has passed a header-stripping gateway or returns after the two-week nonce window cannot be verified either and is dropped by the sink. pepsi-setup(1) warns about a stage that leaves the option unset.

ORDER_CHOICES

(JSON, required) The Taler v1 order choices array, used verbatim: one or more OrderChoice objects describing the accepted payments (for example several amounts in different currencies, or token-family inputs/outputs). See the GNU Taler merchant API.

PAYMENT_DEADLINE

(duration, optional) How long the message is held paused awaiting payment before it is rejected; also the order’s pay_deadline. Uses h/m/s units only (calendar units such as d are rejected). Default 48 h.

DELAY_DSN_AFTER

(duration, optional) Send the sender a one-shot delayed delivery-status notification (RFC 3461) once a still-unpaid message has been held this long, without releasing the message — it stays paused until PAYMENT_DEADLINE. The DSN is sent only when the sender requested NOTIFY=DELAY and a BOUNCE_STAGE is wired (it is routed there with kind = delay), and only when that time falls strictly before PAYMENT_DEADLINE. Uses h/m/s units only. Unset (the default) disables delay warnings.

SUMMARY

(string, optional) Human-readable order summary shown to the payer. Default E-mail delivery.

FULFILLMENT_MESSAGE

(string, optional) Message shown to the payer after a successful payment. Default Your e-mail has been queued for delivery.

BLOCK_RESPONSE_STAGE

(string, optional) The stage at which the payment-request auto-reply is injected — usually the head of a signing/relay chain (for example a pepsi-stage-dkim-sign(1) stage). Must reference an existing stage. When unset, no reply is sent (the message is still paused awaiting payment).

BLOCK_RESPONSE_FROM

(string, optional) The From: header of the auto-reply. When unset it defaults to the original recipient (the protected mailbox).

BLOCK_RESPONSE_SUBJECT

(string, optional) The Subject: of the auto-reply. Default Payment required to deliver your e-mail.

BLOCK_RESPONSE_SUPPRESS

(duration, optional) The per-sender window for the auto-reply: a sender that was already sent a payment request for the same protected mailbox (the first envelope recipient) within this window gets no request for the next message, which is still held for payment all the same. The request goes to an envelope sender that nobody has verified, so without a window a flood of messages bearing one forged sender becomes the same flood of requests at that address. Claimed and recorded in one statement (payment_request_should_send over pepsi.payment_request_reply, the vacation_should_reply pattern), so two workers cannot both send one; rows are pruned as they age out. h/m/s units only (capped at a year); 0 s answers every message. Default 1 h.

REQUIRE_AUTHENTICATED

(boolean, optional) Send the payment request only to a sender whose envelope domain passed SPF or whose From: domain passed DMARC; the message is held for payment either way. Defaults to no: a definite fail never gets a request, but softfail, neutral, none and temporary errors do, so a sender at a domain that publishes neither record learns why its mail is held. yes closes the one way a forged envelope sender at such a domain can make this host mail an address of the forger’s choosing. Same option as in [stage-<vacation>] and [stage-<list-command>].

PAYMENT_MESSAGE_DEFAULT_LANGUAGE

(string, optional) The fallback language for the auto-reply body, used when the message carries no detected state.language or none of the detected languages has a payment-request.<lang>.body template (under [pepsi] TEMPLATE_DIR). That template must exist (pepsi-setup checks whenever BLOCK_RESPONSE_STAGE is set). Case-insensitive. Default en.

The stage also requires the shared [pepsi-payments] section (the merchant backend and access token, documented below) and, for the payment webhook to release paused messages, the [pepsi-httpd] RESUME_AUTHORIZATION_TOKEN (see pepsi-httpd(1)).

95.2.1.1.22.15. pepsi-stage-auto-pay Options

A stage with PROGRAM = pepsi-stage-auto-pay reads:

MAX_TOTAL

(amount, required) The largest amount that this stage spends, in total, to deliver one original message: a GNU Taler amount CURRENCY:VALUE (for example EUR:5). The cap is cumulative across every payment demand returning for that message (all sharing one Pepsi-Origin nonce, e.g. a mailing-list fan-out) and single-currency: a demand in any other currency is not paid. The operator can override it for one account with pepsi-settings(1); an account cannot change it by e-mail: pepsi-stage-edit-settings(1) refuses it, MAX_TOTAL_PER_DAY and the wallet selection however permissive its EDITABLE_STAGES is.

MAX_TOTAL_PER_DAY

(amount, required unless MAX_TOTAL is zero) The largest amount that one wallet may spend on payment demands in any 24 hours (a rolling window), across however many original messages. MAX_TOTAL does not provide this aggregate limit, since a correspondent who received k of our messages can demand MAX_TOTAL for each. The wallet follows WALLET_MODE/WALLET_SCOPE: a local user’s own wallet, the shared account’s per-sender wallet, or its one unified wallet (then the limit is the deployment’s). Never per correspondent: mailing lists and aliases make the demanding party unknowable. Must be in MAX_TOTAL’s currency. Enforced atomically with MAX_TOTAL by auto_pay_try_spend over the pepsi.auto_pay_spend ledger; a payment that fails to settle is credited back. A section with a non-zero MAX_TOTAL and no daily limit makes the worker refuse to start (and pepsi-setup(1) refuse the configuration): MAX_TOTAL bounds one message, so a stolen submission password would otherwise drain the wallet one message at a time.

NEXT_STAGE

(string, required) Where a message is forwarded when it is not a payment demand, is not provably ours, or is not paid (over budget / settlement failure). pepsi-setup(1) refuses a stage without one, or with one that names no stage.

WALLET_MODE

(``local-user`` | ``shared``, default ``shared``) Which account the wallet helper pays from. local-user drops to the bounce recipient’s own local login (the original sender) and uses that user’s default wallet — the recipient must resolve to a permitted local account (the LOCAL_DOMAINS/TARGETS/ RECIPIENT_DELIMITER test, as for pepsi-stage-relay-to-maildir(1)). shared drops to a single dedicated account (WALLET_USER).

WALLET_USER

(string, default ``pepsi-wallets``) The shared account to which the helper drops in WALLET_MODE = shared; its home holds the wallet database(s). Its primary group must be the group under which pepsi-helper-auto-pay(1) is installed (pepsi-wallets); the helper refuses any other account, so that root, not the configuration, decides which account runs the wallet.

WALLET_SCOPE

(``per-sender`` | ``unified``, default ``per-sender``) In shared mode, how the shared account’s wallet databases are segregated: one per original-sender address (per-sender), or a single wallet shared by everyone (unified — e.g. a business where individual wallets are not sensible).

WALLET_CLI

(ignored) The helper runs taler-wallet-cli (by default /usr/bin/taler-wallet-cli) and no other program; the path is fixed when Pepsi is built (make TALER_WALLET_CLI=… or ./configure --with-taler-wallet-cli=…). pepsi-setup(1) warns when the option is still set.

WALLET_PAY_OPTIONS

(string, default none) Extra arguments appended to the wallet’s pay invocation, whitespace-separated. The literal none passes no extra options. (--yes and --choice-index 0 are always added by the helper to confirm the payment and to name the contract choice it priced.) Nothing is needed here by default — the wallet’s handle-uri already waits for the payment to reach a terminal state.

HELPER

(string, default ``pepsi-helper-auto-pay``) The privileged wallet helper binary (a name on $PATH or an absolute path).

The following options enable and configure the wallet self-service role (a locally-submitted message to the control address operates the sender’s own wallet by e-mail; see pepsi-stage-auto-pay(1)):

RESPONSE_STAGE

(string, optional) The stage at which the self-service reply is injected (so it is DKIM-signed and relayed). Setting it enables the self-service role; leaving it unset means the stage only pays inbound demands.

CONTROL_LOCAL_PART

(string, default ``pepsi-wallet``) The local part of the wallet control address: a locally-originated message to <part>@<served-domain> is a wallet-control message.

RESPONSE_FROM

(string, optional) The From: of the self-service reply. Defaults to <{CONTROL_LOCAL_PART}@{domain}> for the served domain addressed.

RESPONSE_SUBJECT

(string, default ``Pepsi wallet``) The Subject: of the self-service reply.

A manual withdraw (top-up) names the GNU Taler exchange to withdraw from in the request (Subject: withdraw CURRENCY:VALUE EXCHANGE-URL); because a wallet is multi-currency and can withdraw from many exchanges, there is no server-side exchange option.

The stage also uses the shared [pepsi-origin] section (the proof-of-origin secret) to verify that a demand is for mail that this deployment actually sent; without it no demand can be verified and none is paid (self-service is unaffected). All wallet work is done by the setuid-root pepsi-helper-auto-pay(1); the stage binary is installed SGID pepsi-wallets so its worker may exec it.

95.2.1.1.22.16. pepsi-stage-check-whitelist Options

A stage with PROGRAM = pepsi-stage-check-whitelist reads:

WHITELIST_NAME

(list, required) The whitelist_name groups to consult in the pepsi.whitelist table — a comma-separated list, queried as one = ANY(...), not a single name.

An entry may be a template containing {localpart} or {login}, which is expanded per envelope recipient before the query: {localpart} is the sub-address-stripped, lower-cased local part, and {login} the passwd login that it resolves to. That is how a per-user namespace managed with pepsi-whitelist(1) — the <login>/segment names — is consulted without a per-address settings override. For example:

WHITELIST_NAME = correspondents, {localpart}/correspondents

consults the shared group and each recipient’s own.

LOCAL_DOMAINS, TARGETS, RECIPIENT_DELIMITER

(optional) The same locality options, with the same defaults, as the delivery stages — read here to resolve {login} (and to strip a sub-address for {localpart}), and to limit RECORD_LIST_CONFIRMATIONS to local recipients.

RECORD_LIST_CONFIRMATIONS

(boolean, optional) Record every inbound message that looks like a mailing list’s subscription confirmation request (a single Message-ID:, confirm in the Subject:, and a From:/Reply-To:/Sender: local part ending in -request, -confirm, -join or -subscribe) in pepsi.list_confirmation, once per local envelope recipient, so that pepsi-stage-auto-whitelist(1) can learn the list when that recipient answers it (its LIST_WHITELIST_NAME). Recording whitelists nothing. Default no.

LIST_CONFIRMATION_DAYS

(integer, optional) How many days a recorded confirmation request counts before pepsi-queue gc deletes it; a reply after that teaches nothing. 1 to 90; default 7.

NEXT_STAGE

(string, required) Where the message advances after the check (whether or not it matched). pepsi-setup(1) rejects a section without one, or one naming a stage that does not exist.

95.2.1.1.22.17. pepsi-stage-auto-whitelist Options

A stage with PROGRAM = pepsi-stage-auto-whitelist reads:

WHITELIST_NAME

(string, required) The whitelist_name group to populate in the pepsi.whitelist table. It should match the group that the inbound pepsi-stage-check-whitelist(1) consults. One literal name in the whitelist name grammar: this stage expands no {login}/{localpart} placeholder, so a value containing one is refused. The operator may name any whitelist, one shared by all local users included; a value that an account owner sets by mail through pepsi-stage-edit-settings(1) must name one in their own <login>/... namespace, or the one that the operator’s configuration names for them.

DKIM_REQUIRED

(boolean, optional) Value stored in the dkim_required column of every row that this stage inserts. Default yes.

DMARC_REQUIRED

(boolean, optional) Value stored in the dmarc_required column of every row that this stage inserts: a reply then matches only if it passed DMARC, on an aligned DKIM signature or an aligned SPF pass (or a trusted ARC sealer vouched for it). Implied by dkim_required; with DKIM_REQUIRED = no it is what keeps a correspondent whose domain does not sign bound to an authenticated identity. Default yes.

LIST_WHITELIST_NAME

(string, optional) Learn mailing lists. An outgoing, locally submitted message may answer a subscription confirmation request that pepsi-stage-check-whitelist(1) recorded (RECORD_LIST_CONFIRMATIONS) for this very sender: it is addressed to the request’s control address, and its In-Reply-To: names the request. The list’s List-Id is then whitelisted as an expiring list-id row in this whitelist. The value is a template that must start with {login}/ (for example {login}/lists), expanded for the envelope sender, so a list that one user joined is never whitelisted for anybody else. The row’s dkim_required is DKIM_REQUIRED and its dmarc_required DMARC_REQUIRED. Unset (the default): no lists are learnt. Add the same name to the check stage’s WHITELIST_NAME so that it is consulted.

LIST_MAX_IDLE_DAYS

(integer, optional) How many days a learnt list row stays in force without a matching posting; each authenticated posting that the check stage matches against it restarts the count. Leaving a list sends no signal, so this option retires the rows of lists that a user has left. 1 to 3650; default 180.

LOCAL_DOMAINS, TARGETS, RECIPIENT_DELIMITER

(optional) The same locality options, with the same defaults, as pepsi-stage-check-whitelist(1). They expand {login} in LIST_WHITELIST_NAME, and are read from the operator’s section when pepsi-stage-edit-settings(1) judges an account owner’s WHITELIST_NAME, to resolve the owner’s login and so their <login>/... namespace.

NEXT_STAGE

(string, required) Where the message advances after the recipients are recorded. pepsi-setup(1) rejects a section without one, or one naming a stage that does not exist.

95.2.1.1.22.18. pepsi-stage-autocrypt-learn Options

A stage with PROGRAM = pepsi-stage-autocrypt-learn reads:

LEARN_KEYS

(boolean, optional) Store the sender’s own key material found in the message (S/MIME signer certificates, application/pgp-keys parts and the Autocrypt: header) at the inbound trust rank, or inbound-signed when an aligned DKIM signature that passed at ingress covered it (see pepsi-stage-autocrypt-learn(1)), where it can never silently replace a better-sourced key. Default YES. Only material claiming the sender’s own address is kept. The same switch records the SMIMECapabilities that an S/MIME signature carries (the per-peer S/MIME capability record, keyed on the signing certificate). Turning it off makes the stage learn no key and no capability at all, LEARN_GOSSIP included; it still records that a correspondent holds one of our keys (pepsi.peer_has_own_key).

LEARN_GOSSIP

(boolean, optional) Also learn the other recipients’ keys from the Autocrypt-Gossip: fields inside a message that arrived encrypted (Autocrypt Level 1 §5.3), at the gossip rank — the bottom of the ladder, below inbound. Default YES; it does nothing unless LEARN_KEYS is also on.

This makes an encrypted reply-all possible to a correspondent from whom one has never had direct mail. A field is used only when it was genuinely inside the ciphertext, only when its addr appears in the message’s own To:, Cc: or Reply-To:, never for the sender’s own address, and never for an address in LOCAL_DOMAINS — nobody may introduce this host to its own users. A gossiped key can never displace a better-sourced one and never makes a signature count as verified.

Note the asymmetry with the sending half ([stage-encrypt] AUTOCRYPT_GOSSIP, default NO): emitting gossip redistributes third parties’ keys to correspondents who did not ask for them, while reading it only fills this host’s own cache. An operator who wants the introductions stored but never used sets [pepsi-keydiscovery] MIN_TRUST = harvested instead of turning this off.

LEARN_FROM_SPAM

(boolean, optional) Whether a message that the pipeline has already scored as spam (state.spam = true) may still teach a key. Default NO, which is Autocrypt Level 1 §5.3’s “messages SHOULD be ignored … when the MUA believes the message to be spam”.

It is an option rather than a fixed rule because the belief is Pepsi’s own: an operator whose spam scoring is deliberately loose may prefer key continuity to the rule. Note that honouring the default requires the stage to be placed after whatever sets state.spam — see pepsi-stage-autocrypt-learn(1).

ACCEPT_ROTATION

(string, optional) When the Autocrypt tier’s newest-wins rule may replace a correspondent’s stored inbound-signed/inbound/gossip key with the key that a newer message carries. newest (the default) is Autocrypt Level 1: a strictly newer effective date suffices, at equal rung. expired additionally requires every stored key for that address and protocol to be revoked or expired (by its recorded validity or its expires_at); otherwise the stored key is kept and the offer is held — audited as key.peer.rotate.held and reported to the recipients like a rotation. A key from an unsigned message never replaces one that a DKIM-signed message brought, whatever this option says; a signed key replacing an unsigned one is governed by it like a rotation. A replacement by a strictly better-ranked source from outside the tier is not. Any other value is a configuration error. Either way every rotation writes a key.peer.rotate audit row; see pepsi-stage-autocrypt-learn(1).

RESPONSE_STAGE

(string, optional) The stage at which the key-change notices are injected: when a correspondent’s key is rotated or held, each local envelope recipient of the message that caused it is mailed the key-rotation.<lang>.body template (null sender, From: postmaster@<domain>). Normally the DKIM-signing stage, like pepsi-stage-encrypt(1)’s RESPONSE_STAGE. Must name an existing stage; pepsi-setup(1) also requires key-rotation.en.body in [pepsi] TEMPLATE_DIR. Without it, changes are audited and logged but nobody is mailed.

LOCAL_DOMAINS, TARGETS, RECIPIENT_DELIMITER

(optional) The shared locality options. Only LOCAL_DOMAINS is consulted: to refuse a gossip field naming an address that this host serves (a key substitution rather than an introduction), and to pick which envelope recipients are ours to send a key-change notice to. Defaults to [pepsi-ingress] ACCEPTED_DOMAINS.

NEXT_STAGE

(string, required) Where the message advances once the stage has learnt whatever it could. The stage never consumes a message, so a missing NEXT_STAGE is refused by pepsi-setup(1) and errors at run time.

95.2.1.1.22.19. pepsi-stage-detect-language Options

A stage with PROGRAM = pepsi-stage-detect-language reads:

NEXT_STAGE

(string, required) Where the message advances after classification (whether or not a language was recorded). The worker refuses to start on a section without one.

LANGUAGES

(list, optional) The candidate languages, as whitespace/comma-separated ISO 639-1 codes (case-insensitive); at least two distinct codes are required. The token * stands for every supported language (75 with the bundled detector) and may be combined with explicit codes. Detection only ever returns languages from this set, so it should cover the languages you expect to receive. Defaults to a broad common set (en de fr es it pt nl pl ru tr ar zh ja).

Narrow it. Every enabled language adds to the memory that each worker process uses, and, more importantly, every language that your traffic never contains still competes for probability. The stage removes non-prose (URLs, addresses, base64 blobs, DNS records) from the body before classifying, which stops a single such token from deciding the answer outright; what remains after that is a genuine contest between the candidates, and a language in which nobody writes to you can still win it on a short message. pepsi-detect-language(1) reclassifies a saved message against any candidate set, so a narrower list can be tried before it is configured.

95.2.1.1.22.20. pepsi-stage-block-language Options

A stage with PROGRAM = pepsi-stage-block-language reads:

NEXT_STAGE

(string, required) Where a message scoring above THRESHOLD advances — and, under ENFORCEMENT = soft, where a flagged message continues too. pepsi-setup(1) refuses a section without one.

BOUNCE_STAGE

(string, required when a message can be bounced) Where a message scoring at or below THRESHOLD is routed so that a failure DSN can be generated (typically pepsi-stage-bounce(1)). Consulted only under ENFORCEMENT = hard, where it is required: pepsi-setup(1) refuses, and the worker refuses to start on, a hard section without one (a per-address override that switches to hard without one fails the blocked message). Worth setting even under soft, so that switching to hard is a one-word edit.

ENFORCEMENT

(``hard`` | ``soft``, optional) What happens to a message that fails the policy. hard (the default) routes it to BOUNCE_STAGE, so it is not delivered. soft delivers it anyway, marked: SUBJECT_FLAG_LABEL is appended to its Subject:, a X-Pepsi-Detected-Languages header records what was detected, and the message advances to NEXT_STAGE.

soft marks exactly the messages that hard would have bounced, which makes it a training mode: run it for a while and the flags in the mailbox are a faithful preview of what enforcement would refuse, at no cost to a correspondent for whose mail the lists have not been tuned yet. Being an ordinary stage option it is per-address overridable (pepsi-settings(1)), so one account can stay in training while the rest of the deployment enforces.

Note that the Subject: rewrite breaks the sender’s DKIM signature and this server’s ARC AMS (both over-sign Subject), exactly as pepsi-stage-vacation(1)’s VACATION_TAG does. That costs nothing on a branch that ends in local delivery, but it does on one that relays onward.

SUBJECT_FLAG_LABEL

(string, optional) The marker appended to a flagged message’s Subject: under ENFORCEMENT = soft. Defaults to [!LANG]. Appended only when the subject does not already contain it (case-insensitively), so a reply quoting it back through the stage does not collect a second one. An empty value re-applies the default; there is no way to switch the marker off, since flagging nothing is the same as leaving the stage out of the pipeline.

WHITELIST

(list, optional) Languages whose probability is added to the score, as whitespace/comma-separated ISO 639-1 codes (case-insensitive) plus the optional pseudo-code none (matching undetected mail). Empty when unset. An entry may carry further subtags (de-CH); each entry is a language range matched by RFC 4647 §3.3.1 basic filtering, so de also matches a detected de-CH while de-CH does not match a bare de.

BLACKLIST

(list, optional) Languages whose probability is subtracted from the score, same syntax as WHITELIST. Empty when unset. A language may appear on at most one of the two lists.

At least one of the two lists must be non-empty: with both empty every message scores 0.0, which the strict score > THRESHOLD gate then fails, so the stage would bounce (or flag) all mail. The configuration is refused rather than accepted, and refusing it keeps “I will fill the lists in later” from causing a silent outage.

THRESHOLD

(float, optional) The score a message must exceed to advance. Defaults to 0.0.

95.2.1.1.22.21. pepsi-stage-vacation Options

A stage with PROGRAM = pepsi-stage-vacation answers mail that arrives while the envelope recipient is away. Every option below is per-address overridable, and that is how the feature is meant to be used: the INI section is the operator’s default (no vacation), and each user’s leave dates — and, if they want, their own message text — come from their pepsi.settings row or from a config_override scope. See pepsi-stage-vacation(1).

NEXT_STAGE

(string, required) Where the message continues. It always does: this stage adds a reply, it never consumes a message. pepsi-setup(1) rejects a stage without it.

RESPONSE_STAGE

(string, required) Where the vacation notice is injected as a new null-sender message, so it is signed and relayed (typically the DKIM-signing stage). pepsi-setup(1) checks that it names an existing stage.

VACATION_RANGES

(list, optional) Comma- or whitespace-separated YYYY-MM-DD:YYYY-MM-DD spans of days on which the recipient is away. Both endpoints are inclusive whole days in the server’s time zone; an empty end (2026-08-01:) is an open-ended leave and a bare date is that single day. Empty when unset, which switches the stage off for that address — the default, and the state of every recipient who has never configured a vacation. A range whose end precedes its start is rejected.

DEFAULT_LANGUAGE

(string, optional) The language whose message is used when none of the sender’s detected languages (state.language) has one. Defaults to en. Written with either separator: pt_br and pt-BR are the same tag.

DEFAULT_MESSAGE_SECTION

(string, optional) The configuration section holding one inline message template per language, as <LANG> = <template>. Defaults to pepsi-vacation-default-message, which ships in ${DATADIR}/config.d with ten languages. A per-address MESSAGE_<LANG> option of this section takes precedence over it, per language.

MESSAGE_<LANG>

(string, optional) The address’s own notice text for one language (MESSAGE_EN, MESSAGE_DE_CH, …), a Mustache template in which two spaces become a newline. Consulted before DEFAULT_MESSAGE_SECTION for that language only. Being an option of the stage’s own section, it is the one form that a user can set through pepsi.settings; the section named by DEFAULT_MESSAGE_SECTION is always read from the base configuration.

EMERGENCY_CONTACT

(address, optional) A single bare address offered to the message template as {{EMERGENCY_CONTACT}}. Unset by default, in which case a template’s {{#EMERGENCY_CONTACT}} block is skipped. A display name or a list of addresses is rejected.

VACATION_TAG

(string, optional) Appended to the forwarded message’s Subject: when a notice was sent, so the recipient can see which mail was answered for them. Defaults to [VACATION]; the sentinel value none disables tagging. An empty value does not — the parser reads an empty option as absent, which re-applies the default. Appending is idempotent.

SUPPRESS_DAYS

(integer, optional) How long after answering one correspondent they may be answered again. Defaults to 7 (the Sieve vacation default, RFC 5230 §4.1); 0 answers every message. Must not exceed 3650 (ten years) — the value becomes a SQL interval subtracted from now(), and a larger one puts the result outside the timestamptz range, which would fail every message to the address rather than the configuration that set it.

REQUIRE_ADDRESSED_TO

(boolean, optional) Answer only when the recipient appears in To:, Cc:, Resent-To: or Resent-Cc: (RFC 3834 §3), so a blind carbon copy or a harvested-list blast draws no reply. Defaults to yes.

REQUIRE_AUTHENTICATED

(boolean, optional) Answer only a sender whose envelope domain passed SPF or whose From: domain passed DMARC (locally submitted mail counts). Defaults to no: a definite fail is never answered, an unconfirmed sender (softfail, neutral, none, a temporary error) still is. yes leaves a correspondent at a domain that publishes neither record unanswered, and in return a forged sender at such a domain draws no notice. The pay-to-send and list-command stages take the same option; the secretary’s is on by default. Whatever its value, a sender that did not pass is answered without its own words: no quoted subject, and {{SENDER_NAME}} is its address rather than its From: display name.

SUBJECT_PREFIX

(string, optional) Prepended to the original subject to form the notice’s subject. Defaults to Auto: (RFC 5230 §4.5). A message with no subject yields the prefix alone, and an already-prefixed subject is not prefixed twice. The prefix also stands alone for a message that arrived encrypted and for a sender that did not pass SPF or DMARC.

95.2.1.1.22.22. pepsi-stage-secretary Options

A stage with PROGRAM = pepsi-stage-secretary holds mail from senders that no whitelist knows and asks them to confirm by replying (confirm-to-send). Every option below but NEXT_STAGE and BOUNCE_STAGE is per-address overridable, so a user may set their own challenge text or PENALTY. See pepsi-stage-secretary(1).

NEXT_STAGE

(string, required) Where whitelisted, confirmed and never-challenged mail (a bounce, locally submitted mail) continues.

RESPONSE_STAGE

(string, required) Where the challenge and the confirmation notice are injected as new null-sender messages (typically the DKIM-signing stage).

BOUNCE_STAGE

(string, optional) The timeout path: where held mail goes when nobody confirmed in time, the challenge bounced, or state.spam is true, and where mail that must not be challenged goes when UNCHALLENGEABLE_STAGE is unset. When it is unset, such mail is deleted.

UNCHALLENGEABLE_STAGE

(string, optional) Where mail that must not be challenged goes: RFC 3834 says not to answer it, its SPF or DMARC verdict is fail, the sender is also a recipient, its From: is not the envelope sender, the sender is not authenticated, the sender’s daily cap is spent, or WHITELIST_NAME does not expand for the recipients. When it is unset, such mail takes the timeout path.

WHITELIST_NAME

(string, required) The one whitelist to which a confirmed sender is written; may be a {login}/{localpart} template, expanded per recipient as by pepsi-stage-check-whitelist(1). A list of names is rejected. The operator may name any whitelist; a value that an account owner sets by mail through pepsi-stage-edit-settings(1) must name one in their own <login>/... namespace, or the one that the operator’s configuration names for them.

CONTROL_LOCAL_PART

(string, optional) Local part of the reply address <CONTROL_LOCAL_PART>-<cookie>@<domain>. Defaults to secretary; at most 30 ASCII letters, digits, ., _ or -, neither starting nor ending with . or - and without ...

HOLD_TIME

(duration, optional) How long held mail waits. Defaults to 120 h; h, m and s units only; must be positive.

REQUIRE_AUTHENTICATED

(boolean, optional) Challenge only a sender whose SPF or DMARC passed. Defaults to yes.

MAX_CHALLENGES_PER_SENDER

(integer, optional) How many challenges one address may be sent per 24 hours, across all whitelists. Defaults to 5; 0 means no limit.

DKIM_REQUIRED

(auto|yes|no, optional) The dkim_required of the whitelist row that a confirmation writes. auto (the default) makes it required when any message held for the challenge passed DKIM (or ARC with DMARC); when none did but one passed DMARC (an aligned SPF pass, or a trusted ARC sealer’s override), the row gets dmarc_required instead. no writes neither.

CONFIRM_NOTICE

(boolean, optional) Tell a confirmed sender that their mail was delivered. Defaults to no.

PENALTY

(string, optional) What the sender agrees to pay if their message was unsolicited, offered to the template as {{PENALTY}}. Unset by default.

SUBJECT_HINT_LENGTH

(integer, optional) How many characters of the held message’s subject the challenge quotes. Defaults to 8; 0 omits the hint; at most 64.

TEMPLATE

(string, optional) Base name of the <TEMPLATE>.<lang>.body challenge templates under [pepsi] TEMPLATE_DIR. Defaults to secretary-challenge.

SUBJECT

(string, optional) The challenge’s subject when no SUBJECT_<LANG> matches the chosen language. Defaults to Please confirm your message to {{RECIPIENT}}, and while it is unset a text chosen in one of the ten shipped languages gets that language’s shipped subject instead; an explicit value is used for every language without a SUBJECT_<LANG>.

DEFAULT_LANGUAGE

(string, optional) Language used when none of the sender’s detected languages has a text. Defaults to en. pepsi-setup(1) requires a template or a MESSAGE_<LANG> for it.

MESSAGE_<LANG>, SUBJECT_<LANG>, CONFIRM_MESSAGE_<LANG>

(string, optional) Per-language challenge text, challenge subject and confirmation text, overriding the templates for that language only.

LOCAL_DOMAINS, TARGETS, RECIPIENT_DELIMITER

(optional) The shared locality options (pepsi-stage-relay-to-maildir(1)): which domains a reply address may be at, and how the whitelist-name placeholders expand. LOCAL_DOMAINS defaults to [pepsi-ingress] ACCEPTED_DOMAINS.

95.2.1.1.22.23. pepsi-stage-if Options

A stage with PROGRAM = pepsi-stage-if branches on a member of the message state JSON:

STATE_PATH

(string, required) The dot-separated path into the message state whose value is tested (object member names and integer array indices, e.g. spam, auth.dkim, dsn.rcpt.0.notify).

VALUE

(string, required, non-empty) The value against which the member at STATE_PATH is compared, by its natural scalar text form (string, true/false, decimal number, or null). An empty option reads as unset.

TRUE_STAGE

(string, required) Where the message advances when the value equals VALUE. pepsi-setup(1) checks that it names an existing stage.

FALSE_STAGE

(string, required) Where the message advances otherwise (the value differs, the path is absent, or it resolves to an array/object). pepsi-setup(1) checks that it names an existing stage.

95.2.1.1.22.24. pepsi-stage-milter Options

A stage with PROGRAM = pepsi-stage-milter hands the message to an existing milter daemon (the sendmail/Postfix mail-filter protocol) and routes it by the filter’s verdict. See pepsi-stage-milter(1), and note in particular that the filter runs post-queue, so a REJECT costs a bounce where an MTA would have answered 5xx inside the SMTP session.

SOCKET

(string, required) Where the milter daemon listens, in sendmail’s S= grammar (which Postfix also accepts): unix:/path (or its synonym local:/path), inet:host:port, inet:port@host, inet6:[addr]:port or inet6:port@addr. A bare path with no scheme is rejected. Pepsi connects to this socket; it never starts, stops or confines the daemon behind it.

MILTER_NAME

(string, optional) Exported to the filter as the {daemon_name} macro and used in log messages. Defaults to the stage’s own name.

ACCEPT_STAGE

(string, optional) Where SMFIR_ACCEPT sends the message. Defaults to NEXT_STAGE, which makes accept and continue the same thing; set it to skip past the rest of a filter chain, which is what Postfix’s milter list does natively. pepsi-setup(1) checks that it names an existing stage.

REJECT_STAGE

(string, optional) Where SMFIR_REJECT sends the message, and where individually rejected recipients are fanned out to. Defaults to the section’s BOUNCE_STAGE. Point it at a pepsi-stage-discard(1) to drop rejected mail instead of bouncing it. pepsi-setup(1) checks that it names an existing stage.

QUARANTINE_STAGE

(string, optional) Where SMFIR_QUARANTINE sends the message. Unset means discard: Pepsi has no quarantine store, only a route. A quarantine request decides the routing regardless of the verdict that follows it, because a sendmail milter quarantines and then still returns an accept. pepsi-setup(1) checks that it names an existing stage.

ON_FAILURE

(``tempfail``/``accept``/``reject``/``discard``, default ``tempfail``) What to do when the milter cannot be reached, times out, or speaks something unparsable — Postfix’s milter_default_action, with the same default. tempfail pauses the message for retry, so a filter that is down delays mail rather than losing it or letting it through unfiltered. A message still deferred after MAX_LIFETIME (by this path or by the filter’s own SMFIR_TEMPFAIL) goes to the section’s BOUNCE_STAGE, or is left failed for pepsi-failure-bouncer(1) when there is none — never to REJECT_STAGE, which may drop mail silently.

ALLOW_ACTIONS

(string, default ``addhdrs chghdrs chgbody``) The SMFIF_* modification actions offered to the filter, whitespace- or comma-separated: addhdrs, chghdrs, chgbody, addrcpt, delrcpt, addrcpt_par, chgfrom, quarantine; plus the shorthands all and none. There is no inshdr: libmilter gates header insertion on SMFIF_ADDHDRS too.

With no sandbox around the filter, this mask is the only way to limit what the filter can change, and the default is where that matters most: every content filter works under it, while a filter that wants to rewrite the envelope has to be granted that explicitly. A filter requiring an action that was not offered is reported by name and takes the ON_FAILURE path, rather than having its modifications silently dropped the way Postfix drops them.

SMFIF_SETSYMLIST is deliberately not listed and needs no grant: it authorises no change to the message.

PROTOCOL_VERSION

(integer 2–6, default 6) The highest milter protocol version offered; the filter negotiates down from it. Postfix’s milter_protocol.

CONNECT_TIMEOUT

(duration, default ``30 s``) Bound on establishing the connection and completing the option negotiation — both halves of “can this filter be reached at all”. Postfix’s milter_connect_timeout.

COMMAND_TIMEOUT

(duration, default ``30 s``) Bound on the reply to any single command up to end-of-body. Postfix’s milter_command_timeout.

CONTENT_TIMEOUT

(duration, default ``300 s``) Bound on the end-of-message verdict, where a content filter does its real work. An SMFIR_PROGRESS from the filter restarts the clock, but one reply wait is never extended past ten times its timeout in all; a filter still reporting progress then takes the ON_FAILURE path. Postfix’s milter_content_timeout.

Each of the three timeouts must be greater than zero and at most 24 h.

RETRY_INITIAL / RETRY_MAX_INTERVAL / RETRY_FACTOR / MAX_LIFETIME

(durations / number, optional) The shared retry schedule for the tempfail path, with the same meaning as in the relay stages. Defaults: 300 s, 1 h, 2, 120 h. There is no DELAY_DSN_AFTER: a message that the filter keeps deferring produces no “delayed” DSN, only the bounce once MAX_LIFETIME is up, and pepsi-setup(1) reports the option as unknown in a milter section.

MACROS_CONNECT / MACROS_HELO / MACROS_MAIL / MACROS_RCPT / MACROS_DATA / MACROS_EOH / MACROS_EOM

(string, optional) The sendmail macros exported at each protocol phase, whitespace- or comma-separated. The defaults are Postfix’s, so a filter’s own documentation applies unchanged: j {daemon_name} {daemon_addr} v _, {tls_version} {cipher} {cipher_bits} {cert_subject} {cert_issuer}, i {auth_type} {auth_authen} {auth_author} {mail_addr} {mail_host} {mail_mailer}, i {rcpt_addr} {rcpt_host} {rcpt_mailer}, and i for the remaining three. A macro whose value this deployment does not know is not sent at all. Set a list to the sentinel none to export nothing at that phase — an empty value reads as absent and re-applies the default. A filter that names its own list with SMFIF_SETSYMLIST overrides these.

95.2.1.1.22.25. pepsi-stage-quarantine Options

A stage with PROGRAM = pepsi-stage-quarantine holds every message that reaches it (paused, with no timeout unless MAX_HOLD is set) until an operator releases it with pepsi-queue quarantine release or deletes it. One of RELEASE_STAGE and NEXT_STAGE is required. The options are read from this file, never from per-address settings. See pepsi-stage-quarantine(1).

RELEASE_STAGE

(string, optional) Where a released message goes. Defaults to NEXT_STAGE. For mail that ingress quarantined, which has skipped every stage before this one, it is normally init. Must not be this stage.

MAX_HOLD

(span, optional) The longest hold, for example 14 days, 2 weeks or 36 h; a day counts as 24 hours, and months and years are refused. The end of a hold is recorded when the hold begins. Unset, a hold lasts until the message is released or deleted, and [pepsi-queue] QUARANTINE_MAX_AGE_DAYS bounds it as at every quarantine stage; set, the stage ends its own holds and pepsi-queue gc leaves it alone.

EXPIRE_STAGE

(string, optional) Where a message goes when its hold reaches MAX_HOLD, marked failure_class = quarantine-expired with RET=HDRS for a DSN. Unset, the message is deleted. Requires MAX_HOLD; must not be this stage.

95.2.1.1.22.26. pepsi-stage-route Options

A stage with PROGRAM = pepsi-stage-route chooses a next stage for each envelope recipient from that recipient’s domain, splitting the message onto sibling rows when the recipients disagree. It exists for a gateway sitting in front of another mail system (see the manual’s “Microsoft Exchange as a gateway” chapter): the domains behind such a gateway are exactly the domains whose public MX is the gateway, so routing one of them to a direct-to-MX relay is a mail loop rather than a delivery failure.

Lookup order per recipient is ROUTES, then the managed-domain set, then NEXT_STAGE.

ROUTES

(string, optional) Whitespace- or comma-separated <domain-pattern>=<stage> pairs, consulted first and in the order written. Patterns are matched case-insensitively and may contain *, which matches any run of characters; they are globs, not regular expressions, and are anchored at both ends, so *.example.org matches mail.example.org but neither example.org nor mail.example.org.evil.test. A value that looks like a regular expression is rejected rather than silently matching nothing. Explicit rules are consulted before the managed set so that one subdomain can be carved out without removing its parent from MANAGED_DOMAINS.

MANAGED_DOMAINS

(string, optional) The domains behind this gateway, whitespace- or comma-separated, * globs permitted. Defaults to [pepsi-ingress] ACCEPTED_DOMAINS, so the set cannot drift from what ingress actually accepts. At least one domain must resolve, from either source.

MANAGED_STAGE

(string, optional) Where a recipient at a managed domain goes — in a gateway deployment, the stage that relays to the system behind it. Without it, managed recipients take NEXT_STAGE, and pepsi-setup(1) then has to prove that this is not a loop.

NEXT_STAGE

(string, required) Where every other recipient goes. Required: the stage never delivers, bounces or drops a message, so every recipient must have somewhere to be.

RECIPIENT_CHECK

(``none``, ``probe`` or ``map``, optional) How pepsi-ingress(1) may learn whether an address at a managed domain exists on the system behind the gateway, so that it can refuse an unknown one at RCPT time (see [pepsi-ingress] VERIFY_RECIPIENTS). The route itself never reads it; it is set here because this section describes the backend. Only used together with MANAGED_STAGE.

none (the default) leaves the managed domains unverified: every address is accepted, and the backend’s own bounce is the answer. probe asks the backend: MAIL FROM:<>, RCPT TO, RSET, with no message sent. Only a 5.1.x refusal (or a bare 550) counts as “no such user”. Anything else accepts the address: an unreachable backend, a deferral or a full mailbox. Answers are cached, a “yes” for an hour and a “no” for five minutes. A backend that accepts every address and bounces later (Exchange with recipient filtering off) always answers “yes”; for such a backend use map, which reads the valid addresses from RECIPIENT_MAP.

PROBE_HOST, PROBE_PORT, PROBE_TLS, PROBE_TIMEOUT

(optional; PROBE_HOST required for ``probe``) Where and how to probe: the backend’s host name or address, its port (default 25), opportunistic (the default), starttls, tls or none, and the per-command timeout (default 10 s). The probe carries an address, never a message, so opportunistic TLS accepts any certificate, as delivery to an MX does; starttls and tls verify it.

RECIPIENT_MAP

(path; required for ``map``) The valid addresses, one per line: an address, or @domain for every address at a domain. Anything after the first word is ignored, so the source file of a Postfix relay_recipient_maps table (alice@example.org OK) can be used as it is. # starts a comment. The file is read on each check. If it cannot be read, every address is accepted.

pepsi-setup(1) checks that every target names an existing stage, and refuses a configuration in which a message for a managed domain could reach pepsi-stage-relay-to-internet(1) — walking forward through NEXT_STAGE and any further routing stages, but deliberately not through BOUNCE_STAGE (a bounce is a new message about a delivery that already failed, and legitimately reaches a relay).

95.2.1.1.22.27. pepsi-stage-aliases Options

A stage with PROGRAM = pepsi-stage-aliases expands the envelope recipients of a message through an alias mapping file before forwarding it:

ALIASES

(string, required) The alias map file, parsed like a Postfix virtual(5) table. The value is a filesystem path taken verbatim, so unlike a path-typed option it is not $-expanded. Each line maps a key (a full address, an @domain catch-all, or a * wildcard such as sales-*@example.org) to one or more comma/whitespace-separated target addresses; # comments and blank lines are ignored. Recipients matching a key are replaced by its targets (transitively, with a loop guard) and the result is de-duplicated; on competing wildcards the most specific match wins. The file is re-read only when its identity (modification time, size or inode) changes; a missing file is treated as an empty map, while a file that exists but cannot be read is an error and the message is retried. pepsi-setup(1) syntax-checks it at install time when present. See pepsi-stage-aliases(1).

NEXT_STAGE

(string, required) Where the (expanded) message advances. pepsi-setup(1) checks that it names an existing stage.

95.2.1.1.22.28. pepsi-stage-edit-settings Options

A stage with PROGRAM = pepsi-stage-edit-settings reads:

EDITABLE_STAGES

(list, required) Whitespace/comma-separated stage names whose options a control e-mail may change. At least one is required, each must name an existing stage (pepsi-setup(1) checks), and a body addressing any stage not listed here is refused.

RESPONSE_STAGE

(string, required) Stage at which the reply is injected (typically the start of the outbound signing/relay path), so it is DKIM-signed and delivered. Must resolve to an existing stage.

NEXT_STAGE

(string, required) Where a non-control message is advanced. pepsi-setup(1) refuses a section without one.

SUBJECT

(string, optional) The exact subject (compared case-sensitively, ignoring surrounding whitespace) that marks a control message, and the subject of the reply. Default Pepsi.

CONTROL_LOCAL_PART

(string, optional) Local part of the control address. Default pepsi.

RESPONSE_FROM

(string, optional) From: header of the reply. Default <CONTROL_LOCAL_PART@domain> for the controlled domain to which the message was addressed.

UNRESTRICTED_UNSAFE_STAGES

(boolean, optional) Lift the safety restriction on what a control e-mail may set. Default NO.

With the default, four things are refused however permissive EDITABLE_STAGES is. An assignment that sets a stage’s PROGRAM is accepted only when the value is a bare pepsi-stage-* command with no path component, so an account owner cannot point one of their editable stages at an arbitrary executable. An assignment that sets HELPER (the program that a delivery stage executes with its setgid privilege) is refused unless it only unsets it; the same applies to SCAN_HELPER, MAILBOX_HELPER and PIN_COMMAND, the other options that name a program to run. An assignment that sets an identity option is refused outright, because there is no safe value to allow. These options are SIGNING_DOMAIN, which overrides the message’s own From: domain and so would have an account’s mail signed as any domain for which this host holds a key, and auto-pay’s WALLET_MODE, WALLET_SCOPE and WALLET_USER, which select whose wallet pays. A spending limit, auto-pay’s MAX_TOTAL and MAX_TOTAL_PER_DAY, is refused too, because a control message is authenticated by the same submission password whose theft those limits bound. Setting this to YES removes all four checks. The option is named after what it does: there is no reason to turn it on unless you trust every address whose overrides are editable.

95.2.1.1.22.29. pepsi-stage-vks-confirm Options

A stage with PROGRAM = pepsi-stage-vks-confirm follows the confirmation link in a key server’s address-verification mail, so an uploaded key becomes findable by address. It sits on the inbound path and advances everything it does not act on — nearly all mail — untouched. See pepsi-stage-vks-confirm(1) for the full list of conditions it checks before fetching anything.

NEXT_STAGE

(string, required) Where every message that this stage does not consume goes. Required rather than optional: a stage on the inbound path that silently dropped what it did not recognise would lose ordinary mail. pepsi-setup(1) checks that it names an existing stage.

VKS_HOST

(string, optional) The only host from which a verification mail may come and at which a link may point. Defaults to the host of [pepsi-keys] VKS_SERVER, and pepsi-setup(1) refuses any other host: uploads go to that server, so its verification mail is the only kind the stage exists to act on. Matched exactly: a subdomain of a key server is not the key server. The option is optional only because of that fallback: with neither this option nor a VKS_SERVER host, the stage refuses to start, because it has no way to tell a key server’s mail from anybody else’s.

MAX_LINKS

(integer, optional) How many links the stage follows at most for one message. Default 3, minimum 1 (0 is refused: to follow no links at all, take the stage out of the pipeline). A genuine verification mail carries one; the bound stops a message that got past every other check from becoming an arbitrary number of requests.

DISCARD_CONFIRMED

(boolean, optional) Whether a confirmation mail that the stage acted on is deleted rather than delivered. Default YES: it is machine mail about an action that Pepsi took, addressed to a mailbox whose owner did not ask for it, and it has already been acted on by the time it would arrive. Only a mail after which at least one identity was verified as published is deleted; when following its links verified nothing, it is delivered regardless.

REQUIRE_AUTHENTICATION

(boolean, optional) Whether SPF or DMARC must have passed, not merely the envelope sender matching VKS_HOST. Default YES. Note that a DKIM pass deliberately does not satisfy this: it says a signature verified, not whose.

There is no BOUNCE_STAGE: the stage never fails a message.

95.2.1.1.22.30. pepsi-stage-dmarc-report Options

A stage with PROGRAM = pepsi-stage-dmarc-report reads the DMARC aggregate reports (RFC 7489 §7.2) that other receivers mail to the served domains’ rua= address, and stores them in pepsi.dmarc_report. It sits on the inbound path, ahead of the whitelist, challenge and payment gates, and advances everything not addressed to the report address untouched. The global [pepsi-dmarc-reports] section configures storage and the verdict window. See pepsi-stage-dmarc-report(1).

NEXT_STAGE

(string, required) Where every message that is not a report goes. pepsi-setup(1) checks that it names an existing stage.

LOCAL_PART

(string, optional) The local part at which the reports arrive, on every LOCAL_DOMAINS domain, compared after the sub-address is stripped. Default dmarc-reports. The recipient check at RCPT accepts it at every served domain, and pepsi-setup(1) names it in the rua= of the DMARC record that it suggests.

DELIVER

(boolean, optional) Also pass the report mail on to NEXT_STAGE, for a site that keeps a mailbox at the address. Default NO: the mail is consumed (stored when it is a readable report about a served domain, dropped otherwise).

MAX_REPORT_SIZE

(size, optional) Cap on a decompressed report; a gzip or zip bomb stops here. Default 16M; none is refused.

LOCAL_DOMAINS, RECIPIENT_DELIMITER

(optional) The served domains (default [pepsi-ingress] ACCEPTED_DOMAINS) and the sub-address delimiter (default [pepsi] RECIPIENT_DELIMITER, else +).

There is no BOUNCE_STAGE: the stage never bounces.

95.2.1.1.23. The [pepsi-dispatch] Section

Options for pepsi-dispatch(1). Per-stage worker-pool sizing (PARALLELISM, MAX_MESSAGES, QUEUE_LIMIT) lives in each [stage-<name>] section above, not here. Every duration below must be greater than zero and at most 168 h; pepsi-setup(1) and the dispatcher refuse anything else.

CONFIG_FILE

(path, optional) The configuration file passed to spawned workers via -c. Set it to this file’s path whenever the dispatcher is started with an explicit -c (the loaded path cannot be recovered otherwise); if unset, workers use the default configuration search.

POLL_INTERVAL

(duration, optional) Safety-net heartbeat: the longest the dispatcher sleeps when no sooner paused retry, worker reap or spawn-cooldown is due, at which point it re-scans for work and requeues any due paused rows. Default 30 s. It is an absolute deadline, not a quiet period: message traffic, and a shorter STATS_INTERVAL, do not push it back, so paused rows are requeued on time even on a busy pipeline.

MAX_RUNTIME

(duration, optional) Maximum real time a worker may spend on a single message, counted from when the worker is ready for it: a worker’s own start-up is not charged to the message, and has a budget of its own (the larger of this and 60 s; see pepsi-dispatch(1)). A worker that exceeds it is killed (and replaced) and the message takes a strike: it is paused and retried after a minute (two after the second strike), and only its third strike sets it timeout, except in a pepsi-stage-relay-to-* stage, where MAX_LIFETIME decides. A section [stage-<name>] can set a MAX_RUNTIME of its own, which wins. Default 300 s, and 900 s for the pepsi-stage-relay-to-* stages, which wait for other hosts; setting this option applies the value to those stages as well.

WORKER_IDLE_TIMEOUT

(duration, optional) How long an idle worker process is kept before it is stopped. Total concurrency is set per stage (PARALLELISM), not globally. Default 5 s.

STATS_INTERVAL

(duration, optional) How often the in-memory pipeline statistics (exported by pepsi-httpd(1) at /metrics) are flushed to the database, in a single transaction. Also flushed as soon as the pipeline goes idle (at most once a second) and on shutdown; an idle dispatcher with nothing new to record writes nothing. Default 60 s.

DB_POOL_SIZE

(number, optional) Maximum number of PostgreSQL connections in the dispatcher’s database pool. Unlike a single-connection stage worker, the dispatcher processes many workers’ results (advancing/failing their messages) concurrently with its own coordinator queries, so it keeps a small bounded pool. The per-statement work is brief, so a handful of connections absorbs heavy worker churn. Defaults to 8; raise it only if the coordinator runs short of connections, and keep the sum of every component’s pool below PostgreSQL’s max_connections.

FAIR_SCHEDULING

(boolean, optional) Share each stage’s worker time fairly among senders (the authenticated account, else the connecting address, an IPv6 one by /64; see “Fair scheduling across senders” in pepsi-dispatch(1)) instead of claiming strictly oldest first, so that one sender’s burst does not delay everybody queued behind it. Default yes; no restores oldest-first.

FAIR_HALF_LIFE

(duration, optional) How quickly a sender’s accumulated lead in worker time fades: it halves every FAIR_HALF_LIFE, so the penalty for a past burst wears off once the sender stops. Default 60 s.

FAIR_FIFO_PERCENT

(number, optional) Percentage of every stage’s claimed slots reserved for its oldest waiting messages regardless of sender. This guarantees that no message waits for ever, however many other senders keep arriving. 1 to 100; 100 is oldest-first with extra bookkeeping (use FAIR_SCHEDULING = no for that). Default 10.

95.2.1.1.24. The [pepsi-list] Section

Options for pepsi-list(1) and the mailing-list subsystem, read by that tool, by the list stages and by pepsi-setup(1). Every option has a default, so a site that hosts no lists needs no section at all.

Pepsi’s mailing-list subsystem is a reimplementation of GNU Mailman 3; its data model, REST API, e-mail command vocabulary and notice-template names are the GNU Mailman project’s design, copyright the Free Software Foundation. See COPYING and vendor/PEPSI-VENDORING.md for the files taken from upstream, which remain under the GPL.

Per-list configuration is not here. Lists are created at run time by people who are not the operator, potentially in their thousands; this file is operator-owned and reloaded as a unit. The 99 per-list attributes live in the mailing_list table and are managed with pepsi-list(1). What follows is only what the site owns.

SITE_OWNER

(address, optional) Where a list’s notices go when the list has no owner of its own. Without it, a list with no owner is an error from pepsi-list check rather than a warning, because its held messages and moderation requests would reach nobody at all.

BASE_URL

(URL, optional) Public URL at which the archive links and the List-* headers point, for domains that do not set their own base_url. Without it no List-Archive: header can be written. When it is an https:// URL, the member pages’ WebAuthn security keys are also bound to its origin (its host is their RP id); otherwise members are offered no security key.

API_USER, API_PASS

(string, optional) HTTP Basic credentials for the GNU Mailman 3 REST API – upstream’s [webservice] admin_user/admin_pass under a Pepsi name. Set both or neither: half a credential authenticates nobody, and pepsi-list check reports one without the other as an error. The API is served only on a listener flagged LIST_API = yes.

API_BASE_URL

(URL, optional) The absolute origin from which the REST API builds every self_link and Location that it emits, e.g. http://localhost:8001; a trailing / is stripped. When it is unset, the request’s own Host is used, which is right behind a reverse proxy.

API_RATE_LIMIT

(integer, optional) Requests per minute per source address on the REST API. Default 3000, deliberately high so a compatibility suite is not throttled; a 429 from that API comes from this limiter.

DEFAULT_LANGUAGE

(string, optional) The language a new list starts in, and the bottom of the preference chain (GET /<api>/system/preferences). Default en.

RELEASE_STAGE

(string, optional) The [stage-<name>] section running pepsi-stage-list-post(1), where a moderator’s accept of a held message re-enters the pipeline. Without it held messages can be read and discarded but not accepted, and pepsi-setup(1) warns. pepsi-list digest injects digest issues at the same stage, and pepsi-list check warns about a list with digests_enabled when it is unset.

NOTICE_STAGE

(string, optional) The stage at which the periodic sweeps of pepsi-list tasks inject their notices: the bounce sweeps’ member notices and the moderators’ notice about expired held posts. pepsi-setup(1) requires it, and checks that it names an existing stage, as soon as a pepsi-stage-list-bounce(1) stage exists: without it a member’s warning count rises without the member ever being told. Without it, held posts past max_days_to_hold also stay held, because nobody could be told of the discard.

BOUNCE_PROBES

(boolean, optional) Whether a member whose bounce score crosses the list’s threshold is sent a probe (the score reset while it is outstanding, and a bounce of the probe disabling the member) rather than disabled at once. Default YES (upstream’s verp_probes defaults off): the probe’s token is the one thing about a bounce that nobody can forge, so it is the final check before delivery is disabled on the strength of reports that somebody else sent. See pepsi-stage-list-bounce(1).

BOUNCE_EVENT_RETENTION

(integer, optional) How long a processed bounce event is kept, in days. Default 1.

UNSUBSCRIBE_SECRET

(string, optional) The secret key of the RFC 8058 one-click unsubscribe token, which pepsi-stage-list-deliver(1) computes and pepsi-httpd(1) verifies. Without it the https: one-click form is not emitted and the mailto: form stands alone. pepsi-setup(1) writes it to secrets.d/pepsi-list.secret (mode 0640, pepsi-httpd:pepsi) and references it with @inline-secret@.

VERP_SECRET

(string) The secret key of the authentication code in every VERP envelope sender that the list fan-out writes (<list>-bounces+<local>=<domain>=<code>@ <host>, pepsi-stage-list-post(1)) and that pepsi-stage-list-bounce(1) checks before it scores a bounce against the member named: a member-shaped address whose code does not verify is dropped unscored. Required wherever either stage is configured — both refuse to start without it, and pepsi-setup(1) refuses the configuration. The wizard generates it, keeps it across re-runs and stores it in secrets.d/pepsi-list.secret beside UNSUBSCRIBE_SECRET. Rotating it makes every bounce of a copy already sent unverifiable.

TEMPLATE_FETCH_TIMEOUT, TEMPLATE_FETCH_MAX_BYTES, TEMPLATE_FETCH_ALLOW_INTERNAL

(duration, integer, boolean; optional) Limits on fetching a list’s list_template URI override, which a list owner rather than the operator sets: the whole-fetch deadline (default 5 s), the largest template accepted (default 65536 bytes), and whether a host resolving to an internal address may be fetched (default NO; every address the host resolves to is checked).

WEB_RATE_LIMIT, WEB_SEARCH_RATE_LIMIT

(integer, optional) Requests per minute per source address on the public list web interface (a [pepsi-httpd-listener-*] with LISTS = yes), and the separate, tighter budget for its search route. Defaults 600 and 30; a value below 1 is raised to 1.

WEB_REGISTRATION

(boolean, optional) Whether the public list web interface lets anybody create a list account (/lists/register, which is also how a lost verification token is sent again). Default YES. With NO the registration form and its handler answer 404 and the sign-in page does not offer them; signing in, password resets and verification links for existing accounts keep working, and accounts come from the operator’s pepsi-list, an import or a list owner instead. List pages and archives are served either way.

MAX_MESSAGE_SIZE

(integer, optional) Site ceiling on a list’s max_message_size, in kilobytes; 0 (the default) means no site ceiling. A per-list value above it is clamped, and pepsi-list check reports it.

MAX_LIST_HOPS

(integer, optional) How many times a message may pass through a list before it is treated as a subscription cycle between two lists and held for the moderators instead of delivered. Default 5. An umbrella list (a list subscribed to another list) is a supported configuration; this limit stops two lists that are subscribed to each other from amplifying mail. The counter travels as an X-Pepsi-List-Hops: header rather than in the message state, because an umbrella list’s mail leaves over SMTP and comes back as a brand-new message; pepsi-ingress strips the header from mail that did not arrive over an authenticated or local submission path, so it cannot be reset by a stranger.

INVITE_RATE

(integer, optional) How many cutover invitations are sent per hour. Default 300. A migrating site’s first act is a mass mailing to its entire membership from an IP with no reputation, so the invitation run is rate-limited and resumable rather than a loop.

ARCHIVE_RETENTION

(integer, optional) Default archive retention in days; 0 (the default) keeps everything. Overridden per list with pepsi-list list set-ext <list> archive_retention_days <n>, where 0 keeps that list’s archive whatever this option says. Applied daily by the retention sweep of pepsi-list tasks --once (the pepsi-list-tasks.timer unit).

SEARCH_TRIGRAM

(off | short | full, optional) Site ceiling on how far a list’s trigram (substring and fuzzy) search index may reach. Default short.

A ceiling, not a default: each list chooses off, short or full up to it, so lowering this value shrinks the index at the next pepsi-archive reindex rather than only affecting lists created afterwards. short indexes the subject, the thread subject and the sender’s name and address; full adds the message body and is likely to be the largest object in the database.

Trigram search needs the pg_trgm extension, which ships in postgresql-contrib. A site without it installs and runs normally with full-text search only; pepsi-list check says which mode the site is in.

LIST_FANOUT_BATCH

(integer, optional) How many sibling rows each fan-out batch creates. Default 256.

A post to a list is delivered as one queue row per recipient, so that each copy can carry that member’s own one-click unsubscribe URI. This bounds how many of those rows pepsi-stage-list-post(1) creates per step (it pauses for about a second between batches). The rows of a fan-out share one stored copy of the body; a member’s copy gets its own when pepsi-stage-list-deliver(1) rewrites it, so the batch size also bounds how quickly those per-member copies accumulate. Raising it makes a large send drain faster and cost more transient space.

TOMBSTONE_RETENTION

(integer, optional) How long a purge tombstone is kept, in days. Default 90.

Purging a message from the archive keeps its Message-ID for this long, so that a resend or a re-run import cannot silently re-archive the thing that was purged. pepsi-archive purge --forget skips the tombstone for the case where even ninety days is unwanted.

ARCHIVE_PARTITIONS

(integer, optional) Hash partitions for the archive tables. Default 32. Read only by pepsi-setup(1), and fixed at install.

PostgreSQL has no online re-partitioning: changing the modulus means a new table and a full copy of every archived message. pepsi-setup creates the partitions once and refuses to change them silently on a later run, and pepsi-list check reports a configuration that disagrees with what is on disk – the installed value is the authority, because the tables cannot be edited and this file can. Pick it once.

95.2.1.1.25. The [pepsi-failure-bouncer] Section

Options for pepsi-failure-bouncer(1), which moves failed/timeout messages to a bounce stage so that the sender is notified. Read only by that tool.

BOUNCE_STAGE

(string, required when the tool is used) The [stage-<name>] label to which a stuck message is moved (and reset to pending). Normally the same bounce stage to which the pipeline already routes permanent failures (e.g. bounce). A message already at this stage is left untouched, so a bounce that fails at the bounce stage does not loop. pepsi-setup(1) checks that the named stage exists. Needed on every deployment that runs pepsi.target: its pepsi-failure-bouncer.timer runs the tool every ten minutes, and each run fails without this option. The shipped configuration and the wizard’s set it to bounce.

MIN_AGE = DURATION

How long a message must have been failed/timeout before it is moved (default 1 h): the window in which an operator can put it back with pepsi-queue(1) before its sender is told. Measured from state.failed_at, which the database stamps when the row fails; a row without the stamp is moved at once. 0 s moves every failure straight away.

95.2.1.1.26. The [pepsi-queue] Section

Options for pepsi-queue(1). Read only by its gc subcommand, which the hourly pepsi-origin-gc.timer runs.

QUARANTINE_MAX_AGE_DAYS = DAYS

(integer, optional) How many days after its arrival a message waiting at a quarantine stage (one that a QUARANTINE_STAGE option names, or one that runs pepsi-stage-quarantine(1) without a MAX_HOLD of its own) is bounced instead of held any longer. Default 14. The bounce goes through the quarantine stage’s BOUNCE_STAGE, else [pepsi-failure-bouncer] BOUNCE_STAGE, and returns no content: a RET=FULL request is treated as RET=HDRS. A message whose content came out of, or failed to open from, an S/MIME EnvelopedData (AES-CBC) ciphertext is deleted instead, as is a member’s copy of a list post: whether a modified CBC ciphertext was held depended on its padding, so a bounce would answer that question. Held mail is stored as plaintext while it is held (in the database, its WAL and every dump), and this limit bounds how long that lasts. 0 holds mail for ever.

95.2.1.1.27. The [pepsi-sendmail] Section

Options for pepsi-sendmail(1), the Sendmail-compatible local submission client the Debian package installs as /usr/sbin/sendmail. Every option has a default, so a site needs no section at all.

The client is unprivileged and asserts no identity: it hands the message to a UNIX-domain ingress listener, which derives the sender’s account from the connecting process’s kernel-reported credentials (AUTH_PEERCRED, above).

SOCKET

(path, optional) The pepsi-ingress UNIX-domain submission socket. Default /run/pepsi/submission.sock.

Despite living in the client’s section, this option is read by both ends: pepsi-ingress serves this socket unconditionally and synthesises its listener from this path, so there is no [pepsi-ingress-listener-*] section for it and no second declaration that could name a different path.

On systemd, the descriptor is inherited when pepsi-ingress.socket already binds this path (it is matched by the address to which the descriptor is bound, not by an FD_INDEX), so a change here needs a matching ListenStream= in the unit. Otherwise the server binds the path itself, mode 0666, and refuses to start if it cannot. That mode grants nothing by itself: opening the socket conveys no right to send, because the kernel supplies the caller’s identity and USERNAME_MAP decides what it may send as.

The special value none disables local submission entirely: no socket is served and pepsi-sendmail(1) refuses to run, so local programs must authenticate on 587/465. pepsi-setup(1) reports this once.

EHLO_NAME

(string, optional) Name announced in EHLO. Defaults to [pepsi-ingress] HOSTNAME (and to localhost if that is unset). Cosmetic: the server authenticates the peer by its credentials, not by what it claims here.

DEFAULT_DOMAIN

(string, optional) Domain appended to the invoking account’s login to form the envelope sender when neither -f nor -r was given, and to a recipient given without an @ (cron’s root). Defaults to [pepsi-ingress] HOSTNAME (and to localhost if even that is unset).

Set it when the addresses that your USERNAME_MAP recognises are at some other domain: the server maps the peer’s uid to a login and then to an address, so a mismatch here makes cron mail arrive from an envelope sender that the site does not own.

95.2.1.1.28. The [pepsi-whitelist] Section

Options for pepsi-whitelist(1), the tool that manages the sender whitelist and can seed one from a user’s mailbox (import). Read only by that tool; every option is optional, so a site that only uses add/list/remove needs no section at all.

LOCAL_DOMAINS

(string, optional) Domains whose senders count as the user’s own mail when a mailbox is scanned: a message whose From:/Sender: is at one of them is one that the user sent, so its recipients become whitelist entries. Comma- or space-separated. Defaults to [pepsi-ingress] ACCEPTED_DOMAINS, and is the same option that pepsi-stage-relay-to-maildir(1) and pepsi-stage-dot-forward(1) use.

TARGETS, RECIPIENT_DELIMITER

(string, optional) As for the delivery stages. TARGETS bounds which local accounts import --all-users seeds (default: the /etc/login.defs UID_MIN..``UID_MAX`` range); RECIPIENT_DELIMITER strips a sub-address before an address is compared.

HOSTERS_FILE

(path, optional) File listing public e-mail hosters, one domain per line (# comments; a leading *. covers a subdomain tree). Domains in it are never proposed as an *@domain wildcard by import --auto-wildcard, however many correspondents the user has there — “everyone at gmail.com” is not a set of people the user knows, and whitelisting it would let every spammer with a free account bypass the anti-spam gate. Their individual addresses are still imported. Defaults to ${DATADIR}/hosters.txt, which make install writes; point this at your own copy to extend the list, since the installed one is overwritten on upgrade.

WILDCARD_THRESHOLD

(number, optional) How many distinct addresses at one domain make import --auto-wildcard propose a single *@domain entry for it. Default 10.

MAX_ENTRIES

(number, optional) The largest number of rows that one import may add. Default 5000. Every row of a whitelist is matched against the From: of every inbound message that consults it, so this is a bound on a permanent per-message cost, not just on table size.

SCAN_HELPER

(string, optional) The mailbox-scan helper binary, located on $PATH (for a setuid run, the fixed system path that replaces the caller’s). Default pepsi-helper-mailbox-scan (see pepsi-helper-mailbox-scan(1)). The database configuration overlay may not set it.

MAILBOX

(path, optional) Mailbox to scan when the user names none. Defaults to the user’s ~/Maildir if it exists, else /var/mail/<login>.

95.2.1.1.29. The [pepsi-httpd] Section

Options for pepsi-httpd(1). The server also reads the served domains (ACCEPTED_DOMAINS), the MTA-STS mx host (the ingress HOSTNAME) and the [pepsi] MTA_STS_* options.

MAX_CONNECTIONS

(number, optional) Maximum number of HTTP connections served concurrently. Default 256.

MAX_CONNECTIONS_PER_IP

(number, optional) Maximum simultaneous connections from one client address (an IPv4 address or an IPv6 /64); a connection over it is closed at once. Connections over a UNIX socket — from a reverse proxy — carry no client address and are not counted, so behind a proxy this limit belongs in the proxy. Default 32; 0 disables it.

DB_POOL_SIZE

(number, optional) Maximum number of PostgreSQL connections in the HTTP server’s database pool. The server handles requests concurrently, so unlike the single-connection stage workers it can use more than one. Defaults to 1; raise it only if the single connection limits how fast the endpoints answer, and keep the sum of every component’s pool below PostgreSQL’s max_connections.

RESUME_AUTHORIZATION_TOKEN

(string, optional) Bearer token guarding POST /resume (compared in constant time); the endpoint is disabled (404) when unset. Use the Taler secret-token: form so the same value can be reused as the merchant pepsi-resume webhook’s Authorization header (see pepsi-stage-anti-spam(1) and the [pepsi-payments] section).

ADDIN

(boolean, optional) Whether the Outlook add-in routes (GET /addin/manifest.xml, the compose and read panes, their script and icons) answer. Default no: a deployment that is not fronting Exchange has no use for them, and a manifest naming a gateway that nobody configured would only lead to support questions. See the manual’s “Microsoft Exchange as a gateway” and “Mail client extensions” chapters.

ADDIN_URL

(string, optional) The public https:// origin substituted into the add-in assets. Unset (the default) derives it from each request’s Host header. That works both when pepsi-httpd terminates TLS itself and when it sits behind a reverse proxy; in the latter case it sees plain HTTP over a UNIX socket and cannot tell the public scheme from the connection. Set it when the Host reaching Pepsi does not name the gateway. The scheme must be https, and this is enforced: Outlook refuses to load add-in resources over plain HTTP, so an http:// origin could only produce a manifest that fails at load time, and pepsi-httpd therefore refuses to start with one rather than serving it. The single exception is a loopback host (localhost, anything under .localhost, 127.0.0.0/8 or [::1]), where plain http:// is accepted so that a developer or a test needs no certificate. The value is checked whenever it is set, whether or not ADDIN is on, so a wrong one is reported before the feature is switched on.

REQUIRE_WEBAUTHN = no | all | KIND [KIND …]

(list, optional) Which kinds of account must use a WebAuthn security key as their second factor: admins (console accounts), users (end users who sign in by e-mail, own:<address>) and members (mailing-list member accounts), or all. Default no. For a kind that is listed, a TOTP code no longer completes a sign-in, an account of that kind without a key registers one as the last step of its next sign-in, and its last key cannot be removed (the operator’s recovery is the API’s WebAuthn reset). Without the list, a key is optional: an account that registers one needs it (or, where it has one, its TOTP code) from then on. admins and users need [pepsi-admin] CONSOLE_URL or ENROL_URL, members an https:// [pepsi-list] BASE_URL; pepsi-httpd(1) refuses to start otherwise.

Each [pepsi-httpd-listener-<name>] section binds one socket, with the same SERVE (tcp/unix/systemd) and transport options as a [pepsi-ingress-listener-<name>] section, except a tcp listener defaults to PORT 443 and MODE is plain or tls (no STARTTLS). A tls listener may set TLS_CERT/TLS_KEY as a fallback certificate; left unset, pepsi-setup(1) fills in the certbot lineage /etc/letsencrypt/live/<HOSTNAME>-web/, a certificate and key separate from the ingress listeners’ (whose key the TLSA record pins). It additionally accepts:

ADMIN = yes | no

Whether the administrative surface — the /api/v1 API, the /ui administration console and the /metrics page — is served on this listener. Optional; defaults to no. On a listener without it, those routes answer a plain 404, byte for byte what any unknown path gets, so publishing the public listener does not publish administration.

/metrics is in that set because per-stage queue depths, crash counters and stage names describe the pipeline; unlike the other two it takes no credential (a Prometheus scraper has none to present), so on a metrics listener this flag is the only access control. See pepsi-httpd(1).

pepsi-httpd(1) refuses to serve them on a flagged listener that would carry them in cleartext off this host: plaintext tcp is accepted only on a loopback address, while tls listeners and unix sockets always qualify. A plaintext SERVE = systemd listener never qualifies: the unit decided where the inherited descriptor listens, and the server cannot see that address, so it refuses the case that it cannot judge rather than allowing it. A flagged listener that fails the test logs a warning at start-up and serves the public endpoints only, and pepsi-setup(1) reports the same at validation time.

The shipped configuration flags one unix listener, which is the shape that needs no credentials at all: a connecting process is identified by SO_PEERCRED. See [pepsi-admin] below.

LIST_API = yes | no

Whether the GNU Mailman 3 compatible REST API (the /3.0/ and /3.1/ routes) is served on this listener. Optional; defaults to no, in which case those routes are a plain 404. It is subject to the same binding test as ADMIN (TLS, a unix socket, or plaintext tcp on loopback), and its credential is [pepsi-list] API_USER/API_PASS.

LIST_API_TESTING = yes | no

Whether that API additionally offers the test-only /3.1/reserved/reset hook, which empties the list and archive tables. Optional; defaults to no, and has no effect unless LIST_API is usable on the listener. For a compatibility test bed only.

LISTS = yes | no

Whether the public mailing-list web interface (archives, subscription pages) is served on this listener. Optional; defaults to no. Unlike the two flags above it is meant to be reachable from the open internet, so the binding test does not apply to it. Its rate limits are [pepsi-list] WEB_RATE_LIMIT and WEB_SEARCH_RATE_LIMIT.

Each [pepsi-httpd-cert-<name>] section registers one certificate for SNI selection: SNI (one or more host names), TLS_CERT and TLS_KEY. A listener’s own TLS_CERT/TLS_KEY is served to clients that send no SNI, and to an SNI name that no section lists only if it is valid for that name; any other SNI name fails the handshake.

95.2.1.1.30. The [pepsi-admin] Section

Options for the administrative API served by pepsi-httpd(1) on a listener flagged ADMIN = yes. Every option has a default, so the section may be omitted entirely. The authentication model, the scope table and the endpoint reference are in the manual’s “The administrative API” chapter.

The same options govern the /ui administration console, which is a client of that API and introduces no configuration of its own: it shares the session timeouts, the rate limits, the body cap, the page size and the configuration-write connection. See the manual’s “The administration console” chapter.

ADMIN_GROUP

(string, optional) UNIX group whose members are local administrators over a UNIX-socket listener, identified by SO_PEERCRED. root always is, group or no group. Default pepsi-admin.

SESSION_IDLE

(duration, optional) Idle timeout of a browser session, pushed forward on every request. Default 30 m.

SESSION_LIFETIME

(duration, optional) Hard lifetime of a browser session, never extended. Default 12 h. There is no “remember me”: this console can revoke a key and read who corresponds with whom, and local administrators, who log in most often, authenticate by SO_PEERCRED and have no session to expire.

EVENT_RETENTION_DAYS

(number, optional) How long audit records are kept, in days. Default 90. pepsi-httpd prune applies both retentions. pepsi-log-prune.timer runs it daily as the pepsi-httpd account, the one database role that holds DELETE on the logs, since no component that processes mail may erase them. The timer is independent of the web server: retention holds whether or not pepsi-httpd.service runs.

MAIL_LOG_RETENTION_DAYS

(number, optional) How long mail-log records are kept, in days, when [pepsi] MAIL_LOG is on. Default 30.

Both retentions are integers of days rather than durations because Section::duration parses through jiff::SignedDuration, which accepts only h/m/s and below.

RATE_LIMIT

(number, optional) Requests per minute per source address (a UNIX-socket listener shares one key for the whole host). 0 disables the limit. Default 120.

LOGIN_RATE_LIMIT

(number, optional) Login attempts per minute, counted per account and per source address — many passwords against one account and one password against many accounts are different attacks. 0 disables the limit. Default 10.

LOGIN_DAILY_LIMIT

(number, optional) Failed password sign-ins per account per day, from every source together. LOGIN_RATE_LIMIT alone still lets 600 guesses an hour reach one account; once an account has failed this many times the console refuses its password sign-ins with 429 until the allowance refills (at this many a day, continuously). A successful sign-in costs nothing, the account name is counted whether or not such an account exists, and the local socket and bearer tokens are not password sign-ins, so an operator can still act while an account is being guessed at. 0 disables the ceiling. Default 100.

MAX_BODY

(number, optional) Largest accepted request body, in bytes. Default 1048576.

PAGE_LIMIT

(number, optional) Default page size of a listing endpoint. A caller may ask for up to 1000; every listing honours limit and offset in its SQL and reports an exact total beside the page, and nothing returns an unbounded result set. Default 100; a configured value outside 1..``1000`` is clamped into that range rather than rejected.

CONFIG_DB

(PostgreSQL connection string, optional) Connection used for configuration writes. Unset by default, in which case PUT/DELETE on /api/v1/config answer 503 with the reason and every other endpoint is unaffected.

Writing pepsi.config_override belongs to the pepsi-config database role, which pepsi-setup(1) grants and explicitly revokes from every service account: a component that processes mail must not be able to rewrite the pipeline in which it runs. pepsi-httpd is such an account, and peer authentication goes by the effective uid, so its own connection cannot be that role. Point this at a connection that authenticates as pepsi-config, by a password in a secrets.d fragment readable only by the pepsi-httpd account or by a pg_ident map. The server checks with SELECT current_user at start-up and refuses a connection that authenticates as anything else, because a boundary that the code merely believes in is not a boundary. The refusal is not fatal: it is logged, the configuration-write path stays off, and the 503 names the role that the connection actually got. A server that started with a privilege that it was not meant to have would be the worse outcome.

The online setup enqueues through the same connection and for the same reason: only pepsi-config may INSERT into pepsi.setup_task, and the privileged applier refuses any row that says otherwise. Without CONFIG_DB the setup endpoints answer 503 too: the server can serve the questions and watch a task, but cannot ask for one.

APPLY_SOCKET

(path, optional) The socket through which pepsi-httpd wakes the privileged setup applier. Default /run/pepsi/setup-apply.sock.

After enqueuing a setup task, pepsi-httpd connects to this socket and closes it. That connection is the entire message: nothing is written to it and nothing is ever read from it, so it cannot become a command channel. Its only effect is that systemd’s socket activation starts pepsi-setup apply, which takes its work from the database (where every row is validated and audited) and exits again when there is none.

Pepsi uses a socket rather than a signal or a spawn because pepsi-httpd runs unprivileged and has no way to start a root process, and should not acquire one. This is the one mechanism that lets it cause a privileged process to run without being able to influence what that process does. A failure to connect is not an error: the task is durably queued either way, and pepsi-setup apply --once from cron or a console picks it up.

This path is also what APPLIER = auto probes; see below.

APPLIER

(auto|yes|no, optional) Whether a privileged setup change can happen from this server at all. Default auto.

The applier’s systemd units are packaged separately (Debian pepsi-httpd-admin, or make install INSTALL_ADMIN_UNITS=no from source), so that a deployment which is administered from a terminal can remove the one mechanism by which an HTTP request reaches /etc/pepsi. Without them, nothing drains pepsi.setup_task and an insert into it has no effect, so the console must not go on offering forms whose submissions would silently never be applied.

auto

Probe two things: that pepsi-setup-apply.socket exists as a unit file where systemd looks for one (installed), and that APPLY_SOCKET exists, is a socket and is writable by this account (armed — connecting to a UNIX socket needs write permission). The socket is never connected to: a connection wakes the applier, so probing that way would start a root process every time a page is rendered. The probe fails closed: any uncertainty, including a path that cannot be examined and a socket node left behind by a removed package, reads as “no applier”.

yes

Assume the applier is reachable and skip the probe. This is for a deployment that drains the queue some other way (pepsi-setup apply --once from cron, a hand-written unit, a host without systemd), where the probe would deny a capability that does exist. It is a promise the operator makes; nothing verifies it.

no

Refuse every privileged setup request whatever is installed. This makes the console read-only without changing the package set.

When there is no applier, pepsi-httpd still serves the setup interview, the staged answers and the task history — read-only, with the controls disabled — and answers the mutating endpoints 503 setup_applier_unavailable. See pepsi-httpd(1).

The ENROL_* options switch on sign-in by e-mail: an end user enters an address on /ui/enrol, receives a one-time link, and confirming it (with the address’s TOTP second factor when one is enrolled, checked by the privileged applier through a confirm-enrolment task) opens a console session confined to own:<address>. Enrolment needs the applier and CONFIG_DB; without them the address form answers that it is unavailable. See pepsi-httpd(1) and the manual’s “The administration console” chapter.

ENROL_STAGE

(string, optional) The stage at which the link mail is injected, normally the one through which local mail is delivered. Unset (the default) switches enrolment off, and its pages answer 404. pepsi-setup(1) refuses a name with no [stage-<name>] section carrying a PROGRAM, and refuses the option when the enrol-link.en.body template is missing.

ENROL_URL

(string; required with ENROL_STAGE) The https:// origin at which the mailed link points (scheme, host and optional port, nothing after it), that is, where users reach an ADMIN = yes listener, directly or through the TLS reverse proxy. Any other form is refused: the link carries a credential. It is never derived from the request’s Host, which a requester could choose.

ENROL_FROM

(string, optional) From: of the link mail. Default postmaster@ the address’s own domain.

ENROL_LIFETIME

(duration, optional) How long a link works. Default 30 m; at least 1 m. A link works once, accepts at most five submissions, and is replaced by the next one mailed to the same address.

ENROL_MAIL_PER_HOUR

(number, optional) How many links are mailed to one target address per hour. Default 3; at least 1.

ENROL_RATE_LIMIT

(number, optional) Enrolment requests and confirmations per client address per hour, on top of RATE_LIMIT. Default 20; at least 1.

CONSOLE_URL

(string, optional) The public https:// origin of the console (scheme, host and optional port), to which WebAuthn security keys are bound: every assertion must name this origin, and its host is the RP id. Default ENROL_URL; with neither set the console offers no security key. Changing the host later makes every registered key unusable (a key signs for the RP id with which it was registered), so pick a name under which users will keep reaching the console. The member pages use [pepsi-list] BASE_URL instead.

95.2.1.1.31. The Egress Identity Option: PUBLIC_IP

PUBLIC_IP = ADDR [ADDR …]

Whitespace- or comma-separated list of public IPv4 and/or IPv6 addresses that send mail as your domains. Each becomes an ip4: or ip6: mechanism in the v=spf1 record that pepsi-setup(1) suggests. No stage reads this option at run time: it is purely an input to the generated SPF record.

PUBLIC_IP is a per-stage option set in a relay stage’s [stage-<name>] section, and pepsi-setup(1) collects it from every stage whose PROGRAM is pepsi-stage-relay-to-internet(1) or pepsi-stage-relay-to-smarthost(1) (it detects them by PROGRAM, never by the section name) and unions the results. A deployment may therefore have several relay stages, each carrying its own PUBLIC_IP:

  • On a pepsi-stage-relay-to-internet stage it is this host’s own public sending IP(s): the host delivers directly to recipients’ MX from them.

  • On a pepsi-stage-relay-to-smarthost stage it is the smarthost’s egress IP(s): mail leaves the internet from the smarthost, so SPF must authorise it (many providers instead publish an include: that you add to the record by hand).

If no relay stage sets PUBLIC_IP, the generated record is a bare v=spf1 -all and pepsi-setup(1) logs a warning. That record tells receivers that no host may send for your domains, and it makes your own outbound mail fail SPF. A receive-only deployment (no relay stage) has no PUBLIC_IP and is not warned.

Each address must be a globally-routable public IP: the address from which receivers see mail arrive. pepsi-setup(1) warns (at validation and in the DNS output) if a PUBLIC_IP is a non-public address (loopback, RFC 1918 / unique-local, link-local, or CGNAT): behind NAT, use the host’s public egress IP, not its LAN address, or outbound mail over that address family will fail SPF.

Reverse DNS (PTR). Each pepsi-stage-relay-to-internet PUBLIC_IP, that is, this host’s own egress IP, must also have a forward-confirmed reverse DNS record that names the stage’s SERVER_NAME: a PTR for the address whose host name in turn resolves (via A/AAAA) back to the same address, and which is the very name that the stage announces in EHLO. Many receiving mail servers treat a missing, non-forward-confirmed, or generic/dynamic-looking PTR as a spam signal and reject or junk the mail, and many of them also compare the EHLO name against the PTR and refuse the session when the two name different hosts (HELO host does not match rDNS). Being inside your ACCEPTED_DOMAINS does not satisfy that test: a host that answers to several names can announce one and reverse-resolve to another, both of them its own, and still be refused. pepsi-setup(1) warns for every PUBLIC_IP whose reverse DNS is not correct in this sense, including that mismatch, and prints the remediation (see pepsi-setup(1)). Reverse DNS for a PUBLIC_IP lives in the zone of the IP’s owner (in-addr.arpa / ip6.arpa), usually your ISP or hosting provider, so unlike the forward records it is often not something that you can publish yourself. Where it cannot be changed, set SERVER_NAME (and [pepsi-ingress] HOSTNAME, the MX record and the TLS certificate) to the name that the PTR already gives. A pepsi-stage-relay-to-smarthost PUBLIC_IP names the smarthost’s egress IPs, whose reverse DNS the smarthost operator controls, so those are not checked.

The unioned record is published identically for every served domain. That is correct but broad; in special setups where different domains send from different hosts, a hand-written per-domain SPF record (listing only that domain’s own sending IPs) can be tighter and still correct. pepsi-setup(1) does not compute that grouping automatically and notes this in its DNS output.

95.2.1.1.32. The [pepsi-stage-relay-to-smarthost] MTA Sections

95.2.1.1.32.1. The Smarthost (MTA) Sections

Each [pepsi-stage-relay-to-smarthost-mta-<name>] section defines one upstream smarthost; the suffix <name> is a free-form label used in logs. These sections are shared by every smarthost-relay stage. A recipient domain is routed to the MTA whose DOMAINS lists it, or to the single CATCH_ALL MTA.

HOST

(string, required) Host name or address of the smarthost to connect to.

PORT

(number, required) TCP port to connect on (e.g. 587 or 465).

MODE

(optional) Transport security: starttls (default), tls (implicit TLS) or plain (cleartext).

TLS_VERIFY

(boolean, optional) Whether the smarthost’s TLS certificate is verified against the system trust store. Default yes; no accepts any certificate, which is not a troubleshooting step but exposes the connection to anyone on the path: whoever can intercept the connection (a man in the middle) presents a certificate of their own and receives the AUTH credentials and every relayed message. For a smarthost with a private CA, name that CA in TLS_CA_BUNDLE (or TLS_CA) instead. With verification on, an OCSP response that the smarthost staples is evaluated and a verified revoked refuses the session; no responder is queried.

TLS_CA

(path, optional) Extra CA certificates (PEM) to trust in addition to the system store. A certificate for the smarthost’s name from any root of the host’s store still authenticates it; TLS_CA_BUNDLE is the narrower choice.

TLS_CA_BUNDLE

(path, optional) The CA certificates (PEM) that are the whole trust store for this smarthost: the system roots are not consulted, so only a certificate that chains to one of these anchors authenticates it. Use it for a smarthost with its own CA, or to pin the one public CA that the provider uses. The file is read when the stage’s worker starts; if it cannot be read or holds no certificate, the worker refuses to start. Setting it together with TLS_CA, or with TLS_VERIFY = no, is a configuration error. A connection verified against it is not given the Certificate Transparency check, as for TLS_CA.

TLS_CLIENT_CERT / TLS_CLIENT_KEY

(path, optional; both-or-neither) A client certificate (PEM chain) and its private key to present to the smarthost during the TLS handshake (mutual TLS). Loaded fresh on every connection. Requires an encrypting MODE (tls or starttls) and applies to PKIX, TLS_VERIFY = no and DANE alike. The key is secret: keep it readable only by the pepsi-token group under which the relay stage runs SGID (on Debian, place cert + key in the SGID /var/pepsi/tls directory). Set AUTH = external to also authenticate the SMTP session with the certificate via SASL EXTERNAL.

DANE

(optional) DANE/TLSA (RFC 7672) enforcement towards this smarthost: off, warn (an explicit opt-out) or strict (the default). When the smarthost publishes DNSSEC-validated TLSA records at _<PORT>._tcp.<HOST>, the certificate is authenticated against them; a certificate that matches a usable record needs no TLS_VERIFY (PKIX) check. In warn a mismatch is logged and the certificate is then checked as without DANE, by TLS_VERIFY: with the default TLS_VERIFY = yes an impostor’s certificate is still refused. In strict a usable-but-mismatching record, or a failed TLSA lookup (including nameservers that cannot be determined), defers the message; under warn such a failure is logged and the hop proceeds with TLS_VERIFY. Where one usage and selector are published under both SHA-256 and SHA-512, only the SHA-512 records are matched (RFC 7671 section 9). Ignored when MODE = plain. Requires a DNSSEC-validating resolver reached over a trusted path (Pepsi trusts the response AD bit); see the stage’s DNS_SERVERS.

ADDRESS_FAMILY

(optional) Which IP address families may be used to reach this smarthost: any, ipv4 (also spelled v4/v4only) or ipv6 (v6/v6only).

Precedence is: this entry, then the owning [stage-*] section, then any. The per-entry level is what makes the option useful: one misbehaving destination can be pinned without forcing every other destination (including one that publishes only AAAA) onto the same family.

The motivating case is Microsoft Exchange Online, which rejects mail from a sending IPv6 address with no PTR record (550 5.7.1 ... S820). A dual-stacked host prefers IPv6, so a machine with correct IPv4 reverse DNS and undelegated IPv6 reverse DNS delivers fine everywhere except there.

With any (the default) the host name is handed to the system resolver. Any other value makes Pepsi resolve the host itself and try each address of the chosen family in turn. A destination that publishes no address of the chosen family is a transient failure, not a bounce: that is an operator error worth retrying past, not one worth destroying queued mail over.

AUTH

(optional) SMTP authentication mechanism: none (default), plain, login, cram-md5, digest-md5, scram-sha-1, scram-sha-256, scram-sha-1-plus, scram-sha-256-plus, auto, external, oauth, ntlm or gssapi. plain/login/cram-md5/digest-md5/the scram-* family/auto all require USERNAME and PASSWORD; oauth requires USERNAME and TOKEN_FILE; external (SASL EXTERNAL, RFC 4422) requires TLS_CLIENT_CERT / TLS_CLIENT_KEY and authenticates by that certificate (no password sent), with an optional USERNAME as the SASL authorization identity. cram-md5 (RFC 2195) and scram-sha-1/scram-sha-256 (RFC 5802 / RFC 7677) are challenge/response: the password is never sent, and SCRAM additionally authenticates the server to Pepsi (a bad server signature aborts the exchange and, like any rejected AUTH, defers the message). The -plus SCRAM variants add tls-server-end-point channel binding (RFC 5929). auto picks the strongest mechanism that the smarthost advertises (SCRAM-SHA-256-PLUS > SCRAM-SHA-256 > SCRAM-SHA-1-PLUS > SCRAM-SHA-1 > CRAM-MD5 > LOGIN > PLAIN); it never selects the deprecated digest-md5, ntlm or gssapi. digest-md5 (RFC 2831) is also a challenge/response with server authentication (rspauth) but is deprecated (RFC 6331 moved it to Historic) and provided only for legacy smarthosts; selecting it logs a warning from pepsi-setup(1) and at runtime. ntlm is the de-facto Microsoft mechanism (no RFC; NTLMv2 only, with tls-server-end-point EPA channel binding) requiring USERNAME/PASSWORD/NT_DOMAIN; it is weak and does not authenticate the server, so pepsi-setup(1) warns. gssapi is SASL GSSAPI/Kerberos (RFC 4752); it takes no password, obtaining a service ticket for SERVICE_NAME from a credential cache (KRB5CCNAME). All are offered only over an encrypted transport (MODE = tls/starttls); ntlm and gssapi reject MODE = plain at configuration time.

USERNAME / PASSWORD

(string, required when AUTH is plain/login/cram-md5/digest-md5/scram-*/auto/ntlm) The SMTP-AUTH credentials. Keep PASSWORD in a mode-restricted file merged with @inline-secret@. For the scram-* mechanisms both are normalised with SASLprep (RFC 4013). USERNAME is also the optional authorization identity for AUTH = external and AUTH = gssapi.

NT_DOMAIN / NT_WORKSTATION

(string; NT_DOMAIN required when AUTH = ntlm) The Windows domain of the NTLM account, and an optional cosmetic client workstation name.

SERVICE_NAME

(string, optional; AUTH = gssapi) The Kerberos host-based service principal of the smarthost, in service@host form. Defaults to smtp@<HOST>.

KRB5CCNAME

(string, optional; AUTH = gssapi) The Kerberos credential cache to read for this smarthost (e.g. FILE:/var/pepsi/krb5/smarthost.cc), overriding the ambient KRB5CCNAME. It is handed to the Kerberos library with the request (gss_acquire_cred_from); the process environment is never changed. Pepsi only reads the cache; an external keytab + k5start/cron job must keep the ticket fresh, and the cache must be readable by the relay worker (the SGID pepsi-token group; see /var/pepsi/krb5). A missing/expired ticket defers the message (transient failure) rather than bouncing it.

TOKEN_FILE

(path, required when AUTH = oauth) File holding the current OAuth 2.0 access token (whitespace-trimmed), re-read on every delivery. The SASL mechanism is chosen from the smarthost’s EHLO (OAUTHBEARER preferred, else XOAUTH2). The relay stage only reads this file; keep it current with pepsi-helper-token-refresh(1) (see the [pepsi-helper-token-refresh-*] sections) or any equivalent external job. A missing/expired/rejected token defers the message (transient failure) rather than bouncing it.

HELO_NAME

(string, optional) Name announced in EHLO to this smarthost. Defaults to the stage’s SERVER_NAME. An explicit HELO_NAME takes precedence over the stage’s EHLO_FROM_PTR.

DOMAINS

(string) Whitespace/comma-separated recipient domains routed to this MTA (case-insensitive). Required unless CATCH_ALL = yes; a domain may be routed by at most one MTA.

CATCH_ALL

(boolean, optional) Whether this MTA receives every domain not matched by a DOMAINS entry. Default no; at most one MTA may set it. An MTA must list DOMAINS or set CATCH_ALL = yes.

95.2.1.1.33. The [pepsi-helper-token-refresh] Sections

These configure pepsi-helper-token-refresh(1), the optional service that keeps the OAuth access tokens of AUTH = oauth smarthosts current. The set of tokens to maintain is derived from the smarthost MTA sections: for each [pepsi-stage-relay-to-smarthost-mta-<name>] with AUTH = oauth the service looks for a matching [pepsi-helper-token-refresh-<name>] section. The service is not part of pepsi.target; enable it explicitly.

Because the per-target sections hold OAuth client secrets, keep them in a file readable only by the pepsi-helper-token-refresh user and include each with the @inline-secret@ directive. A reader that cannot open the file, such as the relay stage running as pepsi, silently skips the directive, so the same pepsi.conf parses for both. See pepsi-helper-token-refresh(1) and the Extending the Pipeline manual chapter.

The optional base section [pepsi-helper-token-refresh] holds service-wide, non-secret options:

STATE_DIR

(path, optional) Private directory (mode 0700) for per-target rotated refresh tokens. Default /var/pepsi/token-refresh.

Each [pepsi-helper-token-refresh-<name>] section (<name> matching an OAuth smarthost MTA) holds:

TOKEN_ENDPOINT

(string, required) The provider’s OAuth 2.0 token endpoint URL. It must be an https:// URL: any other scheme fails that target’s refresh rather than sending the client secret in cleartext. It is also how the service tells a missing secret section from an unreadable one: an @inline-secret@ file that this account cannot open simply is not there, so an absent TOKEN_ENDPOINT skips that target with a warning instead of failing the service. The remaining options below are then errors, not skips.

GRANT

(optional) refresh_token (the default; e.g. Google) or client_credentials (e.g. Microsoft 365 app-only).

CLIENT_ID / CLIENT_SECRET

(string, required) The OAuth client credentials, sent in the request body.

REFRESH_TOKEN

(string, required for GRANT = refresh_token) The long-lived refresh token. A rotated value returned by the endpoint is persisted under STATE_DIR and then takes precedence.

SCOPE

(string, required for GRANT = client_credentials; optional otherwise) The requested scope.

REFRESH_MARGIN

(duration, optional) How long before a token’s stated expiry to refresh it. Default 5 m. Uses h/m/s units only.

95.2.1.1.34. The [pepsi-payments] Section

This optional section configures the GNU Taler payment integration. When it is absent (or MERCHANT_BACKEND_URL is unset) pepsi-setup(1) performs no merchant checks and no webhook is provisioned. The same section is read at run time by pepsi-stage-anti-spam(1) to create per-message payment orders.

MERCHANT_BACKEND_URL = URL

Base URL of the Taler merchant backend, optionally including the instance (…/instances/$ID). pepsi-setup(1) requests GET /config at the backend root (any trailing /instances/$ID is stripped) to confirm it is a taler-merchant backend, and GET /private/orders?limit=1 at this URL to confirm the access token. Required to enable the integration.

It must be an https:// URL, or an http:// one whose host is the loopback interface (localhost, 127.0.0.0/8, ::1). MERCHANT_ACCESS_TOKEN is attached to every request as a bearer credential, so a cleartext backend anywhere else, including one that “is only on the LAN”, hands that long-lived credential to whatever sits on the path. Requests are bounded (10 s to connect, 30 s in total), so an unresponsive backend costs a message, not the stage: pepsi-stage-anti-spam(1) holds that message and asks again until its payment deadline, then delivers it unverified.

MERCHANT_ACCESS_TOKEN = TOKEN

Access token for the merchant backend, in the Taler secret-token:… form, sent as an Authorization: Bearer credential. It needs the orders-read and webhooks-read/webhooks-write permissions. Required when MERCHANT_BACKEND_URL is set.

The provisioned pepsi-resume webhook fires on the pay event and POSTs {"message_id":"{{order_id}}"} to https://<host>/resume (the shortest [pepsi-httpd-cert-*] SNI host), authenticated with [pepsi-httpd] RESUME_AUTHORIZATION_TOKEN. The merchant order_id must therefore equal the message’s external token.

95.2.1.1.35. The [pepsi-vacation-default-message] Section

The per-language vacation notices to which pepsi-stage-vacation(1) falls back, one option per language:

[pepsi-vacation-default-message]
EN = Hello {{SENDER_NAME}},  I am away until {{VACATION_END}}.
DE = Hallo {{SENDER_NAME}},  ich bin bis {{VACATION_END}} abwesend.

The option name is the language tag (EN, DE, PT_BR — either separator), and the value is a Mustache template. Which language is used, which fields expand, and why two spaces become a newline are all documented in pepsi-stage-vacation(1).

This section normally already exists. make install ships it as ${DATADIR}/config.d/vacation.conf, and taler’s configuration loader parses every file in ${DATADIR}/config.d before pepsi.conf. So a stage configured with no message of its own still has ten languages available, and an operator who wants different wording redefines just the language they care about in pepsi.conf: later definitions win option by option, never section by section, so overriding EN leaves the other nine in place. Editing the shipped file works too, but a package upgrade overwrites it.

The section name is only a default (DEFAULT_MESSAGE_SECTION), so an operator who wants several message sets (a formal one for a support address, a terse one for everyone else) can define more sections and point different stages, domains or addresses at them.

An account owner never touches this section: their own text goes in MESSAGE_<LANG> in the stage’s own section, which the settings layer can carry and which wins per language.

95.2.1.1.36. The [pepsi-autoconfig] Section

This optional section publishes mail account autoconfiguration (draft-ietf-mailmaint-autoconfig): the XML document that a mail client fetches, knowing only the user’s address, so that it can configure itself instead of asking for eight settings the user usually cannot supply. It is served by pepsi-httpd(1) at /mail/config-v1.1.xml on autoconfig.<domain>, and at /.well-known/autoconfig/mail/config-v1.1.xml on the mail domain itself.

The feature is off until an incoming server is named. If you omit the section, or set neither IMAP_HOST nor POP3_HOST, both endpoints answer 404. A client that finds a configuration document stops walking the fallback chain, so publishing one that cannot tell it how to read mail leaves the user worse off than publishing nothing at all.

Pepsi does not serve mailboxes (see pepsi-stage-relay-to-lmtp(1)), so the incoming half must name whatever MDA the deployment pairs with, typically Dovecot on the same host.

Two things outside this file are needed as well. An autoconfig.<domain> DNS record must resolve to this server, and the TLS certificate must cover that name: clients try the https://autoconfig.… URL first, and a certificate error there is a failed lookup. The certificate half is handled for you when pepsi-setup(1) provisions certificates: with this section naming an incoming server it adds autoconfig.<domain>, for every served domain, to the names that it requests for the TLS [pepsi-httpd-listener-*] certificate. The DNS record is not handled for you, since it is published in your zone. A deployment unwilling to add the name can rely on the /.well-known/ form alone, at the cost of being found only by clients that try it.

IMAP_HOST, POP3_HOST

(hostname, optional) The mailbox server to advertise. Setting either enables the feature; setting neither disables it. There is no default: an invented hostname would be worse than silence.

IMAP_PORT, POP3_PORT

(number, optional) Defaults 993 and 995, the implicit-TLS ports.

IMAP_SOCKET, POP3_SOCKET

(``SSL`` | ``STARTTLS`` | ``plain``, optional) Transport security, in the draft’s own vocabulary (SSL means implicit TLS); tls and none are accepted as spellings of SSL and plain. Default SSL. A value of plain is refused unless ALLOW_PLAIN_AUTOCONFIG (below) says it is intended.

ALLOW_PLAIN_AUTOCONFIG

(yes/no, default no) Acknowledge that a server that this section advertises with a *_SOCKET of plain is meant to be used without TLS. Without it, a plain anywhere in this section makes pepsi-setup(1) validate refuse the configuration and pepsi-httpd(1) refuse to start, each naming the option, the server and its port. A plain that slipped in by mistake therefore never reaches a client, which would apply it without asking and send its password and mail in clear. Set it to yes on a closed network (a loopback or VPN-only mailbox server) where plaintext is the deliberate choice; the plaintext server is then published as asked, and pepsi-httpd still logs a warning for it at every start. It never affects a derived submission server, which is never plaintext.

IMAP_AUTH, POP3_AUTH

(optional) One of the draft’s authentication values: password-cleartext, password-encrypted, NTLM, GSSAPI, TLS-client-cert, OAuth, client-IP-address, none. Default password-cleartext, which over SSL is the ordinary password-over-TLS arrangement rather than anything sent in the clear. An unrecognised value is a start-up error, not a silently published typo.

SMTP_HOST, SMTP_PORT, SMTP_SOCKET, SMTP_AUTH

(optional) The submission server to advertise. Normally omit all four: they are derived from the port, the MODE and the authentication mechanism of the [pepsi-ingress-listener-*] section flagged SUBMISSION = yes, so moving submission from STARTTLS on 587 to implicit TLS on 465 updates the published document by itself, and the two cannot drift apart. Set them only when the public submission endpoint is not the listener, for instance behind a load balancer. Setting SMTP_HOST switches off the derivation entirely, so give the others too if they differ from 587/STARTTLS/ password-cleartext. SMTP_SOCKET = plain needs the same ALLOW_PLAIN_AUTOCONFIG acknowledgement as the incoming servers.

A UNIX-socket or systemd-activated submission listener is never advertised: a remote client cannot use the first, and the second has no port in the configuration to publish.

DISPLAY_NAME, DISPLAY_SHORT_NAME

(text, optional) What the client shows the user. Both default to the first [pepsi-ingress] ACCEPTED_DOMAINS entry (the ingress HOSTNAME when no domain is configured).

DOCUMENTATION_URL

(URL, optional) A help page for the account settings, published as the draft’s <documentation> element. Omitted when unset.

[pepsi-autoconfig]
IMAP_HOST = mail.example.org
POP3_HOST = mail.example.org
DISPLAY_NAME = Example Mail
DISPLAY_SHORT_NAME = Example
# SMTP_* deliberately omitted: derived from the submission listener.

95.2.1.1.37. The [pepsi-tlsrpt] Section

This optional section configures SMTP TLS Reporting (RFC 8460). It has two independent halves; omit the section to disable both. pepsi-setup(1) reads it for the advertising half; the sender half is read at run time by the relay stages (session recording) and pepsi-tlsrpt(1) (the daily report job).

RUA = URI [, URI …]

Reporting address(es) advertised in the _smtp._tls.<domain> TXT record that pepsi-setup(1) emits for each domain, so that other senders report to us their TLS results for mail to our domains. A mailto: or https: URI, or a comma-separated list, stored verbatim. When unset, no record is published.

SEND_REPORTS = yes | no

Whether the relay stages record each outbound TLS session in pepsi.tls_session. Optional; defaults to no. It is the switch for the recording half only: when RUA is set, pepsi-tlsrpt(1) does not test it, it simply finds no sessions to report when nothing records them (with neither RUA nor this option the section counts as absent, and pepsi-tlsrpt report refuses to run).

REPORT_FROM = ADDRESS

Envelope sender and From: of the report e-mails that pepsi-tlsrpt(1) sends. Required to send reports (its domain is the report submitter). Reports are not null-sender (RFC 8460 §5.3: they must be DKIM/DMARC-alignable); the report-about-a-report loop is prevented by the injected state.tlsrpt flag.

REPORT_STAGE = STAGE

Pipeline stage at which report e-mails are injected (so that they are signed and relayed), like the pepsi-stage-anti-spam(1) BLOCK_RESPONSE_STAGE. Must reference an existing [stage-*]. Required to e-mail (mailto:) reports.

ORGANIZATION = NAME

organization-name placed in emitted reports. Optional; defaults to the REPORT_FROM domain.

CONTACT = ADDRESS

contact-info placed in emitted reports. Optional.

RETAIN_DAYS = DAYS

How many days pepsi-tlsrpt prune keeps pepsi.tls_session counters. Optional; defaults to 7. pepsi-tlsrpt-prune.timer runs the prune daily.

95.2.1.1.38. The [pepsi-dmarc-reports] Section

This optional section governs the DMARC aggregate reports that pepsi-stage-dmarc-report(1) stores. It is read by that stage (at worker start), by pepsi-queue(1) gc, pepsi-status(1), the administrative console and pepsi-setup(1) check. Every option has a default.

RETAIN_DAYS = DAYS

How many days a report is kept after the end of the period that it covers; pepsi-queue gc (pepsi-origin-gc.timer, hourly) deletes older ones with their records. Default 90, at least 1.

WINDOW_DAYS = DAYS

How many days back, by the end of each report’s period, the summaries and the pepsi-setup check verdict look (every source aligned, so p=reject is safe; or the sources it refuses). Default 7; between 1 and RETAIN_DAYS.

95.2.1.1.39. The [pepsi-telemetry-client] Section

This optional section configures the local feature-telemetry aggregator, pepsi-telemetry-client(1). All options have working defaults; the whole feature is gated by [pepsi] SHARE_TELEMETRY above, which is off unless the operator turned it on. Nothing here has any effect until it is on. (The central collector, pepsi-telemetry(1), reads the separate [pepsi-telemetry] section instead.)

UNIXPATH = PATH

Local UNIX socket on which the daemon listens for feature events; the producer programs connect to the same path. Optional; defaults to /run/pepsi-telemetry/socket.

UNIXPATH_GROUP = GROUP

Group to which the socket is chgrp-ed (mode UNIXPATH_MODE), so that the producers can connect: the users pepsi (stage workers, dispatcher), pepsi-ingress, pepsi-httpd and pepsi-keydisc, which are all members of it. Optional; defaults to pepsi-telemetry.

UNIXPATH_MODE = OCTAL

Permission bits of the socket. Optional; defaults to 660.

SUBMIT_INTERVAL = DURATION

Interval between submissions to the collector (h/m/s units only — see the duration note above). Optional; defaults to 60 s. Zero is a configuration error, not a busy loop.

MAX_FEATURES = N

Cap on the number of distinct feature names held in memory, bounding memory against a misbehaving local producer. Optional; defaults to 4096.

95.2.1.1.40. Stored Data

For every accepted message, pepsi-ingress(1) inserts one row into the pepsi.workqueue table containing a local identifier (workqueue_id), a random token, the reception timestamp (received_at), the envelope sender (mail_from; the empty string for the null sender <>), the envelope recipient list (rcpt_to), and the parsed from_header and subject headers. The message itself is stored split in two: a headers column (the RFC 5322 header block up to but not including the blank-line separator, with the RFC 5321 §4.4 trace Received: header and, above it, the Authentication-Results header prepended; the ARC set is added later by pepsi-stage-arc(1)) and a body (everything after the blank line; empty for a header-only message). The reconstruction invariant is raw = headers || CRLF || body. Splitting the message lets stages that only touch the headers or envelope load (and rewrite) just the headers column and never pull the (potentially large) body.

The body is not a column of pepsi.workqueue but a row of its own table, pepsi.workqueue_body (body_id, body, and the generated size octets), which the message row references by body_id. This keeps a multi-recipient message from being stored once per recipient. Every row split from it references the same body row, whether the split comes from per-address settings, a relay stage’s one row per recipient, a mailing-list fan-out, or a per-recipient bounce or DSN, so a 25 MiB post to a thousand members is one 25 MiB body and a thousand small rows. A stage that rewrites a body (decryption, a list’s footer) stores a new body row and repoints only its own message (copy-on-write), so no rewrite can reach a sibling. A body is deleted by a trigger as soon as the last row referencing it is deleted or repointed, and pepsi-dispatch(1) sweeps the rare orphan that a race leaves behind (pepsi.workqueue_body_gc()). header_octets is the matching generated size of headers. The queue admission check (MAX_QUEUE_BYTES, pepsi.queue_usage()) sums the two size columns, which roles that may not read the message itself can still read. The computed SPF, DKIM and DMARC verdicts are stored in the row’s state under an auth key, and the authserv_id under state.origin; the arc verdict starts as none and is filled in by the ARC stage. The dispatcher is not notified from that transaction: pepsi-ingress(1) coalesces admissions and issues at most one wake per DISPATCH_WAKE_INTERVAL, out of band and after the rows commit, with an empty payload (see that option’s description above). A LISTEN workqueue consumer therefore gets no per-message notification and no payload to parse.

Each row additionally carries its processing state for the stage pipeline that runs after ingress: a stage (the [stage-<stage>] section of the program currently responsible for advancing the message), a status (one of pending, running, paused, failed or timeout), a state (the JSON object carried with the message, documented in pepsi.state(7)), and a timeout (when a paused message should be re-queued). Every new message is inserted explicitly at the initial stage — stage = init, status = pending — so it enters the pipeline at [stage-init]. These columns are inspected and repaired with pepsi-queue(1).

pepsi.workqueue (with its bodies in pepsi.workqueue_body) is the only queue of messages in flight; the schema has some eighty-five tables in all. The table that every deployment uses besides the queue is pepsi.dns_address: a cache of resolved A/AAAA addresses for recipient mail-exchanger hosts, with per-address connect health, maintained by pepsi-stage-relay-to-internet(1). Each row records a host, one resolved address, the DNS-TTL expires_at, a failed flag and the last_success_at time, so a working address is preferred until its TTL elapses and a host is re-resolved once all its cached addresses have failed or expired. It carries no message data; pepsi-queue(1) gc deletes its expired rows. Beside it, pepsi.mta_sts_policy holds the MTA-STS policies that the same stage has fetched, per recipient domain, until their max_age passes, so a policy stays enforced across worker restarts; pepsi-queue(1) gc refreshes them before that, so a policy does not lapse for want of mail.

The rest are the feature tables, each described with the component that owns it: the pipeline counters stage_stats and dispatch_stats (pepsi-dispatch(1), exported by pepsi-httpd(1) at /metrics), whitelist (pepsi-whitelist(1)), tls_session (pepsi-tlsrpt(1)), settings (pepsi-settings(1)), vacation_reply (pepsi-stage-vacation(1)), payment_request_reply (pepsi-stage-anti-spam(1)), secretary_challenge, secretary_sent and secretary_answered (pepsi-stage-secretary(1)), mailbox_quota (pepsi-quota(1)), config_override (the database configuration layer, pepsi-config(1)), origin_nonce and auto_pay_spend (pepsi-stage-auto-pay(1)), telemetry (pepsi-telemetry(1)), secure_message and secure_access (pepsi-secure-link(1)), the key store crypto_identity / peer_key / peer_has_own_key / ca_trust / key_request / otp_key / otp_pending / smime_capability / compromised_key / compromised_key_import / crl_cache / ca_issuer_cache (pepsi-keys(1) and pepsi-keydisc(1)), signed_sender (pepsi-stage-decrypt(1)), dmarc_report and dmarc_report_record (pepsi-stage-dmarc-report(1)), ip_blocklist, ip_blocklist_source and reputation_check (pepsi-reputation(1)), the mailing-list tables mailing_list and list_* (pepsi-list(1)) except list_confirmation, the table of subscription confirmation requests that outside lists send to local users (pepsi-stage-check-whitelist(1) records them and pepsi-stage-auto-whitelist(1) matches them), the list archive archive_* (pepsi-archive(1)), the RFC 7293 login record login_assignment (pepsi-setup(1), The login assignment record), the logs event_log and mail_log, the telemetry daemon’s liveness row telemetry_client (pepsi-telemetry-client(1)), the schema record schema_file, and the administrative surface admin_account / admin_session / api_token / setup_task / setup_task_log / own_enrolment / own_session / webauthn_credential / webauthn_challenge (pepsi-httpd(1) and pepsi-setup(1)). All of them are created by pepsi-setup(1). Apart from secure_message (ciphertext awaiting its recipient), the list archive, whose purpose is to keep posts, and the messages a list holds for moderation, none holds message content.

The state column is the JSON object carried with the message from ingress to its terminal stage; it is the channel through which stages communicate. Ingress seeds it with the connection’s SMTP-origin provenance, the inbound SPF/DKIM/DMARC verdicts and any RFC 3461 DSN parameters; later stages merge in their own verdicts and scratch. Its full layout, with every key and who writes and consumes it, is documented in pepsi.state(7).

95.2.1.1.41. Example

A complete forwarder: receive on the three canonical SMTP ports, ARC-seal on arrival, SRS-rewrite, deliver direct-to-MX, and bounce failures (signing the bounce before delivery):

[pepsi]
DKIM_SELECTOR = pepsi
ARC_DOMAIN = example.org
ARC_ALGORITHM = rsa

[pepsi-postgres]
CONFIG = postgres:///pepsi
# SQL_DIR defaults to ${DATADIR}/sql; set it when running from a checkout.

[pepsi-ingress]
HOSTNAME = mail.example.org
ACCEPTED_DOMAINS = example.org example.com
MAX_MESSAGE_SIZE = 26214400

# The three canonical SMTP listeners. TLS_CERT/TLS_KEY are omitted so
# pepsi-setup auto-fills the certbot path and obtains the certificate.

# Port 25: cleartext with opportunistic STARTTLS.
[pepsi-ingress-listener-mx]
SERVE = tcp
BIND_TO = 0.0.0.0
PORT = 25
MODE = starttls
MYNETWORKS = 127.0.0.0/8 ::1/128 10.0.0.0/8

# Port 465: implicit TLS (SMTPS), authenticated submission via Dovecot SASL.
[pepsi-ingress-listener-submissions]
SERVE = tcp
BIND_TO = 0.0.0.0
PORT = 465
MODE = tls
SUBMISSION = yes
SASL_TYPE = dovecot
SASL_PATH = /run/dovecot/auth-client-pepsi

# Port 587: cleartext submission upgraded with STARTTLS.
[pepsi-ingress-listener-submission]
SERVE = tcp
BIND_TO = 0.0.0.0
PORT = 587
MODE = starttls
SUBMISSION = yes
SASL_TYPE = dovecot
SASL_PATH = /run/dovecot/auth-client-pepsi

[pepsi-srs]
SRS_DOMAIN = srs.example.net
SECRET_FILE = /etc/pepsi/srs.secret

# init: ARC-seal the message as received, then hand to SRS.
[stage-init]
PROGRAM = pepsi-stage-arc
NEXT_STAGE = srs

[stage-srs]
PROGRAM = pepsi-stage-srs
NEXT_STAGE = deliver

# deliver: direct-to-MX; failures go to the bounce stage.
[stage-deliver]
PROGRAM = pepsi-stage-relay-to-internet
SERVER_NAME = mail.example.org
POSTMASTER = postmaster@example.org
BOUNCE_STAGE = bounce
# This host's public sending IP(s); pepsi-setup unions PUBLIC_IP from every
# relay stage into the SPF record.
PUBLIC_IP = 203.0.113.7 2001:db8::25

# bounce: build an unsigned DSN, sign it, then deliver it.
[stage-bounce]
PROGRAM = pepsi-stage-bounce
SERVER_NAME = mail.example.org
POSTMASTER = postmaster@example.org
NEXT_STAGE = bounce-sign
BOUNCE_MESSAGE = default

[stage-bounce-sign]
PROGRAM = pepsi-stage-dkim-sign
NEXT_STAGE = deliver

To relay via a smarthost instead, replace the deliver stage’s PROGRAM with pepsi-stage-relay-to-smarthost and add [pepsi-stage-relay-to-smarthost-mta-*] sections, e.g.:

[pepsi-stage-relay-to-smarthost-mta-smarthost]
HOST = smtp.relay.example.net
PORT = 587
CATCH_ALL = yes

95.2.1.1.42. Files

Every Pepsi component reads the same file. When a component is started without –config, the first existing path from the following list is used:

  • $XDG_CONFIG_HOME/pepsi.conf

  • $HOME/.config/pepsi.conf

  • /etc/pepsi/pepsi.conf

  • /etc/pepsi.conf

pepsi-setup --wizard writes /etc/pepsi/pepsi.conf; make install places a reference pepsi.conf.sample beside it, which documents every option but is not itself a working configuration.

Before that file is read, every *.conf in ${DATADIR}/config.d is parsed, so packaged defaults are in place and pepsi.conf overrides them option by option (a section defined in both is merged, not replaced). Two are shipped:

  • vacation.conf — the per-language vacation notices; see The [pepsi-vacation-default-message] Section above.

  • reputation.conf — the IP blocklists; see The [pepsi-reputation-list-*] Sections above.

make install deletes any thunderbird.conf from that directory, because every file there is parsed and that one would set a global CRYPTO_ALLOW_DOWNGRADE = yes. The per-peer S/MIME capability record described under CRYPTO_ALLOW_DOWNGRADE makes that decision for each correspondent instead.

These files belong to the package: redefine the options you want in pepsi.conf rather than editing them, or an upgrade will discard the change.

95.2.1.1.43. See Also

pepsi-ingress(1), pepsi-dispatch(1), pepsi-httpd(1), pepsi-setup(1), pepsi-config(1), pepsi-queue(1), pepsi-status(1), pepsi-sendmail(1), pepsi-whitelist(1), pepsi-settings(1), pepsi-tlsrpt(1), pepsi-quota(1), pepsi-failure-bouncer(1), pepsi-list(1), pepsi-keys(1), pepsi-keydisc(1), pepsi-secure-link(1), pepsi-detect-language(1), pepsi-telemetry(1), pepsi-telemetry-client(1), pepsi-helper-token-refresh(1), pepsi-helper-auto-pay(1), pepsi-helper-mailbox-scan(1), pepsi-stage-arc(1), pepsi-stage-srs(1), pepsi-stage-encrypt(1), pepsi-stage-decrypt(1), pepsi-stage-autocrypt-learn(1), pepsi-stage-secure-link(1), pepsi-stage-vks-confirm(1), pepsi-stage-dmarc-report(1), pepsi-stage-route(1), pepsi-stage-dkim-sign(1), pepsi-stage-relay-to-internet(1), pepsi-stage-relay-to-smarthost(1), pepsi-stage-relay-to-lmtp(1), pepsi-stage-relay-to-maildir(1), pepsi-stage-dot-forward(1), pepsi-stage-bounce(1), pepsi-stage-discard(1), pepsi-stage-anti-spam(1), pepsi-stage-auto-pay(1), pepsi-stage-check-whitelist(1), pepsi-stage-auto-whitelist(1), pepsi-stage-detect-language(1), pepsi-stage-block-language(1), pepsi-stage-if(1), pepsi-stage-milter(1), pepsi-stage-aliases(1), pepsi-stage-vacation(1), pepsi-stage-edit-settings(1), pepsi-archive(1), pepsi-stage-list(1), pepsi-stage-list-post(1), pepsi-stage-list-deliver(1), pepsi-stage-list-command(1), pepsi-stage-list-bounce(1), pepsi.state(7), systemd.socket(5)

95.2.1.1.44. Bugs

Report bugs to the Pepsi issue tracker.