70.1.49. pepsi-config

inspect and edit the effective pepsi configuration

Manual section:

1

70.1.49.1.1. Name

pepsi-config - look up, expand, dump and edit the merged Pepsi configuration.

70.1.49.1.2. Synopsis

pepsi-config [GLOBAL-OPTIONS] get [-f | –filename] SECTION OPTION

pepsi-config [GLOBAL-OPTIONS] pathsub PATH-EXPR

pepsi-config [GLOBAL-OPTIONS] dump [-d | –diagnostics] [–origin] [–scope SCOPE]

pepsi-config [GLOBAL-OPTIONS] set [–scope SCOPE] SECTION OPTION VALUE

pepsi-config [GLOBAL-OPTIONS] unset [–scope SCOPE] SECTION [OPTION]

pepsi-config [GLOBAL-OPTIONS] list [–scope SCOPE] [–drafts]

pepsi-config [GLOBAL-OPTIONS] export [–from DIR] [–password-file FILE] ARCHIVE

pepsi-config [GLOBAL-OPTIONS] import [–into DIR] [–force] [–password-file FILE] ARCHIVE

70.1.49.1.3. Description

pepsi-config inspects – and edits – the effective configuration shared by every Pepsi component. All components read the same INI-style configuration file (see pepsi.conf(5)) and the same database configuration overlay, so a single tool suffices for both; the per-component config subcommands that earlier releases shipped have been retired in favour of this one.

The reading commands report the effective configuration: the file amended by the pepsi.config_override table. A database that cannot be reached is not an error for them – the file’s configuration is reported, with a warning – because an operator most often reaches for this tool when something is wrong.

The writing commands (set, unset) edit the database overlay only. They never modify the configuration file, which stays the operator’s own, and they are refused unless the caller holds the pepsi-config PostgreSQL role (pepsi-config adopts that account when it is started as root). That grant is the enforcement: no Pepsi component that processes mail may write the configuration that defines the pipeline it runs in.

The scope chain, and which sections may live in the database at all, are described in pepsi.conf(5).

70.1.49.1.4. Commands

get [-f | –filename] SECTION OPTION

Print the effective value of OPTION in SECTION. With –filename, the value is interpreted as a path and $-expansion is applied.

pathsub PATH-EXPR

Print PATH-EXPR with ${VAR} and $VAR placeholders substituted from the [PATHS] section and the environment.

dump [-d | –diagnostics] [–origin] [–scope SCOPE]

Print the merged configuration. With –diagnostics, also show which file and line each option came from. With –origin, annotate every value with the layer that set it (file, or the database scope) and every section with whether a change to it is applied live or needs a restart; –scope resolves the chain for a particular domain or address (default global).

set [–scope SCOPE] SECTION OPTION VALUE

Store one override in the database. The change is validated first by building the configuration it would produce and running the owning stage’s own parser over it; a value that stage would reject is refused, with that stage’s error, and nothing is stored. Prints whether the change is live or needs a restart.

unset [–scope SCOPE] SECTION [OPTION]

Remove one override, or – with no OPTION – every override the scope carries for SECTION. The affected options revert to the next layer down, ultimately the configuration file.

list [–scope SCOPE] [–drafts]

Print the stored overrides with their timestamps and authors. –drafts additionally shows staged rows, which no running component reads.

export [–from DIR] [–password-file FILE] ARCHIVE

Write a password-encrypted archive of the configuration directory (by default the directory holding the loaded configuration file): the configuration file, any fragments beside it, and the secrets.d secret fragments. Each file’s mode, owner and group are recorded by name. ARCHIVE may be - for standard output. This deliberately does not cover the database overlay, which pg_dump already backs up properly.

import [–into DIR] [–force] [–password-file FILE] ARCHIVE

Restore an archive written by export. Ownership is restored, so this normally needs root; a file whose recorded owner does not exist on this machine is refused, not guessed. Existing files are left alone unless –force is given.

70.1.49.1.5. Scopes

SCOPE is one of:

global

The whole deployment. The default for set and unset.

domain:DOMAIN

Messages whose relevant address is at DOMAIN.

address:ADDRESS

Messages whose relevant address is exactly ADDRESS.

The relevant address is the envelope sender for a locally-originated message, otherwise each envelope recipient – the same rule the per-address settings layer uses (pepsi-settings(1)).

70.1.49.1.6. Global Options

These global options precede the subcommand (a trailing flag is rejected).

-c FILE, –config FILE

Read the configuration from FILE instead of searching the default locations.

-L LOGLEVEL, –log LOGLEVEL

Set the logging verbosity. LOGLEVEL is one of error, warn, info, debug or trace (default: info).

-v, –verbose

Show log messages from all sources, including third-party libraries.

-h, –help

Print a usage summary and exit.

-V, –version

Print the version and exit.

70.1.49.1.7. Exit Status

0

Successful completion.

1

An error occurred, for example a malformed configuration file, a missing SECTION/OPTION, a rejected override value, a wrong archive password, or insufficient database privileges for a write. The reason is written to the log.

70.1.49.1.8. Files

When –config is not given, the first existing file from the following list is used. Every Pepsi component shares the same configuration file, so this is the same list each one searches:

• $XDG_CONFIG_HOME/pepsi.conf

• $HOME/.config/pepsi.conf

• /etc/pepsi/pepsi.conf

• /etc/pepsi/pepsi.conf

70.1.49.1.9. Examples

Check which domains mail is accepted for:

pepsi-config -c /etc/pepsi/pepsi.conf get pepsi-ingress ACCEPTED_DOMAINS

Dump the merged configuration with source annotations:

pepsi-config -c /etc/pepsi/pepsi.conf dump --diagnostics

Show where every effective value came from:

pepsi-config dump --origin

Raise one stage’s queue lifetime without editing a file or restarting anything:

pepsi-config set stage-relay MAX_LIFETIME '48 h'

Give one domain a different setting, and take it away again:

pepsi-config set --scope domain:example.org stage-relay DELAY_DSN_AFTER '4 h'
pepsi-config unset --scope domain:example.org stage-relay DELAY_DSN_AFTER

Back up everything that is not in the database:

pepsi-config export /root/pepsi-config-backup.pca

70.1.49.1.10. See Also

pepsi.conf(5), pepsi-setup(1), pepsi-settings(1)

70.1.49.1.11. Bugs

Report bugs to the Pepsi issue tracker.