68. pepsi-setup

Provision the database, signing keys and DNS for a deployment.

68.1. Role

pepsi-setup is the administrative bootstrap tool. In one invocation it validates the configuration, installs the schema, has the DKIM signing daemon make the signing keys that it lacks and prints the DNS records to publish; a separate check verifies live DNS. References: pepsi-setup(1) / pepsi.conf(5).

68.2. Features

  • Configuration validation. Parses [pepsi], [pepsi-ingress], [pepsi-dkim] and the [stage-*] pipeline; checks that [stage-init] exists, that every NEXT_STAGE/BOUNCE_STAGE resolves, that each stage’s program configuration (including smarthost routing) parses, and that domains and PUBLIC_IP values are well-formed. On any error it changes nothing and exits non-zero.

  • TLS certificate provisioning. For every TLS-terminating listener/cert section that has no TLS_CERT/TLS_KEY, it fills in the standard certbot path layout (rewriting the config file in place, comments preserved) and then runs certbot certonly --standalone to obtain any certificate not yet on disk (or to widen one that no longer covers every name). Pass --no-certbot to skip the certbot call and manage certificates yourself. A certificate that is missing and cannot be obtained is deferred, not fatal: the rest of the run proceeds and the end-of-run summary says what is left to do.

  • TLS access provisioning. The servers run as unprivileged users, while certbot keeps /etc/letsencrypt root-only. Under systemd, pepsi-setup writes a LoadCredential= drop-in per unit so that systemd reads each certificate and key as root at unit start and hands the service a private copy — the file permissions then do not matter at all. It also grants POSIX ACLs and installs a certbot deploy hook (which re-grants and restarts the servers, so a renewed certificate is actually served), and finally verifies that anything left over really is readable, by becoming the service user and opening the file.

  • Schema installation. The sole installer of the single pepsi schema: applies the numbered patch series and the re-creatable procedures from SQL_DIR; idempotent and re-runnable. It records what it applied, by content hash, so every program can refuse a schema from another release, and it refuses to install over a newer schema itself (see Upgrading). run --reset drops and recreates the schema (destroying queued mail; the DKIM keys, which pepsi-dkim(1) keeps in files, are untouched).

  • Signing keys. pepsi-setup holds no private key. It hands every domain that Pepsi is authoritative for to the signing daemon (pepsi-dkim sync-domains, pepsi-dkim(1)): the union of ACCEPTED_DOMAINS, each stage’s SERVER_NAME/POSTMASTER domain, any explicit SIGNING_DOMAIN, SRS_DOMAIN or fixed RESPONSE_FROM, and ARC_DOMAIN. The daemon makes an RSA key of [pepsi-dkim] RSA_BITS (default 2048) and an Ed25519 (RFC 8463) key for every domain that has none, under its own account, and reports their records. A daemon that cannot be run defers the step, not the run. DKIM key files that are left under [pepsi] KEY_DIR (<domain>/dkim.rsa.key and <domain>/dkim.ed25519.key) are deleted once the daemon answers, since nothing signs with them, and their records are listed as removable.

  • DNS record output. Prints, in BIND zone format, the DKIM public keys that the daemon reports as needed (<DKIM_SELECTOR>-YYYYMM._domainkey and <DKIM_SELECTOR>-YYYYMM-ed25519._domainkey, the next generation’s too during a rotation; removable ones as comments), an SPF policy built from the PUBLIC_IP of every relay stage (unioned), a DMARC suggestion where none is published (with rua=mailto:dmarc-reports@<domain> when a stage runs pepsi-stage-dmarc-report), an MTA-STS _mta-sts TXT record (RFC 8461), a TLSRPT record when [pepsi-tlsrpt] RUA is set, and DANE/TLSA records for the TLS listeners, plus a commented-out, optional CAA suggestion (RFC 8659, with the certbot account’s accounturi when it can be read) when certificates come from Let’s Encrypt, and a commented-out wildcard *.<domain>. TXT "v=spf1 -all" for the subdomains that nobody sends as, with sp=reject; np=reject recommended for a DMARC record that leaves them a weaker policy. Records already published with the right value are left out. The policy file itself is served by pepsi-httpd, not printed. Long RSA records are split into multiple character-strings. The same SPF record is suggested for every served domain; the output notes that special multi-host setups may prefer a tighter, still-correct per-domain grouping, which pepsi-setup does not compute automatically.

  • Live DNS verification (check): queries DNS and reports, per domain, whether the published DKIM p= matches the key that the daemon holds (a record that a DNS host cut short at a 255-byte string is named as such; a retired key’s record is listed as removable), the SPF record lists every PUBLIC_IP and every one of its terms follows the RFC 7208 grammar (an unknown mechanism such as ipv4: voids the whole record), the DMARC record is valid and its rua=/ruf= destinations can receive the reports (an external one must publish its _report._dmarc authorisation record), and the _mta-sts TXT is present and parseable. A DMARC reports group says per domain, from the authenticated aggregate reports that pepsi-stage-dmarc-report stored for the last WINDOW_DAYS, whether every reported source aligned, so that p=reject is safe, or which sources it refuses (advisory). It also compares the MTA-STS policy with the live MX records and with what is actually served, and checks that the SRS domain can receive its bounces and, when ALLOW_ALIGNED_DOMAIN accepts an SRS domain aligned with a served one, that the served domain’s DMARC record (aspf=s, or an enforcing policy with DMARC_ENFORCE on) closes the SPF route that forged mail would take. It compares any published TLSA record with the certificate that the listener serves (when a record stops matching the key, senders that enforce DANE refuse our mail) and asks public validating resolvers whether that TLSA record, and the MX records of the accepted domains, are DNSSEC-authentic (a record without the AD bit is never used for DANE). It reports dangling targets: an MX or NS host with no address, a CNAME at mta-sts., openpgpkey. or autoconfig. pointing at a name with no address, an SPF include:/redirect= naming a domain with no SPF record, and an SPF a:/mx: naming a host with no address or MX. It lists the subdomains that the configuration names (the EHLO host, mta-sts., autoconfig.) that exist without an SPF record of their own, which a wildcard does not cover. It fetches every HTTPS name under which pepsi-httpd is reached and reports one whose answer lacks a Strict-Transport-Security header of at least six months (a front server that does not pass it on). And it counts the DNS lookups that the domain’s SPF record costs a receiver, through every include, against the RFC 7208 limits of 10 lookups and 2 void lookups. For every address with a published end-to-end identity it fetches what the Web Key Directory and the OPENPGPKEY/SMIMEA records serve and reports a fingerprint that the key store does not publish (Checking what is actually served). Informational: its findings set the exit status only with --fail-on-findings, which pepsi-setup-check.timer runs daily, so that a record which breaks later makes that unit fail (systemctl --failed). run logs the same TLSA and dangling-target findings as warnings, and warns when a component that trusts the DNSSEC AD bit (DANE in a relay stage or in key discovery) uses a resolver that does not validate; run and check both state, with their IP addresses, the resolvers off this host that the installation trusts with DNSSEC validation (nothing when every resolver is on loopback). Validation also warns about an ingress MYNETWORKS entry wider than one host (not loopback), since every host in it may relay and send as any address, and the reverse-proxy site that it writes for nginx or Apache turns TLS session tickets off for forward secrecy. The site sets no cipher list (the front server’s is shared with its other sites), but run reads the front server’s effective configuration (nginx -T, or Apache’s configuration tree) and warns when it still enables TLS 1.2 suites without forward secrecy (static RSA key exchange), or says that it could not tell.

  • Setup wizard (--wizard): a short interactive interview that writes a complete, already-validated configuration file (to the --config path, or /etc/pepsi/pepsi.conf by default) and then offers to run the full setup. It imports a previous run’s answers from the file’s [pepsi-wizard] section; --force overwrites a file that has no such section without prompting.

