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: SOCKET takes sendmail’s own S= 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-ingress recorded under state.origin: the peer address and its PTR name, the HELO name, the TLS version and cipher, the listener (the local address, exported as {daemon_addr} in Postfix’s default connect macro list j {daemon_name} {daemon_addr} v _), the BODY=/SMTPUTF8 parameters, 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, a pepsi-sendmail submission) is presented as a loopback session, which is what sendmail does for local submission.

  • An action allow-list: ALLOW_ACTIONS decides 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 with addrcpt/delrcpt, changing the sender with chgfrom) and quarantine have to be granted explicitly. all and none are 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_FAILURE path. 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_FAILURE mirrors milter_default_action and 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 RCPT phase is peeled onto its own sibling row at REJECT_STAGE and the rest of the message carries on, with state.dsn.rcpt sliced in step with rcpt_to on 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, until MAX_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

CONTINUE

NEXT_STAGE

ACCEPT

ACCEPT_STAGE (default NEXT_STAGE)

REJECT

REJECT_STAGE (default BOUNCE_STAGE)

TEMPFAIL

paused for retry, then BOUNCE_STAGE or failed

DISCARD

deleted, silently

QUARANTINE

QUARANTINE_STAGE; deleted when unset

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) and state.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 to QUARANTINE_STAGE carries a fresh state.quarantine request (reason, by) for pepsi-stage-quarantine. A rejected message also carries state.bounce, with the filter’s SMTP code, RFC 3463 enhanced status and text in their own fields. A deferred message (or recipient copy) carries state.attempts and state.last_error; one rejected with nowhere to go is left failed with state.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).