95.1.10. pepsi-stage-bounce

rewrite a message into a delivery-status bounce

Manual section:

1

95.1.10.1.1. Name

pepsi-stage-bounce - the bounce-generation stage of the Pepsi pipeline.

95.1.10.1.2. Synopsis

pepsi-stage-bounce [GLOBAL-OPTIONS] worker

95.1.10.1.3. Description

pepsi-stage-bounce is a stage program: pepsi-dispatch(1) runs it as a persistent worker, which reads message ids on standard input. Each id identifies a row of the pepsi.workqueue table. The stage loads that row, refusing to act unless its status is running, and reads its own configuration from the message’s [stage-<stage>] section (see pepsi.conf(5)).

It rewrites the message in place into an RFC 3464 delivery-status notification (DSN): the envelope sender becomes the null sender (<>), the envelope recipient becomes the original message’s sender, and the body becomes a multipart/report quoting the original headers.

“The original message’s sender” is state.srs.original when pepsi-stage-srs(1) recorded one, and the mail_from column otherwise. The distinction matters on any relaying path, because SRS necessarily runs before the delivery stage. By the time a DSN is composed here, the envelope sender is one of our own SRS aliases. A report addressed to it would go out to the next hop and come back in through our own MX to be decoded, pass through the whole inbound pipeline as a null-sender message, and only then reach an address that was on the row all along. SRS is a return path for a bounce that the next hop generates; a report that we write ourselves needs no such detour. See pepsi.state(7). By default this is a failure bounce (Action: failed); when the routing stage tags state.bounce with kind = success, it is instead a positive (Action: delivered) report. The diagnostic and the recipient are taken from the state that the routing stage left on the row. The DSN’s From: is Mail Delivery Subsystem <POSTMASTER>, and POSTMASTER defaults to postmaster@SERVER_NAME. The rewritten DSN is left unsigned; the row is advanced to the stage’s NEXT_STAGE, normally pepsi-stage-dkim-sign(1), which DKIM-signs it (as the postmaster’s domain) before a delivery stage such as pepsi-stage-relay-to-internet(1) relays it. A DSN is reflected mail: it is sent because a stranger sent something, to an address that the stranger chose. The advance is therefore a held one: the row goes to NEXT_STAGE paused for a random time of up to [pepsi] REFLECTION_HOLD_MAX (default 30 s; see pepsi.conf(5)), and the dispatcher then releases it. This keeps reports from many hosts from being timed to land on one victim at once.

A message that is already a bounce (it has the null envelope sender) is not rewritten: it is deleted and the deletion is logged. A bounce is never itself bounced (RFC 5321 §6.1).

A report is also not sent to an envelope sender that the inbound message did not authenticate, either by an SPF pass for its domain or by an aligned DKIM pass for a From: at that domain (or a parent or subdomain of it). Spam forges its sender, so a bounce for it lands on an innocent third party (backscatter), and that gets this host blocklisted. Such a message is dropped with a warning in the log. When it failed on this host rather than at the next hop, the warning names the stage and the recorded error. A temporary DNS error is no verdict, so a report is sent when one stopped a check for the sender’s own domain (SPF for the envelope sender, or DMARC or a signature by that domain for a From: there) and neither SPF nor DMARC failed outright. An error about any other domain does not count: a forger chooses the domain of a signature, and can keep its DNS from answering. Mail that our own users submitted, and messages that a stage created itself (with no state.auth at all), are always reported. BOUNCE_UNAUTHENTICATED = send turns the check off.

DSN (RFC 3461): a failure bounce is generated only when the failed recipient’s NOTIFY requested FAILURE. The stage acts on the NOTIFY, ORCPT and ENVID that the routing delivery stage copied from the recipient’s state.dsn entry onto the state.bounce object. When no NOTIFY is carried, the default is FAILURE, so ordinary mail still bounces; but NOTIFY=NEVER (or a NOTIFY list without FAILURE) means the sender does not want a failure report, and the message is then dropped without a bounce. When the original ENVID and ORCPT were supplied, they are echoed into the DSN as Original-Envelope-Id and Original-Recipient.

