95.1.11. pepsi-stage-relay-to-internet

deliver a message directly to the recipient’s MX hosts

Manual section:

1

95.1.11.1.1. Name

pepsi-stage-relay-to-internet - the direct-to-MX delivery stage of the Pepsi pipeline.

95.1.11.1.2. Synopsis

pepsi-stage-relay-to-internet [GLOBAL-OPTIONS] worker

pepsi-stage-relay-to-internet [GLOBAL-OPTIONS] mta-sts DOMAIN

95.1.11.1.3. Description

pepsi-stage-relay-to-internet is a stage program run by pepsi-dispatch(1) as a persistent worker reading message ids on standard input. It loads that pepsi.workqueue row (refusing to act unless its status is running), reads its [stage-<stage>] section, and delivers the message directly to the recipient domain’s mail exchangers, using the message’s own envelope sender (the null sender <> for bounces). Delivery is one recipient per attempt: a row that still holds several recipients is first split into one row per recipient (each with its slice of state.dsn), all of which re-enter this stage. A message carrying more than MAX_HOP_COUNT Received: header fields is treated as a mail loop and fails permanently.

It performs its own DNS MX lookup: candidate hosts are tried in ascending MX preference (equal-preference hosts in random order), a domain with no MX records falls back to its address records (the implicit MX of RFC 5321 §5.1), and a non-existent domain or RFC 7505 null MX is a permanent failure. A null MX is reported as 556 with the enhanced status 5.1.10 (RFC 7505 §4.1), so that the bounce says that the address can never be deliverable, rather than looking like any other 550. Each MX host’s A/AAAA addresses are selected with Happy-Eyeballs and cached, per address, in the dns_address table; the ADDRESS_FAMILY setting (intersected with the families the host can route) chooses which to use. Connections are made on port 25. Every query is made for the fully-qualified name, so a search list in /etc/resolv.conf is never applied: without that, a domain with no MX records would be looked up a second time under each search domain. The resulting NXDOMAIN would then be reported instead of the domain’s own NODATA, turning an ordinary implicit-MX delivery into a permanent failure.

Unless disabled with MTA_STS = no, the recipient domain’s MTA-STS policy (RFC 8461) is honoured: an enforce policy restricts delivery to the listed MX hosts over STARTTLS with a certificate that validates for the host, failing the message (transient) when no MX matches. A testing policy is validated the same way, and the attempt and its outcome are recorded for TLS Reporting, but it never blocks delivery: a transport-security failure (or a policy that matches no MX) falls back to opportunistic STARTTLS over all MX hosts, so the domain owner learns from the reports whether enforce would break mail before switching to it. Domains with no policy use opportunistic STARTTLS. Policy lookups fail open only when nothing is cached; with TLS Reporting on, a failed fetch of an advertised policy is then recorded as sts-policy-fetch-error (sts-webpki-invalid for a certificate that did not validate for the policy host’s name or against the system roots), at most once per domain and worker every five minutes, so the domain owner learns that its policy host was unreachable. The policy file is fetched only from a public address: a policy host that resolves solely to loopback, a private or link-local range (cloud metadata included), CGNAT, unique-local IPv6 or another non-public address is not contacted, since a recipient domain could otherwise aim the fetch inside the deployment; that counts as a failed fetch.

Policies are cached for their max_age (capped at one week) in the pepsi.mta_sts_policy table, shared by every worker and kept across worker recycling and restarts, so a policy once fetched stays enforced even if the _mta-sts record is later stripped or the policy host blocked (RFC 8461 §5.1); an expired row is never enforced, and pepsi-queue gc deletes it. Only usable (enforce/testing) policies are stored. The _mta-sts TXT id is re-checked on each use of a cached policy (RFC 8461 §3.1): a changed id triggers an immediate refetch, while a transiently unreachable record (or a failed refetch of a changed policy) keeps the still-valid cached policy. A policy host that returns a transient 5xx/429 is treated as “fetch failed” (fail open, not cached as “no policy”), whereas a 404, a non-text/plain body, mode: none or an unparseable policy is a definitive absence: it removes a cached policy for the domain, and each worker remembers it (in memory only) for five minutes before asking again.

A cached policy is refreshed on use once less than half of its lifetime (its max_age, capped at one week) remains (RFC 8461 section 10.2): the policy file is fetched again even when the id is unchanged or the _mta-sts record has disappeared, and a successful fetch stores the policy for its full lifetime again, so a domain that is mailed regularly never reaches a “first contact” again. A refresh that fails, or finds no usable policy under the unchanged id, keeps the cached policy (a domain withdraws its policy by publishing mode: none under a new id, RFC 8461 section 8.3); the worker then waits five minutes before trying again, and once less than a quarter of the lifetime remains each failure is logged as a warning, so a refresh that keeps failing is noticed before the policy lapses.

