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_originistrue) and has a non-empty envelope sender (a null-sender message is never a control message);its
Subject:is exactly SUBJECT (defaultPepsi); andone of its envelope recipients is
<CONTROL_LOCAL_PART>@<domain>(default local partpepsi) for adomainthe 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
PROGRAMis only accepted when its value is apepsi-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_HELPERandPIN_COMMAND;an assignment that sets an identity option (
SIGNING_DOMAIN,WALLET_MODE,WALLET_SCOPEorWALLET_USER) or a spending limit (MAX_TOTALorMAX_TOTAL_PER_DAY) is refused outright, however permissiveEDITABLE_STAGESis.
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, elseinfo).- -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.