32. pepsi-ingress

The inbound SMTP server (MTA) and the entry point of the pipeline.

32.1. Role

pepsi-ingress runs the SMTP server that receives mail, authenticates it at the boundary, and stores each accepted message as one pepsi.workqueue row at stage = init before notifying the dispatcher. It is the only component that talks to external sending clients; everything downstream operates on the stored row. The exhaustive option reference is pepsi-ingress(1) / pepsi.conf(5).

32.2. Features

32.2.1. Reception (RFC 5321)

  • SMTP/ESMTP server with per-listener transport: cleartext, STARTTLS upgrade (RFC 3207) and implicit TLS (RFC 8314); listeners bind TCP, UNIX or systemd-activated sockets.

  • Message bodies via DATA or CHUNKING/BDAT (RFC 3030).

  • Advertises SIZE (enforcing MAX_MESSAGE_SIZE → 552), PIPELINING, ENHANCEDSTATUSCODES, 8BITMIME (RFC 6152), SMTPUTF8 (RFC 6531), DSN (RFC 3461) and RRVS (RFC 7293), and — on a TLS-protected session only — REQUIRETLS (RFC 8689): the parameter tags the message (state.tls_required) for validated TLS on every further hop, a TLS-Required: No header field tags it for the opposite, and on a cleartext session the parameter is refused with 530 5.7.10; VRFY answers 252, EXPN 502.

  • Accepts mail only for ACCEPTED_DOMAINS (others → 550 5.7.1 relaying, unless the session is authenticated); always accepts the domainless <Postmaster> (RFC 5321 §4.5.1), rewritten to POSTMASTER or postmaster@HOSTNAME.

  • Unknown recipients at a served domain are refused at RCPT with 550 5.1.1 when something on the host can tell (VERIFY_RECIPIENTS = auto, the default): a local account, an alias, a mailing list, a service address, or an LMTP/gateway backend asked with MAIL FROM:<>/RCPT TO. Every uncertainty accepts; MAX_INVALID_RECIPIENTS (10) unknown recipients close the session with 421. See Unknown recipients and backscatter.

  • Legacy routing syntax. A local part with % (the percent hack) or ! (a bang path) at a served domain is refused 550 5.1.3 unless a mailbox authority vouches for the address, so a back end behind an unverified domain is never handed a route to a third party.

  • Reverse DNS. With IPREV_ACTION = reject, ingress answers 550 5.7.25 (RFC 7372) to the recipients of an unauthenticated session that is not a submission session and whose client’s reverse DNS definitely fails (iprev=fail); <postmaster> is excepted. The default none only records the verdict.

  • Durable acceptance: returns 250 only after the row commits; a database outage yields a transient 451.

  • MAX_CONNECTIONS and a budget of MAX_OPEN_SOCKETS file descriptors bound the number of concurrent connections. Against connection abuse, ingress limits the rate of new connections per source range (CONN_RATE_PER_SECOND); a source range is one IPv4 address or one IPv6 /32 prefix. When that bound is reached and a new connection arrives, ingress closes the connection that has been idle longest in the source range whose connections have together been idle longest (if no connection is idle, the oldest one). One source range may hold MAX_CONNECTIONS_PER_IP (16) connections, all local connections together MAX_LOCAL_CONNECTIONS (32, at most half of them per uid; when it is full, a uid holding fewer evicts the heaviest uid’s longest-idle connection, idle at least 5 s, with 421 4.3.2).

  • Per-session and cross-session limits: MAX_MESSAGES_PER_SESSION (100), at most 1000 recipients per transaction (452 4.5.3), three failed AUTH per session and AUTH_FAILURES_PER_HOUR (20) per source range (then 421 without asking the SASL backend), ACCOUNT_AUTH_FAILURES_PER_HOUR (10) per account from all sources (then ACCOUNT_AUTH_DELAY, 20 s, before each attempt from a range the account has not signed in from, one attempt at a time; never a lock), and LOCAL_MESSAGES_PER_MINUTE / LOCAL_MESSAGE_BURST per local uid (451 4.7.1), and USER_RECIPIENTS_PER_HOUR / USER_RECIPIENT_BURST (500 each) accepted recipients per SASL account (450 4.7.1).

  • Routing loops: a message that already passed this host’s ingress MAX_SELF_HOPS (5) times, counted from its own Received: fields, is refused 554 5.4.6.

  • Queue admission control: while the queue or the disk under it is at a [pepsi] limit (MAX_QUEUE_ROWS, MAX_QUEUE_BYTES, MIN_FREE_SPACE) ingress answers 452 4.3.1 at RCPT, DATA/first BDAT and after the end of data; every uncertainty admits. The limits and what they protect are listed in Availability and under Resource limits.

  • An HTTP request line or header (GET/POST/CONNECT, Host:, …) sent to the SMTP port closes the session with 554, so a browser or HTTP proxy cannot be used to smuggle SMTP commands in a request body. The tenth line that is no command at all closes it with 421 4.7.0, and a TLS ClientHello whose ALPN offer names only HTTP protocols is refused with a no_application_protocol alert (the ALPACA vector; RFC 9325).

  • Per-command read timeouts (COMMAND_TIMEOUT/DATA_TIMEOUT, RFC 5321 §4.5.3.2) close slow or stalled sessions; TLS_HANDSHAKE_TIMEOUT (30 s) closes a connection whose TLS handshake, implicit or after STARTTLS, has not completed by then. A connection waiting for the next bytes of a DATA/BDAT body counts as idle, so a client trickling its body can be evicted like one that sends no command. SESSION_TIMEOUT (30 m) bounds the whole session besides: the per-read timeouts are reset by every byte, the deadline by nothing, so a transaction cannot be parked at a point of the client’s choosing for longer than that.

  • An oversized DATA body is read on to its end and refused with 552; once a further MAX_MESSAGE_SIZE octets arrive without the end-of-data marker, the server answers 552 and closes instead.

  • Header limits. A top-level header block with more than MAX_HEADER_FIELDS (1000) fields, or a field larger than MAX_HEADER_FIELD_SIZE (100 KiB unfolded), is refused 552 5.3.4 on every listener, the bound the Dovecot advisories CVE-2024-23184/23185 ask of the MTA in front of the mail store.

  • SMTP smuggling defence. A bare LF in a DATA body, or a dot framed by a bare CR (<CR>.<CR>, <CR>.<CR><LF>, <CR><LF>.<CR>), is refused with 500 5.6.0 and the connection closed, so no receiver that treats a lone CR or LF as a line ending can be shown an early end of the message. Other bare CRs pass unchanged.

  • Lenient line lengths. The RFC 5321 §4.5.3.1.4/§4.5.3.1.6 limits (512-octet command lines, 1000-octet text lines) bind senders; per the same section’s guidance that receivers be liberal, ingress accepts longer lines. The internal caps MAX_CMD_LINE and MAX_DATA_LINE only guard against memory exhaustion and do not enforce conformance: when a line with no terminator grows past the cap, ingress drops the connection.

