95.1.62. pepsi-helper-dot-forward

run a single user’s ~/.forward as that user

Manual section:

1

95.1.62.1.1. Name

pepsi-helper-dot-forward - privileged helper that processes one local user’s ~/.forward after dropping to that user.

95.1.62.1.2. Synopsis

pepsi-helper-dot-forward TARGET-UID [–pipe] [–file] < message

95.1.62.1.3. Description

pepsi-helper-dot-forward is a minimal, security-hardened helper that runs exactly one local user’s ~/.forward file. It exists so that a trusted but unprivileged caller (a member of the pepsi-forward group, in practice pepsi-stage-dot-forward(1)) can have any local user’s ~/.forward processed as that user, and do nothing else.

The helper is installed setuid-root, owned root:pepsi-forward with mode 4750. Only members of the pepsi-forward group may execute it; when they do, the kernel runs it with an effective uid of root. Given the numeric uid of the target user as its sole positional argument, and the raw message on standard input, the helper:

  1. resolves the target user’s passwd entry, refusing uid 0 / the login root and any uid below /etc/login.defs UID_MIN (default 1000);

  2. drops to the target user fully and irreversibly: it installs the user’s supplementary groups, then the gid, then the uid (real, effective and saved), and verifies that root cannot be regained, as pepsi-helper-maildir-writer(1) and pepsi-helper-auto-pay(1) do. When the user’s groups cannot be read, only the primary group is kept;

  3. refuses to act (exit 3) when the home directory, or the ~/.forward itself, is not owned by the target uid or is group- or world-writable (mode & 0o022). This is the sendmail/postfix-local rule: the file names |command and /file directives that the helper runs as that user, so anyone else who can write the directory could plant one. Note that the home directory is checked before the helper looks for ~/.forward, so on a host with group-writable homes the account is refused even when it has no ~/.forward at all;

  4. if the user has no ~/.forward file, exits 1 (the stage then proceeds to its next stage). A file of blank lines and comments gets the same answer, since it directs nothing;

  5. otherwise reads ~/.forward and acts on each non-empty, non-# line as the user: a bare address is collected as a forwarding address, and an address written \name is collected with its marker, which the calling stage reads as sendmail’s “deliver to this name and expand it no further”; |command pipes the message to /bin/sh -c command (only with –pipe); /absolute/path appends the message to that file (only with –file). A directive whose kind was not enabled, or whose execution fails, is a failure. A |command is run with an environment built from scratch: HOME, USER, LOGNAME and SHELL from the target user’s passwd entry (/bin/sh when its shell field is empty) and PATH set to /usr/local/bin:/usr/bin:/bin. Nothing else is set and nothing is inherited from the caller, so the delivery agent cannot steer the command through variables such as PYTHONPATH, PERL5LIB or BASH_ENV.

A |command runs in its own process group and is given 300 seconds; on expiry the entire group is SIGKILLed (the group, because a pipe directive routinely forks) and the run is reported as a temporary failure (exit 3), so the message is retried rather than bounced. A /path directive opens the target with O_NOFOLLOW|O_NONBLOCK and refuses anything that is not a regular file, so a FIFO or a symlink cannot block the helper indefinitely. Without these bounds any local account could wedge a dispatcher worker for the lifetime of the pipeline simply by writing |sleep infinity in its ~/.forward.

A directive may be written double-quoted, which is the form that the documentation of procmail and maildrop tells users to use: "|IFS=' ' && exec /usr/bin/procmail -f- || exit 75 #bob". One line may also carry several comma-separated entries, as permitted by the grammar for the right-hand side of the alias database, which .forward inherits. One layer of surrounding double quotes is removed before the directive is classified, and a comma inside double quotes does not split.

The message is read from standard input only when a |pipe//file directive that consumes it may run (i.e. when –pipe or –file is given).

95.1.62.1.4. Arguments

TARGET-UID

The numeric user id whose ~/.forward is processed. It must have a passwd entry; uid 0 / the root account and any uid below /etc/login.defs UID_MIN are refused.

–pipe

Permit |command directives (the stage passes this when its ALLOW_PIPE is on).

–file

Permit /path file-append directives (the stage passes this when its ALLOW_FILE is on).

95.1.62.1.5. Exit Status

0

The ~/.forward was processed successfully. The forwarding addresses that it named are written one per line to standard output.

1

The user has no ~/.forward, or one with only blank lines and comments. The caller proceeds to its next stage.

2

Processing failed: a pipe command exited non-zero (other than 75) or was killed by a signal, a file could not be written, a disabled directive was requested, or the ~/.forward names more than 100 addresses. A human-readable diagnostic is written to standard output for inclusion in the bounce. This is a permanent failure of that recipient.

3

An operational failure of the host, not of the delivery: the helper is not installed setuid-root, the target uid has no passwd entry or the passwd lookup itself failed (an NSS/LDAP outage), the account is root or below UID_MIN, the home directory is not absolute, or the home directory or the ~/.forward itself is not exclusively the target user’s (not owned by them, or group-/world-writable). The diagnostic goes to both standard output and standard error. The caller must treat this as retryable: the message stays queued rather than being bounced for a condition that the operator can fix.

The unsafe-home case is a property of the account rather than of the message: with chmod 0775 ~alice every message to alice stops here and stays queued, and none of them reach local delivery. chmod g-w,o-w on the home directory (and on ~/.forward) is the fix.

A |command that asks to be tried again also exits 3: one that exits 75 (EX_TEMPFAIL, what procmail and maildrop report for a locked mailbox or a full disk), one that runs past the 300-second limit, and one that cannot be started at all. The command’s own diagnostic goes to both output streams. Directives earlier in the file have already acted by then and act again on the retry, as they would under any delivery agent that defers part of the way through a .forward.

4

|command or /file directives took the message and the ~/.forward names no address. Nothing is left to deliver for this recipient.

When invoked by a user who is not a member of the pepsi-forward group, the kernel refuses to execute the binary at all; the helper itself never runs.

95.1.62.1.6. Security

Membership of the pepsi-forward group is the access-control gate. The helper runs arbitrary commands and writes arbitrary files only as the unprivileged target user, never as root: it drops privilege completely before reading the ~/.forward or touching any of the user’s files, and refuses to act for the root account. Only the first 64 KiB of ~/.forward are read.

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

95.1.62.1.7. See Also

pepsi-stage-dot-forward(1), pepsi-helper-maildir-writer(1), pepsi-dispatch(1), pepsi.conf(5)

95.1.62.1.8. Bugs

Report bugs to the Pepsi issue tracker.