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 (pass matches pass);

  • a boolean matches true or false;

  • 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, else info).

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