41. pepsi-stage-aliases¶
Expand envelope recipients through an alias / mailing-list map.
41.1. Role¶
pepsi-stage-aliases rewrites a message’s envelope recipients through a
mapping file before delivery: every recipient that matches an entry in the map is
replaced by that entry’s target addresses, recipients that match nothing are left
unchanged, the resulting list is de-duplicated so each address is delivered to at
most once, and the message advances to NEXT_STAGE. It is the classic
/etc/aliases / virtual-domain expansion step, and is normally placed just
before local delivery. It loads only the envelope and state, never the
headers or body, and it never fails or finishes a message (an unreadable map is
retried, see below). Reference:
pepsi-stage-aliases(1).
41.2. Features¶
Postfix-style map file.
ALIASESnames a human-readable file parsed like a Postfix virtual(5) table: each non-blank line maps one key to one or more target addresses, separated by commas or whitespace. A key is a full address, an@domaincatch-all, or a*-glob such assales-*@example.org. Targets are kept verbatim; they must be fulllocal@domainaddresses and may not themselves contain a wildcard. A key with no targets is ignored, so a recipient is never silently deleted.Most-specific match wins. A recipient is lower-cased and looked up verbatim; on a miss the
@domaincatch-all is tried, then the most specific matching*wildcard (a narrowsales-*@example.orgbeats a broad*@example.org, which beats a bare*). Sub-address (+tag) detail is not stripped, so a specific list address can be aliased on its own.Transitive expansion with loop breaking. When a target is itself a key it is expanded in turn, so nested distribution lists resolve to their leaf addresses; a cycle, or a chain deeper than 32 hops, is broken by resolving the repeated key to its literal address rather than recursing forever.
Cached. The map is read into a process-global cache and re-parsed only when the file’s identity (modification time, size or inode) changes, so a busy worker does not re-read it per message. A missing file is treated as an empty map (no aliases configured). A file that exists but cannot be read (permissions, an I/O error) is an error: the message is paused and retried like any other fault of the host, rather than delivered unaliased.
pepsi-setupsyntax-checks the file at install time when it exists.
41.3. Delivery Status Notifications¶
state.dsn.rcpt runs parallel to the recipient list, so it is rebuilt in
lockstep with the rewritten recipients. An expanded target inherits the NOTIFY
of the original recipient with any SUCCESS removed (a NOTIFY that was only
SUCCESS becomes NEVER), so one submission to an alias does not draw one
positive DSN per member. Following RFC 3461 §5.2.7, the target also carries an
ORCPT pointing at that original recipient (its existing ORCPT if any,
otherwise rfc822;<original-recipient>) and an expanded_from naming it, so
that a DSN about the target names only the original recipient, with a generic
diagnostic
(pepsi-stage-bounce). The same mark makes pepsi-stage-srs give a
target off-site a forward return address rather than an SRS one, so a report
that the target’s own server sends comes back here and is answered the same way
(Forwarding addresses in delivery reports). An unexpanded recipient keeps its DSN entry, and
message-level RET/ENVID and every other state key are preserved.
41.4. Configuration¶
[stage-<name>]: PROGRAM = pepsi-stage-aliases, the ALIASES map-file
path, and the NEXT_STAGE the expanded message advances to. pepsi-setup
creates a starter ALIASES template when the file is missing and syntax-checks
it when present. See pepsi-stage-aliases(1) and Configuration.
41.5. State¶
Inputs: the envelope
rcpt_toand the parallelstate.dsn.rcpt.Outputs: a rewritten
rcpt_toand matchingstate.dsn.rcpt(only when an alias applied or a duplicate was removed); no otherstateis touched.Transitions: advance to
NEXT_STAGE(the only transition), after a random hold of up to[pepsi] REFLECTION_HOLD_MAX(30 s) when an alias applied, because an expanded message is reflected mail (Unknown recipients and backscatter).
41.6. See also¶
pepsi-stage-relay-to-maildir, pepsi-stage-relay-to-lmtp, pepsi-stage-if, Supported Features, pepsi-stage-aliases(1).