45. pepsi-stage-dot-forward

Process per-user ~/.forward files.

45.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. The stage normally sits just before local delivery. Reference: pepsi-stage-dot-forward(1).

45.2. Features

45.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 that the ~/.forward named; those restart the pipeline at RESTART_STAGE (default init) so they are re-authenticated and re-routed like fresh mail, after a random hold of up to [pepsi] REFLECTION_HOLD_MAX (30 s), since a forwarded copy is reflected mail (Unknown recipients and backscatter). An empty result (the message was consumed by a |pipe//file directive) drops the recipient.

  • Failed — the recipient is routed to BOUNCE_STAGE when its ~/.forward fails: a pipe command error, a file write error, a disabled directive, more than 100 addresses, or an address that the stage refuses as unusable (over 256 octets, white space, control characters, < > " , ; or an invalid domain).

  • Host problem — the helper could not act at all (not installed setuid-root, a passwd lookup failure, a home directory or ~/.forward that is not exclusively the user’s), or a |command asked to be tried again (exit 75, EX_TEMPFAIL) or ran out of its 300 seconds. Nothing is bounced: the message stays queued and is retried until MAX_LIFETIME, and the recipients already processed in that pass are committed first, so no ~/.forward runs twice for them.

A message with several recipients can mix these; the forwarded addresses, the per-recipient bounces and the kept recipients are reconciled in one split of the message followed by its terminal (one statement when no recipient stays on the message).

45.2.2. ~/.forward directives

The helper acts on each entry as the user. It skips blank and # lines, and a line may hold several comma-separated, optionally double-quoted entries. A bare address becomes a forwarding address. |command pipes the message to /bin/sh -c when ALLOW_PIPE is on, with an environment built only from the user’s passwd entry and a fixed PATH. /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.

An address written with sendmail’s leading \ means “deliver to this name and expand it no further”, and is not restarted at RESTART_STAGE. The canonical line for keeping a local copy, \bob in ~bob/.forward, simply keeps that envelope recipient on this row, so it advances to NEXT_STAGE and is delivered locally; any other \name becomes a sibling row at NEXT_STAGE. That is also what stops a \ entry re-entering this stage.

45.2.3. Loop prevention

Because forwarding restarts the pipeline, every forwarded row carries its forwarding chain in state["dot-forwarders"] (see The message state): the chain of the row it came from plus the login whose ~/.forward forwarded it. A recipient whose user is already in its row’s chain is routed to BOUNCE_STAGE without re-running its ~/.forward (a null-sender message is dropped instead), so a forwarding cycle terminates and the sender is told. The chain is per forwarding path: several recipients of one message that forward each get a sibling row carrying only their own chain.

45.2.4. Recycled addresses

A local recipient whose RRVS= parameter or Require-Recipient-Valid-Since field names a date before a recorded change of owner of its login is bounced with 550 5.7.17 before the helper runs, so a new owner’s ~/.forward cannot carry the message away (A login that changes owner). Forwarded addresses do not inherit the request.

45.3. Privileges

The stage must be installed setgid pepsi-forward, with mode 2550 and owner pepsi:pepsi-forward. Only the owner may execute it, so no other local user reaches the setgid bit. That group membership is what lets the dispatcher’s pepsi worker exec the 4750 root:pepsi-forward helper. Only the helper runs the ~/.forward as the target user, and it refuses to act for root or any uid below UID_MIN. The stage enforces the rule itself as well: running with the setgid bit, it refuses a real user other than root or pepsi before reading any configuration. The helper refuses a home directory or ~/.forward that is not exclusively the user’s (a host problem, so the message waits), opens ~/.forward without following symlinks, and runs a |command in its own process group with an environment built only from the user’s passwd entry; a command gets 300 seconds and the helper as a whole 330 before it is killed and retried. See The privilege split and A local shell user. Carrying that bit is why the stage is a standalone binary rather than one of the programs folded into the unified pepsi binary.

45.4. Configuration

[stage-<name>]: PROGRAM = pepsi-stage-dot-forward, NEXT_STAGE (where a passthrough recipient goes — normally local delivery), BOUNCE_STAGE (where a failed ~/.forward recipient goes), RESTART_STAGE (default init), ALLOW_PIPE and ALLOW_FILE (both default yes), HELPER (default pepsi-helper-dot-forward) and the shared locality options LOCAL_DOMAINS (defaulting to [pepsi-ingress] ACCEPTED_DOMAINS), TARGETS and RECIPIENT_DELIMITER. pepsi-setup checks that RESTART_STAGE names a real stage. See pepsi-stage-dot-forward(1).

45.5. State

  • Inputs: state["dot-forwarders"] (the loop guard) and state.dsn.

  • Outputs: state["dot-forwarders"] on every forwarded row (restarted or \name): the source row’s chain plus the login whose ~/.forward produced it. state.dsn.rcpt is rebuilt in lockstep with each row’s recipients, and each forwarding target is marked with expanded_from (the recipient it replaces). A DSN about a target therefore names only that recipient (pepsi-stage-bounce), and a copy sent off-site leaves with a forward return address (pepsi-stage-srs, Forwarding addresses in delivery reports), so that a report from the target’s own server is answered the same way rather than relayed. A bounced recipient’s row carries state.bounce.

45.6. See also

pepsi-stage-relay-to-maildir, pepsi-stage-aliases, pepsi-stage-bounce, Supported Features, pepsi-stage-dot-forward(1), pepsi-helper-dot-forward(1).