53. pepsi-setup

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

53.1. Role

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

53.2. Features

  • Configuration validation. Parses [pepsi], [pepsi-ingress] 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. Pass --no-certbot to skip the certbot call and manage certificates yourself (setup then fails if one is missing rather than trying to obtain it).

  • 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 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 — by becoming the service user and opening the file — that anything left over really is readable.

  • 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. run --reset drops and recreates the schema (destroying queued mail; on-disk keys are kept).

  • Key generation. For every domain Pepsi is authoritative for — the union of ACCEPTED_DOMAINS, each stage’s SERVER_NAME/POSTMASTER domain, and ARC_DOMAIN — creates an RSA-2048 and an Ed25519 (RFC 8463) DKIM key under KEY_DIR (mode 0600 in 0700 dirs) if absent; existing keys are never overwritten.

  • DNS record output. Prints, in BIND zone format, the DKIM public keys (<selector>._domainkey and <selector>-ed25519._domainkey), an SPF policy built from the PUBLIC_IP of every relay stage (unioned), and an MTA-STS _mta-sts TXT record (RFC 8461). 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 local key, the SPF record lists every PUBLIC_IP, and the _mta-sts TXT is present and parseable. Purely informational (always exits 0).

  • 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.

53.3. Command-line options

Run with no subcommand performs the full setup (the same as run). Full detail is in pepsi-setup(1); the options are:

  • run — validate, provision TLS, install schema, generate keys, print DNS (the default action). -r/--reset first drops and recreates the schema (destroys all queued mail; on-disk keys are kept).

  • check — query live DNS and report mismatches; makes no changes, always exits 0.

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

  • --wizard — run the interactive configuration wizard (does not require an existing configuration file); --force overwrites an un-importable file without prompting.

  • -c/--config FILE, -L/--log LEVEL, -v/--verbose, -h/--help, -V/--version — the options shared by all Pepsi tools.

53.4. Configuration

Reads the shared [pepsi] (KEY_DIR, DKIM_SELECTOR, 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).

53.5. See also

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