95.1.43. pepsi-setup¶
provision the Pepsi database, signing keys and DNS for a deployment
- Manual section:
1
95.1.43.1.1. Name¶
pepsi-setup - install the schema, validate config, have the DKIM keys made and print DNS records.
95.1.43.1.2. Synopsis¶
pepsi-setup [GLOBAL-OPTIONS] [run [-r | –reset]]
pepsi-setup [GLOBAL-OPTIONS] schema [–backup-dir DIR] [–backup-keep N] [–if-installed]
pepsi-setup [GLOBAL-OPTIONS] check [–fail-on-findings]
pepsi-setup [GLOBAL-OPTIONS] validate
pepsi-setup [GLOBAL-OPTIONS] visualize
pepsi-setup –wizard [–force] [–expert SPEC] [–answers FILE] [–import MTA [–import-root DIR] | –no-import] [-c FILE]
pepsi-setup [GLOBAL-OPTIONS] questions
pepsi-setup [GLOBAL-OPTIONS] apply [–once] [–idle SECS]
pepsi-setup [GLOBAL-OPTIONS] apply –clear
pepsi-setup [GLOBAL-OPTIONS] bootstrap [–valid-for SECS] [–admin-url URL]
pepsi-setup [GLOBAL-OPTIONS] import [MTA] [–root DIR] [–out DIR] [–alias-style STYLE]
GLOBAL-OPTIONS include –no-certbot, –no-reverse-proxy, and -y/-n to answer prompts non-interactively (see Global Options).
95.1.43.1.3. Description¶
pepsi-setup is the administrative bootstrap tool for a Pepsi deployment. In a single invocation it:
Validates the configuration. It parses the
[pepsi]and[pepsi-ingress]sections (including listeners) and the[stage-*]pipeline. It checks that a[stage-init]exists, that everyNEXT_STAGE/BOUNCE_STAGEresolves, that each stage’s program configuration (including upstream-MTA routing) parses, that every domain name is well-formed and that eachPUBLIC_IPentry is a valid IP address. It warns when a relay stage’sPUBLIC_IPis a non-public address (loopback, RFC 1918 / unique-local, link-local or CGNAT), and when a relay stage sets noPUBLIC_IPat all (the record then degrades to a barev=spf1 -all). A non-public address can never send mail on the Internet, so listing it, with the trailing-all, makes outbound mail from that address family fail SPF; behind NAT, use the host’s public egress IP, not its LAN address. It warns about everyMYNETWORKSentry of an ingress listener that covers more than one host (wider than/32or/128) and is not loopback: every host in it may relay through this server and send as any address without authenticating, so a network grant extends to every machine that is, or later joins, that network. List single hosts, and let other clients authenticate with SASL or a TLS client certificate. It also refuses the reserved.invalidplaceholder identity shipped in the sample configuration: if any ofHOSTNAME,ACCEPTED_DOMAINS,[pepsi] ARC_DOMAINor a stageSERVER_NAMEstill ends in.invalid(e.g.example.invalid), it stops with an error naming the offending values, because the sample was never edited; it does not provision keys and DNS for a domain that can never receive mail. Set those fields to your real domain, or runpepsi-setup --wizard. It warns about every option set in a known section that nothing reads, suggesting the closest real option name, because a misspelt option silently takes its default. It also warns about options renamed since an earlier release (see “Renamed options” in pepsi.conf(5)). Sections it does not know are left alone. It checks[pepsi-dkim](see pepsi-dkim(1)):RSA_BITSis 2048, 3072 or 4096;ROTATION_LEAD_DAYSis shorter than a non-zeroROTATION_DAYS;RETIRE_AFTER_DAYSis at least 1 and exceeds theSIGNATURE_EXPIRATION_DAYSof every pepsi-stage-dkim-sign(1) and pepsi-stage-arc(1) stage, since a key retired while its signatures are still valid makes mail in transit fail DKIM;NOTIFY_ADDRESSis an address; andDNS_UPDATE = rfc2136comes with aTSIG_KEY_NAME, a base64TSIG_SECRETand aTSIG_ALGORITHMofhmac-sha256,hmac-sha384orhmac-sha512. It warns whenPUBLISH_RETIRED_KEYSis on but no pepsi-httpd listener serves HTTPS to the public (the keys would be written for nobody to fetch), or when it is on withoutROTATION_DAYS(keys then retire only on a manualpepsi-dkim rotate). If anything is wrong, it reports the problem and exits non-zero without installing a schema, generating a key or publishing anything. (Validation is not literally the first thing that runs. The steps below that repair the configuration file necessarily precede it, because validation is run against their result: the reverse-proxy integration, the certbot paths, the proof-of-origin secret, the telemetry identifier and theMAILBOX_FS_QUOTAprobe.) The operator-edited map files (below) are deliberately not part of this step, so an unrelated map typo can never block the run. If the pipeline uses apepsi-stage-detect-languagestage but that binary is not found on$PATH(it ships in its own large package, separate from the rest of Pepsi), the run warns and continues; installpepsi-stage-detect-languagebefore starting the service, or the detect-language stage will fail to spawn. Two further non-fatal warnings flag likely misconfigurations: apepsi-stage-block-languagestage with aBLACKLISTbut an emptyWHITELISTand a non-negativeTHRESHOLD(which bounces all neutral-language mail; see pepsi-stage-block-language(1)), and a non-progressingNEXT_STAGEcycle (a chain ofNEXT_STAGEedges that loops back on itself, so a message would circle untilMAX_LIFETIME; legitimate re-entry throughBOUNCE_STAGE/RESTART_STAGEis not flagged). It also warns when aTARGETSentry admits a uid below/etc/login.defsUID_MINon a stage whose setuid helper refuses such uids, since a recipient matched only by that entry fails in the helper on every message. Those stages are pepsi-stage-relay-to-maildir(1), pepsi-stage-dot-forward(1), and pepsi-stage-auto-pay(1) inWALLET_MODE = local-user. It warns when[pepsi-ingress] ACCEPTED_DOMAINSis set butDMARC_ENFORCEis not: the compiled-in default isno, so such a configuration delivers mail that fails DMARC; an explicitnois left alone. It warns when a smarthost section points at Exchange Online (…mail.protection.outlook.com) and no[pepsi-ingress-exchange-online-*]section names the tenant: mail that Exchange Online’s outbound connector sends through this host to other domains is then refused (see pepsi.conf(5)). It warns about a pepsi-stage-anti-spam(1) stage withoutBOUNCE_TARGET_STAGE, which forwards a null-sender message without a validPepsi-Originproof (a forged bounce) past the payment gate, and, with[pepsi-origin] ENABLED = no, about every anti-spam stage (every bounce then goes to that target) and every pepsi-stage-secretary(1) stage (every bounce then passes it).With a stage running pepsi-stage-srs(1), an
[pepsi-srs] SRS_DOMAINthat is DMARC-aligned with a served domain is an error: anACCEPTED_DOMAINSentry or other sending identity itself, a subdomain or parent of one, or a name sharing its last two labels with one (there is no public-suffix list, so the test errs towards aligned). Forwarded mail leaves with its envelope sender rewritten into that domain, from this host’s addresses, so SPF passes for it at the next hop; an aligned SRS domain would let a message forged as a served domain, received from outside and forwarded, pass DMARC there on SPF alone.[pepsi-srs] ALLOW_ALIGNED_DOMAIN = yesturns the error into a warning for a host that cannot have a dedicated domain. The warning names what closes the route:aspf=sin the served domain’s DMARC record when the SRS domain is a subdomain of it, orp=quarantine/p=rejectthere together with[pepsi-ingress] DMARC_ENFORCE = yes, so that a forgery is refused on arrival. check then reads that DMARC record (or the organisational domain’s, when the served domain has none) and reports it asSRS alignment:[ok]whenaspf=sis published and the two names differ, or the policy enforces andDMARC_ENFORCEis on,[MISMATCH]with the remedy otherwise. It warns about every[pepsi-srs] PREVIOUS_SECRET_FILElast changed more thanMAX_AGE_DAYSago: every address that the retired key signed has expired, so it verifies nothing and can be removed. Only the file’s modification time is consulted, never its content. It also warns when a stage runs pepsi-stage-srs(1) but none runs pepsi-stage-bounce(1): a remote report about a copy that an alias or~/.forwardsent off-site is then dropped by pepsi-ingress(1) and the sender is never told.The end-to-end cryptography settings are validated here too: the
[pepsi]CRYPTO_*options and the[pepsi-crypto]key-store section (see pepsi.conf(5)). Individually valid but jointly wrong combinations are errors:CRYPTO_SMIME_SHARED_KEY = yeswith an elliptic-curveCRYPTO_SMIME_ALGORITHM, the defaultp256included (several S/MIME clients reject one EC key doing both ECDSA and ECDH), aCRYPTO_GENERATE_RSA_BITSother than 2048, 3072, 4096 or 8192 (the sizes generated in constant time) or belowCRYPTO_MIN_RSA_BITS(the deployment would generate keys that it then refuses), an implausibly smallCRYPTO_MIN_RSA_BITS, a non-positiveIDENTITY_VALIDITY_DAYS, and aKEY_WRAP_KEY_IDthat could not name its ownKEY_WRAP_SECRET_<ID>option. A[pepsi-crypto]section that says anything at all but has noKEY_WRAP_SECRETis likewise an error, and the message names the@inline-secret@fragment that the secret should have come from, together with its owner and mode: the@inline-secret@mechanism only warns about a fragment it cannot read, so an unreadable one is otherwise indistinguishable from an unset option. A secret shorter than 16 characters is refused, because it is the single key that opens every stored private key. A deployment that does no end-to-end cryptography configures none of this and is not nagged about it. Three options that are valid but weaken what a message’s protection means are accepted with a warning each:CRYPTO_MIN_RSA_BITSbelow 2048,CRYPTO_ALLOW_WEAK_DIGESTS = yes(SHA-1 signatures, whose collisions let a signature or a CMS digest algorithm be substituted) andCRYPTO_ALLOW_DOWNGRADE = yes(S/MIME 3DES on decryption, and the unauthenticated S/MIME CBC container for every recipient rather than only for those whose capability record needs it).For each pepsi-stage-encrypt(1) stage it also checks the pEp preset (
ENABLE_PEP) and the key self-service. It warns whenENABLE_PEPis on but[pepsi-crypto] AUTO_CREATE_IDENTITY = no(a valid site veto, but then no sender gets a key automatically; sayENABLE_PEP = noto make it explicit) or noKEY_WRAP_SECRETis configured (no sender can be given a key); whenRESPONSE_STAGEis unset (users are not told when a new key is registered for their address, and the e-mail key commands topepsi-keys@<domain>are off); and when[pepsi-ingress] USERNAME_MAPgrants a wildcard, naming those accounts: they may send as any matching address but can never register their own key for one. It refuses aRESPONSE_STAGEnaming no stage, and, whenRESPONSE_STAGEis set, aTEMPLATE_DIRlacking thekey-registered.en.bodyorkeys.en.bodyfallback template.Setup also repairs an orphaned fragment. The secret and the
@inline-secret@directive that pulls it in are two halves of one statement living in two files, and the fragment outlives the configuration that referenced it. A regenerated or hand-writtenpepsi.conftherefore leaves a deployment wheresecrets.d/pepsi-crypto.secretis present and correct, nothing loads it, and every message through pepsi-stage-encrypt(1) fails. Neither half looks wrong on its own, and re-running asrootdoes not help: root can read the fragment, but the directive is what pulls it in. When the fragment exists and the configuration does not reference it, setup adds the directive and says so. This rotates nothing and writes no key material, so it is safe even when the secret itself is unreadable. What it cannot recover is a non-defaultKEY_WRAP_KEY_IDthat went with the lost file, so the warning names the id it asserted; set it by hand if the key was stored under another.Prepares the operator-edited map files. On every run it walks the configured lookup tables: the
[pepsi-ingress] USERNAME_MAPand eachpepsi-stage-aliasesstage’sALIASESmap. A file that does not exist is created from a commented starter template (mode0644) that documents the file’s purpose and shows the syntax, so the operator finds a self-documenting file in the right place. A file that does exist is syntax-checked with the same parser that the owning component uses at run time, so a malformed line (or an address/domain typo) is surfaced with its line number. This step is purely advisory: a bad map, or a template that cannot be written, is logged as a warning and never aborts the run (the run-time parsers are themselves lenient, warning and skipping a bad line). In--wizardmode this runs only afterpepsi.confhas been written, so a map problem never prevents the wizard from writing the configuration.Integrates with an existing front HTTP server. If another web server (nginx or Apache) is already listening on ports 80/443, pepsi-httpd cannot bind 443 and
certbot --standalonecannot bind 80. Rather than fight for the ports, pepsi-setup detects the front server (viass), confirms that it does not already serve any of themta-sts.<domain>host names, and then does two things.First, it keeps
[pepsi-httpd-listener-https]socket-activated but plain-HTTP (SERVE = systemd,MODE = plain), stripping any direct-bindMODE = tls+TLS_CERT/TLS_KEYand the now-unneeded[pepsi-httpd-cert-*]sections. It also drops apepsi-httpd.socketoverride (/etc/systemd/system/pepsi-httpd.socket.d/10-reverse-proxy.conf) that rebindsListenStreamfrom443to a UNIX socket at/run/pepsi/httpd.sock(SocketGroup=the front server’s group:www-dataon Debian,nginx/apache/httpdelsewhere).On a host that systemd does not run, nothing hands pepsi-httpd a socket, so the listener binds the UNIX socket itself instead:
SERVE = unix,UNIXPATH = /run/pepsi/httpd.sock,UNIXPATH_MODE = 660andUNIXPATH_GROUPthe front server’s group, again withMODE = plain. pepsi-setup then restarts pepsi-httpd (its launchd job on macOS; on another init system it tells you to).When the front server is gone, or with
--no-reverse-proxy, pepsi-setup undoes both: it deletes thepepsi-httpd.socketoverride, or on a host without systemd turns the listener back intoSERVE = tcpon port 443. It then setsMODE = tlsagain and adds a[pepsi-httpd-cert-mta-sts-<domain>]section for eachmta-sts.<domain>name that noSNInames, unless[pepsi] MTA_STS_MODE = none. The TLS step that follows fills in their certificate paths, obtains the certificates and restarts pepsi-httpd. A listener on a socket of your own is left alone.Second, it writes a reverse-proxy site (
pepsi-mta-sts) into the front server’ssites-availableand enables it insites-enabled(conf.dfor non-Debian nginx). The site terminates TLS for those host names, sendsStrict-Transport-Security: max-age=31536000on them (pepsi-httpd sends it only on its own TLS listeners; a front server configured by hand must add it too, which check verifies), turns TLS session tickets off and forwards the requests to the socket. Tickets are off (ssl_session_tickets off/SSLSessionTickets off) because a ticket key that the server keeps until it restarts would let whoever obtains it decrypt every recorded session resumed with it, undoing forward secrecy. The site sets no cipher list: the front server is the operator’s, shared with its other sites, so which old clients to drop is that server’s policy. Instead pepsi-setup reads the front server’s effective TLS settings and warns when they still enable TLS 1.2 suites without forward secrecy (static RSA key exchange): anybody who later obtains the server’s private key can decrypt the sessions recorded with those suites. When the settings cannot be read, pepsi-setup says so. In this layout the front server terminates TLS, so the certificates (this step and the SMTP MX certificate of the next step) are obtained through that server’s certbot authenticator plugin (--nginx/--apache) rather than--standalone. This step is a no-op when no front server is present, and is skipped entirely with--no-reverse-proxy(in which case pepsi-httpd binds 443 directly). Once thepepsi-mta-stssite exists, a re-run regenerates it and reloads the front server only when its text changes: anmta-sts.<domain>name for a newly accepted domain joins it (unless the front server already serves that name elsewhere, which is deferred as below), its certificate obtained first, and a site written by an older pepsi-setup gains what the current one sends, such asStrict-Transport-Security. Edits made to the file by hand are therefore overwritten. When the front server’s configuration test refuses the new text, the previous text is put back and the step is deferred. In some cases the integration is deferred rather than aborting the run: when the front server already serves one of themta-sts.<domain>names (a conflict that you must resolve), when it is a server that pepsi-setup cannot yet automate (Caddy, lighttpd, Apache Traffic Server; wire the proxy by hand or pass--no-reverse-proxy), when pepsi-setup is not running as root, or when the MTA-STS certificate itself cannot be obtained (the reverse-proxy site references the live certificate, so it cannot be written until the certificate exists). The end-of-run summary then gives an actionable message, and pepsi-httpd stays in its direct-bind configuration; in each case, re-runpepsi-setup runonce the cause is resolved. The socket directory/run/pepsicomes from the package’ssystemd-tmpfilesentry (no unit may declareRuntimeDirectory=pepsi: systemd would re-own the directory and every socket in it on each start), and pepsi-setup writes/etc/tmpfiles.d/pepsi-reverse-proxy.confgranting the front server’s user access to it beside the socket drop-in; that user must be able to reach the group-shared socket.Provisions TLS certificates. For every listener that terminates TLS and has no
TLS_CERT/TLS_KEYset, it fills the options in with the standard certbot layout (/etc/letsencrypt/live/<lineage>/fullchain.pemandprivkey.pem), writing them into the configuration file in place (comments are preserved). These listeners are the[pepsi-ingress-listener-*]sockets withMODE = tls/starttls, the TLS[pepsi-httpd-listener-*]sockets, and each[pepsi-httpd-cert-*]SNI certificate. Mail and web have separate certificates and keys, each a certbot lineage of its own:the mail lineage
<HOSTNAME>(the[pepsi-ingress] HOSTNAME), used by every ingress listener: the key that theTLSArecord pins;the web lineage
<HOSTNAME>-web, used by the TLS[pepsi-httpd-listener-*]sockets (and by a[pepsi-httpd-cert-*]section whose firstSNIhost isHOSTNAME);one lineage per other
[pepsi-httpd-cert-*]section, named after its firstSNIhost (mta-sts.<domain>in a configuration the wizard wrote).
pepsi-httpd, the more exposed of the two servers, therefore never holds the mail key: a key taken from it matches no published
TLSArecord, so a sender that enforces DANE refuses it for the MX. Listeners of one service share their lineage.A configuration in which the HTTPS listener (or such a certificate section) still names the mail lineage’s paths, as in the layout of a single shared lineage, is split by the next run: pepsi-setup obtains the web lineage and, once its certificate and key are on disk, replaces that section’s
TLS_CERT/TLS_KEYwith the web lineage’s and logs a notice. Until then (--no-certbot, or a deferred certificate) the section keeps the shared certificate and keeps working, and a later run finishes the split. The mail certificate, its key and itsTLSArecord are not touched. A certificate that the operator configured outside the certbot layout is never moved.The HTTPS listener’s (web) certificate covers
HOSTNAMEandopenpgpkey.<domain>for every domain inACCEPTED_DOMAINS, because that is where the Web Key Directory’s advanced method is fetched from (pepsi-httpd(1)). When[pepsi-autoconfig]turns mail autoconfiguration on, it also coversautoconfig.<domain>, which is the first URL that a mail client tries. These names are added to the listener’s own certificate rather than given a[pepsi-httpd-cert-*]section of their own, since that certificate is the fallback served whenever SNI matches nothing; so one certificate covers both the SNI hit and the fallback.The ingress listeners’ (mail) certificate covers every MX host that an MTA-STS policy permits, that is, the
[pepsi] MTA_STS_MXset across all served domains. The reason has no counterpart on the HTTPS side. RFC 8461 §4.1 requires the certificate that an MX presents to match the name that theMXrecord gave the sender, and pepsi-ingress(1) serves exactly one certificate per listener: it records the client’s SNI but never selects on it. A host reachable asmx.example.organdmail.example.nettherefore cannot answer with two certificates; it needs one certificate carrying both names. Wildcardmxentries (*.example.net) are skipped with a warning, so a deployment that publishes one must supply that certificate itself. HTTP-01 cannot satisfy a wildcard, and passing one to certbot would fail the whole request, including the names that would have worked.Then, for each such host, pepsi-setup runs
certbot certonly --standalone(HTTP-01 over TCP/80, registered without an email) when the certificate is not on disk. When it is on disk, pepsi-setup reads the Subject Alternative Names out of it and re-runs certbot (--expand, same--cert-name) if they do not cover every name above. That matters because a certificate’s name set is not fixed at first issuance: adding a served domain, turning on autoconfiguration or naming a new MX host all widen it. A certificate whose names cannot be read is left alone rather than re-issued, since “I could not tell” must not spend a rate-limited issuance. Every name is checked against DNS, not just the certificate’s own--cert-name: certbot validates each-dseparately and fails the whole request if one of them cannot be reached.pepsi-setup decides which certificates it may drive certbot for by comparing the configured
TLS_CERT/TLS_KEYagainst the layout paths that it would itself have written for that host. The test cannot be “isTLS_CERTset?”, because a successful first run sets it, after which every listener would look operator-configured and no certificate could ever be widened again. Paths equal to the layout are pepsi-setup’s to keep current; anything else is a certificate that the operator chose and is never touched, and a half-configured section (one of the two options set) is left to the strict validation, which reports it better. A certificate that is missing and cannot be obtained is deferred rather than fatal: setup continues (installs the schema, generates keys, prints DNS records) and lists every deferred certificate in a summary at the very end, with the concrete next step and a reminder to re-runpepsi-setup runonce the obstacle is cleared. Re-running is idempotent and only completes what is still missing. A certificate is deferred when--no-certbotwas given,certbotis not installed, pepsi-setup is not running as root (so it cannot bind TCP/80), the host’s DNS does not resolve to a configuredPUBLIC_IP(so the challenge would fail), orcertbotitself fails (for example a transient ACME-server incident or a rate limit; a plain re-run then retries). The DNS case distinguishes a name with no A/AAAA record from one that resolves elsewhere (reporting the addresses it found versus the configuredPUBLIC_IPs). Because the certificate file is then absent, the DANE/TLSA record for that host cannot be computed, so the DNS output prints a comment saying the record is still missing and how to provision it. Only a genuinely unusable invocation is fatal: an unwritable configuration file, or an unknown path for it (when no configuration file exists at any default location and no--configwas given), so that the auto-filled paths cannot be persisted. Note that a server whose TLS listener still lacks a certificate will not start until the certificate exists.Gives the servers access to their key material. The TLS servers (pepsi-ingress, pepsi-httpd) run as unprivileged users and cannot read certbot’s root-only
/etc/letsencrypt/{live,archive}tree, so a listener would otherwise fail to start with a bare permission denied. Three mechanisms address this, applied on every run:systemd service credentials — the primary mechanism wherever systemd runs the servers. For each server, pepsi-setup writes
/etc/systemd/system/<unit>.d/10-tls-credentials.confnaming every certificate and key that the server reads as aLoadCredential=entry. systemd then opens those files as root when it starts the unit and passes private copies to the service under$CREDENTIALS_DIRECTORY(a per-unit tmpfs directory readable by that one service), where Pepsi’s TLS loader looks up each configured path before falling back to reading the path itself, so the file permissions stop mattering altogether. The drop-in is regenerated from the configuration on every run and lists only files that exist, because systemd refuses to start a unit whose credential source is missing; re-runpepsi-setup runafter adding, moving or removing a certificate. When the drop-in changes, pepsi-setup reloads systemd andtry-restarts the affected server (only if it is running) so the new material takes effect.POSIX ACLs and a certbot deploy hook — the fallback for a deployment that systemd does not run, and the vehicle that handles renewals. For every certbot-managed certificate that the configuration references, pepsi-setup grants those service users read+traverse access with POSIX ACLs (
setfacl). It also installs a certbot deploy hook at/etc/letsencrypt/renewal-hooks/deploy/pepsi-cert-access.shthat re-applies the grant on every future issuance/renewal and restarts the Pepsi servers. A one-time grant would not survive, because certbot rotatesarchive/<host>/privkeyN.pem; the hook’s default ACLs make freshly-created files inherit access too. The restart is what actually puts a renewed certificate into service: each server reads its material once at start-up, and systemd materialises credentials when the unit starts. This half is best-effort: it needs root,setfacl(theaclpackage), and an ACL-capable filesystem, and a missing prerequisite is deferred with the fix, not fatal. Certificates outside certbot’s tree (operator-setTLS_CERT/TLS_KEY) are not managed and only warned about; grant their read access yourself.Verification — for anything not covered by a credential, pepsi-setup does not assume the grant worked. It forks, becomes the service user and tries to open the file, so a certificate that is still unreadable (an ACL silently ignored by the filesystem, a root-only parent directory, an operator-set path that nobody granted) is reported as a deferred step naming the exact file, user and unit, instead of surfacing later as a server that refuses to start.
launchd on macOS — the launchd jobs start pepsi-ingress and pepsi-httpd as root, and each reads its certificates and keys before it drops to its account, so no file has to be readable by a service user and no ACL is granted. pepsi-setup records which TLS files each server reads (under
/var/lib/pepsi/launchd-tls) and restarts a running server’s job (launchctl kickstart -k) when that list changes. The certbot deploy hook is installed as well; on macOS it only restarts the jobs that launchd has loaded.Ensures Dovecot reachability. When local delivery via LMTP or submission authentication via Dovecot SASL is configured, pepsi-setup probes the configured socket as the service user that will connect to it: the dispatcher’s
pepsifor LMTP,pepsi-ingressfor SASL. This catches the common case of a socket that exists but is unreachable: Dovecot’s shared/run/dovecot/auth-clientis0600 dovecotand cannot be opened bypepsi-ingress. If a socket is missing or unreadable and a local Dovecot is present, pepsi-setup (running interactively as root) offers to install/etc/dovecot/conf.d/10-pepsi.conf, a dedicatedunix_listenerowned by the Pepsi service user (mode = 0600, so the shared socket’s permissions are left untouched). It then validates the merged configuration withdoveconfand reloads Dovecot. When it cannot (not root, no terminal to ask at,doveconfrejecting the result, or no local Dovecot), it prints the drop-in and defers so you can deploy it by hand. Pepsi’s defaultSASL_PATHis this private socket,/run/dovecot/auth-client-pepsi. This check runs on everypepsi-setup run, not only under--wizard.-y/--yes-to-allinstalls the drop-in without prompting;-n/--no-to-allskips the install and just prints it; either makes the run fully non-interactive.Checks for another MTA on the SMTP ports. Pepsi is rarely the first mail server on a host: Debian pulls in Postfix or Exim as the default
mail-transport-agent. If one of them is still listening, pepsi-ingress cannot bind and the failure is silent in a particularly misleading way: under socket activation it ispepsi-ingress.socketthat fails (systemctl status pepsi-ingress.socketreportsResult: resources), mail keeps being delivered by the other server using its alias and virtual maps, and every change topepsi.conftherefore appears to have no effect whatsoever. pepsi-setup reads the kernel’s listener table (/proc/net/tcp) for each port that the[pepsi-ingress-listener-*]sections need, and names the offending process (with its pid) when the holder is neithersystemdnor Pepsi itself. These ports are the configuredPORTfor aSERVE = tcplistener, and the shipped socket unit’sFD_INDEXmapping (0 → 25, 1 → 465, 2 → 587) for aSERVE = systemdone. This is advisory: it is deferred to the end-of-run summary rather than fatal, since an operator mid-migration may deliberately want the old MTA up a while longer. Resolve it by stopping and disabling the other server (systemctl disable --now postfix) and then startingpepsi-ingress.socket.Checks that the resolver validates DNSSEC, and names whom it trusts. In the same phase, pepsi-setup asks the resolver that the component uses (its
DNS_SERVERS,[pepsi] DNS_SERVERS, or/etc/resolv.conf) a question whose answer it knows, and looks for theADbit. It does so only when the configuration asks for DANE: a relay stage whoseDANEis notoff(strictis the default for both relay stages, and for each smarthost[pepsi-stage-relay-to-smarthost-mta-*]section), ordanein[pepsi-keydiscovery] SOURCES. Pepsi trusts a validating resolver rather than validating DNSSEC itself, so a resolver that never setsADmakes DANE and DANE-based key discovery find nothing at all, silently; that finding is deferred, not fatal. It then states whom the installation trusts: when any of those resolvers is neither a loopback address nor reached over DNS over TLS or HTTPS, a notice lists their IP addresses and where each is named, saying that the operator trusts them to validate DNSSEC. TheADbit is a single unauthenticated header bit, so whoever runs such a resolver, and anyone on the path to it, decides what counts as validated (a forged TLSA,OPENPGPKEYorSMIMEArecord included). Nothing is refused at run time: DNS setup is outside Pepsi’s scope, and the recommended setup is a validating recursive resolver of one’s own on the host (unbound, or systemd-resolved withDNSSEC=yes) at127.0.0.1/::1, for which the notice stays silent.checkprints the same notice.Installs the database schema. Every Pepsi component shares one database (the
[pepsi-postgres]section) and the onepepsischema; pepsi-setup is the sole installer. The schema is a single patch series (pepsi-NNNN.sql) with oneprocedures.sql, applied from[pepsi-postgres] SQL_DIR(default${DATADIR}/sql). The operation is idempotent and may be re-run after upgrades. The other components have no schema-initialization command of their own.Provisions the database login roles. Each Pepsi service account gets a same-named PostgreSQL login role, authenticated over the local socket by peer authentication, and the grants it needs on the
pepsischema. The pipeline rolepepsi(andpepsi-crypto) gets the whole schema, less the carve-backs below. As the very last step, the grants of the three services that are not the pipeline are cut back to what an audit of their code says that they use, and setup refuses to finish if PostgreSQL disagrees:pepsi-ingressINSERTintopepsi.workqueueandpepsi.workqueue_body(plusSELECTof the ids thatworkqueue_addreturns and of the two generated size columns,header_octetsandoctets, that the queue admission check sums),SELECTonconfig_override,mailbox_quota,login_assignment(the RFC 7293 test atRCPT), the downloaded IP blocklists (ip_blocklist,ip_blocklist_source) andcrl_cache(TLS client-certificate revocation),SELECTof thelist_nameandmail_hostcolumns ofmailing_list(the recipient check),INSERTon the two append-only logs. It cannot read any message already queued.pepsi-telemetryIts own
pepsi.telemetrytable.pepsi-httpdEverything that the console, the portal, the list site and the archive use, within these limits. On
pepsi.workqueueit gets only the envelope,stateand routing columns, neverheadersor the body, and it cannot repoint a message’sbody_id. Onpepsi.workqueue_bodyit gets onlyINSERT(the web forms send mail) andDELETE(deleting a message drops the body that only it carried; the foreign key refuses to delete a body that another message still references), neverSELECTof the body. It gets nothing at all onsettings,whitelist,vacation_reply,payment_request_reply, the secretary tables,telemetry,origin_nonce,auto_pay_spend,archive_category,archive_tag,list_post_rate,mta_sts_policy,list_confirmation,crl_cache,ca_issuer_cache,smime_capability,otp_key,otp_pending,compromised_key,compromised_key_import,login_assignment,ip_blocklist,ip_blocklist_source,reputation_checkorsigned_sender. It may only read the statistics, quota, DNS, TLS-report and DMARC-report tables and the telemetry daemon’s liveness row (telemetry_client). Conversely, the credential tables (admin_account,admin_session,api_tokenand the end-user console’sown_enrolmentandown_session) belong topepsi-httpdalone, and the audit and mail logs are append-only for every role that processes mail;pepsi-httpdmay delete from them to prune, but no service role may update them.
The default privileges for tables that a later patch creates are revoked from
pepsi-ingressandpepsi-telemetryas well. See the manual’s “Security model” for the reasoning and its “Test Suite” for how the boundary is tested.Three further roles are deliberately narrower still:
pepsi-whitelistGranted
SELECT,INSERTandDELETEonpepsi.whitelistand nothing else, so a program that every local user may execute (pepsi-whitelist(1), installed setuid) cannot reach the message queue, the statistics or the signing keys.pepsi-keydiscThe key-discovery services (pepsi-keydisc(1)), which parse key material fetched from the open internet and are therefore the likeliest process here to be broken into. This is the narrowest role in the deployment:
SELECT/INSERT/UPDATE/DELETEonpepsi.peer_key(filling that cache is its whole job, and the conflict rule has to be able to replace a row),SELECT/INSERT/UPDATEonpepsi.key_request,EXECUTEon thekeydisc_*functions and the twocrypto_*helpers they call,SELECT/INSERT/UPDATE/DELETEonpepsi.crl_cache(the revocation lists it fetches; it is the only role that writes them, whilepepsiandpepsi-cryptomay only read them and no other role sees them), the same onpepsi.ca_issuer_cache(the intermediate certificates it fetches),SELECTon the list of known compromised keys (pepsi.compromised_keyandcompromised_key_import, so it refuses to store a listed key), and, onpepsi.workqueue,SELECTplus a column-levelUPDATE (status, timeout).Those two columns are the interesting part. They are exactly enough to move a message parked on an address from
pausedback topending, which is whatkeydisc_resolveandkeydisc_sweepdo (plainSECURITY INVOKERfunctions, so the reach has to be granted explicitly rather than inherited). With a table-level grant this account could rewrite a message’s recipients or its body; with these two columns it can only wake a message up. It has no access topepsi.crypto_identityat all.pepsi-cryptoThe account that custodies end-to-end private key material. It receives the ordinary pipeline grants across the schema plus the
pepsi.crypto_identity.private_wrappedcolumn, and it is the only role that does. It is also the only role that writes the list of known compromised keys (pepsi.compromised_key,compromised_key_import: whatpepsi-keys blocklist updateandpeer screenrecord);pepsiandpepsi-keydiscmay only read it, and the other roles do not see it. A writer could make Pepsi refuse any correspondent’s key, so the stage workers that parse hostile mail may not.
That last column is what the exercise is for. Immediately after the blanket grants, pepsi-setup revokes the table-level
SELECT/INSERT/UPDATEonpepsi.crypto_identityfrom every ordinary service role and grantsSELECTback column by column for every column exceptprivate_wrapped. The ordinary service roles arepepsi(the dispatcher and every stage worker),pepsi-ingress,pepsi-httpdandpepsi-telemetry.INSERTis not granted back, andUPDATEonly on the columns that the role’s code writes: theis_primary,publishedandvks_wantedflags (pepsiandpepsi-httpd) and the key-server progress columns (pepsi). So those roles can read and publish an identity’s public half but cannot replace it, its fingerprint, or what address, protocol and purpose it is for, and a compromise of an unrelated stage yields nothing more, even with full database access under that role; pepsi-setup asks PostgreSQL afterwards and refuses to finish if any of them can still write another column. (DELETEhas no column granularity in PostgreSQL and stays whole: a stage that can delete an identity row can deny service, but it still cannot read a key.) The column list is read back frominformation_schemarather than hard-coded, so a column added later is covered automatically and the grant cannot go stale against the schema. Like everything else in this step it is idempotent, and it is deliberately re-applied on every run, because the blanket grants re-add the table-level privilege each time.The wrapped column is only half of the custody model; the key that opens it lives in a
secrets.dfragment (below). Note also that PostgreSQL peer authentication keys off the effective uid, not the gid, so a program that must be this role has to be this account, which is what pepsi-keys(1) arranges around each database call. See pepsi-keys(1).Has the signing keys made. It hands the set of domains that Pepsi is authoritative for to the signing daemon,
pepsi-dkim sync-domains DOMAIN...(see pepsi-dkim(1)). That set is the union of[pepsi-ingress] ACCEPTED_DOMAINS, the domains of each stage’sSERVER_NAME/POSTMASTER, an explicitSIGNING_DOMAIN, the[pepsi-srs] SRS_DOMAINof an SRS stage, a self-service stage’s fixedRESPONSE_FROM, and the[pepsi] ARC_DOMAINif set. pepsi-setup never creates, reads or holds a private key: the daemon makes keys for every domain that has none (an RSA key of[pepsi-dkim] RSA_BITSand an Ed25519 key, asDKIM_ALGORITHMSandARC_ALGORITHMask), retires the keys of a domain that left the set, and prints its status document, from which run takes the DKIM records. A new key signs at once, so DKIM fails at receivers until its record is published. For each domain for which the daemon reports a record still to publish or a rotation waiting for DNS, run logs a warning; an RSA key below 2048 bits in that status (made under another policy) is warned about here and as anote:ofpepsi-setup check, withpepsi-dkim rotateas the remedy. When the daemon cannot be run, the step is deferred, not fatal: the records come from the status file it last wrote, if any, and outbound mail waits in the queue until the daemon has keys for every domain.Once the daemon answers, the DKIM key files that release 0.0.0 kept under
[pepsi] KEY_DIR(<domain>/dkim.rsa.keyand<domain>/dkim.ed25519.key) are deleted, with each per-domain directory left empty, since nothing signs with them; their records (<DKIM_SELECTOR>._domainkeyand<DKIM_SELECTOR>-ed25519._domainkey) are logged and printed as removable.Prints DNS records. It writes to standard output, in BIND zone-file format, the records to publish for each domain: the DKIM public keys that pepsi-dkim(1) reports as needed in DNS (its
next,currentandretiringkeys, at<DKIM_SELECTOR>-YYYYMM._domainkeyfor RSA and<DKIM_SELECTOR>-YYYYMM-ed25519._domainkeyfor Ed25519, an RSA value split into quoted strings of at most 255 bytes), an SPF policy (v=spf1 …) built from thePUBLIC_IPaddresses of every relay stage (unioned; see below), a DMARC policy (_dmarc.<domain>TXT; see below), and an MTA-STS record (_mta-sts.<domain>TXT, unlessMTA_STS_MODE = none) so other senders use validated TLS for our inbound mail. The MTA-STS policy file itself is served over HTTPS by pepsi-httpd(1) athttps://mta-sts.<domain>/.well-known/mta-sts.txt(itsmxset comes from[pepsi] MTA_STS_MX, falling back to the[pepsi-ingress] HOSTNAME), so pepsi-setup prints only the_mta-stsTXT record and a reminder to pointmta-sts.<domain>at the server. The record’sidis derived from that domain’s own policy, so two domains with differentmxsets advertise different ids. Unlike every other record here, the MTA-STS one is printed only for the[pepsi-ingress] ACCEPTED_DOMAINS. DKIM, SPF and DMARC authenticate an identity this host sends as, so they cover the wider set above; MTA-STS is a promise about mail coming in, and only for an accepted domain is that promise kept: pepsi-httpd(1) answers/.well-known/mta-sts.txtfor those hosts alone, and the certificate (and any front-server site) is obtained for those names alone. A domain that is only a sending identity (a relaySERVER_NAME, an explicitSIGNING_DOMAIN, the[pepsi-srs] SRS_DOMAIN) but still has a published_mta-stsTXT record gets a; DELETE:comment instead: it advertises a policy that no component serves, so the request falls through to whatever else answers on that address. When[pepsi-tlsrpt] RUAis set, a TLSRPT record (_smtp._tls.<domain>TXT,v=TLSRPTv1; rua=…) is also printed, so other senders report their TLS results toward our domains to the advertised address (see pepsi-tlsrpt(1)). Long RSA records are split into multiple character-strings automatically. Finally, for each TLS-terminating ingress listener it suggests a DANE/TLSA record (RFC 7672) under the MX hostname (_<port>._tcp.<HOSTNAME>IN TLSA 3 1 1 <hash>), where the association data is the SHA-256 of the served certificate’sSubjectPublicKeyInfo. This is the3 1 1(DANE-EE / SPKI / SHA-256) form, so the record survives certificate renewals that reuse the key pair. For a certbot certificate it obtains, it passes--reuse-key, and on every run it setsreuse_key = Truein the renewal configuration (/etc/letsencrypt/renewal/<name>.conf) of every certbot certificate that the configuration uses, so certbot keeps the key at renewal and the record stays valid. (A record already published for an earlier key must still be replaced by the one printed now.) A deliberate key change is a manual procedure: publish the next key’s record beside the current one, wait out the TTL, then switch keys and remove the old record (the Pepsi manual, chapter “Operations”, gives the steps). The TLSA records already published are compared with the certificate that each listener serves. BesidesHOSTNAME, this covers every MX host of every accepted domain and every accepted domain itself, as long as the name resolves to this host; a name that resolves elsewhere pins the key of another server and is skipped. The comparison works the way a sending MTA does it (RFC 7672: a DANE-EE record against the leaf, a DANE-TA record against any certificate in the chain file, any selector and matching type): when records are published and none matches, a warning is logged and printed into the DANE block, because every sender that enforces DANE refuses to deliver to this host until the record is replaced. A mismatch at a name that is no accepted domain’s MX host is reported as well, with the advice to remove the record: senders that follow RFC 7672 do not look there, but a sender that does refuses to deliver. If such a record is not DNSSEC-validated, no sender uses it and it is not reported. A DANE-TA record whose anchor is not in the chain file (a root the server does not send) cannot be judged and is only noted. Each published TLSA RRset is also asked of the public resolvers ([pepsi] PUBLIC_RESOLVERS, which validate DNSSEC) with the AD bit requested; a record they return without it is reported as published but not DNSSEC-validated, and so is theMXRRset of an accepted domain when TLSA records exist for that domain’s MX host: a sender uses TLSA records only when both validate (RFC 7672), so an unsigned zone or a missingDSat the parent turns the pin into decoration. A resolver that answersSERVFAIL(also how a bogus signature shows) gives no verdict here. Publish these only in a DNSSEC-signed zone; the port-25 record is the one that authenticates inter-MTA delivery (submission ports are flagged as a note, since senders there use the PKIX certificate). No TLSA record is printed or checked for the pepsi-httpd(1) HTTPS listeners: HTTPS clients (browsers, MTA-STS policy fetchers) do not use DANE, and the web certificate has a key of its own, so only the mail key is pinned.When certificates come from Let’s Encrypt through certbot (a
/etc/letsencrypt/live/path whose renewal configuration names no other ACME server), a block marked OPTIONAL, not applied suggests a CAA record (RFC 8659), commented out:; example.org. IN CAA 0 issue "letsencrypt.org", under the accepted domain that each certificate host lies below (else the host itself). When the lineage’s certbot account can be read (running as root), the value carries itsaccounturi(RFC 8657), so only this host’s ACME account can obtain a certificate. The record makes a CA that is misled by a hijacked domain validation refuse to issue, but it restricts every certificate for the domain, not only Pepsi’s, which is why it is never applied. Add anissuerecord for each other CA that the domain uses before publishing it, and dropaccounturiif certbot’s account may change. The block is printed only with other records to publish; it never by itself makes the zone output appear. check reports the CAA records actually published (see check).A block marked Subdomains (SPF, OPTIONAL, not applied) suggests, commented out,
; *.example.org. IN TXT "v=spf1 -all"for every served domain whose wildcard does not already answer with an SPF record. SPF is evaluated for the exact name inMAIL FROM, so without it a forged sender at an invented subdomain gets SPFnonefrom every receiver that does not enforce DMARC. It is never applied, because a wildcard TXT record is also the answer to every other TXT query at a name below the domain that does not exist, and it does not answer for a name that exists; check lists those (see check). Like the CAA block, it never by itself makes the zone output appear.Two further blocks concern end-to-end key publication (see pepsi-keys(1)). First, for every served domain whose
openpgpkey.<domain>host does not already resolve, a reminder to publish an A/AAAA record for it: the Web Key Directory’s advanced method, which every current client tries first, is fetched from that name, so it must point at the pepsi-httpd(1) host. A domain that already publishes keys is flagged in the output and warned about in the log, because for it the advanced lookup is failing today rather than merely unconfigured. (The direct method on the apex works without it, so this is a degradation, not a breakage.) Second, anOPENPGPKEY(RFC 7929) orSMIMEA(RFC 8162) record for each published, active identity in the key store, under the RFC’s hashed owner name (SHA-256 of the local part truncated to 28 octets, hex; this is not the Web Key Directory hash, which is z-base-32 SHA-1 of the lower-cased local part). These are not compared against live DNS: each is a few hundred bytes whose owner name is a per-identity hash, so probing would cost one query per user for records that the operator pastes wholesale. The listing stops after twenty identities; usepepsi-keys dns <address>for a specific one. Publish key records only in a DNSSEC-signed zone: a key in an unsigned zone comes from whoever can answer for the zone. A further comment says what the zone’s denial of existence reveals: underNSECevery published address can be listed and underNSEC3the common local parts recovered, which online signing with minimally covering records (RFC 4470/7129) resists; an address list that must stay private is published by WKD only.A last block concerns mail autoconfiguration. When
[pepsi-autoconfig]is on, every served domain’sautoconfig.<domain>host that does not already resolve is listed with a reminder to point it at the pepsi-httpd(1) host. Unlike the Web Key Directory reminder above this is close to a total failure rather than a degradation: a client trieshttps://autoconfig.<domain>/mail/config-v1.1.xmlfirst, and the/.well-known/form on the apex, which needs no new record, is optional in the draft, so a client that does not try it simply finds nothing.The SPF record is built from
PUBLIC_IP, a per-stage option that pepsi-setup reads from every relay stage and unions. A relay stage is recognised by itsPROGRAM(pepsi-stage-relay-to-internet(1) or pepsi-stage-relay-to-smarthost(1)), never by the section name. A deployment may thus have several relay stages, each with its ownPUBLIC_IP(a pepsi-stage-relay-to-internet stage lists this host’s own sending IPs; a pepsi-stage-relay-to-smarthost stage lists the smarthost’s egress IPs, since mail leaves the internet from there). If a relay stage exists but none setsPUBLIC_IP, the record is a barev=spf1 -all, which forbids all hosts from sending as your domains and makes your own outbound mail fail SPF, and pepsi-setup logs a warning. A receive-only deployment (no relay stage) is not warned. The unioned record is suggested identically for every served domain: correct, but broad. In special setups where different domains send from different hosts, a hand-written per-domain SPF record listing only that domain’s own sending IPs is tighter and still correct; pepsi-setup does not compute that grouping automatically and prints a note to that effect alongside the suggested records.One SPF case gets an explicit note in the zone output, not merely a suggested record: a domain that already publishes two
v=spf1records. RFC 7208 §4.5 makes that a permanent error, so no SPF policy applies (the first record does not win). The repair is to merge them, so the suggested record is printed with a note saying that adding it without removing the others changes nothing. A leftoverv=spf1 include:<old provider>is the commonest thing an MTA migration leaves behind.Every term of the published record is checked against the grammar of RFC 7208 §12, not only the
ip4:/ip6:terms that pepsi-setup asks for: the mechanismsall,include,a,mx,ptr,ip4,ip6andexistswith their qualifiers, address syntax and CIDR lengths (/0–/32,/0–/128), theredirect=andexp=modifiers (each at most once), unknownname=valuemodifiers, domain arguments that end in a top-level label, and macro syntax. One unknown mechanism (ipv4:,ip:,inculde:) or malformed term makes receivers return a permanent error for the whole record, so no SPF policy applies even though our addresses are listed; check reports it as[INVALID], naming the term, and the repair is in place.ptris valid but noted: RFC 7208 §5.5 says it SHOULD NOT be used.The published SPF record of each served domain is also counted against the processing limits of RFC 7208 §4.6.4: following every
include:andredirect=(aredirect=only when the record has noall), it adds up the terms that make a DNS query (include,a,mx,ptr,exists,redirect) and the void lookups among them (ana,mxorincludetarget that does not exist). More than 10 lookups, or more than 2 void ones, and receivers return a permanent error: the domain has no usable SPF policy, although the record looks fine. The count is the worst case (no mechanism matches before the end), which is the case a forged message is judged under. A warning is logged, and check reports it as[INVALID].The DMARC record is the one pepsi-setup cannot derive: which policy a domain wants is an operator decision, not a consequence of the configuration. So this block is about the record being usable, and it behaves differently depending on what is already published:
Nothing published.
v=DMARC1; p=reject; adkim=sis suggested: every message Pepsi sends for a served domain carries a DKIM signature whosed=is exactly theFrom:domain, so the policy that actually stops forgeries costs its own mail nothing, even with strict DKIM alignment, which keeps a subdomain’s signature from speaking for the domain. The comment beside it names the one risk: another service sending as the domain (a newsletter tool, a ticket system) must first sign with aligned DKIM or be listed in SPF, andp=none(monitoring only) is the fallback until it does; a service that signs as a subdomain needsadkim=sdropped. SPF alignment is left relaxed, and the comment recommends addingaspf=sonce every service sending as the domain uses an envelope sender exactly at it (Pepsi does). When a stage runs pepsi-stage-dmarc-report(1) for the domain, the suggestion addsrua=mailto:dmarc-reports@<domain>(itsLOCAL_PART), the address at which that stage reads the aggregate reports that tell you whether every sender aligns; check then reports what they say. Without such a stage the comment asks for anrua=mailto:<address>and names the stage.A valid record. Nothing is printed, exactly like the other records, unless a stage reads the reports and the record’s
rua=leaves its address out: the record to publish instead is then printed, the published one with every tag kept in order and the address added torua=(or anrua=tag added at the end). Eachrua=/ruf=destination is checked as check describes (an external one without its_report._dmarcauthorisation record, one that cannot receive mail); a problem is printed as a; WARNING:comment and logged. When itsp=isquarantineorrejectand[pepsi-ingress] DMARC_ENFORCEis off, a warning is logged: the domain asks every other receiver to act on a DMARC failure that this host delivers. A warning recommends the same record withsp=reject; np=rejectwhen the record leaves the subdomains a weaker policy thanreject: ap=other thanrejectwith nosp=, or an explicit weakersp=ornp=(the policy for names that do not exist). A subdomain that nobody sends mail as can refuse forgeries while the domain itself is still monitored. check shows the same advice beside the record.A record that receivers would ignore. The reason is printed as a comment and logged as a warning, and no replacement value is offered. This is deliberate: a record that fails to parse is still a statement of intent, and a malformed record must be repaired where it stands rather than replaced by the bare record that this tool would otherwise suggest. Fixing a typo should not silently drop a domain’s
rua,spor deliberatep=quarantine.
Validity is judged strictly, tag by tag, against RFC 7489 §6.4 rather than by looking for substrings, because a DMARC record fails silently: nothing bounces, no receiver complains, and the domain simply stops being protected while everyone believes it is. In particular, a record with a single missing
;, say… p=reject; aspf=s adkim=s, is still perfectly good generic tag-list syntax (RFC 6376 §3.2 allows spaces and=inside a tag value), so a loose reader sees the tagaspfwith the values adkim=sand accepts it; only the DMARC-specific value grammar rejects it. Where the offending value contains something shaped like the next tag, the diagnostic says so by name (tags are separated by ';', and there is none before 'adkim='). The other things reported are a second DMARC record at the same name (RFC 7489 §6.6.3: receivers discard the whole set), a repeated tag (RFC 6376 §3.2, where which value wins is undefined), a missingp=tag, and anrua=/ruf=address written without itsmailto:scheme. Everything that pepsi-setup calls valid is cross-checked in the test suite against the very parser that pepsi-ingress(1) applies to inbound mail, so a record blessed here cannot be one that a receiver throws away. The checks above are deliberately stricter than that parser, since a record can parse and still not be the policy that its author published.Before suggesting each TXT record (DKIM, SPF, DMARC, MTA-STS, TLSRPT), pepsi-setup first queries live DNS (best-effort): a record that is already published with the correct value contributes nothing to the output, not even its per-domain section header, so only the records that genuinely need (re-)publishing are printed. The
mta-sts.<domain>reminder to publish an A/AAAA (or CNAME) record is likewise emitted only when that host does not already resolve, and the DANE/TLSA block is printed only when a TLS-terminating ingress listener exists. When nothing needs changing, the whole zone dump is suppressed and a singlesetup: DNS records checked and they are OKline is logged instead, so re-running over an already-configured zone is silent. The probe is non-fatal: when DNS is unreachable (or a resolver cannot be built) every record is treated as a change and printed. The DMARC block is the exception in that last respect: with no answer from DNS there is nothing to compare against and no local value to fall back on, so it stays silent rather than telling a domain that may already be correct to publish a new policy. (Use the check subcommand for live verification of the published TXT records.)“Already published with the correct value” means correct at every authoritative nameserver of the zone, not just in the system resolver’s answer. For each TXT record pepsi-setup also finds the zone’s
NSset and asks each server directly, without recursion: a secondary still serving an old key, a delegated server that no longer serves the zone (a lame delegation) or one that does not answer at all makes receivers see the right record only some of the time, so the record is printed with a; NOTE:line naming each server that disagrees (and a warning is logged). A wrong answer from the resolver that every authoritative server contradicts is marked as a stale cache. When no authoritative server can be reached, as on a network that lets only the local resolver out on port 53, a warning is logged once and the resolver’s answer alone decides.A DKIM selector record is judged the way a verifier reads it (RFC 6376 §3.6.1), not by its
p=alone: exactly one key record at the name,v=(if present) first andDKIM1, ak=naming the key type (an Ed25519 key with nok=tag fails everywhere, since the tag defaults torsa), noh=/s=restriction excludingsha256/email, not=y(testing mode, under which a signature counts for nothing) and ap=equal to the key that pepsi-dkim(1) reports for the selector. Only the selectors that[pepsi] DKIM_ALGORITHMSsigns with are printed and checked, plus the one that the ARC seal needs on theARC_DOMAIN. A record that can go is printed as a; remove:comment, never as a record; such a record belongs to a key that the daemon retired, or to a 0.0.0 key file that run deleted. When the daemon has not reported its keys yet, the zone has no DKIM records and a warning says to startpepsi-dkim.serviceand look again. Next to the Ed25519 record, or in a log line when every record is already correct, pepsi-setup notes that Gmail, Microsoft 365 and Yahoo do not verify Ed25519 signatures and that Google’s DMARC aggregate reports list them asfail. This is expected and harmless, since the RSA signature supplies DMARC’s aligned pass, and the Ed25519 signature can be removed withDKIM_ALGORITHMS = rsa.In the same phase pepsi-setup also checks the reverse DNS (PTR) of each pepsi-stage-relay-to-internet
PUBLIC_IP, that is, of this host’s own egress addresses (a pepsi-stage-relay-to-smarthostPUBLIC_IPis the smarthost’s, so it is skipped). Each address is judged against the name that the owning stage announces, itsSERVER_NAME(falling back to the ingressHOSTNAMEwhen a stage sets none), because that is the pair that a receiver compares. APUBLIC_IPis correct only when itsPTRexists, forward-confirms, and names exactly that host; every other outcome is a warning:no PTR record — a strong spam signal at many receivers;
a PTR that is not forward-confirmed — the
PTRhost name does not resolve (A/AAAA) back to the same IP, so the round-trip check (forward-confirmed reverse DNS, FCrDNS) that many MTAs apply fails and they treat the IP as having noPTRat all;a generic / dynamically-assigned-looking PTR — a name that embeds the IP or carries a residential-pool token (
dynamic,dsl,pool…), which receivers often penalise;a PTR naming a different host than the ``EHLO`` name — the record is perfectly well-formed and forward-confirmed, it simply names another host. A large family of receivers refuses the session outright with HELO host does not match rDNS. This fires even when the ``PTR`` name is one of your own
ACCEPTED_DOMAINS: a machine that answers to several names (sayexample.organnounced inEHLOwhile its address reverse-resolves toexample.net) passes every other check here and still has its mail refused;a PTR that could not be looked up at all — an undelegated reverse zone or unreachable DNS. Correctness could not be established, and an address with no usable
PTRis refused or junked by many receivers, so this is reported rather than passed over silently.
Each warning carries concrete remediation. Because reverse DNS for a
PUBLIC_IPlives in the IP owner’s zone (in-addr.arpa/ip6.arpa), the usual fix is to ask your ISP or hosting provider to set thePTRto the announced name; if you run the reverse zone yourself, the missing-PTR message prints the exact… IN PTR …record to publish. For a name mismatch where thePTRis already one of your own domains, the message also offers the other direction, since that fix needs nobody else’s cooperation: adopt thePTRname as this host’s identity ([pepsi-ingress] HOSTNAMEand every stage’sSERVER_NAME, with the MX record and TLS certificate following it). The two names must denote one host; sharing a domain is not enough. The wizard’s hostname default is taken from the samePTRlookup (see –wizard below), so an interview-generated configuration starts out agreeing with reverse DNS.A relay stage with
EHLO_FROM_PTR = yes(see pepsi.conf(5)) announces the forward-confirmedPTRname of its sending address itself, so for that stage thePTRis compared with its own name: the name mismatch cannot occur, while a missing, unconfirmed or generic-lookingPTRis still reported. Without a forward-confirmed name the stage falls back toSERVER_NAME, and the check judges that name as usual.DNS as the Internet sees it. Every check above is made from this host, and from there a zone served from the host’s own network always looks healthy. Behind NAT, a query from inside for a reverse zone whose nameserver is this very machine is answered by the LAN, by the router or by the host itself. A query from the Internet, meanwhile, times out at a router that forwards port 25 but not port 53, or reaches a nameserver that serves a smaller zone than its parent delegates, so that resolvers that minimise their queries (RFC 9156) receive
REFUSED. Receivers then defer every message with cannot find your reverse hostname, and the local check says thePTRis correct.So pepsi-setup asks again through the public resolvers named by
[pepsi] PUBLIC_RESOLVERS(by default Google, Cloudflare and Quad9, each over IPv4 and IPv6; see pepsi.conf(5)): thePTRof everyPUBLIC_IP, forward-confirmed through the same resolver; each domain’sMXset and the TXT records that the check subcommand verifies; and the addresses of the ingressHOSTNAME. All of them are asked, because they differ in the address family that they use to reach a nameserver and in how they walk a delegation, and a zone that is reachable only over IPv6, or lame only for a minimising resolver, fails for some of them and not for others. A receiver uses one of those too. Any resolver that cannot resolve a name, finds no record, or sees a different answer from this host’s (split-horizon DNS) is a warning, naming the resolver and, when it sends one, its RFC 8914 extended error (No Reachable Authority: At delegation …). When the zone’s nameservers resolve to this host’s own or private addresses, the warning says so and names the usual causes: a port forward that is missing or disabled for UDP or TCP port 53, an IPv6 firewall rule, or a served zone that is not the delegated one. The check subcommand reports these as[UNREACHABLE](a correct record that the Internet cannot read) and lists thePTRverdicts in a reverse DNS group of their own.Resolvers that cannot be reached from this host are dropped silently (a host without IPv6 connectivity loses the IPv6 ones); when none can be reached, a warning is logged once and only the local view is checked.
PUBLIC_RESOLVERS = noneturns this check off.MTA-STS cross-checks. Everything else pepsi-setup verifies about MTA-STS is self-consistent by construction: the
_mta-stsTXT record carries anidderived from the policy, and the policy is derived from the configuration, so comparing them can only succeed. Two things are not derived from the configuration, and underMTA_STS_MODE = enforceeither one being wrong silently stops all inbound mail for the domain. Both are checked on everypepsi-setup run, and reported by the check subcommand and the web console; like thePTRfindings they are warnings and never fail the run.The policy’s ``mx`` set against the live MX records. A policy is a promise that senders may connect only to the hosts it names. A sender resolves the domain’s
MX, finds a host that the policy does not permit, and refuses to deliver. Every compliant sender does this at once, and this side shows no symptom beyond mail that never arrives. This is the failure that theMTA_STS_MXfallback invites, becauseHOSTNAMEis theEHLOgreeting name and need not be a name that anyMXrecord points at. The warning names the hosts on each side and prints the singleMTA_STS_MXline that would make them agree, qualified per domain when the served domains have different MX hosts, along with the alternative of changing theMXrecord instead and the advice to fall back toMTA_STS_MODE = testinguntil they do agree. This check also reports a domain with noMXrecord, an RFC 7505 null MX on a domain we accept mail for, anMXtarget that is aCNAME(forbidden by RFC 5321 §5.1, and senders may refuse it), a policy entry that matches no liveMXhost (harmless, but it widens what senders will connect to), and aDOMAIN:HOSTentry naming a domain that is not inACCEPTED_DOMAINS. Such an entry applies to no policy at all, and it is what a typo in the option looks like.Whether the policy can be fetched.
pepsi-setuprequestshttps://mta-sts.<domain>/.well-known/mta-sts.txtand compares what comes back with the policy that this configuration defines. The comparison is semantic, so line endings and key order are not differences. Redirects are not followed, because RFC 8461 §3.3 forbids a sender from following them, and a policy served only behind one is a policy that no sender can read. A correct TXT record in front of a policy that nobody can fetch is not hypothetical. One unreachable socket, misconfigured front server or missing certificate is enough for every sender to get a502instead, while every unit staysactiveand nothing is logged. Senders that already cached a policy keep enforcing the old one for up tomax_age, so the failure does not even end by itself. A5xxis reported with the front-server socket as the thing to check.When the published name cannot be reached from this host, because it does not resolve yet or because the network will not let the host reach its own public address, the request is retried against this machine over the loopback interface. The published name stays in SNI and
Host, so the certificate is still validated against the name that a sender would use. That result is labelled as a local probe, because it says what a sender would get oncemta-sts.<domain>resolves here; it is the reason a purely local misconfiguration is still reported on a host whose DNS is not yet published.
The SRS domain can receive its own bounces. When a stage runs pepsi-stage-srs(1), pepsi-setup checks that
[pepsi-srs] SRS_DOMAINhas anMXrecord or, failing that, anA/AAAArecord (RFC 5321 §5.1’s implicit MX). An SRS address is a return path: the rewrite makes this host the bounce destination for mail it did not write, and the HMAC in the address exists so that pepsi-ingress(1) can decode a returning bounce and relay it to the original sender. Without either record, that round trip ends in silence: forwarding works, SPF passes at the next hop, and every bounce is discarded by the MTA that tried to return it, so the original sender is never told that their message did not arrive. An RFC 7505 null MX (MX 0 .) is the same answer stated deliberately, and anMXtarget that is aCNAMEis reported for the same reason as everywhere else (RFC 5321 §5.1, RFC 2181 §10.3). The warning prints the record to publish, naming a host that the accepted domains already route mail to, and offers the alternative of dropping the stage if nothing is forwarded off-site. (An accepted domain, which would receive already, is not an alternative: it is DMARC-aligned with itself, see above.) Like the checks above it is a warning and never fails the run.The check exists because the omission is invisible from every other angle. The SRS domain is a sending identity, so it joins the set that gets DKIM keys and SPF and DMARC advice; pepsi-setup suggests no
MXrecord for any domain, that being the operator’s own routing decision. An operator who publishes everything they are told to publish therefore ends up with two of the three records that the domain needs, and nothing anywhere says so.Forward-confirmation queries authoritative DNS only and deliberately ignores the local
/etc/hostsfile, because a mail host commonly lists its own name there against127.0.1.1or a NAT-internal address, which would otherwise make a perfectly forward-confirmed name look unconfirmed. These findings are deliverability warnings, not errors: they never fail the run.Verifies the payment backend (optional). When a
[pepsi-payments]section configures a GNU Taler merchant backend, pepsi-setup checks it over HTTP:GET /configmust identify ataler-merchantbackend (so the URL is correct) andGET /private/orders?limit=1must return200(so theMERCHANT_ACCESS_TOKENis correct). It then ensures apepsi-resumewebhook exists thatPOSTs to pepsi-httpd’s/resumeendpoint whenever an order is paid. It creates the webhook if absent; if apepsi-resumewebhook already exists, it logs a warning when its definition differs from the expected one (it is never silently overwritten). The webhook targets the shortest configured[pepsi-httpd-cert-*]SNI host over HTTPS and authenticates with[pepsi-httpd] RESUME_AUTHORIZATION_TOKEN. When no merchant backend is configured this step is skipped entirely.Reminds about credentials that expire out of band. When any smarthost MTA uses
AUTH = oauth, pepsi-setup validates the corresponding[pepsi-helper-token-refresh-<name>]secret sections that it can read (it runs asroot) and prints a reminder that those access tokens must be kept current, for example by enabling pepsi-helper-token-refresh(1), which is not part ofpepsi.target. When one usesAUTH = gssapiit likewise reminds that the Kerberos credential cache has to be renewed out of band (a keytab plusk5startor cron) and be readable by the dispatcher’s worker, sanity-checking any cache path it can see. Both reminders go to the log (standard error), after the zone output, so they can never corrupt a redirected zone file.
All behaviour is driven by an INI-style configuration file (see pepsi.conf(5)). The same configuration file is shared with the other Pepsi tools.
95.1.43.1.4. Privileges and ownership¶
pepsi-setup may be run either directly as the database owner (for example
su pepsi-owner -c 'pepsi-setup … run') or as root. When it is run as
root it manages two distinct identities itself, so the resulting objects are
owned by the right accounts:
Database objects are created as the
pepsi-ownerrole. Before any database work (schema install, role provisioning, settings validation, payment-backend check) pepsi-setup assumes the effective identity of thepepsi-owneruser; PostgreSQL peer authentication then connects as the same-named role, so thepepsischema, its tables, sequences and functions are owned bypepsi-owner. Thepepsi-owneruser/role and the database itself must already exist (the Debian package creates them; otherwise create them by hand). Only the effective uid changes, so root is regained afterwards.The signing daemon works as its own account.
pepsi-dkim sync-domains, run by root, creates[pepsi-dkim] STATE_DIRandPUBLIC_DIRwhen missing and becomes thepepsi-dkimaccount before it touches a key, so every key file belongs to that account (mode0600in0700directories) and no other.
When pepsi-setup is not run as root, neither switch happens: it operates
entirely as the invoking user, which must therefore be the database owner, and
pepsi-dkim sync-domains must be able to write the daemon’s directories (or
reach the running daemon). Deleting the 0.0.0 key files under KEY_DIR
needs write access there.
Note
ARC sealing (performed by pepsi-stage-arc(1) on inbound mail) uses the
[pepsi] ARC_DOMAIN’s DKIM key of ARC_ALGORITHM, so there is no
separate ARC key or DNS record: ARC verifiers fetch the seal’s public key
from the same DKIM record. When ARC_DOMAIN is set, pepsi-setup
simply includes it among the signing domains it hands to pepsi-dkim(1)
and the domains it prints records for.
95.1.43.1.5. Wizard¶
For a first deployment, –wizard replaces hand-editing with a short interactive interview and writes a complete, already-validated configuration file.
The interview is presented as a sequence of numbered steps that group
related questions: Server identity, Existing mail system, Local delivery,
Submission authentication, Trust loopback, Forwarded mail,
Transport security, Content filtering, Anti-spam paywall, Account
self-service and End-to-end cryptography (plus Expert options under
–expert). Each step is shown as a Step X/Y banner with a one-line
description, in colour on a capable terminal (set the NO_COLOR environment
variable to disable it). Which steps appear (and therefore Y) follows from
the chosen direction and whether a local Dovecot is detected. The manual’s The
Wizard chapter draws the pipeline that each direction produces and lists what
every question decides. When stdin is a real terminal, prompts are
line-edited with the usual GNU-readline key bindings (Home/End,
Ctrl-Left/Ctrl-Right to skip words, Ctrl-A/
Ctrl-E/Ctrl-K/Ctrl-U/Ctrl-W, and Up/Down to recall
earlier answers); a piped (non-terminal) stdin, as the test suite and scripts
use, falls back to plain line reads. Each answer is validated the moment
it is entered (hostnames and domains must be fully-qualified, the postmaster a
valid address, sending IPs real IP literals, ports numeric, the payment hold a
h/m/s duration, and so on), so a mistake is reported at its own
prompt and corrected on the spot rather than only at the final whole-config
validation.
It first asks the direction that the host serves, which determines the SMTP
listeners (port 25 for inbound, 465/587 for outbound) and the relay stages that
appear: inbound (receive mail for our domains from the Internet, delivering
it locally and/or relaying it onward), outbound (send our own users’
submissions directly to the Internet) or both (the default; split on
state.local_origin with a routing stage). It then asks for the hostname,
accepted domain(s), postmaster address, public sending IP(s) and the database
connection string, proposing sensible defaults (the parent of the hostname as
the domain). The hostname default is taken from reverse DNS: the wizard
detects this host’s public addresses (the same detection described for the
sending IPs below), looks up their PTR records, and offers the first name
that forward-confirms back to the address and does not look auto-generated.
Only if there is no such name does it fall back to /etc/hostname. This is
deliberate: a receiving mail server compares the name announced in EHLO
against the PTR of the address that the session comes from and rejects when
they disagree (HELO host does not match rDNS), while /etc/hostname is a
purely local label that no receiver ever sees. On a host that answers to
several names the two routinely differ, and reverse DNS lives in the IP owner’s
zone, so it is normally the half that cannot be changed. When the offered
default (a previous run’s answer, or /etc/hostname) contradicts the
PTR, the wizard says so and names both before asking. The public sending
IP(s) default is auto-detected and offered for confirmation: the
hostname’s published A/AAAA records unioned with the host’s own
globally-routable interface addresses, plus the WAN IPv4 that the local UPnP
gateway reports via upnpc (miniupnpc), if installed. The gateway is asked
only when the other sources find no public IPv4 (a NAT host with a private
IPv4). Only public addresses are suggested: a private/loopback/link-local
address is never pre-filled (behind NAT the detected value is the public egress
IP, not the LAN address). The operator confirms or edits it before anything is
written.
On the inbound path the next question is whether an existing mail system,
Microsoft Exchange or Microsoft 365, sits behind this host. Answering yes makes
Pepsi a transparent gateway: it becomes the MX and hands everything to the
tenant endpoint, so there are no local mailboxes and the local-delivery
questions below are skipped. It then asks for that endpoint’s host and SMTP port
(warning that it must be the tenant-specific endpoint, not the domain’s public
MX, which is this host and would loop) and for the IP address family to reach it
over (any/ipv4/ipv6; Exchange Online refuses mail from an IPv6
address with no reverse DNS, so ipv4 is the escape hatch when IPv6 reverse
DNS is not delegated).
Otherwise, on the inbound path it asks which local-delivery method(s) to
use: Maildir (pepsi-stage-relay-to-maildir) and/or LMTP to an MDA
(pepsi-stage-relay-to-lmtp). When Maildir is enabled, it also asks whether
to honour per-user ~/.forward files (pepsi-stage-dot-forward; the
generated section forwards to addresses only, with ALLOW_PIPE /
ALLOW_FILE left off).
Still on the inbound path, it asks whether this host should answer mail for
recipients who are away (pepsi-stage-vacation, default no). Answering yes
only puts the stage in the pipeline, after alias expansion and after the spam
gates, so that a notice is never sent on behalf of an alias or in reply to mail
that the gates would have refused. Nobody is answered until leave dates
exist, and those are ordinary per-address configuration rather than a wizard
answer: a user can set their own by e-mail, an operator with pepsi-settings
set <address> vacation VACATION_RANGES …, and a holiday everybody shares with
pepsi-config set --scope domain:<domain> stage-vacation VACATION_RANGES ….
The generated section therefore leaves VACATION_RANGES unset (with the
syntax in a comment) and points RESPONSE_STAGE at the shared signing tail
so each notice is signed and relayed. On a host with no local delivery,
such as a pure forwarder or an Exchange front, it also sets VACATION_TAG =
none: tagging the subject would otherwise rewrite a header covered by the
author’s DKIM signature and by this host’s own ARC seal, which the next hop
would see fail. See pepsi-stage-vacation(1).
It then asks for the upstream smarthost (optional when local delivery or an Exchange system handles the served domains, required otherwise).
Two questions then decide how mail leaves this host with a signature of its
own. The first concerns programs running on this host, such as cron,
mail(1), logwatch, git send-email or a web application, which are
otherwise refused with 550 5.7.1 Relaying denied for any recipient outside a
served domain.
The wizard does not ask whether to serve the UNIX-domain submission socket
that /usr/sbin/sendmail uses. pepsi-ingress always serves it, deriving it
from [pepsi-sendmail] SOCKET, so no listener section is written and there is
nothing to answer wrongly. The kernel tells pepsi-ingress which account
opened the socket, so a caller can only ever send as itself: the login is run
through USERNAME_MAP exactly as a SASL username would be. See
pepsi-sendmail(1), and SOCKET = none to switch it off.
What it does ask, as a yes/no question defaulting to no, is whether to
additionally trust loopback. It asks this only on a host serving both
directions: the answer becomes MYNETWORKS on the port-25 MX listener, which
only an inbound host has, and the question is only worth asking of a host that
also submits.
TRUST_LOOPBACKAdd
MYNETWORKS = 127.0.0.0/8 ::1/128to the port-25 listener (merged with any networks set through the expert options, never duplicated). This trusts a network position rather than a user, so any local process, including a compromised web application, can send as anyone. It is also what lets a message that this host relays to itself (a served domain whose public MX is this host) re-enter as a fresh submission and loop. Say yes only for software that insists on speaking SMTP to port 25 and cannot be pointed at the socket.
Either way the resulting messages count as locally originated
(state.local_origin) and are therefore DKIM-signed by the outbound path.
On the inbound path it asks whether to DKIM-sign the mail this host forwards
(defaulting to yes): an alias expanding off-site, a ~/.forward pointing at
another provider, or the whole pure-relay path. Those messages leave down the
inbound tail, which the outbound [stage-dkim-sign] never touches, so without
this they arrive at the next hop with our SRS envelope but dkim=none from us.
Answering yes emits a second signing stage, [stage-dkim-sign-relay], between
the SRS rewrite and the destination, with SIGNING_DOMAIN pinned to the
primary served domain. That pin is deliberate: signing is fail-closed, and the
author’s domain belongs to somebody else, so deriving the signing domain from a
foreign From: would fail every forwarded message for want of a key.
The host’s own identity is the configured hostname throughout, distinct from
the accepted recipient domains (which scope SRS, MTA-STS and the TLS-report
addresses). That identity covers the ARC sealing domain ([pepsi]
ARC_DOMAIN), every relay/bounce SERVER_NAME and the fallback listener
certificate.
The way those listeners bind their ports depends on the host. When the system
is managed by systemd (detected by the presence of /run/systemd/system),
the wizard writes socket-activated listeners (SERVE = systemd with a
FD_INDEX per listener) so the privileged ports are bound by .socket
units and inherited by the unprivileged service; otherwise it falls back to
direct binds (SERVE = tcp with BIND_TO / PORT). The ingress
listeners always take FD_INDEX 0 for port 25, 1 for 465 and 2 for 587,
matching the shipped pepsi-ingress.socket, which lists all three whichever
direction the host serves. With socket activation you must install the
matching .socket units (a pepsi-ingress.socket listing
ListenStream=25, 465 and 587 in that order, and a
pepsi-httpd.socket for port 443); the wizard prints a reminder after writing.
Two transport-security questions follow. On the inbound path it asks whether to
serve an MTA-STS policy (default yes): when enabled it sets
MTA_STS_MODE = enforce and adds a [pepsi-httpd-cert-*] section for each
accepted domain’s mta-sts.<domain> policy host (served over HTTPS by
pepsi-httpd), whose certificate pepsi-setup provisions via certbot like
any other; you must point each mta-sts.<domain> name’s DNS at the server for
the policy to be reachable. The hosts that the policy permits are not asked for:
they are read from the served domains’ live MX records and written as
[pepsi] MTA_STS_MX (left out when no MX record exists yet, so the policy
falls back to HOSTNAME; see MTA-STS cross-checks above). It then asks
whether to send SMTP TLS Reports (TLSRPT, RFC 8460; default yes), which
emits the [pepsi-tlsrpt] section.
The same step closes with the one question that is not about this deployment at
all: whether to share anonymous feature-usage telemetry with the Pepsi
project ([pepsi] SHARE_TELEMETRY, default no). It is opt-in, so the
prompt explains what would be sent before asking: a random 256-bit
SYSTEM_ID and counts of which Pepsi features this host has exercised, never
addresses, message data, host names or IP addresses. Pressing Enter through the
whole interview therefore shares nothing. Saying no disables the entire path:
no identifier is generated, setup never starts the daemon, and a daemon that the
operator started is sent dormant. See pepsi-telemetry-client(1).
The pepsi-httpd sections are always written, whatever else is declined:
HTTPS on port 443 with the web certificate, which is separate from the one that
the SMTP listeners use (serving the MTA-STS policy when that is on), and the administrative console on
/run/pepsi/admin.sock for the pepsi-admin group. pepsi.target
starts the server and its socket on every host, so a configuration without a
listener would leave it failing and restarting.
A short feature menu follows, asked only where it applies to the chosen
direction: whether to block mail by detected language (and, if not, whether
to still localize bounce messages, which enables language detection). When
detection is enabled it first prints the full list of supported ISO 639-1 codes
and asks which languages the detector should recognise, accepting * (the
default) for every language the detector supports and rejecting any
unsupported code on the spot (rather than only at the final validation). Only a
detected language can then be allowed or blocked, so when blocking is on it next
asks for a single combined language policy in a +allow/-block syntax.
For example, +en +fr -ja -zh allows English and French while blocking
Japanese and Chinese, and 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 the fate of undetected mail. This
one answer is split into the stage’s WHITELIST and BLACKLIST options.
It then asks whether to ask unknown senders to confirm by reply
(SECRETARY, pepsi-stage-secretary(1), default no), and about the
GNU Taler anti-spam paywall (which also enables the correspondent whitelist
so known contacts skip the payment request). When the paywall is enabled the
wizard asks for the merchant backend URL first and immediately verifies it
over HTTP (GET /config must identify a taler-merchant backend), reading
back the currencies that the backend supports. The price must be quoted in one
of them, so the URL has to be known before the price is asked. It then asks for
the access credential: either a ready-made access token (recognised by its
secret-token: prefix, and verified against the backend) or the instance
password, which the wizard exchanges for a scoped access token via POST
/private/token (requesting the all scope so the token can also manage the
pepsi-resume webhook). Finally it asks the price per message as a
space-separated list of Taler amounts (e.g. EUR:1 CHF:1 KUDOS:10),
validated against the backend’s currencies; each amount becomes one choice in
the generated v1 order ORDER_CHOICES, letting the payer pick a currency.
When both the paywall and confirm-to-send are off, and the host also has an
outbound path, the wizard instead asks whether to merely learn a
correspondent whitelist from outgoing mail.
On the outbound path a self-service step then asks up to two independent yes/no questions, both defaulting to no. The first is whether account owners may edit their own per-address settings by e-mail (pepsi-stage-edit-settings(1)); it is asked only on a host serving both directions, because every stage that an account owner may edit is an inbound one. The second is whether they may operate their own GNU Taler wallet by e-mail (balance, top-up and peer-to-peer payments), served by the same pepsi-stage-auto-pay(1) that pays inbound payment demands.
The last step, asked whichever direction was chosen, is end-to-end
cryptography (default no): whether this gateway should encrypt and decrypt
mail itself (OpenPGP and S/MIME), so users need no client plugin. Saying yes puts
pepsi-stage-encrypt(1) and pepsi-stage-decrypt(1) in the pipeline;
nothing is encrypted until a recipient’s key is known, and keys come from
discovery (pepsi-keydisc(1)), from pepsi-keys(1), or from the mail
that correspondents send us. On the inbound path it then asks whether to learn
correspondents’ keys from that mail (Autocrypt, default yes), which adds
pepsi-stage-autocrypt-learn(1), and whether to re-encrypt what the gateway
decrypted to the user’s own mail-client key before filing it (REENCRYPT,
default yes), which adds pepsi-stage-reencrypt(1) in front of local
delivery. On the outbound path it asks whether to
enable pEp-style automatic encryption (PEP, default yes): every
sender at a served domain gets an OpenPGP key on their first message, advertised
in an Autocrypt: header, and mail is signed inside the encryption. It
states the cost before asking: eager key creation puts a wrapped private key
for everybody who sends mail into the database, and their public key into the
Web Key Directory, whether or not they ever use encryption. It then writes the
answer explicitly, ENABLE_PEP = yes or ENABLE_PEP = no, into
[stage-encrypt] in pepsi.conf, where it takes effect (no config.d
file sets it). When accepted it asks whether to also attach the sender’s key as
a file (ATTACH_KEYS_AS_FILES, default no),
written only when chosen. The encrypt stage is always given RESPONSE_STAGE =
dkim-sign, so the key-registered notices and the replies to the e-mail key
commands are signed and relayed like any other outgoing mail. The browser setup
interview asks the same questions. The key store, key discovery and the
key-encryption key are provisioned by the rest of setup regardless of the
answer.
SRS is wired automatically on every inbound path, whatever the relay
destination, with a generated secret; only its SRS_DOMAIN is asked, on the
same step as the forward-signing question and with no default. It has to be a
dedicated domain that is not aligned with the served ones; an aligned answer is
accepted only after a second question, SRS_ALLOW_ALIGNED.
95.1.43.1.5.1. Mail filters (milters) found on this host¶
On a host that receives mail, the wizard scans it for milter daemons and
offers each one it finds as a milter that pepsi-ingress(1) consults
during the SMTP session (a [pepsi-ingress-milter-<label>] section, named in
[pepsi-ingress] MILTERS; see pepsi.conf(5)). It never installs one,
and never starts or confines the daemon: as under sendmail and Postfix, the
filter keeps its own package, unit and user account, and Pepsi is only a
client. The scan is skipped on an outbound-only host, where no session receives
mail from outside, and every filter it finds is consulted for mail arriving at
the listeners that are not submission listeners. A filter for submitted mail
is configured by hand or, on a host that also receives, carried over from an
imported non_smtpd_milters as a pepsi-stage-milter(1) stage on the
submission path.
Seven filters are recognised: milter-greylist, milter-regex,
clamav-milter, spamass-milter, rspamd (through its rspamd_proxy
milter worker), mimedefang and amavisd-milter.
Each is looked for in three stages, and a filter is offered only when all three succeed:
Installed — its binary is on
$PATHor in the usualsbindirectories, or a systemd unit file for it exists.Listening somewhere — a socket is read from the filter’s own configuration file (
clamav-milter.conf’sMilterSocket,greylist.conf’ssocket, an/etc/defaultfragment’sSOCKET=or-pflag, Rspamd’sbind_socket), then from its unit’sExecStart, then from the paths that its distribution ships.Answering — setup completes a real milter option negotiation with each candidate socket and takes the first that succeeds.
The handshake is what makes the offer trustworthy: an installed package proves
nothing about a stopped daemon, and a wrong guess in the path lists costs
nothing, because a socket that does not answer is simply never offered. It also
settles what the filter is allowed to do. ALLOW_ACTIONS must grant every
action that a filter asks for, or the negotiation fails and the filter’s
ON_FAILURE applies, and the filter states that set during negotiation. Setup therefore
offers everything purely to hear the answer, and writes out precisely what
was asked and nothing more. A filter that only inspects is granted none;
MIMEDefang is granted the envelope actions exactly when the site’s own Perl
policy uses them.
The accepted filters are listed in [pepsi-ingress] MILTERS by what they
do rather than by the order in which they were found: policy and greylisting
first, then virus scanning, then spam scoring, then the general-purpose
frameworks. Filters carried over from an MTA import have no known purpose and
therefore come after all of these, keeping the relative order in which that MTA
ran them. Pepsi’s own greylister, when the GREYLIST answer is yes, comes
first of all. A section’s label is the filter’s name without the milter-
prefix ([pepsi-ingress-milter-clamav]); milter-greylist keeps the prefix,
because greylist is the label of Pepsi’s own greylister.
A filter in the session answers the sending server itself. When it refuses a
recipient or a message, the client receives its 4xx or 5xx, as under an
MTA, so nothing has to be bounced afterwards and no backscatter arises.
Whenever any milter is consulted in the session, the wizard also writes
[stage-quarantine] (PROGRAM = pepsi-stage-quarantine, RELEASE_STAGE =
init): pepsi-ingress offers a filter the quarantine action only when such
a stage exists, and stores a quarantined message there until it is released.
The message has been through no stage when it is stored, so on release it
starts at the pipeline’s first stage.
With –expert, or when a previous run chose it, each filter’s question has a
third answer, after-decrypt. It places the filter as a pepsi-stage-milter
stage after [stage-decrypt] (so the filter sees plaintext) and before the
whitelist, paywall and Autocrypt stages (so those can branch on whatever the
filter tagged). Such a stage runs after pepsi-ingress has answered 250,
so its rejected mail is dropped rather than bounced: bouncing would send
backscatter to whatever address the forged spam named. Its REJECT_STAGE
therefore points at a generated [stage-discard-rejected] (a
pepsi-stage-discard with DISPOSITION = failure, BOUNCE = no); the
verdict is still recorded in state.milter and in the log. Setting
REJECT_STAGE = bounce restores notification, and the generated section says
so. milter-greylist has no such answer, because greylisting works only by
refusing delivery in the session. A stage carried over from
non_smtpd_milters keeps REJECT_STAGE = bounce, since its sender is a
local user.
Filters whose function Pepsi already performs are not offered:
opendkim, openarc, opendmarc, SPF policy daemons and postsrsd.
Running one alongside Pepsi means two components signing or judging the same
message. They are not silently skipped: when one is found, the scan says so and
names the Pepsi feature that replaces it, so that a scan which found nothing to
offer is distinguishable from a scan that did not run. Spam classification is
deliberately not in this category: Pepsi has its own opinions about spam, but
they are different opinions from a Bayesian scorer’s, and an operator may
reasonably want both.
Each answer is remembered under its own MILTER_* key (MILTER_CLAMAV,
MILTER_RSPAMD, …) in [pepsi-wizard], as yes, no or
after-decrypt. Only filters that this run actually found are written there;
a re-run scans again.
After the scan the wizard asks GREYLIST: whether to greylist with Pepsi’s
own greylisting milter, pepsi-greylist. The answer defaults to no, because
greylisting delays the first message from every new correspondent by at least
five minutes, and by as long as the sending server waits before it retries.
Yes writes [pepsi-ingress-milter-greylist] with SOCKET =
unix:/run/pepsi-greylist/milter.sock, ALLOW_ACTIONS = none and
ON_FAILURE = accept, first in [pepsi-ingress] MILTERS. run then
enables and starts pepsi-greylist.service (the launchd job on macOS) when a
milter section names the greylister’s socket; it never disables the service.
The generated configuration is validated through exactly the same checks as
run before it is written, so the wizard never produces a file that would
later fail to load. If validation does fail, the wizard prints the offending
error and re-runs the interview with your previous answers pre-filled as the
defaults, so you can correct the broken option(s) without re-entering
everything. The interview answers are recorded in a [pepsi-wizard] section
at the end of the file, and re-running –wizard imports them as the new
defaults. Secrets (the smarthost password, merchant access token and the
generated SRS key) are not stored there.
Because the main configuration is written world-readable (mode 0644, so the
unprivileged stage accounts can read it), the wizard does not leave secrets
in it. Every secret that it would otherwise write inline is moved into a
restricted secrets.d/*.secret fragment next to the configuration and
referenced from it with an @inline-secret@ directive (see
pepsi.conf(5)). These secrets are the SRS SECRET, the smarthost/LMTP
PASSWORDs, the merchant MERCHANT_ACCESS_TOKEN and the
pepsi-httpd RESUME_AUTHORIZATION_TOKEN. The generated
ones (the SRS key, the /resume token) are read back from the existing
fragment and reused, so re-running the wizard never silently rotates them (which
would invalidate SRS senders already in flight or the deployed payment webhook).
A credential added to the file by hand is moved by run, before it secures
the fragments: every option the wizard would externalize, and also
[pepsi-keydiscovery] LDAP_BIND_PASSWORD (to secrets.d/pepsi-keydisc.secret),
[pepsi-list] API_PASS (to secrets.d/pepsi-list.secret),
[pepsi-dkim] TSIG_SECRET (to secrets.d/pepsi-dkim.secret) and the OAuth
CLIENT_ID, CLIENT_SECRET and REFRESH_TOKEN of a
[pepsi-helper-token-refresh-<name>] section (to
secrets.d/pepsi-helper-token-refresh.secret). The value is merged into the
fragment, keeping the secrets already there, and the line in the main file is
replaced by an @inline-secret@ directive at the end of its section. An
option whose name says it is a password, secret or token but whose reader
Pepsi does not know (one that no Pepsi program defines) stays where it was
written, and run warns about it on every run, naming the section and option:
move the value into a file that only its reader can read and pull it in with an
@inline-secret@ directive. An option naming a file (SECRET_FILE,
TOKEN_FILE) is a path, not a credential, and is left alone.
95.1.43.1.5.2. Secret prompts¶
The secrets that you type (the smarthost and LMTP passwords, the merchant access
token) are never echoed and never written into [pepsi-wizard]. On a re-run
they are read back from their secrets.d fragment, so the prompt shows
[***] and Enter keeps the stored secret:
Smarthost password [***]:
Three answers are possible:
- Enter
Keep what is stored. When the fragment exists but this process may not read it (it belongs to the service account and the wizard is running unprivileged), the fragment is left completely untouched and the configuration keeps pointing at it; the secret is preserved without the wizard ever seeing it.
- a value
Replace the stored secret with what you typed.
- Enter twice
Leave the secret unset for now. This is offered only when nothing is stored and only on a terminal; the wizard then writes the configuration without that option, prints the section, option and file to add it to, and leaves a commented line in the fragment naming it. The services will not work until you fill it in and run
pepsi-setup run.
For a smarthost that authenticates, the wizard then offers to check the credentials by opening a session to the relay and authenticating, exactly as a delivery does but without the message. A mistyped password then surfaces while you are still there to correct it, rather than as mail that quietly stops flowing:
Check these credentials against smtp.relay.example:587 now [Y/n]:
If the relay refuses them the wizard offers to take the password again; if it cannot be reached at all (firewall, DNS, the host being down) it says so and does not push you into retyping a password that may be perfectly good. The check is skipped entirely when stdin is not a terminal: an unattended run must not depend on the network being up.
Each directive is written after the last option of the section that it feeds, because a directive ends its section for the parser (see pepsi.conf(5)). The fragments are secured (mode and ownership) as soon as they are written and again by run; see the run command below. The wizard then re-loads the file it has just written and validates that, so a configuration it cannot itself parse is never left behind. After writing, the wizard offers to run the full setup (run) immediately.
If the target file already exists and contains a [pepsi-wizard] section, its
answers are imported as defaults. If it exists without one, the wizard warns
that it cannot import previous answers and asks for confirmation before
overwriting; –force overwrites without prompting.
Note
The anti-spam paywall requires its message templates (e.g.
payment-request.en.body) to be installed under [pepsi] TEMPLATE_DIR
(default ${DATADIR}/templates, i.e. /usr/share/pepsi/templates for a
--prefix=/usr installation); make install places them there.
Because the wizard validates against the live environment, enabling the
paywall before the templates are installed reports a clear error rather than
writing a configuration that would fail at run time.
95.1.43.1.5.3. Answering without a terminal¶
–answers FILE runs the whole interview from a JSON object of question
identifier to value, asking nothing. It is not a second implementation of the
wizard: the same interview() runs, with every prompt short-circuited to the
supplied answer (or, where there is none, to the wizard’s own default, exactly
as pressing Enter would). The branch structure, the per-field validation and the
rendering are therefore the interactive ones.
The identifiers are what pepsi-setup questions prints, and they are the same
keys that the generated [pepsi-wizard] section round-trips, so a
configuration that a previous run wrote is itself a valid answer file once that
section is turned into JSON. The expert options (–expert, and whatever
an MTA migration found) share that namespace and are accepted here too,
validated by the same check that the --expert prompt applies. The browser
interview deliberately refuses them, since an option that nothing asks about is
not one that a web form should set. An unknown
identifier is an error naming the key rather than a silently dropped line, because
an answer that is quietly ignored looks exactly like one that was accepted and had
no effect.
Secrets may appear in the file (SMARTHOST_PASSWORD, LMTP_PASSWORD,
MERCHANT_ACCESS_TOKEN); they are moved into secrets.d fragments like any
other, so the file itself should be treated as a credential and deleted
afterwards. A secret already stored in a fragment is carried forward when the
answer file does not mention it, which is what makes a scripted re-run
non-destructive.
Example:
cat > answers.json <<'EOF'
{
"DIRECTION": "both",
"HOSTNAME": "mx.example.com",
"DOMAINS": "example.com",
"POSTMASTER": "postmaster@example.com",
"PUBLIC_IPS": "203.0.113.7",
"LOCAL_METHODS": "maildir",
"MTA_STS": "yes"
}
EOF
pepsi-setup --wizard --answers answers.json -c /etc/pepsi/pepsi.conf
95.1.43.1.6. Migrating from another MTA¶
Nobody installs a mail server on an empty machine. When –wizard finds no configuration at the target path, it looks for the mail server the host runs today — Postfix, Exim, Sendmail, qmail or Stalwart — and offers to import its settings as the interview’s answer defaults. If several are configured it presents a numbered menu; –import MTA picks one without asking and –no-import skips the search entirely. Auto-detection is skipped when stdin is not a terminal, so a scripted –wizard run keeps producing the configuration that its answers describe rather than one shaped by whatever was left over on the machine.
Whichever server is imported, the SRS domain into which a postsrsd beside it
rewrites forwarded senders (SRS_DOMAIN= in /etc/default/postsrsd, or
srs-domain in /etc/postsrsd.conf) becomes the default of the
SRS_DOMAIN question: every bounce of mail forwarded before the migration is
addressed to it, and the question has no other default. If that domain is
aligned with a served one, the question explains why and asks for another; a
run with no terminal to ask on stops with that explanation.
Nothing is imported silently. Every imported value becomes the [default] on
its question, which the operator confirms or corrects, and everything that could
not be carried over is collected into a migration report written next to
the configuration as import-report.txt (also printed as a one-line summary
before the interview starts). The report groups its findings into four
categories:
FAILEDA file could not be read or parsed; nothing was imported from it.
UNSUPPORTEDUnderstood, but Pepsi has no equivalent, as for a
header_checkstable or an alias delivering to a command. The entry names what Pepsi offers instead, where something does. A trusted network of the old server outside loopback is reported here too, one entry per network, rather than carried intoMYNETWORKS: Pepsi trusts a network only as far as[pepsi-ingress] SENDER_MAPbinds it, and pepsi-ingress refuses to start on an unbound one, so the operator adds the network and its binding by hand.APPROXIMATEDImported with different semantics, such as mbox delivery becoming Maildir, a
maximal_queue_lifetimerounded to whole hours, a loopback network dropped fromMYNETWORKS.UNKNOWNA directive the importer does not recognise, and therefore did not migrate. Reported so an unrecognised setting is visible rather than invisible.
An import can never fail the run: an unreadable file, a corrupt line or a directive from a fork that nobody has heard of produces a warning, and the rest of the configuration is still imported.
95.1.43.1.6.1. Milters¶
The milters that Postfix or Sendmail consulted for mail arriving over SMTP are
carried over as milters that pepsi-ingress consults during the SMTP
session, in the same order, so a filter that refused mail still answers the
sending server. The wizard asks once whether to carry them over
(MILTERS_ENABLED), negotiates with each one to learn which actions it needs,
and writes its [pepsi-ingress-milter-<label>] section (see
the milter scan above for labels and order). Each option that the old
MTA set for its milters lands on every one of them:
Postfix |
Pepsi |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
a |
Sendmail’s INPUT_MAIL_FILTER and MAIL_FILTER define the filters, and
confINPUT_MAIL_FILTERS (which each INPUT_MAIL_FILTER extends) decides
which of them run and in which order; a filter that is defined but not listed
is reported and not carried over. S= is the SOCKET, carried verbatim;
F=T becomes ON_FAILURE = tempfail, F=R reject, and no flag
accept; T=C:…;S:…;R:…;E:… becomes CONNECT_TIMEOUT, the larger of the
S and R values COMMAND_TIMEOUT, and E CONTENT_TIMEOUT. The
confMILTER_MACROS_* defines become the MACROS_* options
(ENVFROM is MACROS_MAIL, ENVRCPT MACROS_RCPT).
A carried-over milter draws no report entry, since nothing about it changed.
These do, as APPROXIMATED: milter_default_action = quarantine, which
held the message in Postfix’s hold queue and becomes tempfail; a macro list
that extends the MTA’s built-in default, which is left at Pepsi’s default for
that phase; a relative socket path, which Postfix resolved inside its chroot;
and every non_smtpd_milters filter. Pepsi’s local submission socket is
served without a listener section, so there is nowhere to name a session milter
for it, and such a filter becomes a pepsi-stage-milter stage immediately
before DKIM signing. That stage runs after the message was accepted, so a
refusal becomes a bounce to the local sender.
95.1.43.1.6.2. Routing tables¶
/etc/aliases, /etc/postfix/virtual, Sendmail’s virtusertable,
qmail’s .qmail-* files and their equivalents are converted into a Pepsi
alias map (see pepsi-stage-aliases(1)) written next to the configuration as
aliases, and a submission-identity table (Postfix’s
smtpd_sender_login_maps and friends) into username.map (see
USERNAME_MAP in pepsi-ingress(1)). An existing file is never
overwritten: the converted table lands at aliases.imported instead, for the
operator to merge.
Pepsi alias keys carry a domain (local@domain, @domain or a *
glob), while /etc/aliases keys are bare local parts, so the wizard asks how
to qualify them (–alias-style for the import command):
per-domainOne line per alias and accepted domain — exact, and the default.
wildcardOne line per alias with a domain glob (
postmaster@*) — compact, but it also matches domains added later.primaryQualify with the first accepted domain only; the others are reported as not aliased.
Entries that Pepsi cannot express are written into the converted map as inert
# UNCONVERTED comments next to a report entry explaining why, so nothing
disappears without a trace. Such entries are a delivery to a command
(|/usr/bin/…), a delivery to a file, or an unreadable :include:. The
generated map is checked with the same strict syntax check that run applies
to a hand-written one.
95.1.43.1.6.3. Per-server coverage¶
- Postfix
/etc/postfix/main.cf(with$parameterinterpolation and continuation lines) andmaster.cf. Identity comes frommyhostname/mydomain, the accepted domains frommydestination,virtual_alias_domains,virtual_mailbox_domainsandrelay_domains; the smarthost fromrelayhostwith its transport fromsmtp_tls_security_level/smtp_tls_wrappermodeand its credentials fromsmtp_sasl_password_maps. Local delivery is read fromhome_mailbox,mailbox_transport/virtual_transport(anlmtp:unix:target becomes Pepsi’s LMTP stage) andmail_spool_directory; submission SASL fromsmtpd_sasl_type = dovecotandsmtpd_sasl_path; the enabled services inmaster.cfdecide the direction.alias_maps/alias_databaseandvirtual_alias_mapsbecome the alias map (virtual entries win, as they do in Postfix), andsmtpd_sender_login_mapsbecomesusername.map, inverted to Pepsi’s login-keyed form.message_size_limit,recipient_delimiter,maximal_queue_lifetime,smtp_helo_nameand thesmtpd_tls_*certificate paths arrive as expert options;mynetworksis reported, network by network, for aSENDER_MAPbinding (seeUNSUPPORTEDabove).Reported rather than migrated:
header_checks/body_checks,transport_maps, canonical rewriting,smtpd_*_restrictions,postscreen_*,content_filter, virtual-mailbox delivery, per-service-ooverrides inmaster.cf, and map types nothing can read as text (regexp:,pcre:,mysql:,ldap:, …). Roughly ninety parameters that describe Postfix’s own installation or tuning are ignored silently; everything else is listed as unrecognised.- Exim
Debian’s answer file
/etc/exim4/update-exim4.conf.confis the richest and most reliable source and takes precedence:dc_eximconfig_configtypegives the direction and whether there is a smarthost,dc_other_hostnamesthe domains,dc_smarthostthe relay,dc_relay_netsthe trusted networks (reported for aSENDER_MAPbinding, not carried over) anddc_localdeliverythe mailbox format. The main section ofexim4.conf.template/exim.conf/conf.d/main/*(everything before the firstbegin) addsprimary_hostname,qualify_domain,domainlist local_domains,hostlist relay_from_hosts,message_size_limit,smtp_accept_maxand thetls_certificatepair. Exim’s list syntax is handled properly: doubled separators,<;overrides,.include,+namedreferences, and.ifdefevaluated against the macros actually defined./etc/aliasesbecomes the alias map,/etc/email-addressesthe submission-identity map, and/etc/exim4/passwd.clientthe smarthost credentials.Exim’s routers, transports, ACLs, rewrite rules, authenticators and retry rules are a programming language, and a half-parse of one produces a plausible but wrong migration. They are therefore not interpreted at all: each
beginblock is reported once, naming what replaces it in Pepsi (the stage graph for routers and transports, listenerMYNETWORKS/SASL plus the whitelist and anti-spam stages for ACLs, SRS and the alias map for rewriting). Two consequences: because the retry ladder lives inbegin retry,MAX_LIFETIMEis never guessed, and because the transport holds the TLS and AUTH policy, the smarthost’s transport security is assumed rather than read. Atls_certificatecontaining a$expansion is a computation, not a path, and is reported instead of imported.- Sendmail
/etc/mail/sendmail.mc, the m4 source that an administrator actually edits, is preferred;sendmail.cfis used when no.mcexists, and then only its reliably-readable lines (Djthe canonical name,DSthe smart host,Cw/Fwthe local host names,DZthe version and theOoptions). The generated rulesets are never interpreted, and the report says so. From the.mc:SMART_HOST(with its mailer prefix, port and brackets),confDOMAIN_NAME,confMAX_MESSAGE_SIZE,confTO_QUEUERETURN,confMAX_DAEMON_CHILDREN,confSERVER_CERT/confSERVER_KEY,ALIAS_FILE,DAEMON_OPTIONS(which ports were served, hence the direction) and theFEATUREs that matter (use_cw_file,virtusertable,authinfo,local_lmtp,plussed_users,local_procmail,nullclient). The tableslocal-host-names,virtusertable,aliasesandauthinfo(the smarthost credentials, with the mechanism from itsM:field) are read;postmasteris resolved through the alias chain to a real address.Reported rather than migrated:
MASQUERADE_ASand friends (Pepsi rewrites senders with SRS instead),access_db,mailertable,domaintable,genericstable,LOCAL_RULE_*/LOCAL_CONFIG/HACK, DNSBL and greet-pause features,smrsh/procmail local mailers, andvirtusertableright-hand sides that Pepsi cannot express (error:,%1).- qmail
The control directory (
/var/qmail/control,/etc/qmailor/usr/local/etc/qmail) is enumerated, not probed by name, so every control file is either consumed, silently ignored as irrelevant, or reported, including ones from a fork that this importer has never heard of.megives the hostname;locals,rcpthosts,morercpthostsandvirtualdomainsthe domains; the:relay:portcatch-all insmtproutesthe smarthost (with credentials when the AUTH patches’ extended form is used);defaultdelivery(or theqmail-startargument inrc) the mailbox format;databytes,queuelifetime,helohostand aservercert.pemthe expert options.The alias table is the
.qmail-*files in qmail’s alias directory:.qmail-foo-barbecomesfoo-bar,:decodes back to.,.qmail-defaultbecomes a catch-all and.qmail-foo-defaulta glob. Their contents pass through as targets, so a|command, a file path or a relative./Maildir/is explained in the report rather than mangled into a nonsense address. Per-user~/.qmailfiles are deliberately not walked (expensive and privacy-sensitive;pepsi-stage-dot-forwardis the runtime equivalent), and no.cdbis ever opened; the textusers/assignis read instead.badmailfrom/badrcptto,spfbehavior,percenthack,qmqpserversandtlsclientsare reported with their Pepsi counterparts.- Stalwart
config.tomlunder/opt/stalwart-mail/etc,/opt/stalwart/etc,/etc/stalwartor/etc/stalwart-mail(a directory of.tomlfragments is read too, and!includedirectives are followed).server.hostnameand theserver.listener.*ports give the identity and direction,queue.outbound.next-hop/queue.strategy.routeand theremote.*table the smarthost (aprotocol = "lmtp"hop becomes local LMTP delivery instead),certificate.*the TLS paths,session.data.limits.sizeand the queue expiry the expert options. Amemory-typedirectory(or aprincipalsarray) yields accounts: each extra address becomes an alias to the account’s primary one, and the logins becomeusername.map. Secrets written as%{file:…}%are resolved;%{env:…}%cannot be and is reported.Stalwart’s own expressions (
[{if = …}, {else = …}]) are never evaluated: only a plain value is honoured, and anything else is reported rather than guessed at. The important case to know about: recent Stalwart versions keep the operational configuration in their data store, not in the TOML. When the file looks like a bootstrap stub, the report says so prominently, names the store, and tells you to export the configuration from Stalwart’s admin interface, because there is nothing on disk for Pepsi to read. IMAP, JMAP, POP3, ManageSieve, Sieve, spam-filter and reporting settings are reported as unsupported with a pointer to the Pepsi (or Dovecot) equivalent.
95.1.43.1.6.4. Credentials¶
Smarthost relay credentials are read from the source MTA’s own password file
(Postfix’s smtp_sasl_password_maps, Exim’s passwd.client, Sendmail’s
authinfo, Stalwart’s TOML) so the operator does not have to recover a
password they may no longer have. The report always names the file from which a
secret was read. Imported passwords follow the same path as typed ones: the wizard
moves them out of the world-readable configuration into secrets.d/*.secret
fragments referenced with @inline-secret@.
95.1.43.1.6.5. What is not migrated¶
Mail already queued in the old server is not migrated; let the queue drain, or flush it, before switching the MX over. DKIM keys are not migrated either; pepsi-dkim(1) makes fresh ones when run hands it the domains, and run prints the DNS records to publish. If the old MTA is still listening on port 25 when the wizard runs, the report says so: pepsi-ingress cannot bind the port until it is stopped and disabled.
95.1.43.1.7. Expert options¶
Between the questions the interview asks and the full option set of pepsi.conf(5) there is a tier of ordinary Pepsi options that nobody should have to answer to get a working server: the message size limit, the recipient delimiter, trusted networks, the queue lifetime, the DKIM selector.
–expert SPEC makes the wizard ask about them, in a final interview step. SPEC is a comma- or space-separated list of group words and/or option names:
highThe options an administrator plausibly tunes:
MAX_MESSAGE_SIZE,MYNETWORKS,RECIPIENT_DELIMITER,MAX_LIFETIME,DMARC_ENFORCE,IP_BLOCKLISTSandMAILBOX_QUOTA(deliberately in this group rather thaninsane: a site that delivers locally will want a default quota and should not have to know the option’s name).insaneEverything in the registry, adding
HELO_NAME,TLS_CERT,TLS_KEY,DNS_TIMEOUT,MAX_CONNECTIONS,MAX_OPEN_SOCKETS,DKIM_SELECTOR,KEY_DIR,MAILBOX_OVER_QUOTAandCRYPTO_ALLOW_DOWNGRADE.- An option name
Ask about exactly this one, whatever its group:
--expert=MAX_MESSAGE_SIZE,RECIPIENT_DELIMITER. Combines with a group word:--expert=high,DKIM_SELECTOR.
all is accepted as a synonym for insane, and none (or off)
clears a group word given earlier in the same SPEC. An unrecognised selector is
an error listing the valid names, not a silently empty selection.
--expert=help prints the list and exits.
Each option is emitted into the section that actually reads it and is recorded
in [pepsi-wizard], so a later re-run keeps it. MYNETWORKS goes onto the
port-25 listener (never a submission listener), MAX_MESSAGE_SIZE onto
[pepsi-ingress], and HELO_NAME onto the smarthost’s route
([pepsi-stage-relay-to-smarthost-mta-smarthost]). Leaving an answer
empty removes the option and restores Pepsi’s own default.
IP_BLOCKLISTS names the shipped IP blocklists that inbound mail is checked
against (spamhaus-drop-v4, spamhaus-drop-v6, blocklist-de-mail,
uceprotect-1; none for none) and writes ENABLED = yes or no into
each [pepsi-reputation-list-NAME] section; see pepsi-reputation(1). A
list fetched by rsync (uceprotect-1) is refused while the rsync program
is not installed. Unanswered, the shipped defaults in config.d apply.
Independently of the wizard, pepsi-setup run warns about any enabled rsync
list on a host without rsync and removes its entries, so that ingress stops
consulting a list that can no longer be refreshed.
RECIPIENT_DELIMITER is the one worth spelling out: it is written into the
global [pepsi] section rather than onto the local-delivery stages, because
pepsi-ingress (which has no stage section of its own) must read the same
value to decide whose mailbox quota a sub-addressed recipient belongs to, and
the stages’ own Locality parser falls back to [pepsi]. MAILBOX_QUOTA,
MAILBOX_OVER_QUOTA and CRYPTO_ALLOW_DOWNGRADE land there too.
–expert only controls which options are asked about. A value found by an MTA import is applied whether or not it was asked for: if Pepsi has the option, a migrated setting is never dropped for want of a question.
95.1.43.1.8. Commands¶
- import [MTA] [–root DIR] [–out DIR] [–alias-style STYLE]
Report what would be migrated from an existing MTA, writing nothing. With no MTA the installed one is detected (and, if several are, they are listed and one must be named). The output is the same migration report that –wizard writes, plus the alias map that would be generated and the wizard answers that the import would pre-fill; secrets are shown as a placeholder, never printed.
This command needs no Pepsi configuration: it is meant to be run before there is one, to see what a migration would produce.
- –root DIR
Read the MTA’s configuration from under DIR instead of
/. Useful for inspecting a backup or another machine’s/etccopied into place.- –out DIR
Write the report and the converted map files into DIR (an existing file is diverted to
<name>.importedrather than overwritten).- –alias-style STYLE
How bare alias names are qualified:
per-domain(default),wildcardorprimary; see Migrating from another MTA.
- run [-r | –reset]
Perform the full setup (validate, provision TLS certificates, install schema, have pepsi-dkim make the DKIM keys, print DNS records). This is also the default action when no subcommand is given. It also provisions the proof-of-origin secret whenever
[pepsi-origin]has neither aSECRETnor aSECRET_FILEand is not switched off withENABLED = no; proof of origin is on by default, so the section need not be present. A random secret is written to asecrets.d/pepsi-origin.secretfragment (owned by thepepsiaccount, mode0640) and referenced from the main configuration with an@inline-secret@directive, keeping it out of that world-readable file; a re-run reuses the existing fragment rather than rotating the key. It is skipped, with a warning, when[pepsi-ingress] HOSTNAMEis unset (the name is bound into thePepsi-OriginMAC) or when the path of the configuration file to update is unknown.On the same principle it generates the
[pepsi-crypto]key-encryption key when there is none, but only after the schema is installed, and only when the database confirms that no wrapped private key exists yet. A missing fragment beside stored keys is a lost key, not a new install, and minting a fresh one would silently make every stored private key unopenable. Both “keys exist” and “I could not check” therefore refuse loudly instead, and name restoring the fragment as the fix.Before anything else, run secures any secret fragments beside the configuration, that is, the
secrets.d/*.secretfiles into which the –wizard externalizes secrets (see below). It gives each the mode0640and hands it to the account that must read it:secrets.d/pepsi.secret(smarthost/LMTP passwords, the merchant access token) topepsi,secrets.d/pepsi-httpd.secret(theRESUME_AUTHORIZATION_TOKEN) topepsi-httpd,secrets.d/pepsi-ingress.secret(the SRSSECRET) topepsi-ingress,secrets.d/pepsi-crypto.secret(the[pepsi-crypto]KEY_WRAP_SECRET, current and retired) topepsi-crypto, andsecrets.d/pepsi-secure-link.secret(the[pepsi-secure-link] PEPPER) andsecrets.d/pepsi-list.secret(the[pepsi-list] UNSUBSCRIBE_SECRET,VERP_SECRETandAPI_PASS) topepsi-httpdwith grouppepsi(these two fragments have two readers, since the portal serves what the stage sealed and the web endpoint verifies the unsubscribe token that the delivery stage computed);secrets.d/pepsi-keydisc.secret(the LDAPLDAP_BIND_PASSWORD) topepsi-keydisc,secrets.d/pepsi-helper-token-refresh.secret(the OAuth client credentials) topepsi-helper-token-refresh, andsecrets.d/pepsi-dkim.secret(the[pepsi-dkim] TSIG_SECRET) topepsi-dkim. Every file named by[pepsi-srs] PREVIOUS_SECRET_FILE(a retired SRS key) is given the ownership and mode of the current one. The SRS secret is owned bypepsi-ingressbecause ingress reverse-decodes SRS return addresses; the SRS stage runs aspepsiand reads it through the sharedpepsi-ingressgroup (the Debian package makespepsia member; a source install must arrange the equivalent). The key-wrapping secret is the one whose loss cannot be recovered from: it opens every stored private key, so back it up separately from the database (see pepsi-keys(1)).This is the first step so that a run that stops later (at a certificate that cannot be issued, or at an unreachable database) still leaves every secret readable by its service. Each fragment is then verified to have really ended up owned by that account, and any that did not is listed among the deferred steps: an unreadable fragment is otherwise invisible, because the configuration loader only warns about an
@inline-secret@file it cannot open, and the service starts and fails later with a misleading “… is not configured”.Last, run brings
pepsi-telemetry-client.serviceinto line with[pepsi] SHARE_TELEMETRY:systemctl enable --nowwhen telemetry is on. When it is off, the unit is left as the operator left it, neither started nor stopped: a running daemon is dormant (no socket, nothing submitted), and keeping it running is what lets the browser console offer to switch telemetry on. Either way run then sends thetelemetry_changednotification, so a running daemon follows the answer at once; turning telemetry off takes effect immediately.pepsi.targetdoes not start that unit: nothing in the targetWantsit, because a unit that the target pulled in would run whatever the answer was. The unit is stillPartOf=the target, though, and so stops with the pipeline. It happens here, at the end, because theSYSTEM_IDis generated earlier in this same run; with telemetry on and no valid identifier the unit is armed anyway (the daemon stays dormant and says why) and the reason is logged. All of it is best-effort: a host with no systemd, no unit installed or no root is told the singlesystemctlcommand instead. See pepsi-telemetry-client(1).- -r, –reset
Drop all existing
pepsiobjects before re-creating them. DANGEROUS: all stored messages are irrecoverably lost. The DKIM keys, which pepsi-dkim(1) keeps in files, are not affected. Only a database built by a development version from a different copy of an unreleased patch ever needs this; an older release’s schema is upgraded in place (see schema).
- schema [–backup-dir DIR] [–backup-keep N] [–if-installed]
Install or upgrade the database schema and re-apply the role grants, and nothing else: no configuration validation beyond
[pepsi-postgres], no certificates, no keys, no DNS. It therefore works with any configuration file that names the database, such as/etc/pepsi/pepsi.confon a mail host or/etc/pepsi-telemetry/pepsi-telemetry.confon a telemetry collector, and it is what a package upgrade runs, before the services restart.The installer records the SHA-256 of every SQL file it applies, and the release it came from, in
pepsi.schema_file; every Pepsi program compares that record with the hashes compiled into it when it connects, and refuses to run (exit status 78) against a schema that is older, newer or built from different files. schema brings an older schema up to this release. It refuses, before changing anything and with exit status 78, a schema that is newer than this release (downgrades are not supported: older stored functions installed over a newer schema would break it), one built from a different copy of a patch file, and one with no record at all (built by a development version before the record existed; such a database has to be drained and re-created with run –reset). It also refuses SQL files inSQL_DIRthat are not the ones that this binary was built with, as in a stale directory after a partial upgrade. Concurrent installers serialise on an advisory lock.- –backup-dir DIR
Before an upgrade changes anything, save the schema with pg_dump(1) (custom format; the
pepsiand_vschemas and the extensions, which the archive’s trigram index needs) as DIR/pepsi-OLD-VERSION-UTC-TIME.dump, mode 0600, run as the schema owner. Taken only when there is something to upgrade. If the dump fails, nothing is upgraded. Restore one with pg_restore(1) into an empty database.- –backup-keep N
After a dump was taken, delete all but the newest N dumps in DIR (judged by the time in the name; files of any other name are left alone). Default
2: the dump just taken and the one before it, enough to undo the latest upgrade or the one before.0keeps every dump. A dump holds everything in the schema (queued mail, the plaintext of decrypted mail still in the queue, wrapped private keys), so dumps that nobody will restore are copies of mail outside the database’s own lifetime. A dump that cannot be removed is logged, and the upgrade goes ahead.- –if-installed
Do nothing when the database has no Pepsi schema yet. A new installation is set up with run; this is for maintainer scripts, which must not install a schema that nobody asked for.
- check
Query live DNS and report, for each authoritative domain, whether the records actually published match what run would generate. It checks the DKIM selector records (one well-formed key record of the right
k=type whosep=public key matches the key that pepsi-dkim(1) holds; see Prints DNS records under run), the SPF record (thev=spf1record lists every configuredPUBLIC_IP), the_dmarcTXT record (exactly one, and strictly valid; see Prints DNS records under run above), and the_mta-stsTXT record (present and a parseablev=STSv1record with anid=tag; theidvalue is chosen by the operator and is not compared, though its syntax is: RFC 8461 §3.1 allows 1 to 32 letters and digits). Each record is reported as[ok],[MISSING],[MISMATCH],[INVALID]or[lookup failed]; every non-[ok]line is followed by an indented→line saying what to do and, when the fix is a record whose value setup knows (DKIM, SPF,_mta-sts, a missing DMARC policy or one whoserua=lacks the report address, a TLSA or CAA record, a subdomain’sv=spf1 -all), by that record in zone-file form, ready to paste and identical to what run prints. A malformed DMARC policy gets no replacement, for the reason given below. The command makes no changes, and without –fail-on-findings its findings never set the exit status: it exits 0 however many records are missing or wrong, so read its output rather than its exit status. (Only a configuration that does not validate, or a resolver that cannot be built at all, makes it exit non-zero; it has nothing to report then.)–fail-on-findings makes it exit 1 when any record is
[MISSING],[MISMATCH],[INVALID]or[UNREACHABLE]or an address is[LISTED], after logging each such finding as a warning (targetsetup), so that it reaches the journal at warning priority. A[lookup failed]does not count, nor do the advisory verdicts ([todo],[none],[NO ACCOUNTURI],[UNVALIDATED],[UNALIGNED],[INCOMPLETE],[UNSCOPED]).pepsi-setup-check.timer, named bypepsi.target, runspepsi-setup -c /etc/pepsi/pepsi.conf check --fail-on-findingsdaily (pepsi-setup-check.service, as root on a read-only file system, since validation reads every service’s secrets); a finding fails the unit, whichsystemctl --failedthen lists.[INVALID]is the verdict for a record that is published but that receivers discard, so that the domain is unprotected while looking configured. Its remedy differs from the others’: the record is repaired in place rather than replaced with the value that run prints. Besides the DKIM findings described below, these checks produce it: a DMARC record that does not parse (or a second one at the same name), more than onev=spf1record (RFC 7208 §4.5 makes that a permanent error, so no SPF policy applies rather than the first one winning), av=spf1record with a term outside the RFC 7208 grammar (an unknown mechanism such asipv4:, a bad address or CIDR length, a malformed macro; the term is named), and more than onev=STSv1record or one whoseid=is outside the allowed syntax. Av=spf1record ending in+allis reported as a[MISMATCH]: it is valid, it passes the “are my addresses listed?” test, and it authorises every host on the Internet to send as the domain, defeating the DKIM and DMARC records published beside it.Every record is checked twice: in the system resolver’s answer, and at each of the zone’s authoritative nameservers asked directly (each address of a server twice before it counts as not answering, since one lost UDP datagram is ordinary). A record that the resolver returns correctly but some nameserver does not (a stale secondary, a lame or unreachable server) is a
[MISMATCH]naming the servers, with a remedy pointing at the zone’s distribution rather than at the record. A DKIM record with the wrong or missingk=, a misplacedv=, anh=/s=restriction excluding what Pepsi signs, or a second key record at the same name is[INVALID];t=yis a[MISMATCH]. When Ed25519 signing is on, a closingnote:explains why Google reports that selector asfail.The DKIM records checked are the ones pepsi-dkim(1) reports in its status file as needed in DNS, each labelled with where its key is in its life:
DKIM (RSA)/DKIM (Ed25519)for the current key,DKIM (RSA, next key)for a key made ahead of a rotation,DKIM (RSA, retiring key)for a replaced key whose signatures may still be in transit. Ap=that is a proper prefix of the daemon’s key, as when a DNS host kept only the first 255-byte string of a long record, is a[MISMATCH]that says the key is cut short and how to enter it as several strings. A record that the daemon reports as removable (a retired key) is an advisory[todo]line,DKIM (retired key), whose remedy is to remove it. A domain for which the daemon has not reported keys, because its status file is not written yet or because it does not sign for the domain, is[MISSING]at<DKIM_SELECTOR>._domainkeywith the remedy to startpepsi-dkim.serviceand run run.A record may also be
[ok]and carry a note: ap=noneDMARC policy is valid, is the right place to start, and enforces nothing, so the report says so rather than leaving a domain to sit in monitoring mode indefinitely.Beyond the TXT records, it runs the two MTA-STS cross-checks described under run for every domain for which an MTA-STS policy is served: the policy’s
mxset against the liveMXrecords, and a fetch ofhttps://mta-sts.<domain>/.well-known/mta-sts.txtcompared with the configured policy. It ends with a note giving theMTA_STS_MXline that would make them agree. For the[pepsi-srs] SRS_DOMAINit adds the deliverability check described under The SRS domain can receive its own bounces.Two groups follow the domains. DANE/TLSA lists every TLSA RRset that is published under a name for which run suggests one, compared with the served certificate as described under Prints DNS records:
[MISMATCH]when no usable record matches the key,[INVALID]when no record has a usage that SMTP applies (DANE-TA or DANE-EE). Names with nothing published are not listed, since publishing TLSA is optional. And within each domain, dangling targets are reported as[MISSING]: anMXrecord naming a host that has noA/AAAArecord (or does not exist); anNSrecord of the domain naming a name server with no address; aCNAMEatmta-sts.<domain>,openpgpkey.<domain>orautoconfig.<domain>pointing at a name with no address; an SPFinclude:orredirect=naming a domain that publishes no SPF record (or more than one); and an SPFa:<host>ormx:<host>naming another host that has no address (noMXrecord, respectively). All are what a migration or a cancelled hosting contract typically leaves behind. A dangling SPF reference makes the domain’s whole SPF policy a permanent error (RFC 7208), and in every case whoever can later create or register that name receives the domain’s mail, answers for its zone, serves its MTA-STS policy or OpenPGP keys, or decides who may send as it. An SPF record over the RFC 7208 lookup limits (see Prints DNS records) is reported as[INVALID]beside them. DANE/TLSA also lists, as[INVALID], a published TLSA RRset that the public resolvers do not mark DNSSEC-authentic, and an accepted domain whoseMXRRset they do not (labelsTLSA (DNSSEC)andMX (DNSSEC)). Those resolvers’ answers are told apart by response code and RFC 8914 Extended DNS Error: a SERVFAIL naming a DNSSEC failure (DNSSEC Bogus, Signature Expired, Signature Not Yet Valid, DNSKEY Missing, RRSIGs Missing, No Zone Key Bit Set, NSEC Missing) means that the chain of trust is broken: validating resolvers refuse the name, so senders behind one cannot resolve it and senders using DANE defer mail. Such a SERVFAIL is reported naming the error, for a TLSA RRset in this group and for an accepted domain’sMXRRset, whether or not DANE is published, under the domain itself; a TLSA RRset answered with a bare SERVFAIL is reported as “bogus or unreachable”. A lookup that merely fails is not reported; only a definite answer is. run logs the same findings as warnings.CAA has one line per accepted domain, and per certificate host that lies below none of them, giving the CAA record set that a CA would consult for it (RFC 8659: the name’s own, else the nearest ancestor’s) and what it means for the certificates run obtains:
[none]when no record restricts issuance (no CAA, or noissueproperty), so every CA issues to whoever passes a domain validation, a hijacked one included;[NO ACCOUNTURI]whenletsencrypt.orgis named without the RFC 8657accounturiof this host’s certbot account;[UNVALIDATED]when the set is right but the public resolvers do not mark it DNSSEC-authentic, so an attacker who answers the CA’s queries can hide it;[ok]otherwise. A set that lets no Let’s Encrypt account obtain a certificate over HTTP-01 (only other CAs, another account’saccounturi,validationmethodswithouthttp-01, an unknown critical property) is a[MISMATCH], since certbot’s next renewal fails; it is the only CAA finding that makes the report’s verdict fail. A domain whose certificates do not come from certbot here is judged on presence and validation only. The record itself is never published by run, which prints it as a commented-out suggestion (see Prints DNS records).DNSKEY judges the keys that sign the zones this host serves: the zone of each accepted domain, of
HOSTNAMEand of the SRS domain, found through theSOArecord (the name itself, or the nearest ancestor that carries one), itsDNSKEYRRset asked of the public resolvers (else this host’s). Revoked keys and keys without the zone flag are skipped. A signed zone validates whatever its keys are worth, and whoever holds or factors a key forges validly signedMXandTLSArecords for the zone, so each of these is a finding:[INVALID]for a key whose algorithm RFC 8624 §3.1 says MUST NOT be used for signing (RSAMD5 1, DSA 3, DSA-NSEC3-SHA1 6, ECC-GOST 12, and since RFC 9905 RSASHA1 5 and RSASHA1-NSEC3-SHA1 7) or calls NOT RECOMMENDED (RSASHA512 10), for an RSA modulus below 2048 bits, and for a key that also signs another of the zones checked (one key behind several zones is how a DNS host signs every customer’s zone alike);[LISTED]for a key in the list of known compromised keys (pepsi.compromised_key: the badkeys list thatpepsi-keys blocklist updatekeeps, and the moduli thatpepsi-keys peer screenfactored), looked up by the badkeys hash of the RSA modulus, the ECDSA x coordinate or the EdDSA key. A clean zone is[ok]listing its keys, an unsigned one[todo](signing is optional; the DNSSEC findings above say what DANE then loses). Each finding counts for--fail-on-findings. When the database cannot be read the list comparison is skipped and a note says so.subdomains lists, as
[MISSING] SPF (subdomain), each subdomain of a served domain that the configuration names, that exists (has an address orMXrecord) and that has no SPF record of its own. The configuration names theEHLOhost of a relay stage,[pepsi-ingress] HOSTNAME,mta-sts.<domain>andautoconfig.<domain>. A wildcard SPF record does not answer for a name that exists, so a forged sender at it gets SPFnone. The record that such a name needs isv=spf1 -all, or, for a name that Pepsi announces inEHLO, the served domains’ SPF record with the sending addresses (receivers check theEHLOname on every bounce). The group is advisory and does not make the report’s verdict fail.Two deliverability groups follow. blocklists has one line per address from which this host sends or receives mail (every
PUBLIC_IPof apepsi-stage-relay-to-internetstage, the addresses of[pepsi-ingress] HOSTNAME,[pepsi-reputation] CHECK_ADDRESSES) and per served domain:[LISTED]naming each DNS blocklist that lists it,[ok]when every list that answered says clean,[lookup failed]when none could be asked (see pepsi-reputation(1)checkfor how a list’s answer is checked before it is believed). mailbox providers turns the records above into the requirements Gmail, Yahoo and Microsoft publish for senders ([ok]or[INCOMPLETE]), and lists their sign-ups, which Pepsi points at but never performs: Gmail Postmaster Tools ([ok]once[pepsi-reputation] GOOGLE_SITE_VERIFICATIONhas a token for every served domain, whosegoogle-site-verification=TXT record run prints and check verifies asGoogle verification), Microsoft SNDS and JMRP for the sending addresses, and Yahoo Sender Hub for the DKIM domains, each[todo]with what to enter where. Only a listing makes the report’s overall verdict fail. run asks the blocklists too, and logs a warning for every listing.A DMARC reports group has one line per served domain, from the authenticated DMARC aggregate reports that pepsi-stage-dmarc-report(1) stored for the last
[pepsi-dmarc-reports] WINDOW_DAYS(7) days:[ok]when every source the receivers reported aligned (DKIM or SPF in alignment with theFrom:domain), sop=rejectrefuses none of them;[UNALIGNED]naming the sources that did not (address, message count, envelope domain, DKIMd=, reporters), whichp=rejectrefuses (a service sending as the domain needs aligned DKIM or SPF first; forwarded mail and forgeries are refused as intended);[todo]when no report arrived, with therua=to publish. A report whose mail passed neither SPF nor DMARC counts for nothing. The group is advisory and never fails the report; it is left out when no stage reads reports and none is stored. With a stage reading reports, a valid record whoserua=leaves the stage’s address out is[MISMATCH]on the_dmarcline, followed by that record with the address added.Within each domain, every
mailto:address that the valid_dmarcrecord names inrua=orruf=is checked where the reports would go (labelDMARC report destination). A destination domain outside the policy domain’s organisation must publish av=DMARC1TXT record at domain._report._dmarc.destination (RFC 7489 §7.1); without one receivers that check send it nothing, which is a[MISMATCH]. A destination, internal or external, with noMXand noA/AAAArecord (or a nullMX) is[INVALID]: a stale or mistyped address, whose reports (the domain’s mail flow, and forruf=whole messages) go to whoever registers the name. A lookup that fails is not a finding. Which processor receives the reports stays the operator’s choice; an address at the domain itself, read by pepsi-stage-dmarc-report(1), keeps them on this host.An HSTS group has one line per HTTPS name under which pepsi-httpd is reached, when an httpd listener is configured: every
[pepsi-httpd-cert-*]SNIhost, the listener’s own host, andopenpgpkey.domain,autoconfig.domain (with[pepsi-autoconfig]on) andmta-sts.domain (with MTA-STS published) for every accepted domain. Each is fetched ashttps://name/with the certificate verified and no redirect followed, and itsStrict-Transport-Securityheader judged as a browser would (only the first header counts):[ok]with a validmax-ageof at least six months (15768000 seconds),[MISMATCH]when the header is absent, shorter, or malformed (nomax-age, a directive twice). pepsi-httpd sends a year on its own TLS listeners, so a[MISMATCH]is usually a front server terminating TLS that does not pass the header on: it must add it. A name that does not answer is left out (reachability is the other checks’ business).includeSubDomainsandpreloadare not asked for; they bind every host of the domain. run logs the same findings as warnings.When any end-to-end identity is published, a published keys group has one line per address (label
Served keys): what a correspondent is given by both Web Key Directory methods (openpgpkey.domain and the domain itself) and by theOPENPGPKEYandSMIMEArecords, fetched with key discovery’s hardened clients and[pepsi-keydiscovery]settings and compared with the published, active rows of the key store.[MISMATCH]means that a channel serves a fingerprint that the store does not publish for that address, for example from another web server on the apex answering the direct method, from a DNS record left over from a rotation, or as a key that somebody else placed there; it makes the report’s overall verdict fail.[INCOMPLETE]means that a stored key is not served, or that neither WKD method serves anything;[lookup failed]means that a channel could not be asked. A DNS record that was never published is not a fault. The detail names every channel and fingerprint; see pepsi-keys(1)identity list --servedfor the same per identity. The check asks from this host, once: a server that answers other askers differently is not detected.When any S/MIME trust anchor is enabled, a trust anchors group has one line per enabled anchor (label
S/MIME anchor, named by itsca_id):[ok]when the operator limited it to named mail domains (pepsi-keys(1)ca scope) or its certificate carriesnameConstraintsof its own,[UNSCOPED]when nothing limits it, so that a signature from any address chaining to that CA readsvalid.unscopedis advisory (it is not a finding for--fail-on-findings) and is also logged as a warning.A last group, state of removed or reassigned accounts, is not about DNS. Pepsi keeps state keyed on an address or a login, and removes none of it when the passwd account goes: per-address overrides (
pepsi.settings), end-to-end identities that are not revoked (pepsi.crypto_identity), a user’s own<login>/...whitelists and a mailbox quota. For each address at a served domain (the[pepsi-ingress] ACCEPTED_DOMAINSand every stage’sLOCAL_DOMAINS, sub-address stripped at[pepsi] RECIPIENT_DELIMITER) and each login whose passwd lookup says there is no such account, one[WARNING]line names the login and the state kept for it. The state may be wanted (an alias or a list address has no account of its own, and a quota may be set before the account exists), so nothing is changed: delete what belonged to a removed account (pepsi-settings remove, pepsi-keys identity revoke, pepsi-whitelist remove, pepsi-quota remove) before the name is given out again. A passwd lookup that fails (an unreachable directory) is not read as “no such account”: those logins are only counted.Pepsi also records when each login was assigned (
pepsi.login_assignment, RFC 7293; see The login assignment record below), and a login that comes back under another uid, or after it was found gone, has a new owner. The database drops the previous owner’s settings, own whitelists, quota and auto-reply records as soon as that is noticed, but never key material: a further[WARNING]line names each key-store identity (not revoked), cached peer key and TOTP second factor for the login’s addresses that is older than the current owner, with the command that disposes of it (pepsi-keys identity revoke ID, pepsi-keys peer remove ID, pepsi-keys otp reset ADDRESS). Until then, an identity still decrypts mail for the address, which is now the new owner’s mail, and may let the new owner read the previous owner’s. The lines repeat on every run until the key is dealt with. The database is read as thepepsi-ownerrole. run logs the same findings as warnings.- questions
Print the setup interview to stdout as JSON: the ordered steps, and for each question its identifier, kind (
text,bool,choice,list,secret,path,port,domain,integer,address,url), prompt, help text, default, whether it is required, the configuration option it maps to when it maps to exactly one, and the condition under which it is asked at all.Both front-ends are described by this model: the terminal interview, and the browser one that pepsi-httpd serves at
/api/v1/setup/questions. It is also the schema that an –answers file is written against. It needs no configuration, since it is what you read before you have one.- apply [–once] [–idle SECS] | apply –clear
Perform the privileged setup work the browser interface has asked for. Run as root. See The applier’s trust model below before deploying this.
On a Debian system the systemd units that run this on demand are in the separate pepsi-httpd-admin package; removing it leaves this subcommand working from a root shell while making it unreachable from the web console. See Removing the capability: the pepsi-httpd-admin package below.
It reads intent rows from the
pepsi.setup_tasktable, each one a request from the administrative API for something in a closed set. It checks that each may be acted on, does it, and records the outcome and its progress lines back into the row. It performs no other work and accepts no other input: in particular it never reads a command, a path to execute or a file to write verbatim from a task.- –once
Drain whatever is pending and exit. What a cron entry or a manual run wants.
- –idle SECS
Without –once, wait on the
setup_taskNOTIFYchannel after draining and exit once SECS pass with nothing to do (default 300). This is what makes socket activation work: pepsi-httpd connects to the doorbell socket after enqueuing, systemd starts this unit, it drains the queue and goes away again. A root process sitting permanently on a queue of work supplied by a web tier is exactly the standing privilege the design avoids.- –clear
Delete every row of
pepsi.setup_taskwithout executing any of them, report how many were removed, and exit. Refused together with –once or –idle: this is an administrative reset, not a draining mode.A task is a durable request to a process running as root and nothing expires it, so a queue that has been sitting there is a hazard rather than a backlog. The applier’s units are a separate package precisely so that a deployment can run with nothing draining that queue, and rows can still reach the queue in that state, for instance from an operator with a root shell. If the missing package is installed months later, every one of them runs at the first doorbell ring, in the order in which it was asked for, against a deployment that has moved on. Consent does not last that long, so installing
pepsi-httpd-adminruns this from itspostinst.Every row goes, not only the
pendingones. Only apendingrow can ever execute and arunningrow is orphaned by definition, so deleting just those two would be enough for safety. But a “clear” that left a console full ofdoneandrefusedrows would not be one, and nothing is lost by removing them: each request, refusal, success and failure is an independent durable audit entry, which this does not touch. The task’ssetup_task_logprogress lines follow it by cascade.A database with no Pepsi schema in it has never held a task, so it is reported as an empty queue rather than as an error, and this is safe to run on a host that has not been set up yet.
Pass a
-cFILE for the draining modes: the applier writes that file and itssecrets.dfragments, and the path comes from its own command line and never from anything a task can influence. It is not strictly required: with no-cthe ordinary default search below applies, and the applier only fails when that finds nothing. But naming the file is the point: the default search consults$XDG_CONFIG_HOMEand$HOME, which is not what a root-run applier should be resolving. –clear executes nothing and so needs no such file.- bootstrap [–valid-for SECS] [–admin-url URL]
Mint the one-time credential that creates the first administrator account, and print it with the
curlcommand that uses it. –admin-url URL is the base URL of the administrative listener to which that command is addressed (defaulthttp://localhost:8080); it affects only the printed example.A fresh install has no account, so nothing can log in to the console that would create one. This prints a bearer token holding the full administrator scope set, valid for SECS (default 3600) and accepted exactly once — enough for a single
POST /api/v1/accounts. It is consumed on presentation by an update that only one racing request can win, so a token read by two people admits one of them.The scope list is not a choice:
POST /api/v1/accountsrefuses to issue a scope that the caller does not hold outright, so a token holdingsetup:writealone could not create an administrator; and since the token is consumed before the handler refuses, the attempt would spend it. The printedcurlasks for exactly the scopes with which the token was minted, rendered from the same list, so the two cannot drift.Single-use because of where it is printed: a token on a terminal is in a scrollback buffer and a token in the journal is readable by whoever can read the journal. Only its digest is stored, so it cannot be recovered; run the command again if you lose it. Running it again also revokes any outstanding bootstrap token.
A local administrator over the
ADMIN = yesUNIX-socket listener is identified bySO_PEERCREDand needs no credential at all, so an expired or lost bootstrap token is an inconvenience rather than a lockout.- validate
Check the configuration exactly as run does before it changes anything: every section it knows, the
[stage-*]pipeline and each stage’s start-up checks, and the files that the configuration names, such asSENDER_MAP. Warnings are logged; a refusal is logged and exits with status 1. Nothing is changed and nothing is asked of the network or the database, so it is safe after any edit and before a restart. The one exception is the milters: validate (and run) negotiates with every[pepsi-ingress-milter-*]filter as check does, and logs a warning for one that does not answer or asks for an action that itsALLOW_ACTIONSwithholds. It also warns about a milter section that no listener runs, and about a milter allowed to change headers or the body when no stage runs pepsi-stage-arc(1): Pepsi applies such an edit to a message that carries an ARC chain only after that stage has verified the chain. The database overlay (pepsi.config_override) is not consulted; run checks it too.- visualize
Print the configured
[stage-*]pipeline to stdout as a Graphvizdotgraph. Each stage is one node, labelled with its configuration section name (e.g.stage-init) and thePROGRAMit runs with thepepsi-stage-prefix stripped (e.g.arc). A solid edge follows each stage’sNEXT_STAGEand a dashed redbounceedge itsBOUNCE_STAGE. The command only reads the configuration (no DNS, schema or filesystem changes); pipe it throughdotto render, for example:pepsi-setup -c /etc/pepsi/pepsi.conf visualize | dot -Tpng -o pipeline.png
95.1.43.1.9. The login assignment record¶
Pepsi has no account lifecycle of its own, since logins come from passwd, but
RFC 7293 (Require-Recipient-Valid-Since) asks a receiver to know when each
address was assigned to its current owner. pepsi.login_assignment keeps
that per login: the uid, when the current assignment was first seen, and
whether it followed an earlier one. It is built from sightings:
local delivery records every login it delivers to, with the uid passwd gave it: pepsi-stage-relay-to-maildir before it writes, pepsi-stage-relay-to-lmtp for every recipient the MDA accepted that resolves to a passwd login (a virtual user of the MDA is not recorded);
run records every existing login that is named in kept state (settings, identities, whitelists, quotas), then looks every recorded login up again;
pepsi-queue gc (hourly,
pepsi-origin-gc.timer) repeats that last step.
A login seen for the first time is a first assignment, whenever that is: what happened before Pepsi was watching is unknown, and RFC 7293 counts an address with one owner since its creation as continuously owned. A login seen again under another uid, or seen again after a check found it gone (even under its old uid), has a new owner. The moment that is noticed, the record restarts and the database drops the per-address state the previous owner left:
pepsi.settingsrows of the login’s addresses (every served domain, sub-address stripped atRECIPIENT_DELIMITER);the login’s own
<login>/...whitelists and their outstanding confirm-to-send challenges;its
pepsi.mailbox_quotarow (a limit set per account belonged to the previous owner; the site default applies again);the vacation and payment-request reply logs of its addresses.
Key material (key-store identities, cached peer keys, a TOTP second factor) is
not dropped: deleting a private key cannot be undone, and under gateway
custody it may be the only thing that opens the previous owner’s archived mail.
It is reported by run and check until the operator disposes of it (see
state of removed or reassigned accounts above). Each reassignment is
written to the event log as an account.reassigned warning, naming both
uids and how many rows went. The login’s mailing-list state is suspended rather
than dropped: its list addresses lose their verification and their link to the
previous owner’s list account, its plain memberships stop receiving
(delivery_status unknown), and owner or moderator roles stay but are
counted in the event (list_roles_kept, with the lists in
list_roles_kept_lists) for the operator to review. Address state not tied
to a login (aliases) is outside the record.
A directory that suddenly knows nobody is not believed: when more than half of
the recorded logins look gone in one check, none is marked, so a broken
nsswitch.conf or an empty LDAP answer cannot wipe every user’s settings on
their return. A lookup that fails is never read as “gone”.
95.1.43.1.10. The applier’s trust model¶
pepsi-setup apply is the one component in Pepsi that runs as root on behalf of an HTTP request.
95.1.43.1.10.1. Why the console does not act¶
pepsi-httpd drops privileges before it accepts a single connection, and must
never be able to regain them: it parses attacker-supplied input for a living. It
therefore cannot write /etc/pepsi/pepsi.conf, hand a secrets.d fragment
to the account that reads it, run certbot, create a database role or generate key
material, and setup has to do all of these.
So it does not try. It writes a row saying what should be true, and the applier decides how. Root stays off the network entirely: it is reached through a database table, not through a socket that speaks a protocol.
95.1.43.1.10.2. The closed task list¶
There are seventeen task kinds and there will not be a general one. An arbitrary-command kind would be a root shell over HTTP wearing a task name.
write-configRender the configuration from an answer set (the same answers that the interview collects), validate it exactly as
pepsi-setup runwould, then write the file and its secret fragments and hand each fragment to its owning account. The answers are the intent; the file is the applier’s own rendering of them. Nothing a task supplies is written verbatim.write-secretStore one credential in the
secrets.dfragment that its reader owns, preserving every other secret in that fragment. It refuses any[section] OPTIONpair that is not already a credential that the secrets layer manages; otherwise it would write an arbitrary option into a root-owned file that every service reads.obtain-certificateObtain the TLS certificates that the configuration asks for. Named hosts narrow what is reported, not what is attempted: letting a task introduce a host would make certbot’s arguments task-supplied.
install-schemaInstall or migrate the schema. ``reset`` is refused: dropping the schema destroys every queued message and makes every wrapped private key unopenable, which is not something a web form may ask for. Use
pepsi-setup run --reseton a console.provision-rolesCreate the database login roles and re-apply their grants.
generate-keysHave pepsi-dkim(1) make the per-domain DKIM keys that it lacks (
pepsi-dkim sync-domains, always with the deployment’s whole domain set, since that command replaces the set). A task may narrow the domains it reports on, never widen them: a domain this deployment does not serve gets no signing key. It fails when the daemon reports no key for a requested domain.dkim-rotateStart a DKIM key rotation for one signing domain now (parameters
domainand an optional booleanhard): the applier runspepsi-dkim -c CONFIG rotate [--hard] DOMAINas root, since the daemon takes administrative requests from root and its own account only. The domain must be one that this deployment signs for. Withouthardthe daemon makes the next keys and switches to them once every authoritative server serves their records; with it, it switches at once, so mail is signed with keys that receivers may not find until their records are published. The result recordsdomain,hardand the command’soutput.run-preflightRun read-only environment probes and record the report. Which probes is an allow-list (
ports,dnssec,dns-records), so “run a preflight” cannot become “run this”.generate-identityGenerate a server-managed OpenPGP key (an MTA key) for one address (parameters
addressand an optional booleanvks, which defaults to[pepsi-keys] VKS_PUBLISHand requests a key-server upload). The address must be at a[pepsi-ingress] ACCEPTED_DOMAINSdomain and aKEY_WRAP_SECRETmust be configured. Always performed on request, even next to the user’s own key or a revoked key. The applier does the work as thepepsi-cryptorole (root becomes that account for the connection, as pepsi-keys(1) does), because only that role may write the private column.register-client-keyRegister the user’s own public key (an MUA key,
custody = client) for one address (parametersaddressandkey, an OpenPGP public key as text, at most 64 KiB). The address must be served, the key must be one OpenPGP certificate with a User ID that names the address, and a fingerprint that the address already has, retired or not, is not registered again. It goes through the applier although no private material is involved: a key registered as the user’s own becomes the address’s public face and verifies signatures as the user’s, so a compromised web tier must not be able to plant one.revoke-identityRevoke one local identity (parameters
address,identity_idand an optional one-linereasonof at most 1024 bytes, recorded as the revocation reason). The identity must belong toaddress. The retirement rule is pepsi-keys identity revoke’s: a signing-only key’s private half is destroyed, an encryption key’s is kept so mail already encrypted to it stays readable. An OpenPGP key whose private half is held gets its revocation certificate first, as with pepsi-keys identity revoke: the Web Key Directory serves it, and a key that had been uploaded to a key server has it queued for pepsi-keys identity publish –retry. The result recordsrevocation_certificate,wkd_serves_revocation,key_server_upload_dueand, inpublished, the same sentences theretiree-mail reply carries. Performed as thepepsi-cryptorole, because destroying a private half writes the private column (and signing the certificate reads it). Revoking an identity that is already revoked changes nothing and succeeds; the result says which happened.set-identity-flagsChange one local identity’s flags for its address’s owner (parameters
address,identity_idand at least one ofis_primary(trueonly),publishedandvks_wanted, booleans). The identity must belong toaddress; a key-server upload needs an active OpenPGP identity and publishes it too. These are the changes that an operator holdingkeys:writemakes directly through the administrative API; an owner underown:<address>asks for them as this task so that the owner’s second factor, which only the applier can check, backs them. The result lists the flags inchanged; setting a flag to the value it has succeeds. Audited askey.identity.update.reset-otpRemove one address’s second factor (parameter
address), which is also how a second factor locked by ten wrong codes is unlocked; its owner then enrols again. Performed as thepepsi-cryptorole, the only one grantedpepsi.otp_key. Removing one that does not exist succeeds and says so.confirm-enrolmentCheck an owner’s second-factor code for the console’s sign-in by e-mail (parameters
addressand an optionalotp) and change nothing else. pepsi-httpd(1) mints a browser session holdingown:<address>for whoever follows a link mailed to the address, but cannot readpepsi.otp_key; it queues this task under the address’s own scope and opens the session only when the task endsdone. An address without a second factor passes.confirm-loginCheck the second-factor code of an administrator signing in to the console with a password (parameters
loginandotp) and change nothing else. A console account with a TOTP second factor (pepsi-keys otp enroll --console LOGIN) keeps it inpepsi.otp_keyunder the subjectconsole <login>, which pepsi-httpd(1) cannot read; once the password has been verified it queues this task and opens the session only when the task endsdone. A missing, wrong, replayed or locked code fails it, and a wrong one counts towards the lock. It is the one kind admitted without any scope, since nobody holds one before signing in; it still must have been written bypepsi-configlike every other row, and the administrative API’s task endpoint refuses it.identity-csrBuild a PKCS#10 certificate request over one S/MIME identity’s existing key (parameters
address,identity_idand an optional one-linedisplay_nameof at most 128 bytes, the subjectCN). The identity must belong toaddress, be S/MIME and hold a private half. The subject alternative name is always the identity’s own address, never a parameter, so a task cannot ask a CA to certify another mailbox over this key. Performed as thepepsi-cryptorole because the request is signed with the private key, exactly as pepsi-keys identity csr does; the PEM request is the task’s result (csr_pem), where the requester reads it. Audited askey.identity.csr.identity-certificateInstall the certificate that a CA issued for one S/MIME identity (parameters
address,identity_idandcertificate, which is PEM or DER as base64, at most 64 KiB; a PEM bundle contributes its first certificate). Refused unless the certificate is over the identity’s own key (checked against the opened private key), namesaddressin itsrfc822Name, is an end-entity certificate allowingemailProtectionwith the key usage that the identity’s purpose needs, and has not expired. The applier then replaces the public half, the fingerprint and the expiry and re-wraps the private key under the new fingerprint (the wrap’s authenticated data binds the blob to it) in one guardedUPDATE; an identity that had expired on its old certificate becomes active again. Installing the certificate already in place changes nothing and says so. Performed as thepepsi-cryptorole because the re-wrap writes the private column. Audited askey.identity.certificate.
These eight act on one address rather than on the deployment, and are authorised differently (see The two gates).
The owner’s second factor. generate-identity, register-client-key,
revoke-identity, set-identity-flags, confirm-enrolment,
identity-csr and identity-certificate accept an optional otp
parameter (six digits). When a task is admitted on own:<address> alone,
that is, when the address’s owner asks rather than an operator holding
keys:write, the applier checks the code against the address’s second factor
(see pepsi-keys(1), otp) before doing anything: an address without
one needs no code, and a missing, wrong, replayed or locked code fails the task
with the reason. The attempt is recorded (a wrong code counts towards the lock)
and a code is used up even if the task then fails.
95.1.43.1.10.3. What is deliberately absent¶
There is no restart, reload or shutdown task, and there will not be one;
the same decision keeps service control out of the console. The cost is
real: a configuration change that needs a component restarted ends with the
operator restarting it. Where possible, components pick changes up by themselves
instead (the config_changed notification does this for the database
configuration overlay).
95.1.43.1.10.4. The two gates¶
A task is acted on only when both of these hold:
its recorded
scopescontainsetup:write, the authorisation that the administrative API established for the principal that asked. For the eight address kinds (generate-identity,register-client-key,revoke-identity,set-identity-flags,reset-otp,confirm-enrolment,identity-csrandidentity-certificate), the required scope is insteadkeys:writeorown:<address>for exactly the address named in the task’s parameters: a user managing their own key is not configuring the server, andsetup:writealone does not suffice.reset-otpis the operator’s alone and does not acceptown:<address>. The address is taken from the parsed parameters, never from the scope list, so a principal confined to one address cannot name another; andits
written_byis thepepsi-configdatabase role, which proves that the row reached the table through the one path that we control. That column is forced fromcurrent_userby aBEFORE INSERTtrigger, so it is a fact about the connection rather than a claim in the payload, and there is no spelling of theINSERTthat gets a forged value past it.
pepsi-setup run enforces the second half against PostgreSQL on every run:
only pepsi-config may INSERT into setup_task; pepsi-httpd may
only SELECT (it enqueues through the separate [pepsi-admin] CONFIG_DB
connection); and no account that processes mail may touch the table at all.
A stage worker parses hostile mail for a living and must not be able to put work
in front of a root process. That is verified, not asserted: a mismatch is a hard
error naming the role and the privilege.
95.1.43.1.10.5. What it cannot promise¶
The applier never saw the HTTP request, so it cannot re-authenticate the
principal. scopes is a claim recorded by the administrative surface; what the
applier verifies is that the claim was recorded by the only role permitted to
record it. A compromise of pepsi-httpd together with its configuration
database credential therefore reaches the closed task list above. That is the
residual risk, and it is why the list is closed and small rather than convenient.
95.1.43.1.10.6. Removing the capability: the pepsi-httpd-admin package¶
The applier is only ever started by systemd socket activation on the doorbell
that pepsi-httpd rings. Those two unit files,
pepsi-setup-apply.socket and pepsi-setup-apply.service, are therefore
the whole of the path from an HTTP request to a change under /etc/pepsi, and
Debian ships them in their own binary package, pepsi-httpd-admin.
pepsi Recommends it, so a default installation has it and the browser
console works as documented. An operator who administers this deployment from a
terminal removes it:
apt remove pepsi-httpd-admin
and pepsi stays installed. A source install has the same lever as
make install INSTALL_ADMIN_UNITS=no.
What that removes is the mechanism, not a button. With the units gone nothing
starts the applier, so a setup_task row is inert however it got there:
pepsi-httpd detects the missing doorbell and serves its configuration and
setup pages read-only, refusing the matching API mutations with
503 setup_applier_unavailable; see pepsi-httpd(1), The privileged
applier, and doing without it.
pepsi-setup itself stays in the pepsi package and is unaffected.
pepsi-setup run, pepsi-setup --wizard, pepsi-setup check and even
pepsi-setup apply --once still work: root running the program is root
acting, which is not what this restricts. What it removes is the web tier’s
ability to cause that to happen.
Note
Package removal deliberately does not revoke the database grant that lets
the pepsi-config role INSERT into pepsi.setup_task, for three
reasons: a maintainer script would need a reachable cluster and a superuser
credential that it does not have, so a hardening step could turn into a
removal failure; the grant is not the boundary that matters, because a row
that nothing drains is inert and the applier’s two gates apply regardless;
and a later reinstall would come back with the console broken in a way whose
error message points at the socket rather than at the grant.
A site that wants the belt as well as the braces can do it by hand, and
pepsi-setup run (which re-applies the grants) puts it back:
REVOKE INSERT ON pepsi.setup_task FROM "pepsi-config";
95.1.43.1.10.7. Auditability¶
Every task is a durable row: who asked, what was requested, when it started and
finished, what it produced, and what went wrong. Every admission, refusal,
success and failure is additionally written to the audit log
(setup.task.requested, setup.task.refused, setup.task.done,
setup.task.failed), which is append-only for every component that processes
mail. Progress lines are streamed into setup_task_log as the work proceeds,
so a certbot run or a schema install can be watched without the applier holding
an HTTP connection.
The applier’s writes are announced, so nobody watching a task has to ask the
database again and again. Two triggers in procedures.sql notify with the task
id as payload: setup_task_progress for every setup_task_log line, and
setup_task_done when a task becomes done, failed or refused,
whichever writer makes that transition: the applier settling a task, or the
applier reaping one that an earlier applier left running. The applier
itself issues no pg_notify; pepsi-httpd(1) listens on both channels
and wakes the requests waiting on that task (GET
/api/v1/setup/tasks/{id}?wait= and the console’s task page). The
setup_task channel that wakes the applier is a different one and is not
fired by either.
95.1.43.1.11. Global Options¶
These global options precede the subcommand (a trailing flag is rejected).
- -c FILE, –config FILE
Read the configuration from FILE instead of searching the default locations (see FILES). pepsi-setup also rewrites this file in place when it auto-fills TLS certificate paths, the reverse-proxy socket, the proof-of-origin secret, the key-encryption-key reference, the telemetry system id and the probed
[pepsi] MAILBOX_FS_QUOTA. When -c is omitted, it resolves the same default location from which the configuration was loaded, normally/etc/pepsi/pepsi.conf, and rewrites that file, so a barepepsi-setup runbehaves likepepsi-setup -c /etc/pepsi/pepsi.conf run. It only reports the path as unknown when no configuration file exists at any default location.- –no-certbot
Do not invoke
certbotto obtain missing TLS certificates. The certbot path layout is still filled into the configuration when needed; a certificate that is then absent is deferred, not fatal: the host is listed in the end-of-run summary with an actionable message, and the rest of the run (schema, keys, DNS) proceeds. Use this when certificates are managed by other means, and note that a successful exit therefore does not assert that every configured certificate is present.- –no-reverse-proxy
Do not auto-integrate with an existing front HTTP server. pepsi-httpd then binds port 443 directly instead of being switched to a UNIX socket behind a reverse proxy (see step 3 of the Description). Use this when no other web server occupies 80/443, or when you wire the reverse proxy by hand.
- -y, –yes-to-all
Assume “yes” to every interactive prompt setup may raise (currently the offer to install the Dovecot drop-in, step 4), so a run never blocks waiting on input, which is useful in scripts and non-interactive deployments. Mutually exclusive with -n.
- -n, –no-to-all
Assume “no” to every interactive prompt: setup takes no offered action and instead prints what it would have done (e.g. the Dovecot drop-in to deploy by hand), then defers it. Also makes the run fully non-interactive.
- –wizard
Run the interactive configuration wizard (see Wizard). The configuration is written to the -c path, or to
/etc/pepsi/pepsi.confwhen no -c is given. Unlike the other modes, this does not require an existing configuration file. It takes no subcommand (pepsi-setup --wizard runis refused): at the end it offers to run the full setup itself. The options below that say “with –wizard” are refused without it, except--expert=help.- –force
With –wizard, overwrite an existing configuration file that has no importable
[pepsi-wizard]answers without prompting for confirmation.- –expert SPEC
With –wizard, also ask about the deeper Pepsi options the interview normally decides for you. SPEC is a group (
high,insane), a comma-separated list of option names, or both;--expert=helplists them and exits. See Expert options.- –answers FILE
With –wizard, answer every question from the JSON object in FILE instead of asking: the keys are the question identifiers that pepsi-setup questions prints (plus the expert option names), and a question the file does not answer takes the wizard’s default, as pressing Enter would. An unknown key or an answer of the wrong shape is an error. Nothing is read from stdin, and every other prompt takes its default too, in particular the closing “Run setup now” offer, so run pepsi-setup run afterwards. See Answering without a terminal.
- –import MTA
With –wizard, import defaults from this existing MTA (
postfix,exim,sendmail,qmail,stalwart) instead of offering a menu of what was detected. Unlike auto-detection this also applies when a configuration file already exists, and it works on a non-interactive stdin. See Migrating from another MTA.- –no-import
With –wizard, do not look for an existing MTA configuration at all.
- –import-root DIR
With –wizard, read the MTA to import from under DIR instead of
/, such as a backup or another machine’s configuration copied into place. This is the same option that the import sub-command spells –root.- -L LOGLEVEL, –log LOGLEVEL
Set the logging verbosity. LOGLEVEL is one of
error,warn,info,debugortrace(default:info). Unlike the other Pepsi programs, pepsi-setup does not honour[pepsi] LOGorLOG_JSON: logging is set up before the configuration is loaded (and the wizard runs before there is one), so pass -L explicitly.- -v, –verbose
Show log messages from all sources, including third-party libraries.
- -h, –help
Print a usage summary and exit.
- -V, –version
Print the version and exit.
95.1.43.1.12. Exit Status¶
- 0
Successful completion.
- 1
An error occurred: a malformed configuration file, an invalid domain name or
PUBLIC_IPentry, a configuration file that could not be written, a failed database connection, or a key that could not be written. The reason is written to the log.A TLS certificate that is missing and could not be obtained is not in this list: it is deferred and reported in the end-of-run summary (step 4), and the run still succeeds.
- 2
The command line itself was wrong (an unknown option, a global option written after the subcommand, a
--wizard-only option without –wizard).- 78
The database schema cannot be used by this release: schema (and run) refuse a schema newer than this program, one built from a different copy of a patch file, one with no installation record, and an
SQL_DIRwhose files are not the ones this binary was built with (see schema).
95.1.43.1.13. Files¶
When –config is not given, the first existing file from the following list is used:
$XDG_CONFIG_HOME/pepsi.conf$HOME/.config/pepsi.conf/etc/pepsi/pepsi.conf/etc/pepsi.conf
Note the last two: every Pepsi program prefers the canonical
/etc/pepsi/pepsi.conf over the bare /etc/pepsi.conf, because the
packaging, the systemd units and @inline-secret@ all name the subdirectory,
and a stale copy directly in /etc must not shadow the file that the running
services read. When more than one of these exists, pepsi-setup logs which
file it is using and which ones are being ignored.
pepsi-setup keeps no signing key. The DKIM and ARC keys are
pepsi-dkim(1)’s, under [pepsi-dkim] STATE_DIR (default
/var/lib/pepsi-dkim); check, run and the console read their public
status from PUBLIC_DIR/status.json (default
/var/lib/pepsi-dkim-public/status.json). [pepsi] KEY_DIR (default
/var/pepsi/keys) is where release 0.0.0 kept its DKIM key files, which
run deletes.
Beside the configuration file, –wizard writes aliases (the alias map,
converted from the previous MTA’s routing tables when one was imported),
username.map (the submission-identity map), secrets.d/*.secret (the
externalized secrets) and, after a migration, import-report.txt. A file that
already exists is never overwritten by an import: the converted content is
written to <name>.imported instead.
95.1.43.1.14. Examples¶
Bootstrap a fresh deployment and capture the DNS records to publish:
pepsi-setup -c /etc/pepsi/pepsi.conf run > pepsi-dns.zone
Re-run after an upgrade that ships new migrations (keys and DNS are unchanged unless a new domain was added):
pepsi-setup -c /etc/pepsi/pepsi.conf run
Validate the configuration and reset the database from scratch:
pepsi-setup -c /etc/pepsi/pepsi.conf run --reset
After publishing (or changing) DNS, verify what is actually live against what Pepsi expects:
pepsi-setup -c /etc/pepsi/pepsi.conf check
Render the stage pipeline to a PNG to review how messages are routed:
pepsi-setup -c /etc/pepsi/pepsi.conf visualize | dot -Tpng -o pipeline.png
Before migrating, see what would be taken from the mail server this host runs today (nothing is written):
pepsi-setup import
Migrate from Postfix, answering the deeper questions too:
pepsi-setup --wizard --import postfix --expert=high
Inspect what a migration would produce from another machine’s /etc, saved
under /mnt/oldhost:
pepsi-setup import postfix --root /mnt/oldhost --out /tmp/migration
95.1.43.1.15. See Also¶
pepsi-config(1), pepsi.conf(5), pepsi-ingress(1), pepsi-stage-relay-to-smarthost(1), pepsi-keys(1), pepsi-keydisc(1)
95.1.43.1.16. Bugs¶
Report bugs to the Pepsi issue tracker.