32.2.2. Trace header

  • Prepends an RFC 5321 §4.4 Received: header before authentication (so the ARC seal covers it), recording the client (HELO/EHLO, reverse-DNS, IP), this server, the transmission type SMTP/ESMTP/ESMTPS/ESMTPA/ ESMTPSA (RFC 3848) and the time; a for clause is added for single-recipient transactions. For an encrypted session the negotiated TLS version and cipher are appended as a (version=… cipher=…) comment after the ESMTPS keyword (RFC 8314 §4.3).

32.2.3. Authentication (recorded at the boundary)

  • SPF (RFC 7208), DKIM verification (RFC 6376 / RFC 8463) and DMARC (RFC 7489), plus iprev/FCrDNS (RFC 8601).

  • Prepends an Authentication-Results header (RFC 8601) with the ingress HOSTNAME as authserv-id; the verdicts are also stored under state.auth (spf/dkim/dmarc/arc).

  • Never counts an rsa-sha1 signature (RFC 8301, permerror) or one under a key published with t=y (RFC 6376 testing mode, neutral) as a DKIM pass, honours the From: domain’s adkim=s in state.auth.dkim, and limits SPF to two void lookups (RFC 7208 section 4.6.4, permerror).

  • Fail-open: only a definite DMARC failure under DMARC_ENFORCE rejects (550); DNS/parse errors are recorded and the mail accepted. The wizard writes DMARC_ENFORCE = yes for a new installation; the compiled-in default is off, so an existing configuration keeps its behaviour, and pepsi-setup warns about one that leaves the option unset, or off while a served domain publishes p=reject. A From: naming several domains is evaluated for each (up to 10), and under DMARC_ENFORCE ingress refuses unauthenticated mail to which DMARC cannot be applied (no From: address, more than 10 domains). The one override is a validating ARC chain (RFC 8617) whose last sealer is named in ARC_TRUSTED_SEALERS, the list of forwarders and mailing lists that the operator trusts (empty by default). Such a message is recorded as state.auth.arc_override, while state.auth.dmarc keeps reading fail. Every refusal is logged with the last sealer of the refused chain (arc-sealer=<domain> when the chain validates), so the log names the candidates for that list.

  • Bounded work: at most MAX_DKIM_SIGNATURES (10) signatures are verified, those that can align with the From: domain first, under one VERIFY_TIMEOUT (20 s) deadline; a timeout is a temperror bound to its own signature, so a forger cannot slow DNS down to escape DMARC_ENFORCE.

