61. pepsi-stage-milter¶
Run a message past a sendmail/Postfix milter mail filter.
61.1. Role¶
pepsi-stage-milter speaks the milter protocol, the mail-filter interface
that sendmail introduced and Postfix adopted. The filters that an operator already
runs therefore work here unchanged: opendkim, rspamd, clamav-milter,
spamass-milter, milter-greylist. For each message the stage connects to
the filter’s socket, replays the message as an SMTP session, applies whatever
modifications the filter asks for, and routes the message by its verdict.
Reference: pepsi-stage-milter(1).
The stage is a client and nothing else. The filter is an existing long-lived
daemon with its own package, its own systemd unit and its own user account,
exactly as under sendmail and Postfix. Pepsi neither starts nor confines it,
because confining a daemon is the job of that daemon’s own unit, and on Debian
that unit already does it. The stage itself therefore carries no privilege: no
setuid bit, no setgid bit, no helper. The filter is trusted with what it is
given: it sees the message in the clear (inbound, after decryption) and may change what
ALLOW_ACTIONS grants it (Principals and how far each is trusted).
61.2. Post-queue, and what that costs¶
Warning
A milter is designed as a pre-queue filter, and Pepsi runs it post-queue. This is the one place where Pepsi’s milter support is not equivalent to an MTA’s.
In an MTA the callbacks run inside the SMTP session, before the server has
accepted the message. This is what lets a milter answer 550 to a forged
sender and generate no bounce at all. Pepsi’s pipeline runs entirely after the
message is queued: by the time any stage sees a row, pepsi-ingress has
already said 250. A REJECT here therefore costs a bounce to whatever
address the envelope named, which for forged spam is an innocent third party.
A greylisting or DNSBL milter carried over from Postfix still filters correctly,
but at the price of backscatter. Point REJECT_STAGE at a
pepsi-stage-discard rather than a pepsi-stage-bounce if that
matters. Filters that only annotate — a signer, or a scorer that adds a header
for a later pepsi-stage-if to branch on — are unaffected.
61.3. Features¶
Both socket families:
SOCKETtakes sendmail’s ownS=grammar, which Postfix also accepts (unix:/path,inet:host:port,inet:port@host,inet6:[addr]:port), so a value copied straight out of either configuration works unchanged.The session is reconstructed, not invented: the connect, helo and mail phases come from what
pepsi-ingressrecorded understate.origin: the peer address and its PTR name, theHELOname, the TLS version and cipher, the listener (the local address, exported as{daemon_addr}in Postfix’s default connect macro listj {daemon_name} {daemon_addr} v _), theBODY=/SMTPUTF8parameters, and how the session authenticated (the RFC 4954{auth_type}/{auth_authen}/{auth_author}/{auth_ssf}macros). A locally injected message (a bounce, an auto-reply, apepsi-sendmailsubmission) is presented as a loopback session, which is what sendmail does for local submission.An action allow-list:
ALLOW_ACTIONSdecides which modifications the filter may make. The default (addhdrs chgbody chghdrs) lets the filter add and change header fields and replace the body, which is all that a filter needs when it changes only the content of a message. Rewriting the envelope (adding or deleting recipients withaddrcpt/delrcpt, changing the sender withchgfrom) andquarantinehave to be granted explicitly.allandnoneare shorthands, and an unknown name is an error rather than a silent no-op. As there is no sandbox around the filter, this list is the only means of limiting what a misbehaving filter can change.An unmet requirement is reported, not ignored: a filter that needs an action which was not offered is named in the log and the message takes the
ON_FAILUREpath. Postfix drops such a request silently, which is how an operator discovers six months later that a signing milter never signed anything.Postfix’s failure semantics:
ON_FAILUREmirrorsmilter_default_actionand defaults the same way (tempfail), as do the three timeouts (30 s / 30 s / 300 s), so a filter that is down delays mail rather than losing it or letting it through unfiltered.Per-recipient rejection fans out: a recipient the filter turns down during the
RCPTphase is peeled onto its own sibling row atREJECT_STAGEand the rest of the message carries on, withstate.dsn.rcptsliced in step withrcpt_toon every resulting row. A recipient the filter only defers (4xx) is peeled onto a row that waits at the milter stage and is filtered again later, untilMAX_LIFETIME; after that it is bounced, never rejected.Header injection is not possible: a header value containing a newline is re-folded rather than allowed to become a second field, and an invalid field name is refused outright.
61.4. Placement¶
Inbound, place it after pepsi-stage-decrypt so the filter sees plaintext, and before the whitelist and spam gates so they can branch on whatever it tagged. Outbound, place it just before pepsi-stage-dkim-sign so our own signature covers its changes.
pepsi-setup --wizard does this for you for the filters it can find. It scans
the host for seven known daemons, confirms each by completing a real option
negotiation with its socket, and emits one stage per accepted filter. It orders
the stages by what each filter does, sets ALLOW_ACTIONS to exactly what that
filter asked for during the negotiation, and routes rejects to a generated
discard stage rather than bouncing them. Filters whose job Pepsi already does (opendkim,
openarc, opendmarc, SPF daemons, postsrsd) are named and skipped.
See the scan in pepsi-setup(1).
A filter that rewrites the body necessarily breaks the originator’s DKIM body
hash and this deployment’s ARC AMS; pepsi-stage-vacation has the
same unavoidable caveat for its subject tag. That is harmless on a
local-delivery branch; on a branch that relays the message onward, prefer a
filter that only adds headers.
61.5. Verdicts¶
|
|
|
|
|
|
|
paused for retry, then |
|
deleted, silently |
|
|
A tempfail that outlives MAX_LIFETIME is no verdict on the message, so it
never takes REJECT_STAGE (which may drop mail silently): it goes to
BOUNCE_STAGE, or is left failed for pepsi-failure-bouncer when there
is none.
A reject or an expired tempfail of a message whose content came out of, or
failed to open from, an S/MIME EnvelopedData (AES-CBC) deletes the message
instead (telemetry decrypt-dropped): the filter’s verdict depends on the
padding of a ciphertext that the sender may have modified, and a bounce would answer
that question (CBC padding and format oracles against unauthenticated S/MIME). A recipient refused at
RCPT is unaffected.
A quarantine is held by pepsi-stage-quarantine: point
QUARANTINE_STAGE at such a stage and the message waits there until an
operator releases or deletes it (pepsi-queue quarantine). The stage records
state.quarantine with the filter’s reason and by = milter:<MILTER_NAME>
on the way.
ACCEPT_STAGE exists because Postfix applies a list of milters, where accept
means “skip the remaining ones”. One filter per stage has no such notion, so
without the option accept and continue would be the same thing; point it past the
rest of a chain to restore the distinction.
61.6. Configuration¶
[stage-<name>]: PROGRAM = pepsi-stage-milter, SOCKET (required),
NEXT_STAGE (required — ``CONTINUE`` is the default verdict and goes there,
and ``ACCEPT_STAGE`` covers only ``ACCEPT``), the routing targets
ACCEPT_STAGE/REJECT_STAGE/QUARANTINE_STAGE, BOUNCE_STAGE (which
REJECT_STAGE falls back to), ON_FAILURE
(tempfail by default, or accept, reject or discard),
ALLOW_ACTIONS, MILTER_NAME (the {daemon_name} macro; defaults to the
stage’s own label), PROTOCOL_VERSION (2 to 6, default 6), the three timeouts
CONNECT_TIMEOUT/COMMAND_TIMEOUT/CONTENT_TIMEOUT, the shared retry
options (RETRY_INITIAL/RETRY_MAX_INTERVAL/RETRY_FACTOR/
MAX_LIFETIME; there is no DELAY_DSN_AFTER, since a deferral by the
filter produces no “delayed” DSN) and the seven MACROS_* lists (MACROS_CONNECT,
MACROS_HELO, MACROS_MAIL, MACROS_RCPT, MACROS_DATA,
MACROS_EOH, MACROS_EOM, each defaulting to Postfix’s own list, with the
sentinel none to export nothing at that phase; an empty value counts as
absent and re-applies the default). pepsi-setup requires NEXT_STAGE and
checks that every routing target resolves to a real stage. See
pepsi-stage-milter(1).
61.7. State¶
Inputs:
state.origin(the recorded session, replayed to the filter) andstate.dsn(kept parallel to any recipient rewrite).Outputs:
state.milter, holding the verdict, protocol version, elapsed time and the modifications applied, plus the filter’s reply code and quarantine reason when present. A quarantined message routed toQUARANTINE_STAGEcarries a freshstate.quarantinerequest (reason,by) for pepsi-stage-quarantine. A rejected message also carriesstate.bounce, with the filter’s SMTP code, RFC 3463 enhanced status and text in their own fields. A deferred message (or recipient copy) carriesstate.attemptsandstate.last_error; one rejected with nowhere to go is left failed withstate.milter_error.
61.8. See also¶
pepsi-stage-if, pepsi-stage-discard, pepsi-stage-bounce, pepsi-stage-dkim-sign, Supported Features, pepsi-stage-milter(1).