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; a NOTIFY=SUCCESS notification (and DELAY warnings) is routed to the optional NOTIFY_STAGE;

  • a permanent reject is routed by its RFC 3463 enhanced status. A bad mailbox (x.1.x, x.2.x other than x.2.2, and a bare 550 with no enhanced status at all) goes to UNKNOWN_MAILBOX_STAGE when the recipient is on one of LOCAL_DOMAINS (default [pepsi-ingress] ACCEPTED_DOMAINS), else to NEXT_STAGE. Over-quota (x.2.2) goes to QUOTA_LIMIT_STAGE (else NEXT_STAGE), a Sieve or policy reject (x.7.x) to SIEVE_REJECT_STAGE (else NEXT_STAGE). Anything else goes to BOUNCE_STAGE when the recipient is on one of LOCAL_DOMAINS and that option is set, and otherwise to NEXT_STAGE;

  • 4xx — transient: retry that recipient (exponential backoff) until MAX_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 (else NEXT_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-recipient NOTIFY/ORCPT) and the retry bookkeeping it wrote on an earlier pass.

  • Outputs: state.bounce on each routed sibling row (recording why the MDA refused, or that the delivery succeeded for a SUCCESS/DELAY notification), and attempts/last_error (plus delay_sent once a delay warning was routed) on the deferred row. state.dsn.rcpt is 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).