..
  This file is part of PEPSI.
  Copyright (C) 2026 GNUnet e.V.

  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-config
============

*Inspect and edit the effective configuration shared by every component.*

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: :manpage:`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.

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.

Validation
==========

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

See also
========

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