95.1.35. pepsi-stage-if¶
branch a message on a test of its stored state value
- Manual section:
1
95.1.35.1.1. Name¶
pepsi-stage-if - the conditional-branch stage of the Pepsi pipeline.
95.1.35.1.2. Synopsis¶
pepsi-stage-if [GLOBAL-OPTIONS] worker
95.1.35.1.3. Description¶
This stage defaults to FUSION = yes: when stage fusion is enabled ([pepsi]
ALLOW_FUSION, the default) and this stage is folded into the unified pepsi
binary, a predecessor may run it in its own worker process instead of
dispatching it separately. See pepsi-dispatch(1) and pepsi.conf(5).
pepsi-stage-if 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 tests one member of the message
state JSON for equality against a configured value: if they are equal it
advances the message to TRUE_STAGE, otherwise to FALSE_STAGE. It is a
programmable fork: an operator can route on any verdict that an earlier stage
recorded (state.spam, state.auth.dkim, …) without writing code.
The stage only ever moves the stage column. It never rewrites the message,
never pauses or fails it, and leaves state untouched, so state.dsn and
every other verdict are preserved across the branch. The message body is never
loaded.
95.1.35.1.4. Condition¶
STATE_PATH is a dot-separated path into the state JSON. A segment
applied to an object selects the member of that name (even a numeric one);
applied to an array it must be a non-negative integer and selects that position.
For example, spam selects the top-level spam flag, auth.dkim the
dkim member of the auth object, and dsn.rcpt.0.notify the
notify field of the first recipient entry.
The value found there is compared to VALUE by its natural textual form:
a string matches its own text (
passmatchespass);a boolean matches
trueorfalse;a number matches its decimal rendering (
3,1.5);JSON null matches the literal
null.
A path that is absent is never equal, and neither is a path that resolves to an array or object, which has no scalar form; such a path takes the FALSE_STAGE branch. VALUE is required and cannot be empty (an empty option reads as unset).
95.1.35.1.5. Configuration¶
Options live in the stage’s own [stage-<name>] section
(PROGRAM = pepsi-stage-if): the STATE_PATH to test, the VALUE to
compare against, and the TRUE_STAGE/FALSE_STAGE branch targets. All four
are required, and pepsi-setup additionally checks that both branch
targets name existing stages. The stage has no NEXT_STAGE (both destinations
are named explicitly). The options are documented in pepsi.conf(5).
All four options are read from the stage’s section after per-address settings
are applied, so when the stage is listed in the EDITABLE_STAGES of a
pepsi-stage-edit-settings(1) stage, a correspondent can change the test
and both branch targets for their own mail.
Never list an if stage that guards a security decision there (see
pepsi-settings(1) and the settings boundary in the manual’s Threat model
chapter).
95.1.35.1.6. State¶
Inputs: the single member of state selected by STATE_PATH.
Outputs: none; the stage only advances the message and leaves state
unchanged. The state layout is described in pepsi.state(7).
Transitions: advances to TRUE_STAGE when the member selected by STATE_PATH equals VALUE (compared by scalar text form), otherwise to FALSE_STAGE. A missing path or a non-scalar value also takes the FALSE_STAGE branch. These two advances are the only transitions; the stage never pauses, fails, reroutes or finishes.
95.1.35.1.7. Commands¶
- worker
Run as a persistent pepsi-dispatch(1) worker, reading message ids on standard input.
95.1.35.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.35.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 STATE_PATH/VALUE/TRUE_STAGE/FALSE_STAGE). The dispatcher requeues what it handed over and retries the stage later.
95.1.35.1.10. Examples¶
Reprocess message 42 through a one-off worker (it must be running):
echo 42 | pepsi-stage-if -c /etc/pepsi/pepsi.conf worker
A pipeline section that sends mail that an earlier stage flagged as spam
(state.spam == true) to the bounce stage and everything else onward:
[stage-if]
PROGRAM = pepsi-stage-if
STATE_PATH = spam
VALUE = true
TRUE_STAGE = bounce
FALSE_STAGE = srs
The next example holds encrypted mail from strangers that nobody here can read. A message encrypted to a key held only in a recipient’s client passes every content filter as ciphertext, and so does a message that no key here fits. With pepsi-stage-decrypt(1) first on the inbound path and pepsi-stage-check-whitelist(1) after it, two branches hold mail that no key here could open when it comes from a sender that the whitelist did not pass:
[stage-whitelist]
PROGRAM = pepsi-stage-check-whitelist
WHITELIST_NAME = default
NEXT_STAGE = known-sender
# Whitelisted senders (state.spam = false) go on unchecked.
[stage-known-sender]
PROGRAM = pepsi-stage-if
STATE_PATH = spam
VALUE = false
TRUE_STAGE = deliver
FALSE_STAGE = undecryptable
# Mail no key here could open waits in a quarantine.
[stage-undecryptable]
PROGRAM = pepsi-stage-if
STATE_PATH = crypto.in.failure
VALUE = no-decryption-key
TRUE_STAGE = hold
FALSE_STAGE = deliver
hold is any stage that keeps the message from the user without telling
the sender: a delivery into a quarantine mailbox, or
pepsi-stage-discard(1). Two rules are not negotiable. Branch only on
no-decryption-key, which means that no key here fits the message, and never
on decryption-failed or on crypto.in.decrypted = false: whether a
modified AES-CBC ciphertext decrypts depends on its padding, so a route that
differs between the two would tell an attacker the answer the moment they
can observe it. And never route the held mail to a bounce stage, for the
same reason. Mail encrypted to the user’s own client key
(crypto.in.for_client) carries no failure and is not held; add a third
branch on crypto.in.for_client = true only if such mail from strangers is
unwanted too.
95.1.35.1.11. See Also¶
pepsi-config(1), pepsi-stage-check-whitelist(1), pepsi-stage-bounce(1), pepsi-dispatch(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1)
95.1.35.1.12. Bugs¶
Report bugs to the Pepsi issue tracker.