Stored policies are also refreshed without a message asking for them, as RFC 8461 section 10.2 asks: pepsi-queue(1) gc, run hourly, fetches every stored policy with half of its lifetime gone (or less than three hours left) under the same rules, using the DNS_SERVERS, DNS_TIMEOUT and MTA_STS_TIMEOUT of the first stage section running this program with MTA_STS on. A domain that keeps publishing a policy therefore never lapses back to a first contact, however rarely it is mailed; a policy whose refreshes keep failing is kept until its max_age runs out.

DANE (RFC 7672): when DANE is strict (the default) or warn and the destination MX host publishes DNSSEC-validated TLSA records, the MX certificate is authenticated against them instead of by PKIX; this takes precedence over MTA-STS for that connection. DANE rests on DNSSEC. Pepsi trusts the AD (Authentic Data) bit of the response rather than validating itself, so the configured resolver (DNS_SERVERS, else [pepsi] DNS_SERVERS, else resolv.conf) must validate and must be reached over a trusted path: loopback, or DNS over TLS or HTTPS (a tls:// or https:// entry, see pepsi.conf(5)). TLSA (and MX) answers without the AD bit are treated as “no DANE”. A worker started with DANE on logs a warning when that resolver is neither a loopback address nor reached over an encrypted entry, and another when it does not validate: the worker asks it for the signed ietf.org SOA and warns when the answer lacks the AD bit (DANE is then configured but never applied) or does not come. pepsi-status(1) shows the same check in its “DNSSEC resolver” section. In strict mode, a usable record that does not match defers the message as a transient failure, as RFC 7672 section 2.2 requires, and so does a failed TLSA or MX-security lookup (for example, for a DNSSEC-bogus record). In warn mode, an explicit opt-out for operators who would rather keep mail flowing to peers with stale TLSA records, the mismatch is logged and delivery proceeds with the unverified certificate check that applies without DANE. Either way STARTTLS is mandatory for such a host (RFC 7672 section 2.2: a secure TLSA RRset means any connection to the host must use TLS): warn relaxes the certificate check, never TLS itself. If a host does not offer STARTTLS, or an attacker strips the offer from the reply, the message is deferred rather than sent in cleartext.

That precedence holds only where DANE is at least as strong as what it replaces. For a host covered by an enforce MTA-STS policy, warn mode is not used, because a warn-mode mismatch accepts any certificate, which would discard the policy’s RFC 8461 §5 validation requirement. Instead, the certificate is validated by PKIX and the substitution is logged. strict mode still takes precedence there. A domain that simply publishes no TLSA records is delivered normally even in strict mode: DANE is opportunistic and applies only when records exist. A domain that publishes TLSA records of which none is usable (a PKIX usage, or a matching type that this build does not implement) is not the same thing: per RFC 7672 §2.2 it has still committed the host to TLS. STARTTLS therefore becomes mandatory for it, unauthenticated but never cleartext, and a hop that does not offer it defers the message. Where one usage and selector are published with both a SHA-256 and a SHA-512 record (matching types 1 and 2), only the SHA-512 records are matched (RFC 7671 section 9, digest algorithm agility): the weaker digest is published only for clients that lack the stronger one, and matching it anyway would leave the connection exactly as strong as that weaker digest. Matching type 0 (the full data) is always matched.

Revocation (RFC 6960): wherever the MX certificate is validated by PKIX (under an MTA-STS policy, for a REQUIRETLS message, or as the DANE warn fallback), an OCSP response that the server staples in the handshake (RFC 6066 status_request) is verified against the certificate’s issuer, or a responder that the issuer authorised. A current revoked answer refuses the session like any other certificate failure; on an opportunistic session it is only logged. A missing, stale or unverifiable response leaves the certificate unchecked, and no responder is ever queried. Under a DANE-TA (usage 2) match the staple is evaluated the same way, and a verified revoked defeats the match. For a certificate that a DANE-EE (usage 3) record matched, the staple is not consulted: that record ties the session to the key that the domain publishes now.

Require TLS (RFC 8689): a message tagged state.tls_required = "required" (it arrived with the REQUIRETLS MAIL FROM parameter, see pepsi-ingress(1)) is sent only under the conditions of RFC 8689 §4.2.1, whatever the recipient domain publishes. Its MX host names must be validated, either by DNSSEC (the MX RRset carries the AD bit, which needs DANE on and a validating resolver) or by an MTA-STS policy. An MTA-STS policy counts in enforce and testing mode alike, since it is the policy’s authenticated fetch and host match that validate the names. A domain that offers neither is a permanent failure (5.7.10). STARTTLS is mandatory and the certificate is authenticated by DANE where the host publishes usable TLSA records (a warn-mode mismatch falls back to PKIX here, never to the accept-any check) and by PKIX against the system roots otherwise (RFC 6125, the MX host name). After the upgrade the host must advertise REQUIRETLS, and the parameter is passed on. A host that fails any of this gets a QUIT and the next MX host is tried; when none can take the message it is bounced with 5.7.30 (no REQUIRETLS at the hop) or 5.7.10 (no validated TLS). If some host failed for a transient reason that a retry might clear, the message is retried instead. The bounce is tagged itself: it travels under the same requirement, returns headers only (RET=HDRS, RFC 8689 §5) and is sent with the parameter where the return path advertises it, but is not refused for a hop that lacks the extension (§5); a bounce that cannot be returned under the requirement is discarded, and its postmaster copy is held to the same rule. A message tagged "no" (it carried TLS-Required: No) is delivered per RFC 8689 §4.2.2 to every MX host over opportunistic STARTTLS: an enforce MTA-STS policy neither restricts the hosts nor demands TLS, and usable TLSA records are matched but a mismatch only warns. A handshake that fails after STARTTLS was offered is still never retried in cleartext (an attacker could force that failure), so such a hop defers the message. Sessions of a "no" message are not recorded for TLS Reporting: the originator asked for policy failures to be ignored, so such a failure is nothing that the domain owner should hear about.

SMTP TLS Reporting (RFC 8460): when [pepsi-tlsrpt] SEND_REPORTS is set, the outcome of each TLS session is recorded as an aggregate counter in pepsi.tls_session, keyed by the applied policy (tlsa/sts/no-policy-found) and MX host. The outcome is a success or a classified failure (starttls-not-supported, certificate/handshake or DANE/MTA-STS validation). pepsi-tlsrpt(1) later compiles these into daily reports. Recording is best-effort (a database hiccup never fails a delivery) and is skipped for a report message itself (state.tlsrpt).

A host that refuses the session with a 5xx reply to the greeting, EHLO, HELO or STARTTLS has said nothing about the recipient, so the next MX host is tried (RFC 5321 section 5.1). Such a refusal is reported as a permanent failure only when no host takes the message and none failed transiently; a 5xx to MAIL FROM, RCPT TO or DATA ends the attempt at once.

A host that answers EHLO with 500 or 502 does not know the command, so the stage greets it with HELO instead (RFC 5321 section 3.2). Such a host advertises no extension: the message is converted to 7-bit where needed, and a hop that must use TLS fails transiently because it offers no STARTTLS.

On success the row is removed (or, if the stage sets NEXT_STAGE, advanced). A transient failure pauses the message with an exponential backoff (re-queued by pepsi-dispatch(1) when its timeout elapses); past MAX_LIFETIME the failure is treated as permanent. A permanent failure of an ordinary message is routed to the stage’s BOUNCE_STAGE (or, with none configured, the row is marked failed). A permanent failure of a bounce (null sender) is never bounced again. With POSTMASTER set, the row is the last of the report, so it is removed only once a copy has been delivered there. While the postmaster’s exchanger defers the copy the row keeps retrying like any other, and when the copy is refused, or still deferred past MAX_LIFETIME, the row is marked failed for an operator to find. pepsi-failure-bouncer(1) removes such a row after its MIN_AGE, since a bounce is never bounced. Without POSTMASTER the bounce is discarded, and so is a bounce addressed to POSTMASTER itself.

DSN (RFC 3461): when the recipient’s MX advertises the DSN extension, the parameters that the origin requested are propagated to it: RET/ENVID and the recipient’s NOTIFY/ORCPT, read from the row’s state.dsn. Otherwise they are omitted. On a permanent failure the recipient’s NOTIFY/ORCPT and the ENVID are handed to the bounce stage so a failure DSN is generated only when requested. This stage preserves state.dsn.

RRVS (RFC 7293): a recipient that arrived with an RRVS= parameter (kept in state.dsn.rcpt) has it passed on verbatim, no-support action included, when the MX advertises RRVS. When it does not, the default action R fails the recipient permanently with 5.7.19 (a DSN, so the sender learns the request could not be enforced), and C continues with the request written as a Require-Recipient-Valid-Since: header field naming that one recipient – each relay transaction carries a single recipient, so the field never discloses one recipient’s date to another.

When the global [pepsi] ORIGINATE_SUCCESS_DSN is enabled and a successful delivery’s recipient requested NOTIFY=SUCCESS, the message is routed (after delivery) to BOUNCE_STAGE, which emits a positive (Action: delivered) report to the sender. With the flag off, or without a SUCCESS request, a successful delivery is simply finished.

When DELAY_DSN_AFTER is set and a still-undelivered message has been queued at least that long, a one-shot “delayed” (Action: delayed) DSN is sent to the sender — but only if the sender requested NOTIFY=DELAY (delay has no implicit default). The original message keeps being retried; the warning is a separate message routed through BOUNCE_STAGE, and is sent at most once.

Proof of origin: when the shared [pepsi-origin] section is configured (on by default; pepsi-setup(1) generates a secret if none is set), each outbound message is stamped with a Pepsi-Origin header before delivery, and the nonce is recorded in pepsi.origin_nonce (valid for two weeks). The header holds an HMAC over the originating sender account, a fresh 128-bit nonce, a timestamp and our HOSTNAME. The same stamping is shared with pepsi-stage-relay-to-smarthost(1) so a message takes a proof whichever outbound path it uses. A returning bounce embeds this header, letting pepsi-stage-anti-spam(1) confirm that the bounce is a reply to mail we actually sent. The header is prepended like the Received: trace header (above any existing signatures, so it disturbs none) and is left unsigned. A nonce that cannot be recorded (a database error) holds the message back, and the message is retried like any host fault (see pepsi-dispatch(1)): a header whose nonce is not on record would make every bounce to the message look forged. Without the [pepsi-origin] section no header is added; a section whose secret cannot be read stops the stage’s workers from starting (the queue is held, and the journal says why), exactly as pepsi-setup(1) refuses it.

Content downgrading (RFC 6152 / RFC 6531): the message is matched to the extensions the MX actually advertises rather than sent verbatim. When the body contains 8-bit octets and the MX supports 8BITMIME the envelope carries BODY=8BITMIME; when it does not, the MIME tree is walked and each 8-bit leaf part is re-encoded with a 7-bit content-transfer-encoding (quoted-printable for text/*, base64 otherwise). What a part declares is not taken as proof of what it holds: a part labelled base64 that carries raw 8-bit octets is re-encoded too, and a multipart/* whose declared boundary= occurs nowhere in its body has no parts to preserve and is encoded whole. The result is then re-tested, because the walk is best-effort over a message that nobody validated (a tree nested past the depth cap is copied through unchanged): a body still carrying 8-bit octets is a permanent failure (554) rather than something to put on the wire, which RFC 6152 §3 forbids “under any circumstances”.

When the message needs SMTPUTF8 (UTF-8 in the headers or envelope) and the MX supports it the envelope carries SMTPUTF8; when it does not, UTF-8 header fields are rewritten as RFC 2047 encoded-words. They are used in the three places where RFC 2047 §5 allows one, so that the field still parses: an unstructured field body, a display-name phrase (a quoted-string becomes one encoded-word, without the quotes) and the inside of a comment (the parentheses stay). A non-ASCII Content-Type or Content-Disposition parameter, for which §5 has no encoded-word, takes the RFC 2231 extended form instead (filename*=UTF-8''caf%C3%A9.txt, split into *0*/*1* sections when one line would not hold it); ASCII parameters are copied as written. This covers every MIME part’s header block, not only the message’s, since that is where an attachment’s filename sits. A non-ASCII boundary= has no encoded form at all: it must match the body’s delimiter lines octet for octet, and RFC 2046 allows it only 7-bit characters. Rather than bounce the message, Pepsi gives the multipart a fresh random ASCII boundary and rewrites its delimiter lines to match. A part header that cannot be converted (say, raw Latin-1 octets) is copied as it stands and left to the 8BITMIME re-test, since the transport sees it as body content. A non-ASCII envelope address, and a non-ASCII octet inside a header address, cannot be downgraded: towards a hop without SMTPUTF8, such a message is a permanent failure (bounced). Re-encoding a body necessarily breaks any body-covering signature already on the message (the originator’s DKIM body hash and the ARC-Message-Signature from pepsi-stage-arc(1)); this is unavoidable, since the MX’s capabilities are only known after MX selection, and rare in practice. Pepsi’s own DKIM signature is not affected in the common case: pepsi-stage-dkim-sign(1) converts an 8-bit body to 7-bit before it signs, so there is nothing left here to re-encode.

95.1.11.1.4. Configuration

Pipeline wiring and every operational option live in the stage’s own [stage-<name>] section (PROGRAM = pepsi-stage-relay-to-internet): the SERVER_NAME/POSTMASTER identities, EHLO_FROM_PTR (announce the forward-confirmed PTR name of each connection’s local address), the connection timeouts, the retry-backoff schedule and MAX_LIFETIME, DELAY_DSN_AFTER, MAX_HOP_COUNT, the DNS settings, MTA_STS/MTA_STS_TIMEOUT, ADDRESS_FAMILY and DANE. They are documented in pepsi.conf(5).

95.1.11.1.5. State

Inputs (read from the row’s state; all optional):

  • state.dsn — the RFC 3461 parameters (message-level ret/envid and the first recipient’s notify/orcpt); propagated to the MX when it advertises DSN and consulted to gate failure/success/delay reports.

  • state.origin — the 8BITMIME/SMTPUTF8 hints (body_8bit, smtputf8) used by the content-downgrading decision.

  • state.tls_required — the RFC 8689 tag ("required" or "no"), see Require TLS above.

Outputs (merged into the row’s state):

  • On a transient failure (pause): attempts, last_error and, once a delay DSN has been emitted, delay_sent.

  • On a permanent failure with a BOUNCE_STAGE (reroute), or on a delay warning (an enqueued clone): a state.bounce object (kind = permanent or delay) for pepsi-stage-bounce(1). For an SMTP-level failure it also records the structured next-hop detail — remote_mta (the recipient’s domain), smtp_code, enhanced_status, phase and reply_text — so the bounce can state precisely why delivery was refused.

  • On a successful delivery with ORIGINATE_SUCCESS_DSN and NOTIFY=SUCCESS: a state.bounce object with kind = success.

  • On a permanent failure with no BOUNCE_STAGE (fail): last_error.

state.dsn, state.origin and state.tls_required are always preserved. The state layout is described in full in pepsi.state(7).

Transitions (the retry schedule is RETRY_INITIAL / RETRY_FACTOR / RETRY_MAX_INTERVAL, bounded by MAX_LIFETIME):

  • successful delivery → finish (the row is deleted), or advance to NEXT_STAGE if one is set; with [pepsi] ORIGINATE_SUCCESS_DSN and a recipient that asked for NOTIFY=SUCCESS it instead reroutes to BOUNCE_STAGE to emit a positive (Action: delivered) DSN;

  • transient failure → pause for the next retry interval;

  • still queued past DELAY_DSN_AFTER with a NOTIFY=DELAY recipient → enqueue a one-shot delay-DSN clone at BOUNCE_STAGE (the original stays queued and keeps retrying);

  • permanent failure, or MAX_LIFETIME exhausted → reroute to BOUNCE_STAGE, or fail (terminal failed) if no BOUNCE_STAGE is configured;

  • an undeliverable bounce (null sender) is never re-bounced: with POSTMASTER set, the row is finished once a copy is delivered there, paused while the copy is deferred, and failed when the copy is refused or MAX_LIFETIME is exhausted; without it the row is finished.

95.1.11.1.6. Commands

worker

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

mta-sts DOMAIN

Diagnostic: look up and print the MTA-STS policy that would apply when delivering to DOMAIN. Uses the system resolver and needs no message or stage configuration.

95.1.11.1.7. Global Options

-c FILE, –config FILE

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

-L LOGLEVEL, –log LOGLEVEL

Set the logging verbosity (default [pepsi] LOG, else info).

-v, –verbose

Show log messages from all sources.

-h, –help; -V, –version

Print a usage summary / the version and exit.

95.1.11.1.8. 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, or the mta-sts lookup completed.

1

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

78

The worker refused to start: its [stage-<name>] section, [pepsi], [pepsi-tlsrpt] or [pepsi-origin] does not parse (or the origin secret cannot be read), or the database schema does not match this build. The dispatcher requeues what it handed over and retries the stage later.

95.1.11.1.9. Examples

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

echo 42 | pepsi-stage-relay-to-internet -c /etc/pepsi/pepsi.conf worker

Check which MTA-STS policy applies to a recipient domain:

pepsi-stage-relay-to-internet -c /etc/pepsi/pepsi.conf mta-sts example.com

95.1.11.1.10. See Also

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

The transport-security guarantees and their limits (what an active network attacker can still do with and without MTA-STS or DANE) are stated in the Threat model chapter of the Pepsi manual; the privileged-program table and the DNS resolver assumption are in its Security chapter.

95.1.11.1.11. Bugs

Report bugs to the Pepsi issue tracker.