32.2.4. Inbound header hygiene

  • A message with more than one From: field is refused 550 5.6.0 on every listener, since clients disagree about which one they show.

  • Ingress removes every Bcc: and Resent-Bcc: field from every message, submitted or not, and on a session that is not authenticated also every X-Pepsi-List-Hops: (the mailing-list loop counter). Both happen after SPF/DKIM/DMARC, so signatures are judged on the bytes that were signed.

  • Display-name claims. A From: whose display name or comment names an address other than the mailbox’s own ("ceo@example.com" <mallory@example.net>, judged as rendered: encoded-words decoded, look-alike @ folded) is marked, not refused or rewritten: any X-Pepsi-Warning the sender wrote is removed, X-Pepsi-Warning: display-name-claims-other-address is prepended and the claimed address is recorded as state.auth.display_name_mismatch. Submitted mail with such a From: is refused instead. See What a security indicator means.

  • Hidden characters in From:. A From: (encoded-words decoded) carrying a bidirectional control, a directional mark or an invisible character, which can make the field render as something else (\u202Eelpmaxe.knab@oec reads as ceo@bank.example), is marked with X-Pepsi-Warning: from-has-bidi-or-invisible-characters; the field is delivered as received. The zero-width joiner and non-joiner and the variation selectors do not count.

  • Disguised attachment names. A message with an attachment whose file name (RFC 2231 and RFC 2047 decoded, attached messages included) carries one of those characters is marked with X-Pepsi-Warning: attachment-name-has-bidi-or-invisible-characters; the name is delivered as received.

  • Look-alikes of a served domain. A From: domain with the same UTS #39 skeleton as a served domain but a different name (examp1e.org) is marked with X-Pepsi-Warning: from-domain-resembles-served-domain, header only, without the [external] tag.

  • Ambiguous MIME (MIME_ANOMALIES, default enforce). The hard classes are refused 554 5.6.0: an empty boundary, a NUL in a MIME header, conflicting duplicate Content-Type/Content-Transfer-Encoding fields, an encoded-word boundary, and differing copies of a message-header Date, Subject, To, Reply-To or Sender. Differing Cc fields are stored as received and marked X-Pepsi-Warning: duplicate-header-cc; log marks the other five the same way (duplicate-header-<field>) instead of refusing them. The soft classes are rewritten before storage to the reading that RFC 2045/2046 mandate: an unknown transfer encoding, whitespace after a quoted-printable soft break, non-alphabet base64 characters, a missing close delimiter, a delimiter line after the close delimiter (the epilogue is dropped), and identical duplicate fields, the RFC 5322 singleton header fields included. The rewrite never happens inside a signed or encrypted part; it comes after SPF/DKIM/DMARC (judged on the bytes as received) and before the ARC seal. A message carrying an ARC chain is therefore stored as received, and pepsi-stage-arc rewrites it once it has verified the chain. The results are recorded as state.mime_anomalies, state.mime_normalise (a rewrite owed to the ARC stage) and state.mime_normalised (who rewrote). log only counts and logs. See Ambiguous MIME is settled at the boundary.

  • Mail from outside that claims to be ours. After verification, ingress marks a message from an unauthenticated session with an X-Pepsi-Warning header in four cases: served-domain-not-authenticated when its From: is at a served domain with no DMARC, aligned DKIM or aligned SPF pass behind it; served-sender-not-authenticated when its Sender: is at a served domain with no passing DKIM signature or SPF pass aligned with it; from-ambiguous when its From: cannot be read in only one way, or names mailboxes in several domains, whatever its verdicts; and dmarc-fail-not-enforced when its DMARC fail was not acted on (DMARC_ENFORCE off, or p=none), except for a failure that a trusted ARC sealer vouched for. Each also puts [external] (TAG_EXTERNAL) at the front of the Subject, adding the field when there is none; rendered copies of the tag are removed from every inbound subject first, so a sender cannot write it. state.auth.warnings lists the values written; EXTERNAL_SUBJECT_TAG = no keeps the headers and leaves the subject alone. See Mail from outside that claims to be ours is marked.

  • ARC verify/seal is not done here — it is the pepsi-stage-arc stage, so ingress holds no ARC keys. Ingress records the session context that the ARC stage needs under state.origin.

