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>] whose DOMAINS lists it, or to the single CATCH_ALL MTA; 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 against TLS_CA_BUNDLE alone, 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 = no accepts any certificate and so hands the AUTH credentials and the mail to whoever can intercept the connection. With verification on, an OCSP response that the smarthost staples is checked and a revoked answer 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-256 and their -plus channel-binding forms, ntlm, gssapi, oauth, or auto to pick the strongest password mechanism that the server offers. Most take USERNAME/PASSWORD; gssapi takes SERVICE_NAME/KRB5CCNAME, ntlm takes NT_DOMAIN/NT_WORKSTATION, and oauth takes USERNAME/TOKEN_FILE.

  • DANE/TLSA (RFC 7672) per MTA section: DANE = off | warn | strict, default strict (warn is an explicit opt-out). A certificate matching a usable TLSA record is accepted without the PKIX check; under warn a mismatch falls back to TLS_VERIFY, so a smarthost is never less verified than with DANE = off. A TLSA lookup that cannot be made (including nameservers that cannot be found) defers under strict and falls back to TLS_VERIFY under warn. 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, else resolv.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_NAME per MTA (defaults to SERVER_NAME).

  • Require TLS (RFC 8689): a message tagged state.tls_required = "required" is relayed only over validated TLS (TLS_VERIFY = no is overridden, MODE = plain bounces it with 5.7.10) to a smarthost that advertises REQUIRETLS after the upgrade (else 5.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 via MAX_HOP_COUNT.

  • A permanent failure (including no matching MTA) routes to BOUNCE_STAGE (or marks failed); 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/ORCPT to the smarthost only when it advertises DSN (RFC 3461); originates failure/success/delay reports under the same rules as the direct stage.

  • Per-hop 8BITMIME/SMTPUTF8 re-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 a Pepsi-Origin header, as in pepsi-stage-relay-to-internet; the smarthost passes it through.

  • TLS Reporting (RFC 8460): with [pepsi-tlsrpt] SEND_REPORTS each TLS session to the smarthost is counted in pepsi.tls_session (policy tlsa when DANE authenticated it, else no-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.origin and state.tls_required.

  • Outputs: attempts/last_error/delay_sent on pause; a state.bounce object when routing to/enqueuing for the bounce stage; last_error on terminal fail. state.dsn/state.origin preserved.

43.6. See also

pepsi-stage-relay-to-internet, pepsi-stage-bounce, pepsi-helper-token-refresh, Supported Features, pepsi-stage-relay-to-smarthost(1).