93. pepsi-config

Inspect and edit the effective configuration shared by every component.

93.1. Role

pepsi-config looks up, expands, dumps and edits the merged Pepsi configuration. Every component reads the same INI-style configuration file and the same database overlay (pepsi.config_override), so a single tool serves them all and no other binary has a config subcommand. It is an operator CLI, not a stage. Reference: pepsi-config(1).

The read commands report the effective configuration: the file amended by the overlay. A database that cannot be reached is not an error: the file’s configuration is reported with a warning instead, because an unreachable database is often exactly when an operator reaches for this tool. The write commands edit the overlay only; they never touch the configuration file, which stays the operator’s own. Writes connect as the pepsi-config PostgreSQL role (adopted automatically when started as root), so who may edit the configuration is a database grant rather than a check in this program.

93.2. Features

  • get SECTION OPTION — print the value of an option in a section; with --filename the value is treated as a path and $-expanded.

  • pathsub PATH_EXPR — substitute ${VAR}/$VAR placeholders in a path expression from the [PATHS] section and the environment.

  • dump — print the merged configuration; --diagnostics adds the parser’s extra output, --origin annotates every value with the layer it came from (file, or the database scope that last set it) and --scope resolves the chain for a scope other than global.

  • set SECTION OPTION VALUE / unset SECTION [OPTION] — write or remove one override (or, for unset without an option, a whole section) in the database overlay at --scope (global by default, or domain:<d> or address:<a>). Sections read from the file only are refused.

  • list — print the stored overrides, optionally restricted with --scope and including staged rows with --drafts.

  • export FILE / import FILE — write and restore a password-encrypted archive of the configuration directory (- for standard output/input; --from/--into choose the directory, --password-file avoids the prompt, --force overwrites existing files). This is the half of a backup that PostgreSQL’s own tools cannot cover: the configuration file and the secrets.d fragments.

Values that are secrets are masked in dump output, so a dump can be attached to a bug report. A proposed set is validated before it is stored, by building the configuration that the change would produce and running the owning stage’s own parser over it: a value that would stop a program from starting is refused rather than written. The overlay never names an executable: HELPER, SCAN_HELPER, MAILBOX_HELPER, PIN_COMMAND and any PROGRAM that is not a bare pepsi-stage-* command are refused, as are credential-bearing options, which only ever live in secrets.d fragments. An attacker who has the configuration file explains why the file is world-readable and why write access to it is equivalent to root; An attacker who has the database explains who may edit the overlay.

export requires a password of at least 12 characters: the archive carries every secret fragment, the key-encryption key included, and can be attacked offline (Argon2id slows such an attack down but does not prevent it).

93.3. Validation

pepsi-config dump pairs with pepsi-setup(1)’s check when validating an installation: check queries live DNS, while dump shows the effective values the components will actually see.

93.4. See also

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