40. pepsi-stage-bounce¶
Rewrite a message into a delivery-status notification (DSN).
40.1. Role¶
pepsi-stage-bounce turns a message into an RFC 3464 DSN: a failure bounce
or, when requested, a positive or delay report. A delivery stage routes a
failed/delivered message here via its BOUNCE_STAGE. The DSN is produced
unsigned and advanced to NEXT_STAGE (normally pepsi-stage-dkim-sign,
then a delivery stage) after a random hold of up to [pepsi]
REFLECTION_HOLD_MAX (30 s), as every piece of reflected mail is
(Unknown recipients and backscatter). References: pepsi-stage-bounce(1) /
pepsi.conf(5).
40.2. Features¶
In-place rewrite into a DSN (RFC 3464
multipart/report): the envelope sender becomes the null sender<>, the recipient becomes the original sender (state.srs.originalwhen pepsi-stage-srs recorded one, else themail_fromcolumn), and the body quotes the original headers; RFC 3463 enhanced status codes are used.RET=FULL (RFC 3461 §6.2): when the sender asked for the whole message back, the stage fetches the body and returns it in full. This is the one extra round-trip in the tree, made only for such a message. If the body exceeds
RET_FULL_MAX_SIZE(default 256 KiB,0to disable the limit), the DSN falls back to the headers alone, as §6.2 explicitly permits.Operator-supplied prose. When
BOUNCE_MESSAGEnames a template, the human-readable part of the DSN is rendered frombounce-<NAME>.<lang>.bodyunder[pepsi] TEMPLATE_DIRwith the full rowstate.<lang>followsstate.languageinqorder, falling back toen: the notice goes to the original sender, and the language detected in their message is the best available proxy for what they read (with no detection on the path, the notice is English). Any render failure falls back to the built-in text, so a bounce is always produced.NOTIFY-aware (RFC 3461): a failure report is emitted only when
NOTIFYrequestedFAILURE(the default when absent);NOTIFY=NEVER(or a list withoutFAILURE) drops the message silently.Three report kinds, selected by
state.bounce.kind:permanent→Action: failed(the default failure bounce);success→Action: delivered(only when a delivery stage originated it underORIGINATE_SUCCESS_DSN+NOTIFY=SUCCESS);delay→Action: delayed(a relay stage’sDELAY_DSN_AFTERwarning).
Echoes the original
ENVID/ORCPTintoOriginal-Envelope-Id/Original-Recipientwhen present.Keeps forwarding addresses confidential: for a recipient that an alias or
~/.forwardexpansion produced (expanded_from), the DSN names the address that the sender used asFinal-Recipientand gives a genericDiagnostic-Codeof the same class (550 <status> delivery to a forwarded address failed) with the enhancedStatus:kept; the target and the real reply go to the journal only (RFC 3464 §4.2). The same DSN answers a remote host’s report about a forwarded copy: pepsi-ingress turns a report sent to the copy’s forward return address into a row at this stage (state.forward_return) and drops the report (Forwarding addresses in delivery reports).Nothing to quote, no third part: when a DSN has nothing of the message to quote, it is a two-part
multipart/report(RFC 6522 §3). This is the case for the report about a forwarded copy of a message that arrived encrypted.Never bounces a bounce (RFC 5321 §6.1): a null-sender message is deleted, not rewritten.
No backscatter (
BOUNCE_UNAUTHENTICATED, defaultdrop): no report goes to an envelope sender that the inbound message did not authenticate (SPF pass for its domain, or an aligned DKIM pass for aFrom:at that domain or a parent or subdomain of it). Mail that our own users submitted and messages that a stage created (nostate.auth) are always reported; a dropped report about a failure on this host is logged as a warning.Failures on this host (no
state.bounce: a stage’s error outlivedMAX_LIFETIMEor was permanent, a worker crash, or pepsi-failure-bouncer): the row is split into one row per recipient, each recipient’s ownstate.dsnNOTIFY/ORCPT/RETis honoured, and the DSN carries a generic diagnostic chosen bystate.failure_class(Status:5.4.7,5.3.0,5.6.0,5.7.1or5.0.0);state.last_erroris never copied into it.Content of mail that arrived encrypted is withheld: whatever
RETasks, the DSN quotes onlyFrom/Sender/To/Cc/Date/Message-ID, whether or not decryption succeeded, so the DSN can neither hand plaintext to whoever re-sent a captured ciphertext nor reveal whether it opened. Every quoted header block loses Pepsi’sX-Pepsi-*fields.A ``REQUIRETLS`` message bounces headers-only (RFC 8689 §5 disregards
RET=FULL), and the DSN inherits thestate.tls_requiredtag so the relay stages return it only over validated TLS.No network I/O: the rewritten message is delivered by whatever
NEXT_STAGEnames; the bounce is left unsigned for the DKIM-sign stage.
40.3. Security¶
Two of the features above are security mechanisms. The backscatter rule is
the second layer of “Unknown recipients and backscatter” in Security model
(protecting the host’s sending reputation, Assets, against
A remote sender). Withholding the content of mail that arrived encrypted
is “Bounces and replies to encrypted mail” there: it keeps plaintext that the
gateway opened from reaching whoever the envelope sender is, and keeps the DSN
from being a decryption oracle (Gateway custody (custody = local, the MTA key),
Bounces after gateway decryption reveal decrypted content,
CBC padding and format oracles against unauthenticated S/MIME). The diagnostic of a
failure on this host never quotes state.last_error, which can name files,
database objects and hosts. That a bounce is never bounced is part of the loop
analysis in Availability.
40.4. Configuration¶
[stage-<name>]: PROGRAM = pepsi-stage-bounce, SERVER_NAME (required;
used in ``From:``/``Reporting-MTA``/``Message-ID``), POSTMASTER (the bounce
From: and DKIM identity; default postmaster@<SERVER_NAME>),
BOUNCE_MESSAGE (the template name, unset for the built-in prose),
RET_FULL_MAX_SIZE (default 256 KiB), BOUNCE_UNAUTHENTICATED
(drop/send, default drop) and NEXT_STAGE (required; normally a
DKIM-sign stage: the DSN is built unsigned, so without one every bounce fails
after the DSN has already been composed). See pepsi.conf(5).
40.5. State¶
Inputs:
state.srs.original(the DSN recipient, when present) andstate.bouncewithkind,diagnostic,failed_recipient, the structured next-hop detail that the relay stages record (remote_mta/smtp_code/enhanced_status/phase/reply_text, which also feeds the DSNStatus:), and the copiednotify/orcpt/envid/ret. Withoutstate.bouncethe report is built fromstate.failed_stage/state.failure_classand the recipient’sstate.dsnentry.state.auth/state.local_originvet the DSN recipient,state.crypto.indecides whether content is withheld andstate.languagepicks the template language;state.tls_required(RFC 8689) forces the headers-only form and is carried onto the DSN. A report spawned as a separate row beside the original (a per-recipient bounce or success notice, a delay warning) carries the original’sstateunder its ownbouncerecord, so the same checks apply to it. The header block is loaded; the body is loaded only for aRET=FULLbounce.Outputs: replaces
statewith{"retry_since": <now>}, because the bounce is a new null-sender message that inherits none of the original’s provenance, and the later stages count itsMAX_LIFETIMEfrom when it was built. This is the only stage that discards thestatethat it receives. The other stages keep it and add keys of their own; a stage that changes the recipients also rebuilds thestate.dsnentries to match.
40.6. See also¶
pepsi-stage-dkim-sign, pepsi-stage-relay-to-internet, pepsi-stage-discard, pepsi-failure-bouncer, Supported Features, pepsi-stage-bounce(1), pepsi.conf(5).