46. pepsi-stage-relay-to-lmtp¶
Deliver locally over LMTP to an MDA (Dovecot) that runs Sieve.
46.1. Role¶
pepsi-stage-relay-to-lmtp is a local-delivery stage that hands each message
to a Mail Delivery Agent — typically Dovecot — over LMTP (RFC 2033). The
MDA files the message and, in doing so, runs the recipient’s Sieve (RFC 5228)
script, so server-side filtering is delegated to the MDA instead of being
implemented in Pepsi. It is an alternative to pepsi-stage-relay-to-maildir.
With LMTP you gain Sieve and a clean per-recipient delivery status, and you need
no setuid helper (the MDA performs the per-user delivery); the cost is that
you run a local IMAP/LMTP server.
46.2. LMTP-native delivery, deliver-and-route¶
The stage delivers one recipient per row, and so one recipient per LMTP
transaction. A message with several recipients is first split, and a recipient
named twice is dropped. LMTP replies name no recipient (RFC 2033 §4.2), so after a
fault nothing could tell whose reply a later one is, and one slow Sieve program
would hold up every recipient of the transaction. The cost is one connection and
one Sieve run per recipient; the rows share one stored body. The stage never
builds a delivery-status notification itself. It delivers, and otherwise
routes the recipient onward by reason. It records the reason under state.bounce, so
that a downstream pepsi-stage-bounce (or a relay) can act on it:
2xx— delivered; aNOTIFY=SUCCESSnotification (andDELAYwarnings) is routed to the optionalNOTIFY_STAGE;a permanent reject is routed by its RFC 3463 enhanced status. A bad mailbox (
x.1.x,x.2.xother thanx.2.2, and a bare550with no enhanced status at all) goes toUNKNOWN_MAILBOX_STAGEwhen the recipient is on one ofLOCAL_DOMAINS(default[pepsi-ingress] ACCEPTED_DOMAINS), else toNEXT_STAGE. Over-quota (x.2.2) goes toQUOTA_LIMIT_STAGE(elseNEXT_STAGE), a Sieve or policy reject (x.7.x) toSIEVE_REJECT_STAGE(elseNEXT_STAGE). Anything else goes toBOUNCE_STAGEwhen the recipient is on one ofLOCAL_DOMAINSand that option is set, and otherwise toNEXT_STAGE;4xx— transient: retry that recipient (exponential backoff) untilMAX_LIFETIME, then route by the same classification;no reply after the whole message was sent — a lost acknowledgement, after which nobody knows whether the MDA filed the mail. The stage waits at least 15 minutes before a retry, and after three such attempts, or at any later give-up, it routes a report to
BOUNCE_STAGE(elseNEXT_STAGE) that tells the sender the outcome is unknown. Workers killed at this stage count too.
A delivered recipient’s row ends, a routed recipient becomes a pending row at
its target stage, and a deferred one stays on its row for the next retry. A
failure of the whole session (connect, STARTTLS, authentication, data
transfer) is retried too. When that failure is permanent, or the message is past
MAX_LIFETIME, the stage routes the recipient onward instead.
A recipient carrying an RFC 7293 RRVS= request has it passed on when the MDA
advertises RRVS; Dovecot does not, so by default (action R) that
recipient is refused here with 5.7.19 and routed like a policy reject, while
action C delivers it (see A login that changes owner).
Because the MDA is the authority on which addresses are local, the stage does no
locality check of its own. Place it after alias expansion, so that only
recipients meant to be local reach it. NEXT_STAGE is mandatory (set it to a
pepsi-stage-bounce to bounce, or to a relay stage to forward off-site); a
message reaching the stage without one is marked failed before the MDA is
contacted, so nothing is delivered.
46.3. Transport¶
The target is either a UNIX-domain socket (SOCKET, the common Dovecot layout:
no TLS, no credentials) or TCP (HOST/PORT, PORT default 24) with optional
TLS = off|starttls|tls and AUTH = none|plain|login|external.
Authentication is refused over cleartext, so any AUTH other than none
requires TLS. The shared LMTP client reuses the SMTP client’s transport, TLS and
SASL machinery (pepsi_common::smtp::deliver_lmtp).
The stage runs as the unprivileged pepsi user and carries no setuid or
setgid bit; the MDA does the per-user delivery and is trusted with what it is
handed, like every external helper the operator wires in
(Principals and how far each is trusted). A PASSWORD is kept out of the world-readable
pepsi.conf: pepsi-setup moves it into secrets.d/pepsi.secret.
46.4. Configuration¶
[stage-<name>]: PROGRAM = pepsi-stage-relay-to-lmtp, NEXT_STAGE
(mandatory), the optional reason targets QUOTA_LIMIT_STAGE /
SIEVE_REJECT_STAGE / UNKNOWN_MAILBOX_STAGE (with LOCAL_DOMAINS) /
NOTIFY_STAGE, the target (SOCKET, or
HOST/PORT with TLS, TLS_VERIFY, TLS_CA, TLS_CLIENT_CERT,
TLS_CLIENT_KEY, AUTH and its USERNAME/PASSWORD), SERVER_NAME
(the LHLO name; defaults to [pepsi-ingress] HOSTNAME), the timeouts
(CONNECT_TIMEOUT/COMMAND_TIMEOUT/DATA_TIMEOUT) and the retry policy
(RETRY_INITIAL/RETRY_MAX_INTERVAL/RETRY_FACTOR/MAX_LIFETIME/
DELAY_DSN_AFTER).
pepsi-setup requires NEXT_STAGE and checks that each of the four
optional targets names a real stage. The stage never builds a DSN itself. The
common BOUNCE_STAGE option, when set, receives a recipient on
LOCAL_DOMAINS that no other option covers, and a message whose stage error
persisted past MAX_LIFETIME.
46.5. State¶
Inputs:
state.dsn(per-recipientNOTIFY/ORCPT) and the retry bookkeeping it wrote on an earlier pass.Outputs:
state.bounceon each routed sibling row (recording why the MDA refused, or that the delivery succeeded for aSUCCESS/DELAYnotification), andattempts/last_error(plusdelay_sentonce a delay warning was routed) on the deferred row.state.dsn.rcptis sliced in lockstep with every row’s recipients.
46.6. See also¶
pepsi-stage-relay-to-maildir, pepsi-stage-aliases, pepsi-stage-bounce, pepsi-quota, Supported Features, pepsi-stage-relay-to-lmtp(1), pepsi.conf(5).