When pepsi-stage-aliases(1) or pepsi-stage-dot-forward(1) produced a recipient by expanding the address that the sender used, the recipient is reported as that address. The expansion records the address (expanded_from in the recipient’s state.dsn entry, which the delivery stage copies onto state.bounce), and any DSN about the target names it as Final-Recipient. Such a DSN has a generic Diagnostic-Code of the same class (550 <status> delivery to a forwarded address failed, 450 … is delayed) and keeps the enhanced Status: code. Where a user’s alias or ~/.forward leads, and what the host there replied, are the user’s data, not the sender’s (RFC 3464 section 4.2, RFC 3461 section 5.2.7.4); the target and the real diagnostic are logged to the journal for the operator, and the BOUNCE_MESSAGE template sees neither them nor the remote_mta, smtp_code, phase and reply_text fields.

A report that a downstream server sends about such a copy is answered the same way. The copy left with a forward return address (pepsi-stage-srs(1)), and pepsi-ingress(1) turns a report to that address into a row at this stage instead of delivering it. The row has the original sender as its envelope sender and the address that the sender used as its recipient. Its state.bounce carries the report’s Action (failed, or delay for Action: delayed) and status class, and the sender’s NOTIFY. The row also has state.forward_return = true, state.crypto.in when the message arrived encrypted, and an unproven state.auth when its sender was not authenticated, so that BOUNCE_UNAUTHENTICATED applies. Its header block holds the sender’s own addressing fields from the report’s returned headers, or nothing for a message that arrived encrypted; a DSN with nothing to quote has no third part (RFC 6522 section 3 makes it optional).

A message that failed on this host arrives with no state.bounce: a stage’s error was retried until MAX_LIFETIME or marked permanent, the message crashed or hung its worker, or pepsi-failure-bouncer(1) moved a failed row here. Such a row may still list several recipients, each with its own NOTIFY, so it is first split into one row per recipient, and each copy is then reported on, or dropped, according to that recipient’s own state.dsn entry (including RET). The diagnostic is a deliberately generic sentence, chosen by state.failure_class, that names at most the stage (state.failed_stage): the recorded state.last_error can name files, database objects and hosts, so it stays in the row and the journal and is never copied into a DSN. The Status: is 5.4.7 for retries-exhausted, 5.3.0 for crashed/timed-out, 5.6.0 for permanent, 5.7.1 for quarantine-expired and 5.0.0 otherwise.

A success report (kind = success) is generated only when the recipient explicitly requested NOTIFY=SUCCESS (success, unlike failure, has no implicit default); the routing stage emits one solely when the global [pepsi] ORIGINATE_SUCCESS_DSN is enabled. A delay report (kind = delay, Action: delayed) is generated only when the recipient requested NOTIFY=DELAY; a delivery stage enqueues a copy of a still-undelivered message here (see DELAY_DSN_AFTER in pepsi-stage-relay-to-internet(1)) while the original keeps being retried. Both success and delay have no implicit default.

The human-readable (text/plain) part of the bounce is, by default, a built-in English notice. When the stage’s BOUNCE_MESSAGE option names a template, that part is instead rendered from bounce-<NAME>.<lang>.body under the [pepsi] TEMPLATE_DIR (a Mustache template; see pepsi.conf(5)). <lang> is chosen from state.language in its q order, falling back to en. The bounce goes to the original message’s sender, and the language that pepsi-stage-detect-language(1) found in the message that they wrote is the best available evidence of what they read. It is a proxy, and where no detection ran (commonly the submission path) the notice is English. A message whose content came out of, or failed to open from, an S/MIME EnvelopedData (AES-CBC, no integrity protection) counts as having no detected language: the language depends on whether a modified CBC ciphertext opened, and a DSN in that language would tell the sender. The rendering context is the whole message state, except what the inbound crypto stages recorded (state.crypto, state.encrypted, state.signature_verified; see Mail that arrived encrypted). It is augmented with the top-level variables server_name, postmaster, bounce_to, failed_recipient, diagnostic, action (failed/delayed/delivered) and the three booleans failed / delayed / delivered. With the next-hop detail that a delivery stage captured (state.bounce.remote_mta / smtp_code / enhanced_status / phase / reply_text), the bounce can therefore state precisely why the next MTA refused the message. Rendering is best-effort: any failure falls back to the built-in text, so a bounce is always produced.

