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 everyNEXT_STAGE/BOUNCE_STAGEresolves, that each stage’s program configuration (including smarthost routing) parses, and that domains andPUBLIC_IPvalues 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 runscertbot certonly --standaloneto obtain any certificate not yet on disk (or to widen one that no longer covers every name). Pass--no-certbotto 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/letsencryptroot-only. Under systemd,pepsi-setupwrites aLoadCredential=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
pepsischema: applies the numbered patch series and the re-creatable procedures fromSQL_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 --resetdrops and recreates the schema (destroying queued mail; the DKIM keys, which pepsi-dkim(1) keeps in files, are untouched).Signing keys.
pepsi-setupholds 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 ofACCEPTED_DOMAINS, each stage’sSERVER_NAME/POSTMASTERdomain, any explicitSIGNING_DOMAIN,SRS_DOMAINor fixedRESPONSE_FROM, andARC_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.keyand<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._domainkeyand<DKIM_SELECTOR>-YYYYMM-ed25519._domainkey, the next generation’s too during a rotation; removable ones as comments), an SPF policy built from thePUBLIC_IPof every relay stage (unioned), a DMARC suggestion where none is published (withrua=mailto:dmarc-reports@<domain>when a stage runs pepsi-stage-dmarc-report), an MTA-STS_mta-stsTXT record (RFC 8461), a TLSRPT record when[pepsi-tlsrpt] RUAis set, and DANE/TLSA records for the TLS listeners, plus a commented-out, optional CAA suggestion (RFC 8659, with the certbot account’saccounturiwhen 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, withsp=reject; np=rejectrecommended 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 DKIMp=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 everyPUBLIC_IPand every one of its terms follows the RFC 7208 grammar (an unknown mechanism such asipv4:voids the whole record), the DMARC record is valid and itsrua=/ruf=destinations can receive the reports (an external one must publish its_report._dmarcauthorisation record), and the_mta-stsTXT is present and parseable. A DMARC reports group says per domain, from the authenticated aggregate reports that pepsi-stage-dmarc-report stored for the lastWINDOW_DAYS, whether every reported source aligned, so thatp=rejectis safe, or which sources it refuses (advisory). It also compares the MTA-STS policy with the liveMXrecords and with what is actually served, and checks that the SRS domain can receive its bounces and, whenALLOW_ALIGNED_DOMAINaccepts an SRS domain aligned with a served one, that the served domain’s DMARC record (aspf=s, or an enforcing policy withDMARC_ENFORCEon) 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 theMXrecords of the accepted domains, are DNSSEC-authentic (a record without theADbit is never used for DANE). It reports dangling targets: anMXorNShost with no address, aCNAMEatmta-sts.,openpgpkey.orautoconfig.pointing at a name with no address, an SPFinclude:/redirect=naming a domain with no SPF record, and an SPFa:/mx:naming a host with no address orMX. It lists the subdomains that the configuration names (theEHLOhost,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 aStrict-Transport-Securityheader 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 theOPENPGPKEY/SMIMEArecords 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, whichpepsi-setup-check.timerruns daily, so that a record which breaks later makes that unit fail (systemctl --failed).runlogs the same TLSA and dangling-target findings as warnings, and warns when a component that trusts the DNSSECADbit (DANE in a relay stage or in key discovery) uses a resolver that does not validate;runandcheckboth 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 ingressMYNETWORKSentry 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), butrunreads 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--configpath, or/etc/pepsi/pepsi.confby default) and then offers to run the full setup. It imports a previous run’s answers from the file’s[pepsi-wizard]section;--forceoverwrites 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.
pepsiandpepsi-cryptoget the pipeline grant less the carve-backs (onlypepsi-cryptomay readcrypto_identity.private_wrappedor touchotp_key; the other roles may update only an identity’s use flags);pepsi-ingress,pepsi-httpdandpepsi-telemetryare cut down to what their code uses;pepsi-keydisc,pepsi-whitelistandpepsi-configget a few named tables or columns. The credential tables (includingown_enrolment/own_session) belong topepsi-httpdalone,crl_cacheis written bypepsi-keydiscalone, and onlypepsi-configmay writeconfig_overrideor enqueue asetup_task. After applying the grants,runandschemaask PostgreSQL and refuse to finish on any mismatch (An attacker who has the database).Secrets. Each secret lives in a
secrets.dfragment 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_DOMAINDMARC-aligned with a served domain (unlessALLOW_ALIGNED_DOMAIN = yes), since forwarding would launder forgeries of that domain into a DMARC pass; aCRYPTO_GENERATE_RSA_BITSother than 2048, 3072, 4096 or 8192 or belowCRYPTO_MIN_RSA_BITS; an S/MIME shared key on an elliptic curve; aKEY_WRAP_SECRETshorter than 16 characters. AMYNETWORKSentry 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 = strictis the relay stages’ default)runchecks that the resolver sets theADbit and names the off-host resolvers that the installation trusts to validate (The network adversary).Recycled logins.
runupdates the RFC 7293 login assignment record and reports key material older than a login’s current owner (A login that changes owner).The applier.
applyacts 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 thepepsi-configrole; there is no restart and no arbitrary command. The second factor of an owner’s request (confirm-enrolmentincluded) 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 topepsi-dkim, print DNS (the default action).-r/--resetfirst 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-dirDIR first saves the schema withpg_dumpwhen there is something to upgrade, and--backup-keepN then deletes all but the newest N dumps (default 2, 0 keeps all);--if-installeddoes 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);runlogs the same warnings.validate— check the configuration exactly asrundoes and change nothing (no database, DNS, keys or certificates); exits 1 on a refusal. Run it after editingpepsi.confand before restarting anything.visualize— print the[stage-*]pipeline as a Graphvizdotgraph on standard output (a solid edge perNEXT_STAGE, a dashed red one perBOUNCE_STAGE); pipe it intodot -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--answersfile is written against this schema.apply— perform the privileged setup work that the browser interface has asked for, reading intent rows frompepsi.setup_task. Normally started on demand by systemd.--oncedrains what is pending and exits;--idleSECS sets how long it waits with nothing to do before exiting;--cleardeletes 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-forSECS,--admin-urlURL).import[MTA] — report what would be migrated from an existing MTA (postfix,exim,sendmail,qmail,stalwart) without writing anything;--rootreads from under another directory,--outwrites the report and converted map files,--alias-stylechooses how bare alias names are qualified.
Options, which all come before the subcommand:
--no-certbot— do not invokecertbotfor 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);--forceoverwrites an un-importable file without prompting. With it:--expertSPEC also asks the deeper options (--expert=helplists them),--importMTA /--no-import/--import-rootDIR control the migration of an existing MTA’s settings, and--answersFILE answers every question from JSON instead of asking.-c/--configFILE,-L/--logLEVEL,-v/--verbose,-h/--help,-V/--version— the options shared by all Pepsi tools. Unlike the others,pepsi-setupignores[pepsi] LOGandLOG_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).