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¶
Import. On a host with no
pepsi.confyet, 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.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.
Render. The answers are turned into a configuration file — this is where the pipeline is assembled.
Validate. The rendered text is loaded and validated through the very same path that
pepsi-setup runuses. 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.Write. The file is written, and the secrets in it (the SRS HMAC key, the smarthost and LMTP passwords, the merchant and
/resumetokens, the mailing lists’UNSUBSCRIBE_SECRETandVERP_SECRET) are moved out into mode-restrictedsecrets.d/*.secretfragments 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 thatpepsi.confitself can stay world-readable without exposing a secret (see Mail appliances store secrets world-readable or unprotected).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 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:
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, whichpepsi-setup applyvalidates 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:
decryptis first on the received branch andencryptis the last of the submitted branch’s own stages to rewrite the message before signing. Everything downstream ofdecrypttherefore 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 afterdecryptand before every gate. It reads the DMARC aggregate reports that other receivers mail todmarc-reports@<domain>(therua=of the DMARC record thatpepsi-setup runsuggests), 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 letspepsi-setup checksay whether the suggestedp=rejectrefuses a legitimate sender.defang(pepsi-stage-defang) comes after every stage that verifies or reads the content and afterdot-forward, so a forwarded copy keeps the bytes that its signatures cover, and beforereencrypt, which seals what it is given. It is wired withDEFANG = offwherever mail is delivered locally and offered inEDITABLE_STAGES: each user turns it on for their own mail, and where it is off it passes a message on its metadata alone.auto-whitelistcomes afterencrypt. It records a recipient to whom the message was really encrypted withsignature_required, and it isencryptthat reports this (state.encrypted); placed earlier, the stage would never write a row with that flag. It only inserts whitelist rows, sodkim-signstill signs the content thatencryptproduced. A recipient whomencryptsends to the secure-link portal, or bounces, leaves by that other route and is not recorded.srsand 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~/.forwardto 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.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 theEHLOname against thePTRof the connecting address and reject when they disagree. If the offered default contradicts thePTR, 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 defaultLOCAL_DOMAINSof the local-delivery stages, the set ofmta-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 theSIGNING_DOMAINof the forward-signing stage are all derived from it.POSTMASTER— Postmaster addressNamed by the bounce stages and the direct-to-MX relay.
PUBLIC_IPS— Public sending IP address(es) for SPFAuto-detected and offered for confirmation, from the hostname’s
A/AAAArecords 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 stringlibpq form; the default
postgres:///pepsiuses 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 hostDefault no. Answering yes makes this host a transparent gateway in front of Exchange: it becomes the MX, Exchange keeps the mailboxes. It inserts the
routestage and a dedicatedexchangerelay 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 portDefault
25.EXCHANGE_ADDRESS_FAMILY— IP address family to reach Exchange overany(default),ipv4oripv6. Exchange Online refuses mail from a sending IPv6 address with noPTRrecord, 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
localto the received branch. Requires the SGID stage and setuid helper thatmake installprovisions (grouppepsi-maildir).DOT_FORWARD— Honour per-user ~/.forward files for Maildir accountsDefault no; offered only alongside Maildir, since it is the system accounts’ own home directories that are read. Adds
dot-forwardimmediately before local delivery, so a recipient with a~/.forwardis diverted before the mailbox write. The generated section forwards to addresses only;ALLOW_PIPEandALLOW_FILEare 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_AUTHand, where the mechanism needs them,LMTP_USERNAMEandLMTP_PASSWORD. Pepsi does not configure Dovecot: if the sockets that it will rely on are absent, a suggested10-pepsi.confis 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
aliasesafter 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 topepsi.confand 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], whoseUNSUBSCRIBE_SECRETandVERP_SECRETare generated once, stored insecrets.d/pepsi-list.secretrather than inpepsi.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 fromALIASES_ENABLED, which only rewrites recipients. See Mailing lists.MILTERS_ENABLED— Carry the milters overOnly 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 amilter-*stage on the submitted branch instead, immediately beforedkim-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_AMAVISOne 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 forMILTER_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 beforeDefault 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 andON_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 runthen enables and startspepsi-greylist.service. Ifmilter-greylistwas accepted too, the wizard says that a new correspondent would be delayed twice.ALIAS_STYLE— Qualify imported alias namesOnly when a migration supplied bare alias names such as
postmasterorroot, which Pepsi’s keys cannot use because they carry a domain:per-domain(one entry per served domain),wildcard(a single@-wildcard) orprimary.VACATION— Answer mail for recipients who are away (out-of-office replies)Default no. Adds
vacationafter 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 withpepsi-settings, at domain scope withpepsi-configfor a shared holiday, or by the users themselves by e-mail. On a host with no local delivery the generated section also setsVACATION_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_USERNAMEandSMARTHOST_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 socketDefault yes. Sets mandatory
AUTHagainst 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 25Default 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-ingressunconditionally serves the UNIX socket that/usr/sbin/sendmailuses, 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 aMYNETWORKSentry for127.0.0.0/8 ::1/128on 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 domainDefault yes. Mail that this host merely forwards (an alias that expands to an address elsewhere, a
~/.forwardto another provider, the whole pure-relay path) leaves down the received branch, which the outbounddkim-signnever touches. Without this option, such mail arrives at the next hop with our SRS envelope butdkim=nonefrom us. Answering yes inserts a second signing stage,dkim-sign-relay, betweensrsand the destination, withSIGNING_DOMAINpinned 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 foreignFrom:would make every forwarded message fail for want of a key. And since the signing daemon signs only aFrom:aligned withd=, the stage signs the forwarded mail whoseFrom:is at our own domain, and passes mail of other authors on unsigned, with their own signatures. A forwarded message whoseFrom: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 underNo default, except the domain that an imported host’s
postsrsdalready 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 toSRS0=…@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 anMXrecord pointing at this host and the SPF record that pepsi-setup(1) prints for it; nobody writes mail from it, so a DMARC record withp=rejectsuits it. TheMXrecord 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 domainAsked only when the answer to
SRS_DOMAINis 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-setuprefuses an aligned domain without it.A re-run never moves an existing
SRS_DOMAINby itself: rewritten senders stay verifiable forMAX_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 withSRS_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 HTTPSDefault yes. Sets
[pepsi] MTA_STS_MODE = enforceand emitspepsi-httpdwith onemta-sts.<domain>certificate section per accepted domain, provisioned bypepsi-setuplike any other. For the policy to be reachable, you must point the DNS of eachmta-sts.<domain>name at this host. Which hosts the policy permits is not asked: it is read from the served domains’ liveMXrecords and written as[pepsi] MTA_STS_MX, or left out (the policy then namesHOSTNAME) when noMXrecord 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 dailypepsi-tlsrpt reportcron entry that the wizard reminds you about.Declining MTA-STS still writes the
pepsi-httpdsections: HTTPS on port 443 (with the host certificate) and the administrative console’s UNIX socket.pepsi.targetstarts 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 projectDefault 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 runmint a random 256-bitSYSTEM_IDand arm thepepsi-telemetry-clientdaemon. 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 languageDefault no. Adds
detect-languageandblock-language.I18N_BOUNCES— Localize bounce messages to the sender’s languageAsked only when blocking is off, since blocking already implies detection. Adds
detect-languagealone, which annotatesstate.languageand refuses nothing.DETECT_LANGUAGES— Languages the detector should recogniseAsked 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
WHITELISTandBLACKLIST. A single-*or+*wildcard covers every other detected language, so+en +fr -*allows only English and French. The literalnonemay 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 weaklyhard(default) refuses mail that fails the policy, routing it tobounce-language.softmarks exactly the same mail instead, with a[!LANG]subject flag and anX-Pepsi-Detected-Languagesheader. 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 undersofttoo, 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-whitelistandsecretaryto the received branch and, when there is also an outbound path,auto-whitelistto the submitted one, all three on thecorrespondentswhitelist. 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]hasBOUNCE_STAGE = bounce, so mail that is not delivered is refused visibly. An unanswered challenge can mean a forged sender, sopepsi-stage-bouncesends the DSN only when the message authenticated the sender’s domain. ItsUNCHALLENGEABLE_STAGEcomes from the other spam defences of the same run, and the first match wins. It is the paywall whenANTI_SPAMis on: mail that cannot be asked to reply is asked to pay, andsecretarythen runs ahead ofanti-spam. Otherwise it is the secretary’s ownNEXT_STAGEwhen a spam or framework milter was accepted, because that filter already ran ahead ofcheck-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 inEDIT_SETTINGS’s allowlist lets users set their own challenge text andPENALTY.ANTI_SPAM— Enable the GNU Taler anti-spam paywall (pay-to-send)Default no. Adds two stages to the received branch,
check-whitelistandanti-spam, and, when there is also an outbound path,auto-whitelistto 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 thebounce-paymentstage and givespepsi-httpda/resumewebhook token.MERCHANT_BACKEND_URL— Taler merchant backend URLAsked first and verified on the spot, because its
/configreports 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 passwordEither 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:10lets the payer pick a currency. Validated against the currencies that the backend advertised.PAYMENT_DEADLINE— How long to hold a message awaiting paymentDefault
48 h. Hours, minutes and seconds only: the duration parser does not accept calendar units.LEARN_WHITELIST— Learn a correspondent whitelist from your outgoing mailAsked instead of the above when both the paywall and
SECRETARYare declined (either of them enables it anyway), and only when there is also an outbound path. It addsauto-whiteliston 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-mailAdds
edit-settings. A message topepsi@<domain>from a local account edits that address’s ownpepsi.settingsoverrides, 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: anEDITABLE_STAGESwith 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-mailAdds
wallet. A message topepsi-wallet@<domain>with a command in theSubjectoperates the sender’s own wallet: balance, top-up, peer-to-peer payments. See pepsi-stage-auto-pay. The section carriesMAX_TOTAL = KUDOS:0andMAX_TOTAL_PER_DAY = KUDOS:0: self-service pays no delivery demand, and an operator who later raisesMAX_TOTALfinds 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
decryptfirst, so everything downstream sees plaintext; on the outbound path it addsencryptlast 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), frompepsi-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 usDefault yes, asked only when
CRYPTOis 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. Addsautocrypt-learnafter 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 forgedFrom: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 itDefault yes, asked only when
CRYPTOis on and there is an inbound path, and emitted only in front of a local delivery method. Addsreencryptimmediately 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 withBOUNCE_STAGE = bounceso thatON_NO_CLIENT_KEY = bounce, set site-wide or per user withpepsi-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
CRYPTOis on and there is an outbound path. Every sender at a served domain gets an OpenPGP key on their first message, advertised in anAutocrypt: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 = yesorENABLE_PEP = no, into[stage-encrypt]inpepsi.conf, rather than left to the stage’s default; it takes effect there, since noconfig.dfile sets it. The encrypt stage also getsRESPONSE_STAGE = noticefor 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 noPROTECT_HEADERS: the stage’s default (off) leaves the outer header block as the sender wrote it, and a population whose clients render protected headers setsPROTECT_HEADERS = yesby hand.ATTACH_KEYS_AS_FILES– Also attach the sender’s public key as a fileDefault no, asked only when
PEPis 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 asATTACH_KEYS_AS_FILES = yesonly 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-ingressserves 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, oneFD_INDEXper listener); anything else gets direct binds. The ingress numbering is fixed to match the shippedpepsi-ingress.socket, which lists all three ports on every host:FD_INDEX0 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.socketunits whoseListenStream=order lines up with theFD_INDEXvalues. The wizard prints a reminder, andpepsi-ingresswarns 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).