pepsi-stage-bounce performs no network delivery and issues no notification; the rewritten message is delivered by whichever stage NEXT_STAGE names.

95.1.10.1.4. Configuration

The bounce stage’s options (SERVER_NAME, POSTMASTER, the required NEXT_STAGE, the optional BOUNCE_MESSAGE template, RET_FULL_MAX_SIZE and BOUNCE_UNAUTHENTICATED) are documented in pepsi.conf(5).

95.1.10.1.5. Returning the message (RET)

The DSN’s third part quotes the message that failed. By default that is its header block, as text/rfc822-headers. When the original sender set RET=FULL on MAIL FROM, the whole message is returned instead, as message/rfc822, which is what RFC 3461 §6.2 asks for. pepsi-ingress(1) records the RET parameter, and it reaches this stage in state.bounce.ret.

The exception is size. §6.2 permits returning the headers alone when the message “exceeds some implementation-specified size”; RET_FULL_MAX_SIZE is that size (default 256 KiB, measured over the whole stored message). Above it, the DSN quietly falls back to the header form and logs that it did so. The value 0 disables the limit, so a RET=FULL message is always returned whole. The body is read from the database only for a message that asked for it and fits, so an ordinary bounce still costs one header-only load.

Every quoted header block, and the header block of a returned message, loses Pepsi’s own X-Pepsi-* annotation fields: they report what the inbound stages found and are meant for the recipient, not for whoever the envelope sender is.

A message tagged REQUIRETLS (state.tls_required = "required", see pepsi-ingress(1)) is quoted by its headers alone whatever RET asks: RFC 8689 §5 says to disregard RET=FULL for such a message, because its bounce may travel a return path without the protection that the message itself demanded. The DSN built here carries the same tag, so the relay stages return it only over validated TLS and pass REQUIRETLS on where the return path advertises it.

95.1.10.1.6. Mail that arrived encrypted

A message that arrived carrying ciphertext (state.crypto.in records it as encrypted or decrypted) is quoted by its addressing fields only: From, Sender, To, Cc, Date and Message-ID, as text/rfc822-headers, whatever RET asks for. No Subject, no body.

We do this to avoid two attacks. pepsi-stage-decrypt(1) runs first on the inbound path, so a message that bounces later in the pipeline (an unpaid pay-to-send gate, a full mailbox, a refusing LMTP server) holds plaintext. An attacker who captured a ciphertext can re-send it under their own envelope sender with RET=FULL, arrange for it to bounce and receive the plaintext; authenticated encryption does not help, because the ciphertext is not modified. Second, a DSN that differed between a message that opened and one that did not (the [decrypted] subject tag, the X-Pepsi-Crypto field, a decrypted body) would tell the sender whether a modified ciphertext still decrypts, which is the building block of padding-oracle attacks on AES-CBC S/MIME. Withholding the same fields in both cases removes that signal from the DSN’s content. What remains is whether a DSN is sent at all and its diagnostic text, which depend on what failed and where, not on the plaintext. The bouncing settings of pepsi-stage-decrypt(1) and pepsi-stage-reencrypt(1) drop, rather than bounce, a message whose ciphertext had no integrity protection, so the existence of a DSN does not tell the sender whether a modified AES-CBC ciphertext opened either.

The automatic replies addressed to the envelope sender follow the same rule: pepsi-stage-vacation(1), the payment request of pepsi-stage-anti-spam(1) and the challenge of pepsi-stage-secretary(1) do not quote the subject of a message that arrived encrypted.

95.1.10.1.7. State

