34. pepsi-stage-relay-to-maildir

Deliver to local users’ Maildirs; forward the rest.

34.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).

34.2. Features

34.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 mailbox name is the local-part with any RECIPIENT_DELIMITER sub-address (default +) stripped, lower-cased.

34.2.2. Partial delivery

  • Local recipients are written to their Maildirs; the remaining recipients are split onto a new pending row at NEXT_STAGE (a smarthost relay, or a bounce stage when no smarthost is configured).

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

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

34.2.3. Retry, bounce and DSN

  • A helper-reported failure (e.g. a full disk) pauses that recipient with exponential backoff up to MAX_LIFETIME, then routes it to BOUNCE_STAGE (honouring the sender’s NOTIFY). A bounce is never re-bounced.

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

34.2.4. Privilege model

  • The stage binary is installed setgid pepsi-maildir (mode 2755). The dispatcher runs it as the unprivileged pepsi user; the setgid bit grants the effective gid needed to exec the group-restricted helper — and nothing else on the host gains that ability.

34.3. Configuration

[stage-<name>] with PROGRAM = pepsi-stage-relay-to-maildir: SERVER_NAME (required), TARGETS, LOCAL_DOMAINS, RECIPIENT_DELIMITER, HELPER, NEXT_STAGE/BOUNCE_STAGE and the retry policy (RETRY_INITIAL/RETRY_MAX_INTERVAL/RETRY_FACTOR/ MAX_LIFETIME). Full reference: pepsi-stage-relay-to-maildir(1).

34.4. State

  • Inputs: state.dsn (per-recipient NOTIFY/ORCPT) and state.local_origin.

  • 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.

34.5. See also

pepsi-stage-relay-to-smarthost, pepsi-stage-relay-to-internet, pepsi-stage-bounce, Supported Features, pepsi-stage-relay-to-maildir(1).