95.1.14. pepsi-stage-dot-forward

process per-user ~/.forward files

Manual section:

1

95.1.14.1.1. Name

pepsi-stage-dot-forward - the ~/.forward processing stage of the Pepsi pipeline.

95.1.14.1.2. Synopsis

pepsi-stage-dot-forward [GLOBAL-OPTIONS] worker

95.1.14.1.3. Description

pepsi-stage-dot-forward is a stage program run by pepsi-dispatch(1). For each envelope recipient that resolves to a local account it runs that user’s ~/.forward file, the classic sendmail/Postfix mechanism by which an account owner redirects their own mail. Locality is decided exactly as in pepsi-stage-relay-to-maildir(1): the recipient’s domain must be in LOCAL_DOMAINS, its mailbox name (local-part, sub-address after RECIPIENT_DELIMITER removed, lower-cased) must resolve to a passwd entry, and that uid must be permitted by TARGETS. A recipient that is not local is left untouched and advances to NEXT_STAGE. A passwd lookup that fails (an LDAP or sssd backend that is down) is not taken to mean “not local”: the message is retried, rather than delivered past the user’s ~/.forward.

The ~/.forward itself is read and executed by the privileged helper pepsi-helper-dot-forward(1), which drops to the target user first. The helper’s exit status tells the stage what became of that recipient:

  • no ~/.forward — the recipient is a passthrough: it stays on the message, which advances to NEXT_STAGE (typically local delivery, then a smarthost). An empty ~/.forward, or one with only blank lines and comments, directs nothing and counts as none. A recipient kept by its own \name entry advances to NEXT_STAGE too, but, whenever the message is split, on a sibling row of its own, so that no retry of this stage runs its ~/.forward a second time.

  • forwarded — the recipient is replaced by the addresses that the ~/.forward named. Those restart the pipeline at RESTART_STAGE (default init) on a new sibling row, so the rewritten recipients are re-authenticated and re-routed like fresh mail. Each address records the recipient it replaces (expanded_from in its state.dsn entry, beside an ORCPT naming it), so a DSN that Pepsi writes about it names only that recipient, with a generic diagnostic (pepsi-stage-bounce(1)): a ~/.forward’s targets are not disclosed to the sender. A copy sent off-site leaves with a forward return address (pepsi-stage-srs(1)) rather than an SRS one, so a report that the target’s own server sends comes back to pepsi-ingress(1), which answers it with the same kind of DSN and does not pass it on. The row starts paused for a random time of up to [pepsi] REFLECTION_HOLD_MAX (default 30 s; pepsi.conf(5)), since a forwarded copy is reflected mail; the dispatcher then releases it.

  • consumed — |pipe or /file directives took the message and the ~/.forward names no address (exit 4). The recipient has its mail and leaves the message.

  • failed — the helper refused or failed for that recipient (exit 2): a pipe command exited non-zero (other than 75), a file could not be written, a disabled directive was requested, or the ~/.forward names more than 100 addresses; or the stage refused an address that the helper returned (one longer than 256 octets, containing white space, a control character or one of < > " , ;, or with an invalid domain). The recipient is routed to BOUNCE_STAGE so that a failure DSN is generated (honouring the sender’s NOTIFY). A message that is itself a bounce (null sender) is never re-bounced.

  • host problem — the helper reported an operational failure (exit 3), a |command asked to be tried again, or the helper could not be run at all, was killed by a signal, or exited with a status that it does not document. An operational failure means that the helper is not installed setuid-root, that the passwd lookup failed, that the account is refused (root, a uid below UID_MIN, a relative home directory), that the home directory or ~/.forward is not exclusively the user’s (not owned by them, or group- or world-writable), or that the ~/.forward is a symbolic link, is not a regular file or cannot be read. The helper checks the home directory before looking for a ~/.forward, so this also refuses accounts that have none. A |command asks to be tried again when it exits 75 (EX_TEMPFAIL), runs out of time or cannot be started. None of these is a verdict on the recipient, so nothing is bounced: the message is retried (one minute, doubling to an hour, until MAX_LIFETIME, after which it goes to BOUNCE_STAGE, or is failed when there is none; see pepsi-dispatch(1)).

    The recipients processed earlier in the same pass have been dealt with: their pipes have run and their files have been written. Before the retry, they are therefore committed with their outcome (forwarded, kept, bounced), and the message is reduced to the recipients that the helper did not reach. A retry therefore never runs a recipient’s ~/.forward twice. The one exception is the recipient whose own ~/.forward deferred part-way through: directives above the one that deferred have acted, and act again.

A single message may have a mix of these outcomes across its recipients; the forwarded addresses, the per-recipient bounces and the kept (passthrough) recipients are reconciled in one split of the message, followed by its terminal (in the same statement when no recipient stays on the message). Every sibling row’s token is derived from the recipient or forwarding login it carries, so a retried pass can never collide with one that an earlier pass created.

95.1.14.1.4. Forwarding loops

Because a forwarded message restarts the whole pipeline, two users forwarding to each other (~bob → alice, ~alice → bob) would loop. To prevent this, every forwarded row carries its forwarding chain in state["dot-forwarders"] (see pepsi.state(7)): the chain of the row it was forwarded from plus the login whose ~/.forward forwarded it. A recipient whose user is already in its row’s chain is not delivered and the helper is not called (a warning is logged), so the chain terminates. The recipient is routed to BOUNCE_STAGE like any other ~/.forward failure, so the sender is told (RFC 5321 §6.1 requires a notification once the message has been accepted). If the message is itself a bounce, the recipient is dropped instead.

The chain belongs to one forwarding path, not to the message: when several recipients of one message forward, each one’s addresses go out on a sibling row of their own carrying only that recipient’s chain. A later hop through one recipient’s ~/.forward is therefore never mistaken for a loop because of another recipient’s entry in the chain. An address that several of them forward to is delivered once, on the row of the first recipient that named it.

95.1.14.1.5. Recycled addresses (RFC 7293)

A ~/.forward is its owner’s own redirection. Under RFC 7293 section 5.2.1, it passes the continuous-ownership test only for the owner that the sender meant. A local recipient may carry a request for ownership since a date (an RRVS= parameter, or a Require-Recipient-Valid-Since header field naming the recipient; see pepsi-stage-relay-to-maildir(1)). When the recipient’s login has a recorded change of owner after that date, the recipient is therefore bounced with 550 5.7.17 via BOUNCE_STAGE before the helper runs, so that the new owner’s forwarding cannot carry the message away. For such a recipient the check records the login’s current uid in pepsi.login_assignment as local delivery does (a recipient without a request is not recorded here); a database error retries the recipient. Forwarded addresses do not inherit the request (RFC 7293 section 8.2: Pepsi holds no ownership record for the new destination).

95.1.14.1.6. Arguments and sub-commands

worker

Run as a persistent pepsi-dispatch(1) worker, reading message ids on standard input and writing one status line each. This is how the dispatcher runs the stage in production.

95.1.14.1.7. Configuration

Read from the message’s [stage-<stage>] section:

PROGRAM

Must be pepsi-stage-dot-forward.

RESTART_STAGE

The stage at which a successfully forwarded message restarts. Defaults to init (re-running the full inbound pipeline, including authentication). Set it to a later stage (e.g. srs) to skip re-authenticating an internally forwarded message. Must name an existing stage.

ALLOW_PIPE

Whether |command directives in a ~/.forward are honoured (the message is piped to the command, run as the user). Defaults to yes.

ALLOW_FILE

Whether /path directives (append the message to a file) are honoured. Defaults to yes. When both ALLOW_PIPE and ALLOW_FILE are no the stage does not pipe the message body to the helper at all (the helper only needs to read forwarding addresses).

TARGETS, LOCAL_DOMAINS, RECIPIENT_DELIMITER

The local-account selection, identical in meaning to pepsi-stage-relay-to-maildir(1). TARGETS defaults to the regular (non-system) uid range from /etc/login.defs, and pepsi-helper-dot-forward(1) refuses any uid below UID_MIN whatever it says (pepsi-setup(1) warns about a token that reaches below it); LOCAL_DOMAINS defaults to [pepsi-ingress] ACCEPTED_DOMAINS; RECIPIENT_DELIMITER defaults to [pepsi] RECIPIENT_DELIMITER and, failing that, to + (none disables sub-address stripping).

HELPER

The privileged ~/.forward helper to run. Defaults to pepsi-helper-dot-forward (resolved on $PATH); set an absolute path to override.

NEXT_STAGE

Where passthrough recipients (no ~/.forward) advance. Required, since most recipients have no ~/.forward. The stage is normally placed just before local delivery, so NEXT_STAGE is the local-delivery stage.

BOUNCE_STAGE

The stage that generates DSNs. A recipient is routed there when running its ~/.forward fails. Without it, that recipient stays on a row with the status failed, with the diagnostic in state.last_error, for pepsi-failure-bouncer(1) or an operator to find.

95.1.14.1.8. A ~/.forward file

The helper reads at most the first 64 KiB of the user’s ~/.forward. Blank lines and lines starting with # are skipped; a line may hold several entries separated by commas, and an entry may be enclosed in double quotes (a comma inside quotes does not separate), as in procmail’s documented "|exec /usr/bin/procmail". Each entry is one of:

  • an e-mail address — collected and used as a new recipient. A bare name such as alice means that account at this site: it is qualified with the recipient’s domain, so alice in mail to bob@example.com becomes alice@example.com;

  • \name — sendmail’s “deliver to name and expand it no further” marker. The address is not restarted at RESTART_STAGE: if it names the recipient’s own account (the canonical \bob in ~bob/.forward, which is how a user keeps a local copy while also forwarding), that recipient simply stays on the message and advances to NEXT_STAGE. Any other \name becomes a sibling row at NEXT_STAGE; a bare name is qualified with the recipient’s domain. Because such a recipient never re-enters this stage, the marker cannot create an unbounded loop. Note that it also bypasses that user’s own ~/.forward, which is what “expand no further” means;

  • |command — when ALLOW_PIPE is on, the message is piped to /bin/sh -c command run as the user, in a process group of its own and with an environment built from scratch: HOME, USER, LOGNAME and SHELL from the user’s passwd entry and PATH fixed to /usr/local/bin:/usr/bin:/bin; nothing is inherited from the stage;

  • /absolute/path — when ALLOW_FILE is on, the message is appended to that file (mbox style) as the user.

A bare name restarts at RESTART_STAGE like any other address, so the recipient’s own name comes back to this stage as a forwarding loop and is bounced. To keep a local copy, write \name.

A |command is given 300 seconds to finish, after which its whole process group is killed and the recipient is retried like a command that exited 75 (a slow delivery agent tells us nothing about the recipient, and bouncing it would discard mail that would have been accepted a minute later). The stage in turn abandons and kills a helper that has not finished after 330 seconds, and reports this as a retryable error rather than a bounce. Both limits are compile-time constants, not configuration. They exist so that one account’s |sleep infinity, or a file directive naming a FIFO, cannot occupy a dispatcher worker for ever, and so that PARALLELISM such accounts cannot stop the stage. A file directive must name a regular file; a FIFO, device or symlink is refused.

95.1.14.1.9. Installation and privileges

To reach the setuid-root helper, pepsi-stage-dot-forward must itself be installed set-group-id to the pepsi-forward group, with mode 2550 and owner pepsi:pepsi-forward. The mode allows owner-execute and not world-execute, because the setgid bit is the gate on the setuid-root helper. The right to execute cannot come from the group bits either, since pepsi is deliberately not a member of the group, so it comes from the owner. pepsi-dispatch(1) runs the stage as the unprivileged pepsi service user. The setgid bit gives the worker an effective gid of pepsi-forward, which is exactly what lets it execute the group-restricted pepsi-helper-dot-forward(1); nothing else on the host gains that ability. make install sets this up (its install-forward-stage step), provided it is run as root and the pepsi-forward group exists; otherwise it prints the exact commands to run by hand.

Because the setgid bit is that gate, the program enforces the same rule itself. When it runs with that bit and the real user is neither root nor the pepsi service account, it exits with an error before any configuration is read. Like the setuid crypto stages, it also strips the environment variables that steer configuration loading (HOME, XDG_CONFIG_HOME, PG*, TALER_*, PEPSI_*) and pins PATH to a safe default. The file mode belongs to the deployment and this check belongs to the program, so neither has to provide the protection on its own.

The Security chapter of the Pepsi manual lists every program carrying a setuid or setgid bit and why; its Threat model chapter states what a local account can and cannot gain through them.

95.1.14.1.10. See Also

pepsi-helper-dot-forward(1), pepsi-stage-relay-to-maildir(1), pepsi-stage-aliases(1), pepsi-stage-bounce(1), pepsi-dispatch(1), pepsi.conf(5), pepsi.state(7)

95.1.14.1.11. Bugs

Report bugs to the Pepsi issue tracker.