Inputs: state.bounce, the report context that the routing stage left on the row. Its kind (permanent ⇒ a failure Action: failed report, success ⇒ Action: delivered, delay ⇒ Action: delayed) selects the report type; diagnostic and failed_recipient are quoted in it; the optional notify/orcpt/envid decide whether the report is emitted at all and what is echoed; the optional expanded_from replaces the recipient and the diagnostic (see above); ret selects whether the whole message or only its headers is returned (see above); and the optional structured next-hop fields remote_mta/smtp_code/enhanced_status/phase/reply_text (written by the relay stages) are surfaced to the BOUNCE_MESSAGE template and, for enhanced_status, into the DSN Status: field (otherwise Status: is 5.0.0, 4.0.0 or 2.0.0 by kind). A row with no state.bounce is reported from state.failed_stage/state.failure_class and its state.dsn instead (see Description); state.last_error is only ever logged. state.srs.original, state.auth and state.local_origin choose and vet the DSN’s recipient, state.crypto.in decides whether content is withheld, and state.language picks the template language. Another stage may spawn a report as a separate row beside the original (a per-recipient bounce or success notice from pepsi-stage-relay-to-maildir or pepsi-stage-discard, a relay’s delay warning). Such a row carries the original message’s state with its own bounce record on top, so these keys reach this stage for it exactly as for a rerouted message; only state.list and the original row’s retry and failure bookkeeping are left behind.

Outputs: the stage rewrites the message in place and replaces state with a single key, retry_since (the time the DSN was built), so that the stages after it count their MAX_LIFETIME from then rather than from the original message’s arrival. When the original carried tls_required = "required", the stage keeps that key as well; it is the one piece of the original’s state that a DSN keeps (RFC 8689 §5). The bounce is otherwise a new null-sender message that inherits none of the original’s provenance (this is the one stage that does not preserve state). The state layout is described in pepsi.state(7).

Transitions:

  • an incoming message that is itself a bounce (null sender) → finish (dropped, never re-bounced);

  • the envelope sender is not authenticated, with no temporary DNS error to excuse it, and BOUNCE_UNAUTHENTICATED is drop → finish (dropped without a DSN, logged as a warning);

  • a row with no state.bounce and more than one recipient → split into one row per recipient first (the copies are reported on independently);

  • the recipient’s NOTIFY does not request the report that this kind would emit (failure has an implicit default; success/delay do not) → finish (dropped without a DSN);

  • otherwise the message is rewritten in place into a DSN and advanced to NEXT_STAGE (the signing/delivery tail).

The stage itself never pauses, fails or reroutes. An error (an unreachable database, say) is retried like any stage’s; a bounce stage normally names no BOUNCE_STAGE, so one that outlives MAX_LIFETIME leaves the row failed, and pepsi-failure-bouncer(1) leaves a row that failed at the bounce stage where it is.

95.1.10.1.8. Commands

worker

Run as a persistent pepsi-dispatch(1) worker, reading message ids on standard input.

95.1.10.1.9. Global Options

These global options precede the subcommand.

-c FILE, –config FILE

Read the configuration from FILE instead of searching the default locations.

-L LOGLEVEL, –log LOGLEVEL

Set the logging verbosity (error, warn, info, debug or trace; default [pepsi] LOG, else info).

-v, –verbose

Show log messages from all sources, including third-party libraries.

-h, –help

Print a usage summary and exit.

-V, –version

Print the version and exit.

95.1.10.1.10. Exit Status

The outcome of each message is reported to pepsi-dispatch(1) on the worker’s status line, not as the exit status.

0

The worker ran until its standard input was closed.

1

A fatal error occurred (unreadable configuration, the database could not be opened, or standard input/output failed). The reason is written to the log.

78

The stage’s section does not parse, or names no NEXT_STAGE: the worker refuses to start, and pepsi-dispatch(1) holds the stage’s messages until the configuration is fixed.

95.1.10.1.11. Examples

Run the bounce stage on message 42 by hand (it must be running):

echo 42 | pepsi-stage-bounce -c /etc/pepsi/pepsi.conf worker

95.1.10.1.12. See Also

pepsi-config(1), pepsi.conf(5), pepsi.state(7), pepsi-stage-dkim-sign(1), pepsi-dispatch(1), pepsi-stage-relay-to-internet(1), pepsi-stage-relay-to-smarthost(1), pepsi-setup(1), pepsi-failure-bouncer(1)

“Unknown recipients and backscatter” and “Bounces and replies to encrypted mail” in the security chapter of the Pepsi manual, and “Loops and amplification” in its threat model.

95.1.10.1.13. Bugs

Report bugs to the Pepsi issue tracker.