43. pepsi-stage-relay-to-smarthost¶
Relay through a configured upstream smarthost.
43.1. Role¶
pepsi-stage-relay-to-smarthost relays mail to a configured upstream MTA
(smarthost) chosen by recipient domain, instead of contacting MX hosts directly.
It is the other interchangeable delivery stage. Reference:
pepsi-stage-relay-to-smarthost(1).
43.2. Features¶
43.2.1. Smarthost routing¶
Routes each recipient domain to the
[…-mta-<name>]whoseDOMAINSlists it, or to the singleCATCH_ALLMTA; a domain with no matching MTA is a permanent failure. A domain may be listed by only one MTA. The MTA sections are shared across all smarthost-relay stages.No MX discovery and no DNS-learned MTA-STS — it speaks only to the configured smarthosts.
43.2.2. Transport and authentication¶
Per-MTA transport
plain/tls(implicit) /starttls(RFC 3207, the default).Certificate verification against the system store (plus an optional extra
TLS_CA), or againstTLS_CA_BUNDLEalone, which replaces the system store so that only the smarthost’s own CA can authenticate it (an unreadable or empty bundle refuses the worker);TLS_VERIFY = noaccepts any certificate and so hands theAUTHcredentials and the mail to whoever can intercept the connection. With verification on, an OCSP response that the smarthost staples is checked and arevokedanswer refuses the session (RFC 6960; nothing is queried). An optional client certificate (TLS_CLIENT_CERT/TLS_CLIENT_KEY).SMTP AUTH (RFC 4954), per MTA:
none,plain,login,external,cram-md5,digest-md5,scram-sha-1/scram-sha-256and their-pluschannel-binding forms,ntlm,gssapi,oauth, orautoto pick the strongest password mechanism that the server offers. Most takeUSERNAME/PASSWORD;gssapitakesSERVICE_NAME/KRB5CCNAME,ntlmtakesNT_DOMAIN/NT_WORKSTATION, andoauthtakesUSERNAME/TOKEN_FILE.DANE/TLSA (RFC 7672) per MTA section:
DANE = off | warn | strict, defaultstrict(warnis an explicit opt-out). A certificate matching a usableTLSArecord is accepted without the PKIX check; underwarna mismatch falls back toTLS_VERIFY, so a smarthost is never less verified than withDANE = off. ATLSAlookup that cannot be made (including nameservers that cannot be found) defers understrictand falls back toTLS_VERIFYunderwarn. Where one usage and selector are published under both SHA-256 and SHA-512, only the SHA-512 records are matched (RFC 7671 section 9). Pepsi trusts the resolver’s AD bit; a worker started with DANE on for some MTA warns when that resolver (DNS_SERVERS, else[pepsi] DNS_SERVERS, elseresolv.conf) is neither on loopback nor reached over DNS over TLS or HTTPS, or when it does not set the AD bit on a signed probe answer; such a resolver does not validate, and DANE is never applied.HELO_NAMEper MTA (defaults toSERVER_NAME).Require TLS (RFC 8689): a message tagged
state.tls_required = "required"is relayed only over validated TLS (TLS_VERIFY = nois overridden,MODE = plainbounces it with5.7.10) to a smarthost that advertisesREQUIRETLSafter the upgrade (else5.7.30), with the parameter passed on;"no"changes nothing here.
43.2.3. Delivery, retry and bounce¶
Sends with the message’s own envelope sender, one recipient per attempt (a multi-recipient row is first split into one row per recipient).
On success, finishes the row (or advances to
NEXT_STAGE).Exponential backoff on transient failure up to
MAX_LIFETIME; loop detection viaMAX_HOP_COUNT.A permanent failure (including no matching MTA) routes to
BOUNCE_STAGE(or marksfailed); a permanent failure of a bounce is discarded, never re-bounced. A rejected credential is a transient failure, never a bounce.
43.2.4. DSN and content adaptation¶
Propagates
RET/ENVID/NOTIFY/ORCPTto the smarthost only when it advertisesDSN(RFC 3461); originates failure/success/delay reports under the same rules as the direct stage.Per-hop
8BITMIME/SMTPUTF8re-advertising or downgrade (RFC 6152 / RFC 6531 / RFC 2045 / RFC 2047).RRVS (RFC 7293) passed on when the smarthost advertises it, otherwise handled by the recipient’s no-support action exactly as in the direct stage.
Proof of origin: with
[pepsi-origin]configured (the default) every outbound message is stamped with aPepsi-Originheader, as in pepsi-stage-relay-to-internet; the smarthost passes it through.TLS Reporting (RFC 8460): with
[pepsi-tlsrpt] SEND_REPORTSeach TLS session to the smarthost is counted inpepsi.tls_session(policytlsawhen DANE authenticated it, elseno-policy-found) for pepsi-tlsrpt.
43.3. Configuration¶
[stage-<name>] with PROGRAM = pepsi-stage-relay-to-smarthost:
SERVER_NAME (required), NEXT_STAGE/BOUNCE_STAGE, the timeouts
(CONNECT_TIMEOUT/COMMAND_TIMEOUT/DATA_TIMEOUT), the retry policy
(RETRY_INITIAL/RETRY_MAX_INTERVAL/RETRY_FACTOR/MAX_LIFETIME/
DELAY_DSN_AFTER), MAX_HOP_COUNT, ADDRESS_FAMILY (the default every
MTA entry inherits) and the DANE resolver settings
DNS_SERVERS/DNS_TIMEOUT. The upstream MTAs are defined in shared
[pepsi-stage-relay-to-smarthost-mta-<name>] sections: HOST/PORT
(both required), MODE, TLS_VERIFY/TLS_CA/TLS_CA_BUNDLE/TLS_CLIENT_CERT/
TLS_CLIENT_KEY, AUTH with its credentials, DANE, ADDRESS_FAMILY,
HELO_NAME, and routing via DOMAINS / CATCH_ALL. Full reference:
pepsi-stage-relay-to-smarthost(1).
43.4. Privilege¶
Installed setgid pepsi-token (mode 2550, owner pepsi:pepsi-token),
and therefore a standalone binary rather than one of the programs folded into the
unified pepsi binary. The dispatcher runs the stage as the unprivileged
pepsi user; the setgid bit gives the worker egid=pepsi-token, so that
it can read the group-restricted files that it needs without making pepsi a
permanent member of that group: the OAuth access tokens that
pepsi-helper-token-refresh writes (AUTH = oauth), a mutual-TLS
TLS_CLIENT_KEY and a Kerberos credential cache (AUTH = gssapi). The file
is not world-executable: the stage accepts -c, so any local user who could
run it could point it at a server of their own and send that server the credentials.
The mode is listed with every other privileged program in The privilege split;
what an active network attacker can and cannot do to a smarthost hop (and what
TLS_VERIFY = no gives away) is stated in An active network attacker.
43.5. State¶
Identical to pepsi-stage-relay-to-internet:
Inputs:
state.dsn,state.originandstate.tls_required.Outputs:
attempts/last_error/delay_senton pause; astate.bounceobject when routing to/enqueuing for the bounce stage;last_erroron terminalfail.state.dsn/state.originpreserved.
43.6. See also¶
pepsi-stage-relay-to-internet, pepsi-stage-bounce, pepsi-helper-token-refresh, Supported Features, pepsi-stage-relay-to-smarthost(1).