Use pepsi-config to inspect the effective configuration.

68.3. Security

pepsi-setup is where most of the deployment’s privilege boundaries are put in place, and it verifies them rather than assuming them:

  • Database roles. Every service account gets its own peer-authenticated role. pepsi and pepsi-crypto get the pipeline grant less the carve-backs (only pepsi-crypto may read crypto_identity.private_wrapped or touch otp_key; the other roles may update only an identity’s use flags); pepsi-ingress, pepsi-httpd and pepsi-telemetry are cut down to what their code uses; pepsi-keydisc, pepsi-whitelist and pepsi-config get a few named tables or columns. The credential tables (including own_enrolment/own_session) belong to pepsi-httpd alone, crl_cache is written by pepsi-keydisc alone, and only pepsi-config may write config_override or enqueue a setup_task. After applying the grants, run and schema ask PostgreSQL and refuse to finish on any mismatch (An attacker who has the database).

  • Secrets. Each secret lives in a secrets.d fragment owned by the one account that reads it, secured first thing on every run; the key-encryption key is generated only when the database confirms that no wrapped key exists yet (An attacker who has the configuration file, The private-key custody boundary).

  • Refused configurations. An [pepsi-srs] SRS_DOMAIN DMARC-aligned with a served domain (unless ALLOW_ALIGNED_DOMAIN = yes), since forwarding would launder forgeries of that domain into a DMARC pass; a CRYPTO_GENERATE_RSA_BITS other than 2048, 3072, 4096 or 8192 or below CRYPTO_MIN_RSA_BITS; an S/MIME shared key on an elliptic curve; a KEY_WRAP_SECRET shorter than 16 characters. A MYNETWORKS entry wider than one host and a front server still offering static-RSA TLS 1.2 suites are warnings.

  • DNSSEC trust. With DANE in use (DANE = strict is the relay stages’ default) run checks that the resolver sets the AD bit and names the off-host resolvers that the installation trusts to validate (The network adversary).

  • Recycled logins. run updates the RFC 7293 login assignment record and reports key material older than a login’s current owner (A login that changes owner).

  • The applier. apply acts only on a closed list of seventeen task kinds, each authorised by the recorded scope and by the fact that the row was written through the pepsi-config role; there is no restart and no arbitrary command. The second factor of an owner’s request (confirm-enrolment included) is checked here, never by the web tier (A second factor for key management, Signing in to the console by e-mail, A compromised component). The reasoning is in pepsi-setup(1), The applier’s trust model.

