83. pepsi-config

Inspect and edit the effective configuration shared by every component.

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

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

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

83.4. See also

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