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, else info).

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