68.4. Command-line options

Without a subcommand, pepsi-setup performs the full setup (the same as run). Full detail is in pepsi-setup(1); the options are:

Subcommands:

  • run — validate, provision TLS, install schema, hand the signing domains to pepsi-dkim, print DNS (the default action). -r/--reset first drops and recreates the schema (destroys all queued mail; the DKIM keys are kept).

  • schema — install or upgrade the schema and the role grants, and nothing else; needs only [pepsi-postgres], so it also works with a telemetry collector’s configuration file. Refuses a newer schema (exit status 78). --backup-dir DIR first saves the schema with pg_dump when there is something to upgrade, and --backup-keep N then deletes all but the newest N dumps (default 2, 0 keeps all); --if-installed does nothing on a database with no schema yet. This is what a package upgrade runs; see Upgrading.

  • check — query live DNS and report mismatches; makes no changes, and its findings set the exit status only with --fail-on-findings (exit 1 on a missing, wrong, invalid or unreachable record or a blocklist listing, each also logged as a warning; a failed lookup does not count). It also warns about per-address state (settings, key-store identities, <login>/... whitelists, mailbox quotas) kept for a login that no longer exists, and about key material older than a login’s current owner (RFC 7293 login assignment record; the database drops the previous owner’s settings, whitelists, quota and reply logs itself, never keys); run logs the same warnings.

  • validate — check the configuration exactly as run does and change nothing (no database, DNS, keys or certificates); exits 1 on a refusal. Run it after editing pepsi.conf and before restarting anything.

  • visualize — print the [stage-*] pipeline as a Graphviz dot graph on standard output (a solid edge per NEXT_STAGE, a dashed red one per BOUNCE_STAGE); pipe it into dot -Tpng.

  • questions — print the setup interview as JSON: the steps, each question’s shape, default, help text and when it is asked. Both the terminal wizard and the browser setup are described by this model, and an --answers file is written against this schema.

  • apply — perform the privileged setup work that the browser interface has asked for, reading intent rows from pepsi.setup_task. Normally started on demand by systemd. --once drains what is pending and exits; --idle SECS sets how long it waits with nothing to do before exiting; --clear deletes every queued row without executing any of them (mutually exclusive with the other two).

  • bootstrap — mint and print the one-time bearer token that creates the first administrator account (--valid-for SECS, --admin-url URL).

  • import [MTA] — report what would be migrated from an existing MTA (postfix, exim, sendmail, qmail, stalwart) without writing anything; --root reads from under another directory, --out writes the report and converted map files, --alias-style chooses how bare alias names are qualified.

Options, which all come before the subcommand:

  • --no-certbot — do not invoke certbot for missing TLS certificates; they are deferred instead (see TLS certificate provisioning above).

  • --no-reverse-proxy — do not auto-integrate with an existing front HTTP server; let pepsi-httpd bind 443 directly.

  • -y/--yes-to-all, -n/--no-to-all — answer every interactive offer the same way, so setup never blocks on input.

  • --wizard — run the interactive configuration wizard (does not require an existing configuration file); --force overwrites an un-importable file without prompting. With it: --expert SPEC also asks the deeper options (--expert=help lists them), --import MTA / --no-import / --import-root DIR control the migration of an existing MTA’s settings, and --answers FILE answers every question from JSON instead of asking.

  • -c/--config FILE, -L/--log LEVEL, -v/--verbose, -h/--help, -V/--version — the options shared by all Pepsi tools. Unlike the others, pepsi-setup ignores [pepsi] LOG and LOG_JSON (logging starts before a configuration is loaded); pass -L.

68.5. Configuration

Reads [pepsi-dkim] (validated in full; PUBLIC_DIR locates the daemon’s status), the shared [pepsi] (KEY_DIR, where run deletes leftover DKIM key files, DKIM_SELECTOR, DKIM_ALGORITHMS, ARC_DOMAIN, ARC_ALGORITHM, ORIGINATE_SUCCESS_DSN, MTA_STS_MODE, MTA_STS_MAX_AGE), [pepsi-postgres] (CONFIG, SQL_DIR), [pepsi-ingress] (HOSTNAME, ACCEPTED_DOMAINS), and the [stage-*] sections — including each relay stage’s PUBLIC_IP (collected by PROGRAM). Full reference: pepsi.conf(5).

68.6. See also

Installation, Configuration, pepsi-setup(1), pepsi-dkim(1), pepsi.conf(5).