95.1.52. pepsi-settings

manage per-address stage option overrides

Manual section:

1

95.1.52.1.1. Name

pepsi-settings - set, list and remove per-address configuration overrides.

95.1.52.1.2. Synopsis

pepsi-settings [GLOBAL-OPTIONS] set ADDRESS STAGE OPTION VALUE

pepsi-settings [GLOBAL-OPTIONS] unset ADDRESS STAGE [OPTION]

pepsi-settings [GLOBAL-OPTIONS] import ADDRESS SOURCE

pepsi-settings [GLOBAL-OPTIONS] get ADDRESS

pepsi-settings [GLOBAL-OPTIONS] list [–json]

pepsi-settings [GLOBAL-OPTIONS] remove ADDRESS

95.1.52.1.3. Description

pepsi-settings is the operator’s tool for the pepsi.settings table, which lets a stage’s options be overridden per e-mail address. A stage normally reads its options from its [stage-<name>] section in the configuration file; the settings table supplies overrides for messages to or from a particular correspondent, with the INI value acting as the default for any option that the override does not mention.

Each row maps one envelope address to a JSON object whose top-level keys are stage section names (stage-<name>) and whose values are objects of OPTION to value. For a given message the relevant address is the envelope sender when the message originates locally (state.local_origin), otherwise an envelope recipient. The address is matched exactly (no domain or subaddress fallback), in canonical form: the tool stores ADDRESS, and compares every message’s address, after Unicode normalisation (NFC), case folding of the local part and conversion of the domain to its A-label. René@Bücher.example and reneU+0301@xn--bcher-kva.example are therefore one row (see the security chapter of the manual, “Addresses are compared in one form”).

The recipients of one inbound message may resolve to different effective configurations for the stage that is about to run. The difference may come from this table or from a domain:/address: scope of the database overlay. In that case the pipeline transparently splits the message into one row per distinct configuration, so that each recipient is processed under its own settings; see pepsi-dispatch(1).

This tool is not a stage. It connects to the same database as the other components through the shared [pepsi-postgres] section and introduces no configuration of its own. When started as root it continues as the pepsi service account; see Running as root.

95.1.52.1.3.1. Relation to the database configuration overlay

The pepsi.settings table is the top layer of the configuration scope chain described in pepsi.conf(5):

configuration file  <  global  <  domain:<d>  <  address:<a>  <  pepsi.settings

The three middle layers live in a different table, pepsi.config_override, and are managed with pepsi-config(1). The two are deliberately not merged:

  • this table is written by account owners themselves, from their own mailbox, through pepsi-stage-edit-settings(1), restricted to the stage sections the operator allowed;

  • config_override defines the pipeline and is writable only through the pepsi-config PostgreSQL role, which no component that processes mail holds.

Keeping them apart is a security boundary rather than duplication. If both lived in one table, a bug in the per-address namespace check would not just leak an override: it would let a user reconfigure the mail server. pepsi-setup(1) verifies the grants against the live database after every install.

Where both mechanisms name the same option for the same message, this table wins: it is the higher layer, and the operator’s EDITABLE_STAGES allowlist already bounds what it may touch.

pepsi-stage-edit-settings(1) checks an account owner’s own choices when the owner writes them, not when a stage reads the row, because a stage cannot tell who wrote it. This tool belongs to the operator and is not subject to those checks: for example, it may point one address’s pepsi-stage-auto-whitelist(1) or pepsi-stage-secretary(1) WHITELIST_NAME at a shared whitelist, which an owner may not choose for themselves. An owner who later edits that stage by mail keeps the stored value unless they change it.

What an override cannot do: a stage’s PROGRAM, its default NEXT_STAGE and its BOUNCE_STAGE are taken from the operator’s configuration before the overrides are applied, so an override of them has no effect. Every other option that the stage reads from its own section is overridden, including its branch targets (TRUE_STAGE, QUARANTINE_STAGE, RESPONSE_STAGE …).

Overrides belong to one owner of a login: when a login is found to have been given to somebody else (a new uid, or back after it was gone), the previous owner’s rows for that login’s addresses are dropped before the new owner’s mail is delivered. The security boundary that this table forms is described in the manual’s Threat model chapter (per-address settings) and Security chapter.