32.2.5. Submission (RFC 6409)

  • A listener with SUBMISSION = yes makes client authentication mandatory and applies the submission fixups (a missing Date:/Message-ID: is added). Any of four mechanisms authenticates a session: a peer address in MYNETWORKS, UNIX-socket peer credentials (AUTH_PEERCRED, the default on a UNIX listener and rejected on TCP), a SASL AUTH exchange (SASL_TYPE = dovecot, offered only over TLS) or a TLS client certificate (TLS_AUTH_CLIENT, TLS_AUTH_CLIENT_CA), requested only from a client offering TLS 1.3, which encrypts it, unless the listener sets TLS_AUTH_CLIENT_TLS12 = yes. An authenticated session is recorded with state.local_origin = true and may relay to any domain.

  • Submission identity (RFC 6409 §6/§8.1). A session with a username (SASL or AUTH_PEERCRED) may use only the addresses USERNAME_MAP grants it (default username@HOSTNAME; an empty entry denies the account). The MAIL FROM and every From: mailbox must be allowed (550 5.7.1); a missing From:, a pure group, a mailbox that does not parse strictly as RFC 5322, or a display name naming another address is refused 550 5.6.0. A Sender: is replaced, added or removed to name the account’s canonical identity. state.origin.from_bound records whether the From: is one concrete granted address, which is what lets a submission speak for it (key registration, key commands).

  • Sender bindings. MYNETWORKS peers and TLS_AUTH_CLIENT certificates send as the addresses SENDER_MAP binds them to (most specific network, or the matched pin), passing the same checks. A certificate that the file does not bind authenticates nothing. If no key covers a MYNETWORKS entry outside loopback whole, the server refuses to start (pepsi-setup validate refuses it too); only a loopback entry is unrestricted. Both the server at start and pepsi-setup validate warn about a network wider than one host that is bound to a bare *. The file is read once at start-up; an error in it stops the server.

  • See The submission identity in Security model and A local shell user.

  • Submission requires a TLS-protected MODE, except on a local UNIX-domain socket, where the kernel supplies the identity and there is no transport to protect.

  • The submitter stays private. On a submission listener (RECEIVED_PRIVACY, on by default there) the Received: header has no from clause (no client address, reverse name or EHLO name), and the client’s User-Agent and X-Mailer are removed, per draft-josefsson-email-received-privacy; the by clause that MAX_SELF_HOPS counts stays, as does the journal’s record of the client.

  • The local submission socket used by pepsi-sendmail needs no listener section at all: ingress synthesises one for [pepsi-sendmail] SOCKET unless an explicit section already serves that path. SOCKET = none is the only switch that turns it off; failing to bind it is fatal.

32.2.6. Mailbox quota

  • When a mailbox quota policy is in force, a recipient whose measured usage is over its limit is refused at RCPT (452 4.2.2 or 552 5.2.2, per [pepsi] MAILBOX_OVER_QUOTA). Ingress only ever reads pepsi.mailbox_quota, and refuses only on a measurement younger than MAILBOX_QUOTA_MAX_AGE; every uncertainty (no row, a stale or absent measurement, a database error) accepts. MAILBOX_QUOTA_RCPT_CHECK = no (default yes) moves all enforcement to delivery time. See pepsi-quota.

