44. pepsi-stage-relay-to-maildir

Deliver to local users’ Maildirs; forward the rest.

44.1. Role

pepsi-stage-relay-to-maildir is the local-delivery stage. For each envelope recipient it decides whether the address is local and, if so, writes the message into that user’s Maildir/new/ via the setuid-root pepsi-helper-maildir-writer(1) helper; every other recipient is forwarded to NEXT_STAGE. Reference: pepsi-stage-relay-to-maildir(1).

44.2. Features

44.2.1. Local recipient matching

  • A recipient is local when its domain is in LOCAL_DOMAINS (default [pepsi-ingress] ACCEPTED_DOMAINS), its mailbox name resolves to a passwd entry, and that uid is permitted by TARGETS.

  • TARGETS is an allow-list of user names, uids, and uid ranges (alice, 452, 1000-1100, 10000-); it defaults to the regular (non-system) uid range from /etc/login.defs. The helper refuses any uid below UID_MIN regardless, so a system account listed here is bounced.

  • The mailbox name is the local-part with any RECIPIENT_DELIMITER sub-address (default +) stripped, lower-cased.

44.2.2. Partial delivery

  • Local recipients are written to their Maildirs; the remaining recipients are split onto a new pending row, and where depends on why they are not local. A recipient on somebody else’s domain is a forward and goes to NEXT_STAGE, which should reach the SRS relay tail. A recipient on one of our LOCAL_DOMAINS that resolves to no permitted account is an unknown mailbox and goes to UNKNOWN_MAILBOX_STAGE, which should lead to a bounce. Relaying it instead would look up our own MX, find this host and post the message back to ourselves. UNKNOWN_MAILBOX_STAGE defaults to NEXT_STAGE.

  • Two addresses for the same local account are delivered only once.

  • A passwd lookup that fails (a directory backend that is down) retries the whole message before anything is delivered; it is never taken as “no such user”.

  • Each local copy gets a Return-Path:, a Delivered-To: loop guard and a Received: trace header prepended.

44.2.3. Retry, bounce and DSN

  • The helper’s exit code decides whether retrying can help. A transient failure (a full disk, an I/O error, a helper not yet installed setuid, a passwd lookup that fails, a helper that could not be run at all) pauses that recipient with exponential backoff up to MAX_LIFETIME and only then routes it to BOUNCE_STAGE. A permanent failure is bounced at once, since no retry can deliver it: the mailbox itself is unusable (wrong ownership or mode, no home, a uid below UID_MIN). A bounce is never re-bounced, a stage with no BOUNCE_STAGE drops the recipient with a warning, and the sender’s NOTIFY is honoured throughout.

  • An over-quota recipient (the helper’s own quota exit) is handled per [pepsi] MAILBOX_OVER_QUOTA: defer (the default) retries it like any transient failure, bounce routes it to QUOTA_LIMIT_STAGE with a 5.2.2 status (falling back to BOUNCE_STAGE). A kernel EDQUOT counts as over quota too. See pepsi-quota.

  • Originates a positive DSN on successful local delivery when [pepsi] ORIGINATE_SUCCESS_DSN is set and the recipient asked for NOTIFY=SUCCESS.

44.2.4. Recycled addresses (RFC 7293)

  • Before writing anything the stage records each local recipient’s login and uid in pepsi.login_assignment; a login seen under a new uid has a new owner, and the previous owner’s per-address state is dropped (A login that changes owner).

  • A recipient whose RRVS= parameter or Require-Recipient-Valid-Since field names a date before a recorded change of owner is not delivered but bounced with 550 5.7.17; role addresses (RFC 2142) are never tested. Require-Recipient-Valid-Since fields are removed from the stored copy.

44.2.5. Privilege model

  • The stage binary is installed setgid pepsi-maildir, mode 2550 pepsi:pepsi-maildir. The dispatcher runs it as the unprivileged pepsi user; the setgid bit grants the effective gid that is needed to exec the group-restricted helper, and nothing else on the host gains that ability. The mode 2550 exists for this last point: at 2755 every local user could exec the stage and inherit the same gid, and from there the setuid-root helper. pepsi cannot take the exec right from the group (it is deliberately not a member), so it takes it from the owner bits instead.

  • The program enforces the same rule itself: running with the setgid bit, it refuses a real user other than root or pepsi before reading any configuration, and strips the environment variables that steer configuration loading.

  • The helper becomes the recipient completely (real, effective and saved ids) and refuses any uid below UID_MIN. See The privilege split and A local shell user.

44.3. Configuration

[stage-<name>] with PROGRAM = pepsi-stage-relay-to-maildir: SERVER_NAME (required), TARGETS, LOCAL_DOMAINS, RECIPIENT_DELIMITER, HELPER (default pepsi-helper-maildir-writer), NEXT_STAGE/BOUNCE_STAGE, UNKNOWN_MAILBOX_STAGE, QUOTA_LIMIT_STAGE and the retry policy (RETRY_INITIAL/RETRY_MAX_INTERVAL/RETRY_FACTOR/MAX_LIFETIME). pepsi-setup checks that UNKNOWN_MAILBOX_STAGE and QUOTA_LIMIT_STAGE name real stages. Full reference: pepsi-stage-relay-to-maildir(1).

44.4. State

  • Inputs: state.dsn (per-recipient NOTIFY/ORCPT) and state.attempts (the retry count).

  • Outputs: attempts/last_error on pause; a state.bounce object on the rows enqueued for the bounce stage; the per-recipient state.dsn is sliced onto each split row. state.dsn/state.origin are preserved.

44.5. See also

pepsi-stage-relay-to-lmtp (the LMTP alternative), pepsi-stage-relay-to-smarthost, pepsi-stage-relay-to-internet, pepsi-stage-bounce, pepsi-quota, Supported Features, pepsi-stage-relay-to-maildir(1), pepsi-helper-maildir-writer(1).