95.1.34. pepsi-stage-edit-settings

change per-address settings from a control e-mail

Manual section:

1

95.1.34.1.1. Name

pepsi-stage-edit-settings - the settings-by-e-mail stage of the Pepsi pipeline.

95.1.34.1.2. Synopsis

pepsi-stage-edit-settings [GLOBAL-OPTIONS] worker

95.1.34.1.3. Description

pepsi-stage-edit-settings is a stage program run by pepsi-dispatch(1) as a persistent worker reading message ids on standard input. It loads the message’s pepsi.workqueue row (refusing to act unless its status is running), reads its [stage-<stage>] section, and decides whether the message is a settings-control message that an account owner sent to change their own per-address settings (the pepsi.settings overrides described in pepsi-settings(1)).

A message is a control message only when all of these hold:

  • it is locally originated (state.local_origin is true) and has a non-empty envelope sender (a null-sender message is never a control message);

  • its Subject: is exactly SUBJECT (default Pepsi); and

  • one of its envelope recipients is <CONTROL_LOCAL_PART>@<domain> (default local part pepsi) for a domain the instance accepts ([pepsi-ingress] ACCEPTED_DOMAINS).

Any other message is advanced unchanged to NEXT_STAGE, so the stage is safe to place anywhere on the local-submission path. A control message that also has ordinary recipients is split first: the control address moves to a row of its own, and the others continue as ordinary mail.

Whether a message is a control message (locally originated, with the right Subject, addressed to the control local part at an accepted domain) can be decided from the message metadata alone, without the body. This stage therefore takes part in stage fusion (see pepsi-dispatch(1)) with a data-dependent gate. It defaults to FUSION = yes, and a predecessor fuses it in-process for every non-control message, which it just advances. For a genuine control message the stage declines fusion: the message is committed and dispatched to a worker of this stage, so that the full body is loaded for parsing. Set FUSION = no to opt out.

The address whose settings are edited is the envelope sender: the owner edits their own settings, and the reply is mailed back to them. (The operator’s submission authentication must therefore bind the envelope sender; otherwise an authenticated user could edit another address’s settings. pepsi-ingress(1) binds it for SASL and local-socket logins through USERNAME_MAP; a MYNETWORKS network or a pinned client certificate is bound only when SENDER_MAP names it.)

95.1.34.1.4. The body

