35. pepsi-stage-dot-forward

Process per-user ~/.forward files.

35.1. Role

pepsi-stage-dot-forward lets a local account owner redirect their own mail with a ~/.forward file. For each envelope recipient that is local (the same LOCAL_DOMAINS / TARGETS / RECIPIENT_DELIMITER test as pepsi-stage-relay-to-maildir) it runs that user’s ~/.forward via the setuid-root pepsi-helper-dot-forward(1) helper, which drops to the user first. Non-local recipients are left untouched. Normally placed just before local delivery. Reference: pepsi-stage-dot-forward(1).

35.2. Features

35.2.1. Per-recipient outcomes

  • No ~/.forward — the recipient is a passthrough and advances to NEXT_STAGE (typically local delivery).

  • Forwarded — the recipient is replaced by the addresses the ~/.forward named; those restart the pipeline at RESTART_STAGE (default init) so they are re-authenticated and re-routed like fresh mail. An empty result (the message was consumed by a |pipe//file directive) drops the recipient.

  • Failed — a failed ~/.forward (pipe command error, file write error, or a disabled directive) routes the recipient to BOUNCE_STAGE.

A message with several recipients can mix these; the forwarded addresses, the per-recipient bounces and the kept recipients are reconciled in one database round-trip.

35.2.2. ~/.forward directives

The helper acts on each non-empty, non-# line as the user: a bare address (optional leading \) becomes a forwarding address; |command pipes the message to a shell when ALLOW_PIPE is on; /absolute/path appends the message to a file when ALLOW_FILE is on. When both ALLOW_PIPE and ALLOW_FILE are off the message body is not even handed to the helper.

35.2.3. Loop prevention

Because forwarding restarts the pipeline, the stage records every processed login in the message state["dot-forwarders"] array (see The message state). A recipient whose user is already listed is dropped without re-running its ~/.forward, so a forwarding cycle terminates.

35.3. Privileges

The stage must be installed setgid pepsi-forward (mode 2755); that group membership is what lets the dispatcher’s pepsi worker exec the 4750 root:pepsi-forward helper, which alone runs the ~/.forward as the target user and refuses to act for root.