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, aTLS-Required: Noheader field tags it for the opposite, and on a cleartext session the parameter is refused with530 5.7.10;VRFYanswers252,EXPN502.Accepts mail only for
ACCEPTED_DOMAINS(others →550 5.7.1relaying, unless the session is authenticated); always accepts the domainless<Postmaster>(RFC 5321 §4.5.1), rewritten toPOSTMASTERorpostmaster@HOSTNAME.Unknown recipients at a served domain are refused at
RCPTwith550 5.1.1when 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 withMAIL FROM:<>/RCPT TO. Every uncertainty accepts;MAX_INVALID_RECIPIENTS(10) unknown recipients close the session with421. See Unknown recipients and backscatter.Legacy routing syntax. A local part with
%(the percent hack) or!(a bang path) at a served domain is refused550 5.1.3unless 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 answers550 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 defaultnoneonly records the verdict.Durable acceptance: returns
250only after the row commits; a database outage yields a transient451.MAX_CONNECTIONSand a budget ofMAX_OPEN_SOCKETSfile 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 holdMAX_CONNECTIONS_PER_IP(16) connections, all local connections togetherMAX_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, with421 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 failedAUTHper session andAUTH_FAILURES_PER_HOUR(20) per source range (then421without asking the SASL backend),ACCOUNT_AUTH_FAILURES_PER_HOUR(10) per account from all sources (thenACCOUNT_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), andLOCAL_MESSAGES_PER_MINUTE/LOCAL_MESSAGE_BURSTper local uid (451 4.7.1), andUSER_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 ownReceived:fields, is refused554 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 answers452 4.3.1atRCPT,DATA/firstBDATand 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 with554, 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 with421 4.7.0, and a TLS ClientHello whose ALPN offer names only HTTP protocols is refused with ano_application_protocolalert (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 afterSTARTTLS, has not completed by then. A connection waiting for the next bytes of aDATA/BDATbody 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
DATAbody is read on to its end and refused with552; once a furtherMAX_MESSAGE_SIZEoctets arrive without the end-of-data marker, the server answers552and closes instead.Header limits. A top-level header block with more than
MAX_HEADER_FIELDS(1000) fields, or a field larger thanMAX_HEADER_FIELD_SIZE(100 KiB unfolded), is refused552 5.3.4on 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
DATAbody, or a dot framed by a bare CR (<CR>.<CR>,<CR>.<CR><LF>,<CR><LF>.<CR>), is refused with500 5.6.0and 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_LINEandMAX_DATA_LINEonly 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 typeSMTP/ESMTP/ESMTPS/ESMTPA/ESMTPSA(RFC 3848) and the time; aforclause is added for single-recipient transactions. For an encrypted session the negotiated TLS version and cipher are appended as a(version=… cipher=…)comment after theESMTPSkeyword (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
HOSTNAMEasauthserv-id; the verdicts are also stored understate.auth(spf/dkim/dmarc/arc).Never counts an
rsa-sha1signature (RFC 8301,permerror) or one under a key published witht=y(RFC 6376 testing mode,neutral) as a DKIM pass, honours theFrom:domain’sadkim=sinstate.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_ENFORCErejects (550); DNS/parse errors are recorded and the mail accepted. The wizard writesDMARC_ENFORCE = yesfor a new installation; the compiled-in default is off, so an existing configuration keeps its behaviour, andpepsi-setupwarns about one that leaves the option unset, or off while a served domain publishesp=reject. AFrom:naming several domains is evaluated for each (up to 10), and underDMARC_ENFORCEingress refuses unauthenticated mail to which DMARC cannot be applied (noFrom:address, more than 10 domains). The one override is a validating ARC chain (RFC 8617) whose last sealer is named inARC_TRUSTED_SEALERS, the list of forwarders and mailing lists that the operator trusts (empty by default). Such a message is recorded asstate.auth.arc_override, whilestate.auth.dmarckeeps readingfail. 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 theFrom:domain first, under oneVERIFY_TIMEOUT(20 s) deadline; a timeout is atemperrorbound to its own signature, so a forger cannot slow DNS down to escapeDMARC_ENFORCE.
32.2.4. Inbound header hygiene¶
A message with more than one
From:field is refused550 5.6.0on every listener, since clients disagree about which one they show.Ingress removes every
Bcc:andResent-Bcc:field from every message, submitted or not, and on a session that is not authenticated also everyX-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: anyX-Pepsi-Warningthe sender wrote is removed,X-Pepsi-Warning: display-name-claims-other-addressis prepended and the claimed address is recorded asstate.auth.display_name_mismatch. Submitted mail with such aFrom:is refused instead. See What a security indicator means.Hidden characters in
From:. AFrom:(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@oecreads asceo@bank.example), is marked withX-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 withX-Pepsi-Warning: from-domain-resembles-served-domain, header only, without the[external]tag.Ambiguous MIME (
MIME_ANOMALIES, defaultenforce). The hard classes are refused554 5.6.0: an empty boundary, a NUL in a MIME header, conflicting duplicateContent-Type/Content-Transfer-Encodingfields, an encoded-word boundary, and differing copies of a message-headerDate,Subject,To,Reply-ToorSender. DifferingCcfields are stored as received and markedX-Pepsi-Warning: duplicate-header-cc;logmarks 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 asstate.mime_anomalies,state.mime_normalise(a rewrite owed to the ARC stage) andstate.mime_normalised(who rewrote).logonly 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-Warningheader in four cases:served-domain-not-authenticatedwhen itsFrom:is at a served domain with no DMARC, aligned DKIM or aligned SPF pass behind it;served-sender-not-authenticatedwhen itsSender:is at a served domain with no passing DKIM signature or SPF pass aligned with it;from-ambiguouswhen itsFrom:cannot be read in only one way, or names mailboxes in several domains, whatever its verdicts; anddmarc-fail-not-enforcedwhen its DMARCfailwas not acted on (DMARC_ENFORCEoff, orp=none), except for a failure that a trusted ARC sealer vouched for. Each also puts[external](TAG_EXTERNAL) at the front of theSubject, 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.warningslists the values written;EXTERNAL_SUBJECT_TAG = nokeeps 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 = yesmakes client authentication mandatory and applies the submission fixups (a missingDate:/Message-ID:is added). Any of four mechanisms authenticates a session: a peer address inMYNETWORKS, UNIX-socket peer credentials (AUTH_PEERCRED, the default on a UNIX listener and rejected on TCP), a SASLAUTHexchange (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 setsTLS_AUTH_CLIENT_TLS12 = yes. An authenticated session is recorded withstate.local_origin = trueand 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 addressesUSERNAME_MAPgrants it (defaultusername@HOSTNAME; an empty entry denies the account). TheMAIL FROMand everyFrom:mailbox must be allowed (550 5.7.1); a missingFrom:, a pure group, a mailbox that does not parse strictly as RFC 5322, or a display name naming another address is refused550 5.6.0. ASender:is replaced, added or removed to name the account’s canonical identity.state.origin.from_boundrecords whether theFrom:is one concrete granted address, which is what lets a submission speak for it (key registration, key commands).Sender bindings.
MYNETWORKSpeers andTLS_AUTH_CLIENTcertificates send as the addressesSENDER_MAPbinds 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 aMYNETWORKSentry outside loopback whole, the server refuses to start (pepsi-setup validaterefuses it too); only a loopback entry is unrestricted. Both the server at start andpepsi-setup validatewarn 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) theReceived:header has nofromclause (no client address, reverse name or EHLO name), and the client’sUser-AgentandX-Mailerare removed, per draft-josefsson-email-received-privacy; thebyclause thatMAX_SELF_HOPScounts 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] SOCKETunless an explicit section already serves that path.SOCKET = noneis 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.2or552 5.2.2, per[pepsi] MAILBOX_OVER_QUOTA). Ingress only ever readspepsi.mailbox_quota, and refuses only on a measurement younger thanMAILBOX_QUOTA_MAX_AGE; every uncertainty (no row, a stale or absent measurement, a database error) accepts.MAILBOX_QUOTA_RCPT_CHECK = no(defaultyes) 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
250and not stored again. The firstRCPT TOstands, with its DSN parameters.Validates and stores
RET/ENVID(MAIL FROM) andNOTIFY/ORCPT(RCPT TO) understate.dsn; malformed values are rejected501.
32.2.8. Recycled logins (RFC 7293)¶
RRVS=<date-time>[;C|R]onRCPT TOis validated (501 5.5.4) and stored understate.dsn.rcpt[i].rrvs. For a served domain the login (local part, sub-address stripped) is looked up inpepsi.login_assignment; a recorded change of owner after the requested time is refused550 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 understate.origin.body_8bit.BINARYMIMEis rejected (501). Per-hop re-advertising/downgrading happens later in the relay stages.
32.2.10. SRS reverse decode¶
A recipient in
SRS_DOMAINwhose 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_DOMAINthat is a forward return address (fwd+…, the envelope sender of a copy an alias or.forwardsent off-site) is accepted only from the null sender, only while it verifies and is younger thanMAX_AGE_DAYS, and only as the transaction’s sole recipient (any other recipient beside it gets452 4.5.3); otherwise550 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’sBOUNCE_STAGE, else a stagebouncerunningpepsi-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
headersandbodycolumns, with the envelope, parsedFrom:/Subject:and the verdicts; inserts atstage = 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 noNOTIFY: 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’sPOLL_INTERVALof 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 thepepsi-ingressaccount with no supplementary groups; under systemd it runs unprivileged from the start and gets root-only certificates asLoadCredential=copies.Its database role is cut down to what admission needs:
INSERTintoworkqueue/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 ofpepsi-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).