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
~/.forwardnamed; those restart the pipeline atRESTART_STAGE(defaultinit) 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//filedirective) drops the recipient.Failed — the recipient is routed to
BOUNCE_STAGEwhen its~/.forwardfails: 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
~/.forwardthat is not exclusively the user’s), or a|commandasked to be tried again (exit75,EX_TEMPFAIL) or ran out of its 300 seconds. Nothing is bounced: the message stays queued and is retried untilMAX_LIFETIME, and the recipients already processed in that pass are committed first, so no~/.forwardruns 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) andstate.dsn.Outputs:
state["dot-forwarders"]on every forwarded row (restarted or\name): the source row’s chain plus the login whose~/.forwardproduced it.state.dsn.rcptis rebuilt in lockstep with each row’s recipients, and each forwarding target is marked withexpanded_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 carriesstate.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).