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-levelret/envidand the first recipient’snotify/orcpt); propagated to the MX when it advertisesDSNand 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_errorand, 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): astate.bounceobject (kind=permanentordelay) 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,phaseandreply_text— so the bounce can state precisely why delivery was refused.On a successful delivery with
ORIGINATE_SUCCESS_DSNandNOTIFY=SUCCESS: astate.bounceobject withkind = 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=SUCCESSit 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=DELAYrecipient → 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, elseinfo).- -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.