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 byTARGETS.TARGETSis 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 belowUID_MINregardless, so a system account listed here is bounced.The mailbox name is the local-part with any
RECIPIENT_DELIMITERsub-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
pendingrow, and where depends on why they are not local. A recipient on somebody else’s domain is a forward and goes toNEXT_STAGE, which should reach the SRS relay tail. A recipient on one of ourLOCAL_DOMAINSthat resolves to no permitted account is an unknown mailbox and goes toUNKNOWN_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_STAGEdefaults toNEXT_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:, aDelivered-To:loop guard and aReceived: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_LIFETIMEand only then routes it toBOUNCE_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 belowUID_MIN). A bounce is never re-bounced, a stage with noBOUNCE_STAGEdrops the recipient with a warning, and the sender’sNOTIFYis 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,bounceroutes it toQUOTA_LIMIT_STAGEwith a5.2.2status (falling back toBOUNCE_STAGE). A kernelEDQUOTcounts as over quota too. See pepsi-quota.Originates a positive DSN on successful local delivery when
[pepsi] ORIGINATE_SUCCESS_DSNis set and the recipient asked forNOTIFY=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 orRequire-Recipient-Valid-Sincefield names a date before a recorded change of owner is not delivered but bounced with550 5.7.17; role addresses (RFC 2142) are never tested.Require-Recipient-Valid-Sincefields are removed from the stored copy.
44.2.5. Privilege model¶
The stage binary is installed setgid
pepsi-maildir, mode2550pepsi:pepsi-maildir. The dispatcher runs it as the unprivilegedpepsiuser; 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 mode2550exists for this last point: at2755every local user could exec the stage and inherit the same gid, and from there the setuid-root helper.pepsicannot 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
rootorpepsibefore 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-recipientNOTIFY/ORCPT) andstate.attempts(the retry count).Outputs:
attempts/last_erroron pause; astate.bounceobject on the rows enqueued for the bounce stage; the per-recipientstate.dsnis sliced onto each split row.state.dsn/state.originare 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).