..
  This file is part of PEPSI.
  Copyright (C) 2026 Pepsi contributors

  PEPSI is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free
  Software Foundation; either version 3, or (at your option) any later version.

===========
pepsi-setup
===========

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

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: :manpage:`pepsi-setup(1)` / :manpage:`pepsi.conf(5)`.

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 :doc:`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 :doc:`pepsi-config` to inspect the effective configuration.

Command-line options
====================

Run with no subcommand performs the full setup (the same as ``run``). Full
detail is in :manpage:`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.

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: :manpage:`pepsi.conf(5)`.

See also
========

:doc:`../installation`, :doc:`../configuration`, :manpage:`pepsi-setup(1)`,
:manpage:`pepsi.conf(5)`.