95.1.19. pepsi-stage-aliases¶
expand message recipients through an alias mapping file
- Manual section:
1
95.1.19.1.1. Name¶
pepsi-stage-aliases - the alias / mailing-list expansion stage of the Pepsi pipeline.
95.1.19.1.2. Synopsis¶
pepsi-stage-aliases [GLOBAL-OPTIONS] worker
95.1.19.1.3. Description¶
pepsi-stage-aliases is a stage program run by pepsi-dispatch(1). It
loads a pepsi.workqueue row (refusing to act unless its status is
running), reads its [stage-<stage>] section, and rewrites the message’s
envelope recipients through the alias map named by ALIASES. 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 recipient list is
de-duplicated case-insensitively, so that each address is delivered to at most
once, and the message is advanced to NEXT_STAGE. Since an expanded message
is reflected mail, it is first held for a random time of up to [pepsi]
REFLECTION_HOLD_MAX (default 30 s; pepsi.conf(5)): the row waits
paused at NEXT_STAGE until the dispatcher releases it. A message that no
alias touched advances at once.
The stage only loads the envelope and state, never the headers or the body. When
no recipient matches the map (and no duplicate is removed) the message is advanced
unchanged.
95.1.19.1.4. Alias file¶
ALIASES names a human-readable mapping file, which is parsed like a Postfix virtual(5) table. Each non-blank line maps one key to one or more target addresses:
# comments begin with '#'; blank lines are ignored
postmaster@example.com alice@example.com
staff@example.com bob@example.com, carol@partner.example
@example.net ops@example.com
sales-*@example.org sales@example.com
The key (left-hand side) is the first whitespace-delimited field: a full
address, an @domain catch-all, or a * wildcard pattern (a *-glob
such as *@example.org or sales-*@example.org). The targets (right-hand
side) are separated by commas and/or whitespace and are kept verbatim. They may
be local or remote, but must be full local@domain addresses and may not
contain a wildcard. pepsi-setup’s syntax check refuses a bare name such as
bob: no key lacks a domain, so such a name could chain to no alias and would
be delivered to as a recipient with no domain. A line with a key but no
targets is ignored (a recipient is never silently deleted). If the same key
appears twice, the later line wins.
As in virtual(5), a line whose first character is whitespace continues
the previous mapping rather than starting a new one, so a long target list may
be wrapped over several lines; blank and all-comment lines in between do not
break such a continuation. A # begins a comment only at the start of a field
(at the start of the line, or after whitespace), so bug#42@example.com is an
ordinary key rather than a truncated one.
Warning
Wildcards are globs, not regular expressions. * matches any run of
characters, and every other character, a . included, is a literal. To
alias a whole domain write *@example.net (or the @example.net
catch-all); .*@example.net is a regular expression and, read as a glob,
demands a leading dot, so it matches no real address and every message to that
domain falls through unaliased. (The pepsi.whitelist patterns of
pepsi-whitelist(1) are POSIX EREs; this map is not.) Both
pepsi-setup’s syntax check and the stage’s own map parser reject or flag
a key that looks like a regular expression, and name the glob that you
probably meant.
The file is read into memory and re-read only when its identity changes, so a
busy worker does not re-parse it for every message. The identity is the
modification time, the size and the inode, so a replacement that preserves
the modification time (cp -p, a restored backup) is noticed too. A missing file is 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 with back-off, like any other fault
of the host, rather than delivered unaliased: if a postmaster@ or catch-all
entry silently did not apply, the message would be misdelivered or bounced. The unreadable file is
not cached, so the next attempt reads it again.
pepsi-setup syntax-checks the ALIASES file at install time when it exists,
and writes a commented starter template when it does not (see
pepsi-setup(1)); a malformed line is reported there as a warning
before deployment rather than only at run time, never as a fatal error.
95.1.19.1.5. Matching and expansion¶
A recipient is lower-cased and looked up verbatim; on a miss the @domain
catch-all key for its domain is tried, and finally any * wildcard key. The
most specific matching wildcard wins: a narrow sales-*@example.org beats a
broad *@example.org, which beats a bare *, and ties are broken
deterministically.
Sub-address (+tag) detail is not stripped, so a specific list address such
as list+announce@example.com can be aliased on its own.
Expansion is transitive: when an alias target is itself a key it is expanded in turn, so nested distribution lists resolve to their leaf addresses. A loop, where an alias refers back to itself directly or through a chain, is broken by resolving the repeated key to its literal address rather than recursing forever. A chain deeper than 32 hops is stopped the same way (the address is delivered to literally, with a warning), so a generated map cannot overflow the worker’s stack.
95.1.19.1.6. Delivery Status Notifications¶
state.dsn.rcpt is 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 that it came from, with any SUCCESS keyword removed; a
NOTIFY that was only SUCCESS becomes NEVER. This follows RFC 3461
§5.2.7.3(c): otherwise one submission to an alias with five members would draw
five positive DSNs for one recipient, and would disclose the alias’s
membership. Following the same section, the target also carries an ORCPT
that points at the original recipient (its existing ORCPT if it had one,
otherwise rfc822;<original-recipient>). The stage also records the original
recipient as expanded_from (the first address of a chain of expansions). A
DSN that pepsi-stage-bounce(1) writes about the target therefore names
only the address that the sender used, with a generic diagnostic, so the sender
does not learn where an alias leads. The same mark makes pepsi-stage-srs(1)
give a target off-site a forward return address rather than an SRS one. A
report that the target’s own server sends then comes back to
pepsi-ingress(1), which answers it with the same kind of DSN instead of
relaying it. The entry is created even when the sender gave no DSN parameters. A recipient that was not expanded keeps
its DSN entry unchanged. Message-level RET/ENVID and all other state
keys are preserved.
95.1.19.1.7. Configuration¶
Options live in the stage’s own [stage-<name>] section
(PROGRAM = pepsi-stage-aliases): the ALIASES map-file path and the
NEXT_STAGE to which the expanded message advances. Both are required:
the stage advances every message that it sees, so pepsi-setup rejects a
section that lacks either. They are documented in pepsi.conf(5).
95.1.19.1.8. State¶
Inputs: the envelope rcpt_to and the per-recipient state.dsn.rcpt.
Outputs: a rewritten rcpt_to and a matching state.dsn.rcpt, written
only when the recipient list actually changed (an alias matched, or a duplicate
was removed); no other state is touched. The state layout is described in
pepsi.state(7).
Transitions: advances to NEXT_STAGE (the only transition that the stage chooses; after a random hold when an alias applied); it never fails, reroutes or finishes a message. An alias file that exists but cannot be read is a host fault: the worker pauses the message and retries it (see Stage errors in pepsi-dispatch(1)).
95.1.19.1.9. Commands¶
- worker
Run as a persistent pepsi-dispatch(1) worker, reading message ids on standard input. This is how the dispatcher runs the stage in production.
95.1.19.1.10. Global Options¶
- -c FILE, –config FILE
Read the configuration from FILE instead of searching the default locations.
- -L LOGLEVEL, –log LOGLEVEL
Set the logging verbosity (default
[pepsi] LOG, elseinfo).- -v, –verbose
Show log messages from all sources.
- -h, –help; -V, –version
Print a usage summary / the version and exit.
95.1.19.1.11. Exit Status¶
The outcome of each message is reported to pepsi-dispatch(1) on the worker’s status line, not as the exit status.
- 0
The worker ran until its standard input was closed.
- 1
A fatal error occurred (unreadable configuration, the database could not be opened, or standard input/output failed). The reason is written to the log. A missing alias file is not an error: it is treated as an empty map.
- 78
The worker refused to start: a
[stage-*]section it serves does not parse (e.g. a missing ALIASES). The dispatcher requeues what it handed over and retries the stage later.
95.1.19.1.12. Examples¶
Reprocess message 42 through a one-off worker (it must be running):
echo 42 | pepsi-stage-aliases -c /etc/pepsi/pepsi.conf worker
A pipeline section placed just before local delivery, expanding recipients and forwarding to the local-delivery stage:
[stage-aliases]
PROGRAM = pepsi-stage-aliases
NEXT_STAGE = local
ALIASES = /etc/pepsi/aliases
95.1.19.1.13. See Also¶
pepsi-config(1), pepsi-stage-relay-to-maildir(1), pepsi-stage-if(1), pepsi-dispatch(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1)
95.1.19.1.14. Bugs¶
Report bugs to the Pepsi issue tracker.