6. The Wizard

pepsi-setup --wizard runs a short interview and writes a complete, already-validated pepsi.conf. It is the intended way to produce a first configuration: the next chapter, Configuration, explains the file the wizard writes, and this one explains how the answers become that file.

The stage pipeline is assembled from the answers. Which stages exist, and how their NEXT_STAGE and BOUNCE_STAGE options wire together, follows mechanically from the direction the host serves and the features that were switched on. There is no menu of pipelines to pick from and no template being filled in; the graph is computed. This chapter shows the three pipelines that the wizard can build, then which question inserts or removes each stage in them.

Note

This chapter describes what the answers do. The operational detail of the command is in pepsi-setup(1): every flag, the MTA migration, the readline bindings, the secret-prompt behaviour and the answer-file format.

6.1. How a run proceeds

  1. Import. On a host with no pepsi.conf yet, the wizard detects an existing Postfix, Exim, Sendmail, qmail or Stalwart and offers to read its settings in as the interview’s defaults. Nothing is adopted silently: every imported value is still shown at its own prompt. On a re-run, the [pepsi-wizard] section of the existing file supplies the defaults instead.

  2. Interview. The wizard asks the questions below, grouped into numbered steps. Each answer is validated as it is entered, so a malformed domain or port is caught at its own prompt.

  3. Render. The answers are turned into a configuration file — this is where the pipeline is assembled.

  4. Validate. The rendered text is loaded and validated through the very same path that pepsi-setup run uses. If it fails, the wizard prints the fault and walks back through the questions with the previous answers pre-filled, so to correct one option, you press Enter to walk past the rest.

  5. Write. The file is written, and the secrets in it (the SRS HMAC key, the smarthost and LMTP passwords, the merchant and /resume tokens, the mailing lists’ UNSUBSCRIBE_SECRET and VERP_SECRET) are moved out into mode-restricted secrets.d/*.secret fragments referenced by @inline-secret@ directives. What was written is then re-loaded and re-validated, because moving the secrets rewrote it. We do this so that pepsi.conf itself can stay world-readable without exposing a secret (see Mail appliances store secrets world-readable or unprotected).

  6. Offer to run setup. Installing the schema, having pepsi-dkim(1) make the DKIM keys, provisioning TLS certificates and printing the DNS records to publish are pepsi-setup run’s job, not the interview’s. The wizard offers to chain straight into it.

The same interview is also asked by the browser setup console (see The administration console).

6.2. The same interview in a browser

There is no second interview. Every question, its shape, its default, its help text and the conditions under which it is asked live in one place as data (pepsi_setup_model::questions), and both front-ends render that model. A question therefore cannot be added to one front-end and not the other, and a test asserts that the two sets of identifiers are equal. Only the presentation differs: the terminal asks one question at a time under the step banners listed below, while the console shows the same questions a page at a time, in its own, coarser grouping.

The Server identity step of the browser setup console

The first step. Each field carries the same help that the terminal prints. Where the answer maps to exactly one option, the field also shows the [section] OPTION that the answer will end up in, so that the same setting can be found in the file afterwards. The strip along the top is the whole interview, with the steps that have been answered marked.

The branching is part of the model too, so the console hides what the terminal would not ask. Below, switching language blocking on has revealed the fields for policy, threshold and enforcement. It has also removed the localize bounce messages question, because blocking already implies detection, and the terminal asks that question only when blocking is off:

The Content filtering step, with the language-policy fields revealed

Content filtering, with blocking switched on.

Two things about the console:

  • Answers are drafts. Each step is staged in the database, not written to /etc; nothing takes effect until the interview is applied. A session that times out half way through has not half-configured a mail server.

  • The console asks; it does not act. It runs unprivileged and cannot write pepsi.conf, run certbot or install the schema. A save records a request, which pepsi-setup apply validates and performs; that program is started separately and runs as root. This privileged half is a Debian package of its own. On a host where it is not installed, the setup pages render read-only, showing every value with the controls disabled and the reason beside them, rather than accepting answers into a queue that nothing drains. Why the boundary sits there, and what the applier checks before acting, is described under The applier’s trust model in pepsi-setup(1) (see also A compromised component).

The screenshots are generated from the shipping templates and stylesheet by contrib/screenshot-setup.sh, so they can be brought back into agreement with the code.

6.3. The first question decides the shape

Before any step banner, the wizard asks:

Mail direction this host serves [both]: inbound | outbound | both

Everything else follows from it. inbound means this host receives mail for your domains from the Internet; outbound means it relays what your own users and local programs submit; both, the default, means that it does each, and the two flows are separated at the first stage. The answer decides which SMTP listeners are written, which of the later steps are asked at all, and which of the three pipelines below is built.

6.3.1. Pipeline: both

The entry stage is a branch on state.local_origin, the flag that pepsi-ingress sets for an authenticated submission. A message that this host received and a message that our own user sent therefore never share a stage. ARC exists to carry an upstream administrative domain’s authentication verdicts across our forwarding hop; sealing our own users’ submissions would publish their SPF/DKIM/DMARC results to the world.

                 pepsi-ingress
 Internet ──▶ :25           :465 / :587 ◀── your users
               │                 │       (and the local sendmail
               └────────┬────────┘        socket, always served)
                        ▼
                      init            pepsi-stage-if on
                        │             state.local_origin
         ┌──────────────┴────────┐
   false │                       │ true  (our own submissions)
         ▼                       ▼
the received branch              list-out            MAILING_LISTS
(second panel below)             │
                                 ▼
                                 wallet              WALLET_SELF_SERVICE
                                 │
                                 ▼
                                 edit-settings       EDIT_SETTINGS
                                 │
                                 ▼
                                 encrypt             CRYPTO
                                 │
                                 ▼
                                 auto-whitelist      LEARN_WHITELIST,
                                                     ANTI_SPAM or SECRETARY
                                 │
                                 ▼
                                 milter-*            imported
                                                     non_smtpd_milters
                                 │
                                 ▼
                                 dkim-sign           (always)
                                 │
                                 ▼
                                 internet            (always)

And the received branch, which is where nearly every feature lives:

(the false branch of the split above)
                │
                ▼
                arc                  pepsi-stage-arc
                │
                ▼
                decrypt              CRYPTO
                │
                ▼
                dmarc-reports        (always)
                │
                ▼
                detect-language      LANGUAGE_BLOCKING
                                     or I18N_BOUNCES
                │
                ▼
                block-language       LANGUAGE_BLOCKING
                │
                ▼
                milter-*             MILTER_* = after-decrypt
                                     (expert; see below)
                │
                ▼
                check-whitelist      ANTI_SPAM or SECRETARY
                │
                ▼
                secretary            SECRETARY
                │
                ▼
                anti-spam            ANTI_SPAM
                │
                ▼
                autocrypt-learn      AUTOCRYPT_LEARN
                │
                ▼
                list ──▶ list-post   MAILING_LISTS
                │        list-command
                │        list-bounce
                ▼
                aliases              ALIASES_ENABLED
                │
                ▼
                vacation             VACATION
                │
                ▼
                route ──▶ exchange   EXCHANGE  (our own domains)
                │
                ▼
                dot-forward          DOT_FORWARD
                │
                ▼
                defang               (with local delivery; DEFANG = off)
                │
                ▼
                reencrypt            REENCRYPT (before local delivery)
                │
                ▼
                local                LOCAL_METHODS (maildir)
                │
                ▼
                local-lmtp           LOCAL_METHODS (lmtp; the two
                                     methods run in the order chosen)
                │
                ▼
                srs                  (always)
                │
                ▼
                dkim-sign-relay      SIGN_RELAYED
                │
                ▼
                smarthost            SMARTHOST_HOST
                or internet          (otherwise)

Reading the figures: a stage with (always) is unconditional for this direction, and every other stage is present exactly when the answer beside it says so. The stages are strung together in the order shown, each one’s NEXT_STAGE pointing at the next one that survived. Switching a feature off therefore does not leave a gap; it shortens the chain. list-out is the same list router as list, placed first on the submission branch so that a local user posting to a list hosted here reaches the list instead of being relayed to its own MX.

Five constraints fix that order:

  • decrypt is first on the received branch and encrypt is the last of the submitted branch’s own stages to rewrite the message before signing. Everything downstream of decrypt therefore sees cleartext (language detection, the whitelist, the paywall), and DKIM signs the bytes that actually go on the wire.

  • dmarc-reports (pepsi-stage-dmarc-report) comes right after decrypt and before every gate. It reads the DMARC aggregate reports that other receivers mail to dmarc-reports@<domain> (the rua= of the DMARC record that pepsi-setup run suggests), and a receiver’s report robot passes no whitelist, challenge or paywall. It is not a question: every other message passes it on its metadata alone, and the reports are what lets pepsi-setup check say whether the suggested p=reject refuses a legitimate sender.

  • defang (pepsi-stage-defang) comes after every stage that verifies or reads the content and after dot-forward, so a forwarded copy keeps the bytes that its signatures cover, and before reencrypt, which seals what it is given. It is wired with DEFANG = off wherever mail is delivered locally and offered in EDITABLE_STAGES: each user turns it on for their own mail, and where it is off it passes a message on its metadata alone.

  • auto-whitelist comes after encrypt. It records a recipient to whom the message was really encrypted with signature_required, and it is encrypt that reports this (state.encrypted); placed earlier, the stage would never write a row with that flag. It only inserts whitelist rows, so dkim-sign still signs the content that encrypt produced. A recipient whom encrypt sends to the secure-link portal, or bounces, leaves by that other route and is not recorded.

  • srs and the relay destination after it are unconditional on the received branch. Recipients that local delivery did not consume are not errors: an alias that expands to an address elsewhere, a ~/.forward to another provider, or (with no local delivery configured at all) the entire pure-relay path. They leave as a forward, which is why the envelope sender is SRS-rewritten first.

6.3.2. Pipeline: inbound

With no submission path there is nothing to branch on, so the if stage disappears and ARC becomes the entry stage itself. The received branch is otherwise identical to the one above, minus the questions that were never asked: no encrypt, no auto-whitelist, no wallet or edit-settings.

Internet ──▶ pepsi-ingress :25
                │
                ▼
                init                 pepsi-stage-arc (the entry stage)
                │
                ▼
                decrypt              CRYPTO
                │
                ▼
                dmarc-reports        (always)
                │
                ▼
                detect-language      LANGUAGE_BLOCKING
                                     or I18N_BOUNCES
                │
                ▼
                block-language       LANGUAGE_BLOCKING
                │
                ▼
                milter-*             MILTER_* = after-decrypt
                                     (expert; see below)
                │
                ▼
                check-whitelist      ANTI_SPAM or SECRETARY
                │
                ▼
                secretary            SECRETARY
                │
                ▼
                anti-spam            ANTI_SPAM
                │
                ▼
                autocrypt-learn      AUTOCRYPT_LEARN
                │
                ▼
                list ──▶ list-post   MAILING_LISTS
                │        list-command
                │        list-bounce
                ▼
                aliases              ALIASES_ENABLED
                │
                ▼
                vacation             VACATION
                │
                ▼
                route ──▶ exchange   EXCHANGE  (our own domains)
                │
                ▼
                dot-forward          DOT_FORWARD
                │
                ▼
                defang               (with local delivery; DEFANG = off)
                │
                ▼
                reencrypt            REENCRYPT (before local delivery)
                │
                ▼
                local                LOCAL_METHODS (maildir)
                │
                ▼
                local-lmtp           LOCAL_METHODS (lmtp; the two
                                     methods run in the order chosen)
                │
                ▼
                srs                  (always)
                │
                ▼
                dkim-sign-relay      SIGN_RELAYED
                │
                ▼
                smarthost            SMARTHOST_HOST
                or internet          (otherwise)

dkim-sign and internet are still written even though no submission reaches them: they are the tail that every bounce goes down (see The shared tail and the bounces), and internet is also the relay destination when no smarthost was configured.

6.3.3. Pipeline: outbound

Only the submission branch is built. The if stage is still emitted, because pepsi-ingress still sets state.local_origin and a message without it must go somewhere. On a submission-only host such a message cannot normally occur, so that branch falls straight through to the signing tail rather than into an inbound chain that does not exist.

your users ──▶ pepsi-ingress :465 / :587
               (and the local sendmail socket, always served)
                 │
                 ▼
               init                  pepsi-stage-if on
                 │                   state.local_origin
        ┌────────┴────────┐
  false │                 │ true
        │                 ▼
        │                 wallet        WALLET_SELF_SERVICE
        │                 │
        │                 ▼
        │                 encrypt       CRYPTO
        │                 │
        └────────┬────────┘
                 ▼
               dkim-sign               (always)
                 │
                 ▼
               internet                (always)

Note what is not here. auto-whitelist is absent even though it is an outbound stage: it is offered only as the write side of a correspondent whitelist whose read side (check-whitelist) lives on the inbound path, and the question that would enable it is asked inside the inbound-only anti-spam step. edit-settings is absent too, and EDIT_SETTINGS is not asked: every stage that an account owner may edit is an inbound one, so on this host its allowlist would be empty (see EDIT_SETTINGS below). There are no milters at all, because the milter scan, the carry-over of imported milters and the greylisting question all belong to the inbound-only local-delivery step. An outbound-only host also has no srs: SRS rewrites the sender of mail we forward, and this host forwards nothing.

6.3.4. The shared tail and the bounces

dkim-sign ──▶ internet is written in every direction, because it is what every generated bounce goes down. The bounce stages themselves are emitted per feature that can produce one:

bounce             (always)           ─┐
bounce-language    LANGUAGE_BLOCKING   ├──▶ dkim-sign ──▶ internet
bounce-payment     ANTI_SPAM          ─┘

discard-rejected   any milter stage     (drops it; never bounces)
quarantine         any session milter   (holds it; see below)

With the crypto stages configured, the stages that compose notices of their own inject them at notice rather than straight at dkim-sign. These stages are encrypt, autocrypt-learn, secretary, anti-spam (BLOCK_RESPONSE_STAGE), vacation, wallet and edit-settings:

[stage-notice]
PROGRAM = pepsi-stage-encrypt
NEXT_STAGE = dkim-sign
# NOTICE_SIGNER = notices@example.org

This is an encrypt instance that passes every notice through until NOTICE_SIGNER is uncommented; from then on, it signs each notice with that identity of the deployment (The notice signer, Forged notices). The comments above the section give the pepsi-keys identity generate line that creates the identity, and remind the operator to point [pepsi-admin] ENROL_STAGE and [pepsi-secure-link] NOTIFY_STAGE there too, which the wizard does not write. Without the crypto stages the notices go to dkim-sign. The mailing-list stages and TLS reports always do: list notices and reports are never signed.

Which stage routes to which is fixed by the same rendering pass: block-language bounces to bounce-language and anti-spam to bounce-payment; the Maildir stage, dot-forward and every relay stage bounce to the plain bounce. The last local method additionally points UNKNOWN_MAILBOX_STAGE there. A recipient on one of our domains with no mailbox must be refused, not relayed, or the lookup would find our own MX and send the message back to ourselves. With two local methods, the first points UNKNOWN_MAILBOX_STAGE at the second, because only the last one can say that no mailbox exists. Both local methods point QUOTA_LIMIT_STAGE at bounce as well, so that a site that sets a quota later does not also have to discover that edge. The LMTP stage never builds a DSN itself, it routes what the MDA refused, so its SIEVE_REJECT_STAGE points at bounce too, and its BOUNCE_STAGE catches a local recipient that no other option covers.

discard-rejected is the exception. It exists for a milter that runs as a pipeline stage: that verdict arrives after Pepsi has accepted the message, so “reject” cannot mean a 5xx in the SMTP session, and bouncing instead would send backscatter to whatever address a forged sender named. Mail rejected by a detected filter that you placed after decryption is therefore dropped, with the verdict still recorded in state.milter and in the log. Pointing the filter’s REJECT_STAGE at bounce is a one-word edit if you want senders told. A filter carried over from an MTA’s list for locally submitted mail keeps REJECT_STAGE = bounce, because its sender is one of your own users. A milter consulted during the SMTP session needs no sink: its refusal is the reply that the sending server receives.

6.3.5. Milters in the SMTP session

Every filter that the host scan found and you accepted, and every filter that an imported Postfix smtpd_milters or sendmail INPUT_MAIL_FILTER list named, is consulted by pepsi-ingress during the SMTP session, after Pepsi’s own checks (see pepsi-ingress, “Milters”). No pipeline stage is written for it. Instead the wizard writes one section per filter and lists them in [pepsi-ingress] MILTERS, which every listener that is not a submission listener runs:

[pepsi-ingress]
MILTERS = greylist milter-greylist clamav spamassassin

[pepsi-ingress-milter-greylist]
SOCKET = unix:/run/pepsi-greylist/milter.sock
ALLOW_ACTIONS = none
ON_FAILURE = accept

[pepsi-ingress-milter-clamav]
SOCKET = unix:/run/clamav/clamav-milter.ctl
PROTOCOL_VERSION = 6
ALLOW_ACTIONS = addhdrs chghdrs

[stage-quarantine]
PROGRAM = pepsi-stage-quarantine
RELEASE_STAGE = init

The label of a section is the filter’s name without its milter- prefix (clamav), except for milter-greylist, which keeps it so that it cannot take the place of Pepsi’s own greylister. The list starts with Pepsi’s greylister when GREYLIST is yes, then follows what each filter does: policy, virus, spam, the general-purpose frameworks, and last the imported filters of unknown purpose, in the order the old MTA ran them.

ALLOW_ACTIONS is exactly what the filter asked for when setup negotiated with it. A filter that did not answer gets no ALLOW_ACTIONS line and so the default of pepsi-ingress: header and body edits, and quarantine. An imported filter also keeps what its old MTA said about it: ON_FAILURE, the timeouts, the protocol version, MILTER_NAME and the MACROS_* lists.

[stage-quarantine] is written whenever any milter is consulted in the session. A filter that asks for a message to be quarantined has it stored there, held until you release or delete it with pepsi-queue, and pepsi-ingress offers a filter the quarantine action only when such a stage exists. The message was stored without going through any stage, so a released message starts the pipeline at its first stage (RELEASE_STAGE = init), as if it had just arrived.

Placing a filter after decryption instead is the expert’s answer after-decrypt to its MILTER_* question (see below). It suits a filter that has to see plaintext, such as a spam scorer on a host that decrypts mail for its users. Such a filter becomes a milter-* stage of pepsi-stage-milter after block-language in the received branch, with REJECT_STAGE = discard-rejected. A filter that an import supplied can be moved there only by editing the configuration: remove it from MILTERS and write the stage by hand.

6.4. The questions

Below, every question the terminal interview can ask, in the order it asks them, with the [pepsi-wizard] key under which its answer is remembered. A step is shown only when the direction (and, for one step, the presence of a local Dovecot) makes it applicable; the Step X/Y banner counts only steps that will really be asked.

6.4.1. Step: Server identity

Asked in every direction.

HOSTNAME — Mail server hostname (MX / EHLO name)

The identity of the host, as distinct from the domains it serves: the ARC sealing domain, every relay and bounce SERVER_NAME, and the subject of the fallback TLS certificate. The default comes from reverse DNS, not from /etc/hostname, because receivers compare the EHLO name against the PTR of the connecting address and reject when they disagree. If the offered default contradicts the PTR, the wizard names both and says why before asking.

DOMAINS — Domain(s) we accept mail for (space separated)

Becomes [pepsi-ingress] ACCEPTED_DOMAINS, and through it the default LOCAL_DOMAINS of the local-delivery stages, the set of mta-sts.* policy hosts, and the domains routed to Exchange. The first one is the primary domain: the TLS-report addresses, the control addresses of the self-service stages and the SIGNING_DOMAIN of the forward-signing stage are all derived from it.

POSTMASTER — Postmaster address

Named by the bounce stages and the direct-to-MX relay.

PUBLIC_IPS — Public sending IP address(es) for SPF

Auto-detected and offered for confirmation, from the hostname’s A/AAAA records unioned with this host’s globally-routable interface addresses (and, on a NAT host with no public IPv4, the WAN address that the local UPnP gateway reports). Only public addresses are ever pre-filled: these end up verbatim in the SPF record, so a private one there makes your own outbound mail fail SPF everywhere. A previous run’s answer is re-checked rather than trusted, since a host may have moved since it was written.

DB_CONFIG — PostgreSQL connection string

libpq form; the default postgres:///pepsi uses peer authentication over the local socket, which is what the packaged service accounts expect. A string containing a password is refused at the prompt, since it would land in the world-readable [pepsi-postgres] CONFIG. For a remote database, give every role its own client certificate or password file through the {role} placeholder, e.g. postgres://db.example.org/pepsi?sslmode=verify-full&passfile=/etc/pepsi/postgres/{role}.pgpass (see CONFIG in pepsi.conf(5)).

6.4.2. Step: Existing mail system

Asked on the inbound path only, and asked before local delivery because the answer decides whether there is a local-delivery question at all.

EXCHANGE — Is there an existing Exchange / Microsoft 365 mail system behind this host

Default no. Answering yes makes this host a transparent gateway in front of Exchange: it becomes the MX, Exchange keeps the mailboxes. It inserts the route stage and a dedicated exchange relay into the received branch (see Pipeline: both), and it suppresses the local-delivery questions entirely. Offering to write mailboxes for domains that Exchange owns would produce a configuration in which a recipient is delivered twice or not at all. Recipients that Exchange does not own (an alias that expands to an address elsewhere, a forward) still leave through the relay tail. See Microsoft Exchange as a gateway.

EXCHANGE_HOST — Exchange host (tenant endpoint, or the on-premises server)

The tenant-specific endpoint, not your domain’s public MX. That MX is this host, and pointing Exchange back at it makes every message loop.

EXCHANGE_PORT — Exchange SMTP port

Default 25.

EXCHANGE_ADDRESS_FAMILY — IP address family to reach Exchange over

any (default), ipv4 or ipv6. Exchange Online refuses mail from a sending IPv6 address with no PTR record, so pinning this one next hop to IPv4 is a common and legitimate answer; other destinations are unaffected.

EXCHANGE_TENANT_ID — Microsoft 365 tenant id (empty: Exchange Online sends directly)

Asked only when the Exchange host is an Exchange Online endpoint (…mail.protection.outlook.com). Exchange Online’s outbound connector cannot log in to Pepsi, and every Microsoft 365 customer sends from the same addresses, so Pepsi relays its outbound mail only when a message proves your tenant (Exchange Online: the tenant proof). With an id, the wizard writes a [pepsi-ingress-exchange-online-tenant] section for all served domains; then switch DKIM signing on for those domains in Microsoft 365. Empty (the default) writes no section, and Exchange Online must send directly.

6.4.3. Step: Local delivery

Inbound path only, and the Maildir/LMTP questions are skipped when Exchange was answered yes.

Maildir — Deliver mail for local system accounts into their Maildir

Adds local to the received branch. Requires the SGID stage and setuid helper that make install provisions (group pepsi-maildir).

DOT_FORWARD — Honour per-user ~/.forward files for Maildir accounts

Default no; offered only alongside Maildir, since it is the system accounts’ own home directories that are read. Adds dot-forward immediately before local delivery, so a recipient with a ~/.forward is diverted before the mailbox write. The generated section forwards to addresses only; ALLOW_PIPE and ALLOW_FILE are left off, as each would run a command or write a file as the target user.

LMTP — Deliver mail locally via LMTP to an MDA (Dovecot, which runs Sieve)

Adds local-lmtp. Pepsi implements no Sieve itself; this hands the message to an MDA that does. When a local Dovecot is detected, the follow-up question is just its LMTP socket path (LMTP_SOCKET). Otherwise the wizard asks for a remote TCP target: LMTP_HOST, LMTP_PORT, LMTP_TLS, LMTP_AUTH and, where the mechanism needs them, LMTP_USERNAME and LMTP_PASSWORD. Pepsi does not configure Dovecot: if the sockets that it will rely on are absent, a suggested 10-pepsi.conf is printed at the end of the run.

Order — Both local methods are enabled — which is tried first?

Asked only when both were enabled. The methods are chained in the order given, each delivering what it can and forwarding the rest to the next; the last one’s leftovers go to the relay tail. Stored in LOCAL_METHODS.

ALIASES_ENABLED — Enable aliases / mailing lists (expand recipients via a map file)

Default no. Adds aliases after the spam gates and just before routing and delivery, so the gates see the address that the sender wrote to while the expanded set is routed per recipient. The map file is created next to pepsi.conf and re-read automatically when its modification time changes.

MAILING_LISTS — Host mailing lists on this server (a GNU Mailman 3 replacement)

Default no. Adds the list router to the pipeline, together with the four stages behind it: posting (moderation chain, handler pipeline, per-member fan-out), the e-mail command interface, per-member delivery with the one-click unsubscribe, and bounce processing. The router goes on both branches, so that a local user posting to a list hosted here reaches the list rather than being relayed to its own MX and arriving back as foreign mail. It also writes [pepsi-list], whose UNSUBSCRIBE_SECRET and VERP_SECRET are generated once, stored in secrets.d/pepsi-list.secret rather than in pepsi.conf, and kept across a re-run, because rotating them would invalidate every unsubscribe URI already delivered and every VERP envelope sender already in flight.

Switching it on configures the machinery; the lists themselves are created afterwards with pepsi-list. A server hosting none pays one envelope check per message. This is separate from ALIASES_ENABLED, which only rewrites recipients. See Mailing lists.

MILTERS_ENABLED — Carry the milters over

Only asked when an MTA import found some. Default yes. A filter from the old MTA’s list for mail arriving over SMTP is consulted during the SMTP session, as before (see Milters in the SMTP session); setup first negotiates with it to learn which actions to allow. A filter from Postfix’s non_smtpd_milters, which ran on locally submitted mail, becomes a milter-* stage on the submitted branch instead, immediately before dkim-sign: Pepsi’s local submission socket has no listener section that could name a milter. Such a stage runs after the message was accepted, so a refusal becomes a bounce to the local sender.

MILTER_GREYLIST, MILTER_REGEX, MILTER_CLAMAV, MILTER_SPAMASSASSIN, MILTER_RSPAMD, MILTER_MIMEDEFANG, MILTER_AMAVIS

One question per filter daemon that a scan of this host found installed and answering. All default to yes, which consults the filter during the SMTP session (Milters in the SMTP session). With --expert, or when a previous run chose it, the question has a third answer, after-decrypt, which places the filter after decryption as a pipeline stage instead. That answer is not offered for MILTER_GREYLIST: greylisting works only by refusing delivery in the session. Filters whose function Pepsi already performs (opendkim, openarc, opendmarc, SPF policy daemons, SRS rewriters) are recognised and reported as superseded rather than offered. See Installation for how the scan finds the filters.

GREYLIST — Greylist mail from senders this server has not seen before

Default no. Asked on every host that receives mail, after the scan. Greylisting asks a sending server to try again later the first time it delivers mail from a sender to one of your users. Mail servers retry on their own, and the message is then accepted; much spam software does not retry, so its mail never arrives. The cost is a delay on the first message from each new correspondent: at least five minutes, and as long as the sending server waits before it retries, which can be an hour or more. Mail from your own users, from correspondents on their whitelists and from large known mail providers is not delayed. Yes writes [pepsi-ingress-milter-greylist] for Pepsi’s greylisting milter, pepsi-greylist, first in [pepsi-ingress] MILTERS, with no actions allowed and ON_FAILURE = accept, so that mail is accepted without greylisting while the daemon is down. No [pepsi-greylist] section is written: the daemon’s defaults are the policy described here. pepsi-setup run then enables and starts pepsi-greylist.service. If milter-greylist was accepted too, the wizard says that a new correspondent would be delayed twice.

ALIAS_STYLE — Qualify imported alias names

Only when a migration supplied bare alias names such as postmaster or root, which Pepsi’s keys cannot use because they carry a domain: per-domain (one entry per served domain), wildcard (a single @-wildcard) or primary.

VACATION — Answer mail for recipients who are away (out-of-office replies)

Default no. Adds vacation after alias expansion and after the spam gates, so a notice is never sent on behalf of an alias or in reply to mail that the gates would have refused. Switching it on answers nobody: leave dates are ordinary per-address configuration, set later with pepsi-settings, at domain scope with pepsi-config for a shared holiday, or by the users themselves by e-mail. On a host with no local delivery the generated section also sets VACATION_TAG = none, because tagging the subject rewrites a header that both the author’s DKIM signature and our own ARC seal cover. That is harmless when the mail stops here, but visible to the next hop when the mail is relayed on.

Smarthost — Also relay recipients local delivery does not handle to a smarthost

Optional when local delivery or Exchange handles your domains, in which case it only serves what neither did; required, and not asked, when neither does, since a pure relay must have somewhere to send. Saying yes collects SMARTHOST_HOST, SMARTHOST_PORT, SMARTHOST_MODE (starttls / tls / plain), SMARTHOST_AUTH (none / plain / login) and, where authenticated, SMARTHOST_USERNAME and SMARTHOST_PASSWORD. The credentials are checked on the spot against the real relay: a refusal offers the password again, while an unreachable relay says nothing about the password and does not push you into retyping a working one.

6.4.4. Step: Submission authentication

Asked only on the outbound path, and only when a Dovecot is installed on this host.

DOVECOT_SASL — Authenticate submissions against the local Dovecot SASL socket

Default yes. Sets mandatory AUTH against a Dovecot SASL socket private to Pepsi (/run/dovecot/auth-client-pepsi) on the 465 and 587 listeners, so mail accounts and IMAP accounts are the same accounts. Declining leaves the listeners with a commented pointer to the alternatives (Dovecot SASL configured by hand, or TLS client certificates).

6.4.5. Step: Trust loopback

Asked only when the host serves both directions, and it is a narrower question than it looks: the answer becomes MYNETWORKS on the port-25 MX listener, which only an inbound host has, and it is only worth asking of a host that also submits.

TRUST_LOOPBACK — Trust loopback connections on port 25

Default no, and the default is the right answer for nearly everyone. The wizard does not ask whether local programs may submit mail, because they always can: pepsi-ingress unconditionally serves the UNIX socket that /usr/sbin/sendmail uses, and the kernel tells it which account opened it, so a caller can only ever send as itself. This question is only about a weaker, additional mechanism: trusting an address, through a MYNETWORKS entry for 127.0.0.0/8 ::1/128 on the port-25 listener. That mechanism authenticates a network position rather than a user, so any local process, including a compromised web application, can then send as anyone. It is also what lets a message that this host relays to itself re-enter as a fresh submission and loop. Say yes only for software that insists on speaking SMTP to 127.0.0.1 and cannot be pointed at the socket.

6.4.6. Step: Forwarded mail

Inbound path only.

SIGN_RELAYED — DKIM-sign mail this host forwards, as this host’s own domain

Default yes. Mail that this host merely forwards (an alias that expands to an address elsewhere, a ~/.forward to another provider, the whole pure-relay path) leaves down the received branch, which the outbound dkim-sign never touches. Without this option, such mail arrives at the next hop with our SRS envelope but dkim=none from us. Answering yes inserts a second signing stage, dkim-sign-relay, between srs and the destination, with SIGNING_DOMAIN pinned to the primary served domain. Signing is fail-closed and the author’s domain belongs to somebody else, so a signing domain derived from a foreign From: would make every forwarded message fail for want of a key. And since the signing daemon signs only a From: aligned with d=, the stage signs the forwarded mail whose From: is at our own domain, and passes mail of other authors on unsigned, with their own signatures. A forwarded message whose From: is at our own domain and that did not authenticate on arrival is left unsigned, so that the signature never makes a forgery of our domain pass DMARC at the next hop.

SRS_DOMAIN — Dedicated domain to put the forwarded-mail return path under

No default, except the domain that an imported host’s postsrsd already used (see pepsi-setup(1), the import section) or a previous run’s answer. Becomes [pepsi-srs] SRS_DOMAIN. Forwarded mail leaves with its envelope sender rewritten to SRS0=…@SRS_DOMAIN, so that the next hop’s SPF check passes. This makes that address a return path: every bounce for forwarded mail is addressed to it. The domain therefore has to receive mail on this host.

It must also be dedicated: not DMARC-aligned with any served domain, so neither one of them nor a subdomain such as srs.<primary>, nor any name sharing its last two labels with one. The SPF pass a forward earns at the next hop is a pass for this domain. If it were aligned with the served domains, a message forged as one of them and sent from outside to an address here that forwards would leave this host passing DMARC. In practice that means a separately registered name. It needs an MX record pointing at this host and the SPF record that pepsi-setup(1) prints for it; nobody writes mail from it, so a DMARC record with p=reject suits it. The MX record is the one thing that pepsi-setup cannot suggest for you, because where a domain’s mail is routed is your decision, not the program’s. The wizard therefore prints the record to publish, and pepsi-setup(1) warns on every run until it exists.

SRS_ALLOW_ALIGNED — Accept an SRS domain aligned with a served domain

Asked only when the answer to SRS_DOMAIN is aligned; default no, which asks for another domain. Yes writes [pepsi-srs] ALLOW_ALIGNED_DOMAIN = yes, which is how a host that cannot have a second domain keeps working, at the price that forwarded forgeries of the aligned domain pass DMARC at the next hop. pepsi-setup refuses an aligned domain without it.

A re-run never moves an existing SRS_DOMAIN by itself: rewritten senders stay verifiable for MAX_AGE_DAYS (21 days by default), so changing it would strand every bounce still in flight. When [pepsi-wizard] does not record one, the value already in [pepsi-srs] is offered as the default. A previous answer that is aligned with a served domain is offered too, and then has to be replaced or confirmed with SRS_ALLOW_ALIGNED. Why alignment matters is explained in the threat model’s forwarding discussion (A remote sender).

6.4.7. Step: Transport security

Always asked; the first question only on the inbound path.

MTA_STS — Serve an MTA-STS policy over HTTPS

Default yes. Sets [pepsi] MTA_STS_MODE = enforce and emits pepsi-httpd with one mta-sts.<domain> certificate section per accepted domain, provisioned by pepsi-setup like any other. For the policy to be reachable, you must point the DNS of each mta-sts.<domain> name at this host. Which hosts the policy permits is not asked: it is read from the served domains’ live MX records and written as [pepsi] MTA_STS_MX, or left out (the policy then names HOSTNAME) when no MX record exists yet.

TLS_REPORTS — Send and advertise SMTP TLS Reports (TLSRPT, RFC 8460)

Default yes; emits [pepsi-tlsrpt]. Applies to any host that sends, so it is asked in every direction. Add the daily pepsi-tlsrpt report cron entry that the wizard reminds you about.

Declining MTA-STS still writes the pepsi-httpd sections: HTTPS on port 443 (with the host certificate) and the administrative console’s UNIX socket. pepsi.target starts the HTTP server on every host, and without a listener it would fail and restart for ever.

SHARE_TELEMETRY — Share anonymous feature-usage telemetry with the Pepsi project

Default no, and it is opt-in in the strict sense: an operator who presses Enter through the entire interview shares nothing. The question explains what would be sent before asking. Yes makes pepsi-setup run mint a random 256-bit SYSTEM_ID and arm the pepsi-telemetry-client daemon. Under that identifier, the daemon periodically reports which features this deployment has exercised and how often; it sends no addresses, message data, host names or IP addresses. No means no identifier is generated and nothing is sent, and re-running the wizard to answer no notifies a running daemon, which goes dormant at once (discarding what it had not sent) rather than waiting for it to notice. The daemon itself is left running if the operator started it: dormant, it submits nothing, and it is what lets the browser console offer this switch (see pepsi-telemetry-client).

6.4.8. Step: Content filtering

Inbound path only.

LANGUAGE_BLOCKING — Reject mail by detected human language

Default no. Adds detect-language and block-language.

I18N_BOUNCES — Localize bounce messages to the sender’s language

Asked only when blocking is off, since blocking already implies detection. Adds detect-language alone, which annotates state.language and refuses nothing.

DETECT_LANGUAGES — Languages the detector should recognise

Asked when either of the above enabled detection, after printing the full list of supported ISO 639-1 codes. * (the default) means every language that the detector supports; naming fewer costs less worker memory. An unsupported code is rejected at the prompt. Only a detected language can then be allowed or blocked, which is why this comes before the policy.

LANG_POLICY — Language policy (+allow / -block, e.g. ‘+en +fr -‘)*

One combined answer, split into the stage’s WHITELIST and BLACKLIST. A single -* or +* wildcard covers every other detected language, so +en +fr -* allows only English and French. The literal none may be listed to decide what happens to mail for which no language could be detected.

LANG_THRESHOLD — Score threshold (mail must score strictly above this)

Default -0.1.

LANG_ENFORCEMENT — Enforce the language policy strictly or weakly

hard (default) refuses mail that fails the policy, routing it to bounce-language. soft marks exactly the same mail instead, with a [!LANG] subject flag and an X-Pepsi-Detected-Languages header. That is how you tune the lists and the threshold against real traffic without throwing anyone’s mail away in the meantime. The bounce stage is written under soft too, so switching over later is a one-word edit.

6.4.9. Step: Anti-spam paywall

Inbound path only.

SECRETARY — Ask unknown senders to confirm by reply before their mail is delivered (confirm-to-send)

Default no. Asked first in this step. Adds check-whitelist and secretary to the received branch and, when there is also an outbound path, auto-whitelist to the submitted one, all three on the correspondents whitelist. Mail from anybody who is neither whitelisted nor confirmed is held, and its sender is asked to reply once (see pepsi-stage-secretary). The generated [stage-secretary] has BOUNCE_STAGE = bounce, so mail that is not delivered is refused visibly. An unanswered challenge can mean a forged sender, so pepsi-stage-bounce sends the DSN only when the message authenticated the sender’s domain. Its UNCHALLENGEABLE_STAGE comes from the other spam defences of the same run, and the first match wins. It is the paywall when ANTI_SPAM is on: mail that cannot be asked to reply is asked to pay, and secretary then runs ahead of anti-spam. Otherwise it is the secretary’s own NEXT_STAGE when a spam or framework milter was accepted, because that filter already ran ahead of check-whitelist. Otherwise it is left unset, and mail that cannot be challenged takes the timeout path, which is that refusal. Most newsletters and transactional mail cannot be challenged. A comment above the section names what the choice rests on; Spam filters and the secretary describes the alternative placement of the filters. Listing the stage in EDIT_SETTINGS’s allowlist lets users set their own challenge text and PENALTY.

ANTI_SPAM — Enable the GNU Taler anti-spam paywall (pay-to-send)

Default no. Adds two stages to the received branch, check-whitelist and anti-spam, and, when there is also an outbound path, auto-whitelist to the submitted one. The three are one feature: the outbound stage records everyone you write to, the inbound one recognises their replies, and only what neither vouched for meets the payment gate. It also emits the bounce-payment stage and gives pepsi-httpd a /resume webhook token.

MERCHANT_BACKEND_URL — Taler merchant backend URL

Asked first and verified on the spot, because its /config reports the currencies in which the price may be quoted, so the backend has to be known before the price can be validated.

MERCHANT_ACCESS_TOKEN — Merchant access token (‘secret-token:…’) or the instance password

Either is accepted: a ready-made access token is verified against the backend, an instance password is exchanged for a scoped access token.

PAYMENT_AMOUNT — Price per message (space-separated Taler amounts)

Each amount becomes one choice in the generated order, so EUR:1 CHF:1 KUDOS:10 lets the payer pick a currency. Validated against the currencies that the backend advertised.

PAYMENT_DEADLINE — How long to hold a message awaiting payment

Default 48 h. Hours, minutes and seconds only: the duration parser does not accept calendar units.

LEARN_WHITELIST — Learn a correspondent whitelist from your outgoing mail

Asked instead of the above when both the paywall and SECRETARY are declined (either of them enables it anyway), and only when there is also an outbound path. It adds auto-whitelist on its own: the correspondents are recorded, and nothing yet consumes the verdict. That is a reasonable thing to switch on early, since a whitelist is only useful once it has some history in it.

6.4.10. Step: Account self-service

Outbound path only, and EDIT_SETTINGS only on a host serving both directions. Both default to no, and both are stages that pass ordinary mail straight through: they act only on a message that a local account sent to their own control address.

EDIT_SETTINGS — Let account owners edit their own settings by e-mail

Adds edit-settings. A message to pepsi@<domain> from a local account edits that address’s own pepsi.settings overrides, restricted to an allowlist of stages that the wizard derives from the inbound gates that you actually enabled: the whitelist, language-blocking, secretary, paywall and vacation stages. All of them are inbound stages, which is why an outbound-only host is not asked. When none of those is in the pipeline, that allowlist is empty, and answering yes emits no stage at all, only a comment saying why: an EDITABLE_STAGES with nothing in it is a control address that can change nothing. See pepsi-stage-edit-settings.

WALLET_SELF_SERVICE — Let account owners operate their GNU Taler wallet by e-mail

Adds wallet. A message to pepsi-wallet@<domain> with a command in the Subject operates the sender’s own wallet: balance, top-up, peer-to-peer payments. See pepsi-stage-auto-pay. The section carries MAX_TOTAL = KUDOS:0 and MAX_TOTAL_PER_DAY = KUDOS:0: self-service pays no delivery demand, and an operator who later raises MAX_TOTAL finds the daily limit beside it, which the stage requires.

6.4.11. Step: End-to-end cryptography

Always asked. Encryption serves what your users send, and decryption what arrives for them; a deployment that does one without the other is rare enough not to be worth two questions. Which halves are actually emitted still follows the direction.

CRYPTO — Encrypt and decrypt mail end-to-end (OpenPGP / S/MIME)

Default no. On the inbound path it adds decrypt first, so everything downstream sees plaintext; on the outbound path it adds encrypt last before signing, so DKIM covers what actually goes on the wire. Nothing is encrypted until a recipient’s key is known. Keys come from discovery (WKD, DANE, VKS, LDAP), from pepsi-keys, or from the mail that correspondents send you. The key store, the discovery daemon and the key-encryption key are provisioned by the rest of setup either way; this answer only decides whether the stages are in the pipeline. See Key management.

AUTOCRYPT_LEARN — Learn correspondents’ keys from the mail they send us

Default yes, asked only when CRYPTO is on and there is an inbound path. Without a decrypt stage there is no plaintext to read gossip from, and without an encrypt stage nothing would ever use a learnt key. Adds autocrypt-learn after every stage that can form a spam opinion and before anything that answers or delivers, which is exactly what Autocrypt Level 1 requires: a message believed to be spam teaches nothing, and a key learnt after delivery is learnt too late to encrypt the reply with. Learnt keys sit on the lowest rungs of the trust ladder: such a key can never displace one from discovery, and a signature checked against one is never reported as verified. This limits what a forged From: can teach, but it does not prevent one from planting or rotating a correspondent’s key, since learning is not gated on DKIM or DMARC (see TOFU and key continuity miss first-contact and new-identity attacks and Keys and certificates imported or trusted without verification).

REENCRYPT — Re-encrypt decrypted mail to the user’s own mail-client key before filing it

Default yes, asked only when CRYPTO is on and there is an inbound path, and emitted only in front of a local delivery method. Adds reencrypt immediately before the first local delivery stage, and so after every stage that reads the content or may forward a copy. A message that the gateway opened with a user’s MTA key is then filed sealed to the MUA key that the user registered. Users with no MUA key still get plaintext; the section is written with BOUNCE_STAGE = bounce so that ON_NO_CLIENT_KEY = bounce, set site-wide or per user with pepsi-settings, can refuse instead. A user who loses that MUA key loses the mail filed under it (see Key management too hard: end-to-end mail clients error-prone or unused). See pepsi-stage-reencrypt.

PEP – pEp-style automatic encryption: give every sender a key and send it along (ENABLE_PEP)

Default yes, asked only when CRYPTO is on and there is an outbound path. Every sender at a served domain gets an OpenPGP key on their first message, advertised in an Autocrypt: header; mail is encrypted whenever a recipient’s key is known or discoverable, and signed inside the encryption (cleartext mail goes out unsigned). A user who registers their own key keeps it, and nothing is uploaded to a key server unless its owner asks.

The question is asked explicitly, with its cost stated before it: key creation becomes eager. Everybody who sends mail gets a key, whether or not they ever use encryption, and the deployment’s Web Key Directory serves it. Every one of those private keys is in the database, wrapped under the key-encryption key, so a compromise of that key would expose them all (see Mail appliances store secrets world-readable or unprotected). No creates keys only for a user who asks for protection. The answer is written either way, as ENABLE_PEP = yes or ENABLE_PEP = no, into [stage-encrypt] in pepsi.conf, rather than left to the stage’s default; it takes effect there, since no config.d file sets it. The encrypt stage also gets RESPONSE_STAGE = notice for its notices and its replies to e-mail key commands (see the notice signer in The shared tail and the bounces). See “pEp-style automatic keys” in Key management. The wizard writes no PROTECT_HEADERS: the stage’s default (off) leaves the outer header block as the sender wrote it, and a population whose clients render protected headers sets PROTECT_HEADERS = yes by hand.

ATTACH_KEYS_AS_FILES – Also attach the sender’s public key as a file

Default no, asked only when PEP is on. The classic OpenPGP way, for correspondents whose client does not read Autocrypt headers; the file is attached until the correspondent has shown they hold the key (they sent an encrypted, signed reply). Written as ATTACH_KEYS_AS_FILES = yes only when chosen.

6.4.12. Step: Expert options

Shown only when --expert named some. These are real Pepsi options that the interview does not normally ask about, and each of them knows which section it belongs in: MAX_MESSAGE_SIZE, MYNETWORKS (an entry outside loopback must be bound in SENDER_MAP, which the wizard does not write, or the configuration is refused), RECIPIENT_DELIMITER, MAX_LIFETIME, DMARC_ENFORCE, IP_BLOCKLISTS (the IP blocklists that inbound mail is checked against; a list fetched by rsync is used only where rsync is installed), HELO_NAME, TLS_CERT/TLS_KEY, DNS_TIMEOUT, MAX_CONNECTIONS, MAX_OPEN_SOCKETS, DKIM_SELECTOR (the prefix of the signing daemon’s selectors), KEY_DIR (an obsolete directory of DKIM key files, which pepsi-setup run deletes; nothing signs from it), MAILBOX_QUOTA, MAILBOX_OVER_QUOTA and CRYPTO_ALLOW_DOWNGRADE. A value already carried in the defaults (from a previous run, or from an MTA import) is applied whether or not --expert asks about it; the flag only decides which ones get a prompt. Leaving an answer empty restores Pepsi’s own default. See pepsi-setup(1).

6.5. What the wizard does not ask

Some things are absent from the interview on purpose:

  • The local submission socket. pepsi-ingress serves it unconditionally, deriving the path from [pepsi-sendmail] SOCKET, so no listener section is written and there is nothing that can disagree with anything else.

  • SRS. The rewrite is wired automatically wherever mail can be forwarded, with a generated HMAC secret. The only choice is which domain the rewritten return path lives under (SRS_DOMAIN, above); the wiring is not.

  • How the listeners bind. A host running systemd (detected by /run/systemd/system) gets socket-activated listeners (SERVE = systemd, one FD_INDEX per listener); anything else gets direct binds. The ingress numbering is fixed to match the shipped pepsi-ingress.socket, which lists all three ports on every host: FD_INDEX 0 is port 25, 1 is 465 and 2 is 587, whichever direction the host serves. So an outbound-only host writes 1 and 2 for its submission listeners, and an inbound-only one 0 for its MX. With socket activation you must install matching .socket units whose ListenStream= order lines up with the FD_INDEX values. The wizard prints a reminder, and pepsi-ingress warns at start-up about any descriptor that no section claimed (the ports that a one-direction host does not serve).

  • Keys, certificates, the schema and DNS. All of that is pepsi-setup run, which the wizard offers to chain into. TLS certificates are provisioned via certbot; a certificate that cannot be obtained defers rather than aborting the run, so the schema, keys and DNS output still happen.

6.6. Re-running it

The interview records every non-secret answer in a [pepsi-wizard] section at the end of the file it writes, and a later --wizard run imports those as its defaults. To change one thing, you re-run the wizard and press Enter until you reach that question. Secrets are handled separately and are never written there. A generated secret (the SRS key, the /resume token, the mailing lists’ UNSUBSCRIBE_SECRET and VERP_SECRET) is read back and kept, because rotating the SRS key would invalidate every rewritten sender still in flight. A typed secret (a smarthost or LMTP password, the merchant token) is offered back at its own prompt as ***, so pressing Enter keeps it without it ever being echoed or re-typed.

Two non-interactive forms exist for the same interview. --answers FILE supplies answers by key from a JSON file, so that no prompt is shown, and is how a configuration can be reproduced across hosts. An unanswered question takes its default; an unknown key, a malformed answer or a required answer with no default is a hard failure rather than a prompt that nobody is there to see. --import names an MTA to migrate from explicitly, rather than detecting one. Both are documented in pepsi-setup(1).