Every change that this tool makes (set, unset, import, remove) is recorded in the shared audit log (pepsi.event_log) with the address and the option touched, but not the value, since an override can name a credential. Changes that an account owner makes by e-mail are not audited.

95.1.52.1.4. Commands

set ADDRESS STAGE OPTION VALUE

Set one option override. STAGE is the stage label (e.g. check-whitelist; a leading stage- is accepted and optional) and is stored as the section key stage-<name>; a stage with no such section in the configuration is refused. VALUE is stored as a string; the stage parses it exactly as it would the corresponding INI value (so a boolean uses YES/NO, a number its digits, and so on). The row and the stage section are created as needed.

unset ADDRESS STAGE [OPTION]

Remove one OPTION from the address’s STAGE section. With OPTION omitted, remove the whole stage section. An emptied section, and then an emptied row, are dropped automatically.

import ADDRESS SOURCE

Replace the address’s entire settings object with the JSON read from the file SOURCE, or from standard input when SOURCE is -. The JSON must be an object whose keys are stage-<name> section names and whose values are objects of JSON scalars (string, number or boolean); the section keys are lower-cased.

get ADDRESS

Print the address’s settings object as pretty JSON, or a notice if none exists.

list [–json]

List all rows. The default output is one address<TAB>JSON line per row; –json emits a JSON array of {address, settings} objects instead.

remove ADDRESS

Delete the address’s settings row entirely.

95.1.52.1.5. Validation

pepsi-setup(1) validates the table after installing the schema: every top-level key must name an existing [stage-<name>] section, and every option value must be a JSON scalar (string, number or boolean). An override keyed on a mistyped stage section is reported as an error rather than silently ignored.

95.1.52.1.6. Running as root

Pepsi gives every component its own PostgreSQL role, which is authenticated over the local socket by the operating-system account that the component runs as, and root is deliberately not one of them. Rather than fail to connect and oblige you to remember sudo -u pepsi pepsi-settings …, the tool detects that it was started as root and becomes the unprivileged pepsi service account before it connects. The stages read pepsi.settings as this account.

Everything that happens before the connection still happens as the invoking user: the configuration file (with any @inline-secret@ fragment) is read first, and so is the JSON document given to import, so a root-only source path works.

If the pepsi account does not exist (in an uninstalled source tree or a test rig), the identity is left untouched, a warning is logged, and the connection is attempted as the invoking user, so a setup in which root can reach the database keeps working.

95.1.52.1.7. 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. When the flag is absent the global [pepsi] LOG option applies, and failing that 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.

95.1.52.1.8. Exit Status

0

Successful completion.

1

An error occurred: a malformed configuration file, invalid JSON, or a failed database connection or query, or a stage with no [stage-<name>] section. The reason is written to the log.

2

The command line itself was wrong (an unknown option, a global option written after the subcommand, a missing argument).

78

The database schema belongs to another Pepsi release (not installed, older, newer or modified); run pepsi-setup schema (see pepsi-setup(1)).

95.1.52.1.9. 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.conf

No other file is read or written: every override lives in the pepsi.settings table.

95.1.52.1.10. Examples

Send mail to vip@example.com through a different whitelist:

pepsi-settings -c /etc/pepsi/pepsi.conf set vip@example.com check-whitelist WHITELIST_NAME vips

Block a different set of languages for one recipient:

pepsi-settings -c /etc/pepsi/pepsi.conf set bob@example.org block-language BLACKLIST 'ru,zh'

Inspect and then clear a recipient’s overrides:

pepsi-settings -c /etc/pepsi/pepsi.conf get bob@example.org
pepsi-settings -c /etc/pepsi/pepsi.conf unset bob@example.org block-language BLACKLIST

Load a whole object from a file:

pepsi-settings -c /etc/pepsi/pepsi.conf import vip@example.com /tmp/vip.json

95.1.52.1.11. See Also

pepsi-config(1), pepsi-dispatch(1), pepsi-stage-check-whitelist(1), pepsi-stage-block-language(1), pepsi-stage-edit-settings(1), pepsi.conf(5), pepsi-setup(1)

95.1.52.1.12. Bugs

Report bugs to the Pepsi issue tracker.