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:

  1. 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 every NEXT_STAGE/BOUNCE_STAGE resolves, that each stage’s program configuration (including upstream-MTA routing) parses, that every domain name is well-formed and that each PUBLIC_IP entry is a valid IP address. It warns when a relay stage’s PUBLIC_IP is a non-public address (loopback, RFC 1918 / unique-local, link-local or CGNAT), and when a relay stage sets no PUBLIC_IP at all (the record then degrades to a bare v=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 every MYNETWORKS entry of an ingress listener that covers more than one host (wider than /32 or /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 .invalid placeholder identity shipped in the sample configuration: if any of HOSTNAME, ACCEPTED_DOMAINS, [pepsi] ARC_DOMAIN or a stage SERVER_NAME still 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 run pepsi-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_BITS is 2048, 3072 or 4096; ROTATION_LEAD_DAYS is shorter than a non-zero ROTATION_DAYS; RETIRE_AFTER_DAYS is at least 1 and exceeds the SIGNATURE_EXPIRATION_DAYS of 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_ADDRESS is an address; and DNS_UPDATE = rfc2136 comes with a TSIG_KEY_NAME, a base64 TSIG_SECRET and a TSIG_ALGORITHM of hmac-sha256, hmac-sha384 or hmac-sha512. It warns when PUBLISH_RETIRED_KEYS is 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 without ROTATION_DAYS (keys then retire only on a manual pepsi-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 the MAILBOX_FS_QUOTA probe.) 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 a pepsi-stage-detect-language stage 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; install pepsi-stage-detect-language before starting the service, or the detect-language stage will fail to spawn. Two further non-fatal warnings flag likely misconfigurations: a pepsi-stage-block-language stage with a BLACKLIST but an empty WHITELIST and a non-negative THRESHOLD (which bounces all neutral-language mail; see pepsi-stage-block-language(1)), and a non-progressing NEXT_STAGE cycle (a chain of NEXT_STAGE edges that loops back on itself, so a message would circle until MAX_LIFETIME; legitimate re-entry through BOUNCE_STAGE/RESTART_STAGE is not flagged). It also warns when a TARGETS entry admits a uid below /etc/login.defs UID_MIN on 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) in WALLET_MODE = local-user. It warns when [pepsi-ingress] ACCEPTED_DOMAINS is set but DMARC_ENFORCE is not: the compiled-in default is no, so such a configuration delivers mail that fails DMARC; an explicit no is 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 without BOUNCE_TARGET_STAGE, which forwards a null-sender message without a valid Pepsi-Origin proof (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_DOMAIN that is DMARC-aligned with a served domain is an error: an ACCEPTED_DOMAINS entry 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 = yes turns the error into a warning for a host that cannot have a dedicated domain. The warning names what closes the route: aspf=s in the served domain’s DMARC record when the SRS domain is a subdomain of it, or p=quarantine/ p=reject there 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 as SRS alignment: [ok] when aspf=s is published and the two names differ, or the policy enforces and DMARC_ENFORCE is on, [MISMATCH] with the remedy otherwise. It warns about every [pepsi-srs] PREVIOUS_SECRET_FILE last changed more than MAX_AGE_DAYS ago: 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 ~/.forward sent 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 = yes with an elliptic-curve CRYPTO_SMIME_ALGORITHM, the default p256 included (several S/MIME clients reject one EC key doing both ECDSA and ECDH), a CRYPTO_GENERATE_RSA_BITS other than 2048, 3072, 4096 or 8192 (the sizes generated in constant time) or below CRYPTO_MIN_RSA_BITS (the deployment would generate keys that it then refuses), an implausibly small CRYPTO_MIN_RSA_BITS, a non-positive IDENTITY_VALIDITY_DAYS, and a KEY_WRAP_KEY_ID that could not name its own KEY_WRAP_SECRET_<ID> option. A [pepsi-crypto] section that says anything at all but has no KEY_WRAP_SECRET is 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_BITS below 2048, CRYPTO_ALLOW_WEAK_DIGESTS = yes (SHA-1 signatures, whose collisions let a signature or a CMS digest algorithm be substituted) and CRYPTO_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 when ENABLE_PEP is on but [pepsi-crypto] AUTO_CREATE_IDENTITY = no (a valid site veto, but then no sender gets a key automatically; say ENABLE_PEP = no to make it explicit) or no KEY_WRAP_SECRET is configured (no sender can be given a key); when RESPONSE_STAGE is unset (users are not told when a new key is registered for their address, and the e-mail key commands to pepsi-keys@<domain> are off); and when [pepsi-ingress] USERNAME_MAP grants a wildcard, naming those accounts: they may send as any matching address but can never register their own key for one. It refuses a RESPONSE_STAGE naming no stage, and, when RESPONSE_STAGE is set, a TEMPLATE_DIR lacking the key-registered.en.body or keys.en.body fallback 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-written pepsi.conf therefore leaves a deployment where secrets.d/pepsi-crypto.secret is 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 as root does 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-default KEY_WRAP_KEY_ID that went with the lost file, so the warning names the id it asserted; set it by hand if the key was stored under another.

  2. Prepares the operator-edited map files. On every run it walks the configured lookup tables: the [pepsi-ingress] USERNAME_MAP and each pepsi-stage-aliases stage’s ALIASES map. A file that does not exist is created from a commented starter template (mode 0644) 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 --wizard mode this runs only after pepsi.conf has been written, so a map problem never prevents the wizard from writing the configuration.

  3. 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 --standalone cannot bind 80. Rather than fight for the ports, pepsi-setup detects the front server (via ss), confirms that it does not already serve any of the mta-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-bind MODE = tls + TLS_CERT/TLS_KEY and the now-unneeded [pepsi-httpd-cert-*] sections. It also drops a pepsi-httpd.socket override (/etc/systemd/system/pepsi-httpd.socket.d/10-reverse-proxy.conf) that rebinds ListenStream from 443 to a UNIX socket at /run/pepsi/httpd.sock (SocketGroup= the front server’s group: www-data on Debian, nginx/apache/httpd elsewhere).

    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 = 660 and UNIXPATH_GROUP the front server’s group, again with MODE = 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 the pepsi-httpd.socket override, or on a host without systemd turns the listener back into SERVE = tcp on port 443. It then sets MODE = tls again and adds a [pepsi-httpd-cert-mta-sts-<domain>] section for each mta-sts.<domain> name that no SNI names, 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’s sites-available and enables it in sites-enabled (conf.d for non-Debian nginx). The site terminates TLS for those host names, sends Strict-Transport-Security: max-age=31536000 on 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 the pepsi-mta-sts site exists, a re-run regenerates it and reloads the front server only when its text changes: an mta-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 as Strict-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 the mta-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-run pepsi-setup run once the cause is resolved. The socket directory /run/pepsi comes from the package’s systemd-tmpfiles entry (no unit may declare RuntimeDirectory=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.conf granting the front server’s user access to it beside the socket drop-in; that user must be able to reach the group-shared socket.

  4. Provisions TLS certificates. For every listener that terminates TLS and has no TLS_CERT/TLS_KEY set, it fills the options in with the standard certbot layout (/etc/letsencrypt/live/<lineage>/fullchain.pem and privkey.pem), writing them into the configuration file in place (comments are preserved). These listeners are the [pepsi-ingress-listener-*] sockets with MODE = 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 the TLSA record pins;

    • the web lineage <HOSTNAME>-web, used by the TLS [pepsi-httpd-listener-*] sockets (and by a [pepsi-httpd-cert-*] section whose first SNI host is HOSTNAME);

    • one lineage per other [pepsi-httpd-cert-*] section, named after its first SNI host (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 TLSA record, 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_KEY with 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 its TLSA record are not touched. A certificate that the operator configured outside the certbot layout is never moved.

    The HTTPS listener’s (web) certificate covers HOSTNAME and openpgpkey.<domain> for every domain in ACCEPTED_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 covers autoconfig.<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_MX set 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 the MX record 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 as mx.example.org and mail.example.net therefore cannot answer with two certificates; it needs one certificate carrying both names. Wildcard mx entries (*.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 -d separately 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_KEY against the layout paths that it would itself have written for that host. The test cannot be “is TLS_CERT set?”, 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-run pepsi-setup run once the obstacle is cleared. Re-running is idempotent and only completes what is still missing. A certificate is deferred when --no-certbot was given, certbot is not installed, pepsi-setup is not running as root (so it cannot bind TCP/80), the host’s DNS does not resolve to a configured PUBLIC_IP (so the challenge would fail), or certbot itself 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 configured PUBLIC_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 --config was 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.conf naming every certificate and key that the server reads as a LoadCredential= 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-run pepsi-setup run after adding, moving or removing a certificate. When the drop-in changes, pepsi-setup reloads systemd and try-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.sh that re-applies the grant on every future issuance/renewal and restarts the Pepsi servers. A one-time grant would not survive, because certbot rotates archive/<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 (the acl package), and an ACL-capable filesystem, and a missing prerequisite is deferred with the fix, not fatal. Certificates outside certbot’s tree (operator-set TLS_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 pepsi for LMTP, pepsi-ingress for SASL. This catches the common case of a socket that exists but is unreachable: Dovecot’s shared /run/dovecot/auth-client is 0600 dovecot and cannot be opened by pepsi-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 dedicated unix_listener owned by the Pepsi service user (mode = 0600, so the shared socket’s permissions are left untouched). It then validates the merged configuration with doveconf and reloads Dovecot. When it cannot (not root, no terminal to ask at, doveconf rejecting the result, or no local Dovecot), it prints the drop-in and defers so you can deploy it by hand. Pepsi’s default SASL_PATH is this private socket, /run/dovecot/auth-client-pepsi. This check runs on every pepsi-setup run, not only under --wizard. -y/--yes-to-all installs the drop-in without prompting; -n/ --no-to-all skips the install and just prints it; either makes the run fully non-interactive.

  5. 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 is pepsi-ingress.socket that fails (systemctl status pepsi-ingress.socket reports Result: resources), mail keeps being delivered by the other server using its alias and virtual maps, and every change to pepsi.conf therefore 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 neither systemd nor Pepsi itself. These ports are the configured PORT for a SERVE = tcp listener, and the shipped socket unit’s FD_INDEX mapping (0 → 25, 1 → 465, 2 → 587) for a SERVE = systemd one. 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 starting pepsi-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 the AD bit. It does so only when the configuration asks for DANE: a relay stage whose DANE is not off (strict is the default for both relay stages, and for each smarthost [pepsi-stage-relay-to-smarthost-mta-*] section), or dane in [pepsi-keydiscovery] SOURCES. Pepsi trusts a validating resolver rather than validating DNSSEC itself, so a resolver that never sets AD makes 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. The AD bit 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, OPENPGPKEY or SMIMEA record 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 with DNSSEC=yes) at 127.0.0.1/::1, for which the notice stays silent. check prints the same notice.

  6. Installs the database schema. Every Pepsi component shares one database (the [pepsi-postgres] section) and the one pepsi schema; pepsi-setup is the sole installer. The schema is a single patch series (pepsi-NNNN.sql) with one procedures.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 pepsi schema. The pipeline role pepsi (and pepsi-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-ingress

    INSERT into pepsi.workqueue and pepsi.workqueue_body (plus SELECT of the ids that workqueue_add returns and of the two generated size columns, header_octets and octets, that the queue admission check sums), SELECT on config_override, mailbox_quota, login_assignment (the RFC 7293 test at RCPT), the downloaded IP blocklists (ip_blocklist, ip_blocklist_source) and crl_cache (TLS client-certificate revocation), SELECT of the list_name and mail_host columns of mailing_list (the recipient check), INSERT on the two append-only logs. It cannot read any message already queued.

    pepsi-telemetry

    Its own pepsi.telemetry table.

    pepsi-httpd

    Everything that the console, the portal, the list site and the archive use, within these limits. On pepsi.workqueue it gets only the envelope, state and routing columns, never headers or the body, and it cannot repoint a message’s body_id. On pepsi.workqueue_body it gets only INSERT (the web forms send mail) and DELETE (deleting a message drops the body that only it carried; the foreign key refuses to delete a body that another message still references), never SELECT of the body. It gets nothing at all on settings, 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_check or signed_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_token and the end-user console’s own_enrolment and own_session) belong to pepsi-httpd alone, and the audit and mail logs are append-only for every role that processes mail; pepsi-httpd may 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-ingress and pepsi-telemetry as 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-whitelist

    Granted SELECT, INSERT and DELETE on pepsi.whitelist and 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-keydisc

    The 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/DELETE on pepsi.peer_key (filling that cache is its whole job, and the conflict rule has to be able to replace a row), SELECT/INSERT/UPDATE on pepsi.key_request, EXECUTE on the keydisc_* functions and the two crypto_* helpers they call, SELECT/INSERT/UPDATE/ DELETE on pepsi.crl_cache (the revocation lists it fetches; it is the only role that writes them, while pepsi and pepsi-crypto may only read them and no other role sees them), the same on pepsi.ca_issuer_cache (the intermediate certificates it fetches), SELECT on the list of known compromised keys (pepsi.compromised_key and compromised_key_import, so it refuses to store a listed key), and, on pepsi.workqueue, SELECT plus a column-level UPDATE (status, timeout).

    Those two columns are the interesting part. They are exactly enough to move a message parked on an address from paused back to pending, which is what keydisc_resolve and keydisc_sweep do (plain SECURITY INVOKER functions, 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 to pepsi.crypto_identity at all.

    pepsi-crypto

    The account that custodies end-to-end private key material. It receives the ordinary pipeline grants across the schema plus the pepsi.crypto_identity.private_wrapped column, 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: what pepsi-keys blocklist update and peer screen record); pepsi and pepsi-keydisc may 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/ UPDATE on pepsi.crypto_identity from every ordinary service role and grants SELECT back column by column for every column except private_wrapped. The ordinary service roles are pepsi (the dispatcher and every stage worker), pepsi-ingress, pepsi-httpd and pepsi-telemetry. INSERT is not granted back, and UPDATE only on the columns that the role’s code writes: the is_primary, published and vks_wanted flags (pepsi and pepsi-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. (DELETE has 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 from information_schema rather 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.d fragment (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).

  7. 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’s SERVER_NAME / POSTMASTER, an explicit SIGNING_DOMAIN, the [pepsi-srs] SRS_DOMAIN of an SRS stage, a self-service stage’s fixed RESPONSE_FROM, and the [pepsi] ARC_DOMAIN if 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_BITS and an Ed25519 key, as DKIM_ALGORITHMS and ARC_ALGORITHM ask), 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 a note: of pepsi-setup check, with pepsi-dkim rotate as 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.key and <domain>/dkim.ed25519.key) are deleted, with each per-domain directory left empty, since nothing signs with them; their records (<DKIM_SELECTOR>._domainkey and <DKIM_SELECTOR>-ed25519._domainkey) are logged and printed as removable.

  8. 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, current and retiring keys, at <DKIM_SELECTOR>-YYYYMM._domainkey for RSA and <DKIM_SELECTOR>-YYYYMM-ed25519._domainkey for Ed25519, an RSA value split into quoted strings of at most 255 bytes), an SPF policy (v=spf1 …) built from the PUBLIC_IP addresses of every relay stage (unioned; see below), a DMARC policy (_dmarc.<domain> TXT; see below), and an MTA-STS record (_mta-sts.<domain> TXT, unless MTA_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) at https://mta-sts.<domain>/.well-known/mta-sts.txt (its mx set comes from [pepsi] MTA_STS_MX, falling back to the [pepsi-ingress] HOSTNAME), so pepsi-setup prints only the _mta-sts TXT record and a reminder to point mta-sts.<domain> at the server. The record’s id is derived from that domain’s own policy, so two domains with different mx sets 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.txt for 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 relay SERVER_NAME, an explicit SIGNING_DOMAIN, the [pepsi-srs] SRS_DOMAIN) but still has a published _mta-sts TXT 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] RUA is 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’s SubjectPublicKeyInfo. This is the 3 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 sets reuse_key = True in 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. Besides HOSTNAME, 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 the MX RRset 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 missing DS at the parent turns the pin into decoration. A resolver that answers SERVFAIL (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 its accounturi (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 an issue record for each other CA that the domain uses before publishing it, and drop accounturi if 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 in MAIL FROM, so without it a forged sender at an invented subdomain gets SPF none from 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, an OPENPGPKEY (RFC 7929) or SMIMEA (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; use pepsi-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: under NSEC every published address can be listed and under NSEC3 the 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’s autoconfig.<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 tries https://autoconfig.<domain>/mail/config-v1.1.xml first, 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 its PROGRAM (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 own PUBLIC_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 sets PUBLIC_IP, the record is a bare v=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=spf1 records. 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 leftover v=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 mechanisms all, include, a, mx, ptr, ip4, ip6 and exists with their qualifiers, address syntax and CIDR lengths (/0–/32, /0–/128), the redirect= and exp= modifiers (each at most once), unknown name=value modifiers, 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. ptr is 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: and redirect= (a redirect= only when the record has no all), it adds up the terms that make a DNS query (include, a, mx, ptr, exists, redirect) and the void lookups among them (an a, mx or include target 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=s is suggested: every message Pepsi sends for a served domain carries a DKIM signature whose d= is exactly the From: 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, and p=none (monitoring only) is the fallback until it does; a service that signs as a subdomain needs adkim=s dropped. SPF alignment is left relaxed, and the comment recommends adding aspf=s once 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 adds rua=mailto:dmarc-reports@<domain> (its LOCAL_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 an rua=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 to rua= (or an rua= tag added at the end). Each rua=/ruf= destination is checked as check describes (an external one without its _report._dmarc authorisation record, one that cannot receive mail); a problem is printed as a ; WARNING: comment and logged. When its p= is quarantine or reject and [pepsi-ingress] DMARC_ENFORCE is 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 with sp=reject; np=reject when the record leaves the subdomains a weaker policy than reject: a p= other than reject with no sp=, or an explicit weaker sp= or np= (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, sp or deliberate p=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 tag aspf with the value s adkim=s and 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 missing p= tag, and an rua=/ruf= address written without its mailto: 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 single setup: DNS records checked and they are OK line 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 NS set 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 and DKIM1, a k= naming the key type (an Ed25519 key with no k= tag fails everywhere, since the tag defaults to rsa), no h=/s= restriction excluding sha256/email, no t=y (testing mode, under which a signature counts for nothing) and a p= equal to the key that pepsi-dkim(1) reports for the selector. Only the selectors that [pepsi] DKIM_ALGORITHMS signs with are printed and checked, plus the one that the ARC seal needs on the ARC_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 start pepsi-dkim.service and 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 as fail. This is expected and harmless, since the RSA signature supplies DMARC’s aligned pass, and the Ed25519 signature can be removed with DKIM_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-smarthost PUBLIC_IP is the smarthost’s, so it is skipped). Each address is judged against the name that the owning stage announces, its SERVER_NAME (falling back to the ingress HOSTNAME when a stage sets none), because that is the pair that a receiver compares. A PUBLIC_IP is correct only when its PTR exists, 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 PTR host 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 no PTR at 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 (say example.org announced in EHLO while its address reverse-resolves to example.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 PTR is 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_IP lives in the IP owner’s zone (in-addr.arpa / ip6.arpa), the usual fix is to ask your ISP or hosting provider to set the PTR to 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 the PTR is already one of your own domains, the message also offers the other direction, since that fix needs nobody else’s cooperation: adopt the PTR name as this host’s identity ([pepsi-ingress] HOSTNAME and every stage’s SERVER_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 same PTR lookup (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-confirmed PTR name of its sending address itself, so for that stage the PTR is compared with its own name: the name mismatch cannot occur, while a missing, unconfirmed or generic-looking PTR is still reported. Without a forward-confirmed name the stage falls back to SERVER_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 the PTR is 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)): the PTR of every PUBLIC_IP, forward-confirmed through the same resolver; each domain’s MX set and the TXT records that the check subcommand verifies; and the addresses of the ingress HOSTNAME. 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 the PTR verdicts 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 = none turns this check off.

    MTA-STS cross-checks. Everything else pepsi-setup verifies about MTA-STS is self-consistent by construction: the _mta-sts TXT record carries an id derived 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 under MTA_STS_MODE = enforce either one being wrong silently stops all inbound mail for the domain. Both are checked on every pepsi-setup run, and reported by the check subcommand and the web console; like the PTR findings 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 the MTA_STS_MX fallback invites, because HOSTNAME is the EHLO greeting name and need not be a name that any MX record points at. The warning names the hosts on each side and prints the single MTA_STS_MX line that would make them agree, qualified per domain when the served domains have different MX hosts, along with the alternative of changing the MX record instead and the advice to fall back to MTA_STS_MODE = testing until they do agree. This check also reports a domain with no MX record, an RFC 7505 null MX on a domain we accept mail for, an MX target that is a CNAME (forbidden by RFC 5321 §5.1, and senders may refuse it), a policy entry that matches no live MX host (harmless, but it widens what senders will connect to), and a DOMAIN:HOST entry naming a domain that is not in ACCEPTED_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-setup requests https://mta-sts.<domain>/.well-known/mta-sts.txt and 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 a 502 instead, while every unit stays active and nothing is logged. Senders that already cached a policy keep enforcing the old one for up to max_age, so the failure does not even end by itself. A 5xx is 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 once mta-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_DOMAIN has an MX record or, failing that, an A/AAAA record (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 an MX target that is a CNAME is 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 MX record 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/hosts file, because a mail host commonly lists its own name there against 127.0.1.1 or 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.

  9. Verifies the payment backend (optional). When a [pepsi-payments] section configures a GNU Taler merchant backend, pepsi-setup checks it over HTTP: GET /config must identify a taler-merchant backend (so the URL is correct) and GET /private/orders?limit=1 must return 200 (so the MERCHANT_ACCESS_TOKEN is correct). It then ensures a pepsi-resume webhook exists that POSTs to pepsi-httpd’s /resume endpoint whenever an order is paid. It creates the webhook if absent; if a pepsi-resume webhook 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.

  10. 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 as root) 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 of pepsi.target. When one uses AUTH = gssapi it likewise reminds that the Kerberos credential cache has to be renewed out of band (a keytab plus k5start or 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-owner role. Before any database work (schema install, role provisioning, settings validation, payment-backend check) pepsi-setup assumes the effective identity of the pepsi-owner user; PostgreSQL peer authentication then connects as the same-named role, so the pepsi schema, its tables, sequences and functions are owned by pepsi-owner. The pepsi-owner user/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_DIR and PUBLIC_DIR when missing and becomes the pepsi-dkim account before it touches a key, so every key file belongs to that account (mode 0600 in 0700 directories) 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_LOOPBACK

Add MYNETWORKS = 127.0.0.0/8 ::1/128 to 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:

  1. Installed — its binary is on $PATH or in the usual sbin directories, or a systemd unit file for it exists.

  2. Listening somewhere — a socket is read from the filter’s own configuration file (clamav-milter.conf’s MilterSocket, greylist.conf’s socket, an /etc/default fragment’s SOCKET= or -p flag, Rspamd’s bind_socket), then from its unit’s ExecStart, then from the paths that its distribution ships.

  3. 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:

FAILED

A file could not be read or parsed; nothing was imported from it.

UNSUPPORTED

Understood, but Pepsi has no equivalent, as for a header_checks table 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 into MYNETWORKS: Pepsi trusts a network only as far as [pepsi-ingress] SENDER_MAP binds it, and pepsi-ingress refuses to start on an unbound one, so the operator adds the network and its binding by hand.

APPROXIMATED

Imported with different semantics, such as mbox delivery becoming Maildir, a maximal_queue_lifetime rounded to whole hours, a loopback network dropped from MYNETWORKS.

UNKNOWN

A 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

smtpd_milters

[pepsi-ingress] MILTERS, in order

milter_default_action

ON_FAILURE: accept, tempfail and reject as they are, quarantine as tempfail

milter_connect_timeout

CONNECT_TIMEOUT

milter_command_timeout

COMMAND_TIMEOUT

milter_content_timeout

CONTENT_TIMEOUT

milter_protocol

PROTOCOL_VERSION

milter_macro_daemon_name

MILTER_NAME

milter_<phase>_macros

MACROS_<phase>: connect, helo, mail, rcpt and data by name, end_of_header as MACROS_EOH and end_of_data as MACROS_EOM

non_smtpd_milters

a pepsi-stage-milter stage on the submission path (see below)

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-domain

One line per alias and accepted domain — exact, and the default.

wildcard

One line per alias with a domain glob (postmaster@*) — compact, but it also matches domains added later.

primary

Qualify 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 $parameter interpolation and continuation lines) and master.cf. Identity comes from myhostname/mydomain, the accepted domains from mydestination, virtual_alias_domains, virtual_mailbox_domains and relay_domains; the smarthost from relayhost with its transport from smtp_tls_security_level / smtp_tls_wrappermode and its credentials from smtp_sasl_password_maps. Local delivery is read from home_mailbox, mailbox_transport/virtual_transport (an lmtp:unix: target becomes Pepsi’s LMTP stage) and mail_spool_directory; submission SASL from smtpd_sasl_type = dovecot and smtpd_sasl_path; the enabled services in master.cf decide the direction. alias_maps/alias_database and virtual_alias_maps become the alias map (virtual entries win, as they do in Postfix), and smtpd_sender_login_maps becomes username.map, inverted to Pepsi’s login-keyed form. message_size_limit, recipient_delimiter, maximal_queue_lifetime, smtp_helo_name and the smtpd_tls_* certificate paths arrive as expert options; mynetworks is reported, network by network, for a SENDER_MAP binding (see UNSUPPORTED above).

Reported rather than migrated: header_checks/body_checks, transport_maps, canonical rewriting, smtpd_*_restrictions, postscreen_*, content_filter, virtual-mailbox delivery, per-service -o overrides in master.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.conf is the richest and most reliable source and takes precedence: dc_eximconfig_configtype gives the direction and whether there is a smarthost, dc_other_hostnames the domains, dc_smarthost the relay, dc_relay_nets the trusted networks (reported for a SENDER_MAP binding, not carried over) and dc_localdelivery the mailbox format. The main section of exim4.conf.template / exim.conf / conf.d/main/* (everything before the first begin) adds primary_hostname, qualify_domain, domainlist local_domains, hostlist relay_from_hosts, message_size_limit, smtp_accept_max and the tls_certificate pair. Exim’s list syntax is handled properly: doubled separators, <; overrides, .include, +named references, and .ifdef evaluated against the macros actually defined. /etc/aliases becomes the alias map, /etc/email-addresses the submission-identity map, and /etc/exim4/passwd.client the 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 begin block is reported once, naming what replaces it in Pepsi (the stage graph for routers and transports, listener MYNETWORKS/SASL plus the whitelist and anti-spam stages for ACLs, SRS and the alias map for rewriting). Two consequences: because the retry ladder lives in begin retry, MAX_LIFETIME is never guessed, and because the transport holds the TLS and AUTH policy, the smarthost’s transport security is assumed rather than read. A tls_certificate containing 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.cf is used when no .mc exists, and then only its reliably-readable lines (Dj the canonical name, DS the smart host, Cw/Fw the local host names, DZ the version and the O options). 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 the FEATUREs that matter (use_cw_file, virtusertable, authinfo, local_lmtp, plussed_users, local_procmail, nullclient). The tables local-host-names, virtusertable, aliases and authinfo (the smarthost credentials, with the mechanism from its M: field) are read; postmaster is resolved through the alias chain to a real address.

Reported rather than migrated: MASQUERADE_AS and 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, and virtusertable right-hand sides that Pepsi cannot express (error:, %1).

qmail

The control directory (/var/qmail/control, /etc/qmail or /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. me gives the hostname; locals, rcpthosts, morercpthosts and virtualdomains the domains; the :relay:port catch-all in smtproutes the smarthost (with credentials when the AUTH patches’ extended form is used); defaultdelivery (or the qmail-start argument in rc) the mailbox format; databytes, queuelifetime, helohost and a servercert.pem the expert options.

The alias table is the .qmail-* files in qmail’s alias directory: .qmail-foo-bar becomes foo-bar, : decodes back to ., .qmail-default becomes a catch-all and .qmail-foo-default a 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 ~/.qmail files are deliberately not walked (expensive and privacy-sensitive; pepsi-stage-dot-forward is the runtime equivalent), and no .cdb is ever opened; the text users/assign is read instead. badmailfrom/badrcptto, spfbehavior, percenthack, qmqpservers and tlsclients are reported with their Pepsi counterparts.

Stalwart

config.toml under /opt/stalwart-mail/etc, /opt/stalwart/etc, /etc/stalwart or /etc/stalwart-mail (a directory of .toml fragments is read too, and !include directives are followed). server.hostname and the server.listener.* ports give the identity and direction, queue.outbound.next-hop / queue.strategy.route and the remote.* table the smarthost (a protocol = "lmtp" hop becomes local LMTP delivery instead), certificate.* the TLS paths, session.data.limits.size and the queue expiry the expert options. A memory-type directory (or a principals array) yields accounts: each extra address becomes an alias to the account’s primary one, and the logins become username.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:

high

The options an administrator plausibly tunes: MAX_MESSAGE_SIZE, MYNETWORKS, RECIPIENT_DELIMITER, MAX_LIFETIME, DMARC_ENFORCE, IP_BLOCKLISTS and MAILBOX_QUOTA (deliberately in this group rather than insane: a site that delivers locally will want a default quota and should not have to know the option’s name).

insane

Everything in the registry, adding HELO_NAME, TLS_CERT, TLS_KEY, DNS_TIMEOUT, MAX_CONNECTIONS, MAX_OPEN_SOCKETS, DKIM_SELECTOR, KEY_DIR, MAILBOX_OVER_QUOTA and CRYPTO_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 /etc copied into place.

–out DIR

Write the report and the converted map files into DIR (an existing file is diverted to <name>.imported rather than overwritten).

–alias-style STYLE

How bare alias names are qualified: per-domain (default), wildcard or primary; 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 a SECRET nor a SECRET_FILE and is not switched off with ENABLED = no; proof of origin is on by default, so the section need not be present. A random secret is written to a secrets.d/pepsi-origin.secret fragment (owned by the pepsi account, mode 0640) 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] HOSTNAME is unset (the name is bound into the Pepsi-Origin MAC) 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/*.secret files into which the –wizard externalizes secrets (see below). It gives each the mode 0640 and hands it to the account that must read it: secrets.d/pepsi.secret (smarthost/LMTP passwords, the merchant access token) to pepsi, secrets.d/pepsi-httpd.secret (the RESUME_AUTHORIZATION_TOKEN) to pepsi-httpd, secrets.d/pepsi-ingress.secret (the SRS SECRET) to pepsi-ingress, secrets.d/pepsi-crypto.secret (the [pepsi-crypto] KEY_WRAP_SECRET, current and retired) to pepsi-crypto, and secrets.d/pepsi-secure-link.secret (the [pepsi-secure-link] PEPPER) and secrets.d/pepsi-list.secret (the [pepsi-list] UNSUBSCRIBE_SECRET, VERP_SECRET and API_PASS) to pepsi-httpd with group pepsi (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 LDAP LDAP_BIND_PASSWORD) to pepsi-keydisc, secrets.d/pepsi-helper-token-refresh.secret (the OAuth client credentials) to pepsi-helper-token-refresh, and secrets.d/pepsi-dkim.secret (the [pepsi-dkim] TSIG_SECRET) to pepsi-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 by pepsi-ingress because ingress reverse-decodes SRS return addresses; the SRS stage runs as pepsi and reads it through the shared pepsi-ingress group (the Debian package makes pepsi a 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.service into line with [pepsi] SHARE_TELEMETRY: systemctl enable --now when 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 the telemetry_changed notification, so a running daemon follows the answer at once; turning telemetry off takes effect immediately. pepsi.target does not start that unit: nothing in the target Wants it, because a unit that the target pulled in would run whatever the answer was. The unit is still PartOf= the target, though, and so stops with the pipeline. It happens here, at the end, because the SYSTEM_ID is 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 single systemctl command instead. See pepsi-telemetry-client(1).

-r, –reset

Drop all existing pepsi objects 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.conf on a mail host or /etc/pepsi-telemetry/pepsi-telemetry.conf on 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 in SQL_DIR that 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 pepsi and _v schemas 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. 0 keeps 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 whose p= public key matches the key that pepsi-dkim(1) holds; see Prints DNS records under run), the SPF record (the v=spf1 record lists every configured PUBLIC_IP), the _dmarc TXT record (exactly one, and strictly valid; see Prints DNS records under run above), and the _mta-sts TXT record (present and a parseable v=STSv1 record with an id= tag; the id value 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 whose rua= lacks the report address, a TLSA or CAA record, a subdomain’s v=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 (target setup), 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 by pepsi.target, runs pepsi-setup -c /etc/pepsi/pepsi.conf check --fail-on-findings daily (pepsi-setup-check.service, as root on a read-only file system, since validation reads every service’s secrets); a finding fails the unit, which systemctl --failed then 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 one v=spf1 record (RFC 7208 §4.5 makes that a permanent error, so no SPF policy applies rather than the first one winning), a v=spf1 record with a term outside the RFC 7208 grammar (an unknown mechanism such as ipv4:, a bad address or CIDR length, a malformed macro; the term is named), and more than one v=STSv1 record or one whose id= is outside the allowed syntax. A v=spf1 record ending in +all is 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 missing k=, a misplaced v=, an h=/s= restriction excluding what Pepsi signs, or a second key record at the same name is [INVALID]; t=y is a [MISMATCH]. When Ed25519 signing is on, a closing note: explains why Google reports that selector as fail.

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. A p= 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>._domainkey with the remedy to start pepsi-dkim.service and run run.

A record may also be [ok] and carry a note: a p=none DMARC 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 mx set against the live MX records, and a fetch of https://mta-sts.<domain>/.well-known/mta-sts.txt compared with the configured policy. It ends with a note giving the MTA_STS_MX line that would make them agree. For the [pepsi-srs] SRS_DOMAIN it 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]: an MX record naming a host that has no A/AAAA record (or does not exist); an NS record of the domain naming a name server with no address; a CNAME at mta-sts.<domain>, openpgpkey.<domain> or autoconfig.<domain> pointing at a name with no address; an SPF include: or redirect= naming a domain that publishes no SPF record (or more than one); and an SPF a:<host> or mx:<host> naming another host that has no address (no MX record, 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 whose MX RRset they do not (labels TLSA (DNSSEC) and MX (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’s MX RRset, 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 no issue property), so every CA issues to whoever passes a domain validation, a hijacked one included; [NO ACCOUNTURI] when letsencrypt.org is named without the RFC 8657 accounturi of 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’s accounturi, validationmethods without http-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 HOSTNAME and of the SRS domain, found through the SOA record (the name itself, or the nearest ancestor that carries one), its DNSKEY RRset 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 signed MX and TLSA records 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 that pepsi-keys blocklist update keeps, and the moduli that pepsi-keys peer screen factored), 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 or MX record) and that has no SPF record of its own. The configuration names the EHLO host of a relay stage, [pepsi-ingress] HOSTNAME, mta-sts.<domain> and autoconfig.<domain>. A wildcard SPF record does not answer for a name that exists, so a forged sender at it gets SPF none. The record that such a name needs is v=spf1 -all, or, for a name that Pepsi announces in EHLO, the served domains’ SPF record with the sending addresses (receivers check the EHLO name 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_IP of a pepsi-stage-relay-to-internet stage, 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) check for 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_VERIFICATION has a token for every served domain, whose google-site-verification= TXT record run prints and check verifies as Google 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 the From: domain), so p=reject refuses none of them; [UNALIGNED] naming the sources that did not (address, message count, envelope domain, DKIM d=, reporters), which p=reject refuses (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 the rua= 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 whose rua= leaves the stage’s address out is [MISMATCH] on the _dmarc line, followed by that record with the address added.

Within each domain, every mailto: address that the valid _dmarc record names in rua= or ruf= is checked where the reports would go (label DMARC report destination). A destination domain outside the policy domain’s organisation must publish a v=DMARC1 TXT 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 no MX and no A/AAAA record (or a null MX) is [INVALID]: a stale or mistyped address, whose reports (the domain’s mail flow, and for ruf= 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-*] SNI host, the listener’s own host, and openpgpkey.domain, autoconfig.domain (with [pepsi-autoconfig] on) and mta-sts.domain (with MTA-STS published) for every accepted domain. Each is fetched as https://name/ with the certificate verified and no redirect followed, and its Strict-Transport-Security header judged as a browser would (only the first header counts): [ok] with a valid max-age of at least six months (15768000 seconds), [MISMATCH] when the header is absent, shorter, or malformed (no max-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). includeSubDomains and preload are 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 the OPENPGPKEY and SMIMEA records, 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 --served for 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 its ca_id): [ok] when the operator limited it to named mail domains (pepsi-keys(1) ca scope) or its certificate carries nameConstraints of its own, [UNSCOPED] when nothing limits it, so that a signature from any address chaining to that CA reads valid. unscoped is 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_DOMAINS and every stage’s LOCAL_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 the pepsi-owner role. 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_task table, 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_task NOTIFY channel 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_task without 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-admin runs this from its postinst.

Every row goes, not only the pending ones. Only a pending row can ever execute and a running row is orphaned by definition, so deleting just those two would be enough for safety. But a “clear” that left a console full of done and refused rows 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’s setup_task_log progress 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 -c FILE for the draining modes: the applier writes that file and its secrets.d fragments, and the path comes from its own command line and never from anything a task can influence. It is not strictly required: with no -c the 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_HOME and $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 curl command that uses it. –admin-url URL is the base URL of the administrative listener to which that command is addressed (default http://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/accounts refuses to issue a scope that the caller does not hold outright, so a token holding setup:write alone could not create an administrator; and since the token is consumed before the handler refuses, the attempt would spend it. The printed curl asks 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 = yes UNIX-socket listener is identified by SO_PEERCRED and 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 as SENDER_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 its ALLOW_ACTIONS withholds. 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 Graphviz dot graph. Each stage is one node, labelled with its configuration section name (e.g. stage-init) and the PROGRAM it runs with the pepsi-stage- prefix stripped (e.g. arc). A solid edge follows each stage’s NEXT_STAGE and a dashed red bounce edge its BOUNCE_STAGE. The command only reads the configuration (no DNS, schema or filesystem changes); pipe it through dot to 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.settings rows of the login’s addresses (every served domain, sub-address stripped at RECIPIENT_DELIMITER);

  • the login’s own <login>/... whitelists and their outstanding confirm-to-send challenges;

  • its pepsi.mailbox_quota row (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-config

Render the configuration from an answer set (the same answers that the interview collects), validate it exactly as pepsi-setup run would, 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-secret

Store one credential in the secrets.d fragment that its reader owns, preserving every other secret in that fragment. It refuses any [section] OPTION pair 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-certificate

Obtain 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-schema

Install 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 --reset on a console.

provision-roles

Create the database login roles and re-apply their grants.

generate-keys

Have 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-rotate

Start a DKIM key rotation for one signing domain now (parameters domain and an optional boolean hard): the applier runs pepsi-dkim -c CONFIG rotate [--hard] DOMAIN as root, since the daemon takes administrative requests from root and its own account only. The domain must be one that this deployment signs for. Without hard the 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 records domain, hard and the command’s output.

run-preflight

Run 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-identity

Generate a server-managed OpenPGP key (an MTA key) for one address (parameters address and an optional boolean vks, which defaults to [pepsi-keys] VKS_PUBLISH and requests a key-server upload). The address must be at a [pepsi-ingress] ACCEPTED_DOMAINS domain and a KEY_WRAP_SECRET must be configured. Always performed on request, even next to the user’s own key or a revoked key. The applier does the work as the pepsi-crypto role (root becomes that account for the connection, as pepsi-keys(1) does), because only that role may write the private column.

register-client-key

Register the user’s own public key (an MUA key, custody = client) for one address (parameters address and key, 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-identity

Revoke one local identity (parameters address, identity_id and an optional one-line reason of at most 1024 bytes, recorded as the revocation reason). The identity must belong to address. 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 records revocation_certificate, wkd_serves_revocation, key_server_upload_due and, in published, the same sentences the retire e-mail reply carries. Performed as the pepsi-crypto role, 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-flags

Change one local identity’s flags for its address’s owner (parameters address, identity_id and at least one of is_primary (true only), published and vks_wanted, booleans). The identity must belong to address; a key-server upload needs an active OpenPGP identity and publishes it too. These are the changes that an operator holding keys:write makes directly through the administrative API; an owner under own:<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 in changed; setting a flag to the value it has succeeds. Audited as key.identity.update.

reset-otp

Remove 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 the pepsi-crypto role, the only one granted pepsi.otp_key. Removing one that does not exist succeeds and says so.

confirm-enrolment

Check an owner’s second-factor code for the console’s sign-in by e-mail (parameters address and an optional otp) and change nothing else. pepsi-httpd(1) mints a browser session holding own:<address> for whoever follows a link mailed to the address, but cannot read pepsi.otp_key; it queues this task under the address’s own scope and opens the session only when the task ends done. An address without a second factor passes.

confirm-login

Check the second-factor code of an administrator signing in to the console with a password (parameters login and otp) and change nothing else. A console account with a TOTP second factor (pepsi-keys otp enroll --console LOGIN) keeps it in pepsi.otp_key under the subject console <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 ends done. 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 by pepsi-config like every other row, and the administrative API’s task endpoint refuses it.

identity-csr

Build a PKCS#10 certificate request over one S/MIME identity’s existing key (parameters address, identity_id and an optional one-line display_name of at most 128 bytes, the subject CN). The identity must belong to address, 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 the pepsi-crypto role 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 as key.identity.csr.

identity-certificate

Install the certificate that a CA issued for one S/MIME identity (parameters address, identity_id and certificate, 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), names address in its rfc822Name, is an end-entity certificate allowing emailProtection with 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 guarded UPDATE; 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 the pepsi-crypto role because the re-wrap writes the private column. Audited as key.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 scopes contain setup: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-csr and identity-certificate), the required scope is instead keys:write or own:<address> for exactly the address named in the task’s parameters: a user managing their own key is not configuring the server, and setup:write alone does not suffice. reset-otp is the operator’s alone and does not accept own:<address>. The address is taken from the parsed parameters, never from the scope list, so a principal confined to one address cannot name another; and

  • its written_by is the pepsi-config database role, which proves that the row reached the table through the one path that we control. That column is forced from current_user by a BEFORE INSERT trigger, so it is a fact about the connection rather than a claim in the payload, and there is no spelling of the INSERT that 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 bare pepsi-setup run behaves like pepsi-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 certbot to 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.conf when no -c is given. Unlike the other modes, this does not require an existing configuration file. It takes no subcommand (pepsi-setup --wizard run is 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=help lists 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, debug or trace (default: info). Unlike the other Pepsi programs, pepsi-setup does not honour [pepsi] LOG or LOG_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_IP entry, 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_DIR whose 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.