The message body is read as a lenient INI snippet: [stage-<name>] section headers and OPTION = value assignments. Blank lines, comments (#/%/;), a leading greeting, and a trailing signature (a -- line) are ignored, so an ordinary e-mail containing the configuration works. Each assignment adds or overrides the stored override for that stage’s option; an assignment whose value is empty (OPTION =) removes the override, reverting the option to its INI default.

Only sections whose stage name appears in EDITABLE_STAGES may be changed; a body addressing any other section is rejected.

For safety, three kinds of assignment are restricted:

  • an assignment that sets a stage’s PROGRAM is only accepted when its value is a pepsi-stage-* command (with no path component), so that an account owner cannot redirect a stage at an arbitrary executable;

  • an assignment that sets an option naming a program that the stage or a setuid tool runs is refused unless its value is empty, which only restores the operator’s setting. These options are HELPER (what a delivery stage executes with its setgid privilege), SCAN_HELPER, MAILBOX_HELPER and PIN_COMMAND;

  • an assignment that sets an identity option (SIGNING_DOMAIN, WALLET_MODE, WALLET_SCOPE or WALLET_USER) or a spending limit (MAX_TOTAL or MAX_TOTAL_PER_DAY) is refused outright, however permissive EDITABLE_STAGES is.

SIGNING_DOMAIN overrides the domain that a message is DKIM-signed as; allowing it would let any account owner have their mail signed as any domain for which this host holds a key. The wallet options select whose wallet pepsi-stage-auto-pay(1) pays from; allowing them would let an account owner spend from a wallet shared with others. The spending limits are what bounds a stolen submission password. That password also authenticates the control message, so allowing the limits to be changed would let the thief lift the bound. Setting UNRESTRICTED_UNSAFE_STAGES = YES in the stage’s configuration lifts all of these restrictions (unsafe; the default is NO).

For the same reason pepsi-setup --wizard never puts a signing stage in EDITABLE_STAGES: it lists only the inbound gates, the vacation responder and the remote-content switch (pepsi-stage-defang(1)), and where none of those is enabled it does not configure this stage at all.

The stage combines the INI defaults, the address’s existing overrides and the new assignments, and validates the result by running each affected stage’s own configuration parser. On top of that come the checks that apply only to an account owner’s own choice. Two stages write a whitelist on the owner’s behalf: pepsi-stage-auto-whitelist(1), which records the recipients of their outgoing mail, and pepsi-stage-secretary(1), which records the senders who answer a challenge. The WHITELIST_NAME of such a stage must name a whitelist in the sender’s own <login>/... namespace, or the one that the operator’s configuration already names for them; a shared whitelist or another user’s is refused. The login is resolved with the locality options (LOCAL_DOMAINS, RECIPIENT_DELIMITER, TARGETS) of the operator’s stage section, not with any override of the owner’s own. The rule applies only when the message changes the whitelist that the sender’s mail feeds. A value already stored in the row, which the operator may have set with pepsi-settings(1), therefore does not stop the owner from editing other options. This stage is the only way an account owner can write pepsi.settings, so it is where the rule is enforced; the operator’s own layers (the INI file, pepsi.config_override at any scope, and rows written with pepsi-settings(1)) may name any whitelist. The settings are judged on top of the operator’s configuration for the sender, domain: and address: overrides of pepsi.config_override included, and the reply quotes that same effective configuration. If anything is invalid, no change is made and a human-readable reply explains every problem. If everything is valid, the merged overrides are stored and a reply quotes the full effective option set (defaults plus overrides) of every editable stage, in INI syntax.

A stage listed in EDITABLE_STAGES has its whole effective configuration quoted back to any account owner who sends a control message, not just the options they changed. Option values whose names look credential-bearing (contain PASS, SECRET, TOKEN, CREDENTIAL, CLIENT_ID, PEPPER or SYSTEM_ID, so PASSWORD and PASSPHRASE too) are replaced with ***, the same masking that GET /api/v1/config applies. The rest of the section, however, including host names and file paths, is disclosed verbatim. Do not list a stage whose section carries anything you would not show a local user. Which stages are safe to list at all is set out under the settings boundary in the manual’s Threat model chapter (tm-settings) and its Security chapter.

Either reply carries Subject: SUBJECT and the null envelope sender <> (RFC 3834, so that it is never itself gated or bounced). It is injected at RESPONSE_STAGE, where it is DKIM-signed and relayed like any outbound mail. The control message itself is then removed.

The framing prose of both replies is localised: it is rendered from the operator-customizable edit-settings.<lang>.body Mustache template under [pepsi] TEMPLATE_DIR, choosing <lang> from the sender’s detected language(s) (the state.language Accept-Language string set by pepsi-stage-detect-language) and always falling back to English (edit-settings.en.body). In the template, the {{#success}} branch frames the quoted effective settings and the {{^success}} branch frames the problem list.

This stage loads the message body but does not modify it.

95.1.34.1.5. Configuration

Options live in the stage’s own [stage-<name>] section (PROGRAM = pepsi-stage-edit-settings): the required EDITABLE_STAGES allowlist (which must name at least one existing stage), the required RESPONSE_STAGE at which the reply is injected, and a NEXT_STAGE for ordinary mail. NEXT_STAGE is also required, since pepsi-setup(1) refuses a section without one: every non-control message is advanced there. The optional SUBJECT/CONTROL_LOCAL_PART/RESPONSE_FROM control parameters and the UNRESTRICTED_UNSAFE_STAGES safety switch complete the section. They are documented in pepsi.conf(5).

The stage reads its own section from the base configuration, never through the per-address override layer, so no account owner’s pepsi.settings row can change what this stage considers a control message or what it allows.

95.1.34.1.6. State

Inputs: state.local_origin (gates whether the message is a control message), state.language (picks the language of the reply), and the envelope sender/recipients and Subject: header.

Outputs: the stage rewrites the pepsi.settings row of the envelope sender and injects a reply; it does not modify the state of the original message (which it removes). The state layout is described in pepsi.state(7).

Transitions:

  • an ordinary message (not locally originated, or not matching SUBJECT / CONTROL_LOCAL_PART) → advance to NEXT_STAGE unchanged;

  • a control message with other recipients → split the control addresses onto a row of their own, and both rows return to this stage;

  • a control message → inject the reply (the INI echo on success, or the error on a rejected/invalid edit) at RESPONSE_STAGE and finish (the original row is deleted).

The stage never pauses, fails or reroutes.

The confirmation is rendered before the new settings are stored, so a missing reply template is retried with nothing changed. Once they are stored, a reply that cannot be queued is logged and the request deleted: the change is made, and must not be made again.

95.1.34.1.7. Commands

worker

Run as a persistent pepsi-dispatch(1) worker, reading message ids on standard input.

95.1.34.1.8. Global Options

-c FILE, –config FILE

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

-L LOGLEVEL, –log LOGLEVEL

Set the logging verbosity (default [pepsi] LOG, else info).

-v, –verbose

Show log messages from all sources.

-h, –help; -V, –version

Print a usage summary / the version and exit.

95.1.34.1.9. Exit Status

The outcome of each message is reported to pepsi-dispatch(1) on the worker’s status line, not as the exit status.

0

The worker ran until its standard input was closed.

1

A fatal error occurred (unreadable configuration, the database could not be opened, or standard input/output failed). The reason is written to the log.

78

The worker refused to start: a [stage-*] section it serves does not parse (e.g. a missing EDITABLE_STAGES or RESPONSE_STAGE). The dispatcher requeues what it handed over and retries the stage later.

A fault of the host (the database, a reply template that cannot be used) is not reported as a failure: the message is paused and retried, as Stage errors in pepsi-dispatch(1) describes.

95.1.34.1.10. Examples

A pipeline section that lets owners edit their whitelist and language policy, replying via the outbound path:

[stage-edit-settings]
PROGRAM = pepsi-stage-edit-settings
EDITABLE_STAGES = check-whitelist, block-language
RESPONSE_STAGE = dkim-sign
NEXT_STAGE = srs

A control e-mail body (Subject: Pepsi, To: pepsi@example.org) that sets a whitelist and clears a language blacklist:

[stage-check-whitelist]
WHITELIST_NAME = my-contacts

[stage-block-language]
BLACKLIST =

95.1.34.1.11. See Also

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

95.1.34.1.12. Bugs

Report bugs to the Pepsi issue tracker.