32.2.7. DSN intake (RFC 3461)

  • A recipient that a transaction names a second time, in any mix of upper and lower case, is answered 250 and not stored again. The first RCPT TO stands, with its DSN parameters.

  • Validates and stores RET/ENVID (MAIL FROM) and NOTIFY/ORCPT (RCPT TO) under state.dsn; malformed values are rejected 501.

32.2.8. Recycled logins (RFC 7293)

  • RRVS=<date-time>[;C|R] on RCPT TO is validated (501 5.5.4) and stored under state.dsn.rcpt[i].rrvs. For a served domain the login (local part, sub-address stripped) is looked up in pepsi.login_assignment; a recorded change of owner after the requested time is refused 550 5.7.17. Role addresses are never tested and every uncertainty accepts; the relay and local delivery stages take the request up again. See A login that changes owner.

32.2.9. Internationalised / 8-bit intake

  • Accepts raw 8-bit bodies and UTF-8 headers/envelope; records the BODY= declaration under state.origin.body_8bit. BINARYMIME is rejected (501). Per-hop re-advertising/downgrading happens later in the relay stages.

32.2.10. SRS reverse decode

  • A recipient in SRS_DOMAIN whose local-part is a valid SRS token is decoded to the original sender and accepted for relay there (even outside served domains — the HMAC authorises it); a forged/expired token is rejected (550). This is how bounces return to original senders. See pepsi-stage-srs.

  • A recipient in SRS_DOMAIN that is a forward return address (fwd+…, the envelope sender of a copy an alias or .forward sent off-site) is accepted only from the null sender, only while it verifies and is younger than MAX_AGE_DAYS, and only as the transaction’s sole recipient (any other recipient beside it gets 452 4.5.3); otherwise 550 5.1.1, counted with the invalid SRS recipients. The remote report it carries is logged and dropped; ingress queues a row at the bounce stage (the SRS stage’s BOUNCE_STAGE, else a stage bounce running pepsi-stage-bounce, else the first such stage) from which pepsi-stage-bounce writes this host’s own DSN to the original sender about the address the sender used (Forwarding addresses in delivery reports). Without a bounce stage the report is dropped with a warning.

32.2.11. Storage and notification

  • Stores the message split into headers and body columns, with the envelope, parsed From:/Subject: and the verdicts; inserts at stage = init / status = pending. The one exception is the row made from a report about a forwarded copy, which enters at the bounce stage.

  • Wakes the dispatcher out of band and coalesced, at most once per DISPATCH_WAKE_INTERVAL (default 5 ms), after the row has committed. The admission transaction itself carries no NOTIFY: PostgreSQL holds a database-wide lock from the moment a transaction queues a notification until it commits, so a notifying insert cannot group-commit. A lost wake-up costs only the dispatcher’s POLL_INTERVAL of latency.

32.3. Privileges

  • Started as root (to bind ports 25/465/587), the server reads its TLS material, binds every listener and then drops to the pepsi-ingress account with no supplementary groups; under systemd it runs unprivileged from the start and gets root-only certificates as LoadCredential= copies.

  • Its database role is cut down to what admission needs: INSERT into workqueue/workqueue_body, read access to the configuration overlay, mailbox_quota, login_assignment, the list names, the downloaded IP blocklists and the certificate revocation lists, and the size columns used by admission control, plus appending to the mail and event logs — never message content. It is never a member of pepsi-maildir. See The privilege split and Trust boundaries.

32.4. Configuration

Read from [pepsi-ingress] (acceptance policy, limits, timeouts, DNS), the [pepsi-ingress-listener-*] sockets (transport and client authentication, per listener), and the shared [pepsi-postgres], [pepsi], [pepsi-sendmail] and [pepsi-srs] sections. The database configuration overlay is applied on top. Full reference: pepsi.conf(5) and Configuration.

32.5. Outputs to the pipeline

Seeds the row’s state with origin (SMTP provenance, including auth_method and from_bound), auth (the SPF/DKIM/DMARC verdicts and any display_name_mismatch), local_origin, spam = false for a message whose sole recipient is <Postmaster>, dsn (the RFC 3461 parameters, when the client requested them), and, for a message with ambiguous MIME, mime_anomalies, mime_normalise and mime_normalised. See Architecture for the state model.

32.6. See also

pepsi-dispatch, pepsi-stage-arc, pepsi-stage-srs, Supported Features, pepsi-ingress(1), pepsi.conf(5).