95.1.1. pepsi-ingress

receive incoming e-mail over SMTP and store it for Pepsi

Manual section:

1

95.1.1.1.1. Name

pepsi-ingress - SMTP server that stores incoming e-mail in PostgreSQL.

95.1.1.1.2. Synopsis

pepsi-ingress [GLOBAL-OPTIONS] serve

95.1.1.1.3. Description

pepsi-ingress is the mail-receiving component of Pepsi. It runs an SMTP server (a Message Transfer Agent) that accepts incoming e-mail over cleartext, implicit TLS and STARTTLS. A client may send the message body with DATA or, if it supports them, with CHUNKING/BDAT (RFC 3030), which the EHLO response advertises. It stores each accepted message in the workqueue table of the pepsi schema of a PostgreSQL database, together with its envelope, a small amount of parsed metadata, and the SMTP-origin metadata of the delivering connection (client IP, HELO/EHLO name, TLS, listener, reverse-DNS/iprev; see pepsi.conf(5)). The message is stored split into a headers column (everything up to the blank line) and a body, so that downstream stages that only touch the headers need not load the body. The body is a row of its own table, workqueue_body, which the message row references: every recipient row that the pipeline later splits off the message shares that one copy (see pepsi.conf(5), Stored Data). The message enters the stage pipeline at the initial stage (stage = init). Once the row has been committed, a NOTIFY on the workqueue channel wakes pepsi-dispatch(1). Ingress sends that notification out of band and coalesces it: it sends at most one per DISPATCH_WAKE_INTERVAL (default 5 ms), so a burst of admissions wakes the dispatcher once. It does so because a transaction carrying a notification cannot group-commit, which would serialise every concurrent SMTP session behind its own fsync. Nothing is at risk if one is lost: the dispatcher’s POLL_INTERVAL sweep is the safety net, so the cost is latency.

The server accepts mail for a configured set of domains (ACCEPTED_DOMAINS), matched by IDNA form, so either spelling of an internationalised domain (U-label or A-label) names the same served domain, as it does for delivery. Within those domains a local part is refused only when the host can tell that nothing would accept it (see Unknown recipients at RCPT); recipients outside the configured domains are rejected as relaying (550) unless the session is authenticated. The one exception is an Exchange Online tenant named by a [pepsi-ingress-exchange-online-*] section (see pepsi.conf(5)): from its SENDER_NETWORKS, with an envelope sender at one of its DOMAINS, such a recipient is accepted for now, and the message is relayed only if it proves the tenant at the end of the data, otherwise refused with 550 5.7.1. The domainless reserved mailbox <Postmaster> is always accepted regardless of the configured domains (RFC 5321 §4.5.1) and rewritten to a routable address, so that the rest of the pipeline (aliases, local delivery, relay) routes it like any ordinary recipient. That address is [pepsi-ingress] POSTMASTER when set, otherwise postmaster@HOSTNAME. To make postmaster mail reach a person, either point POSTMASTER at a real mailbox or add an alias for the rewritten address in a pepsi-stage-aliases ALIASES map. Such a message is also committed with state.spam = false so that the language and pay-to-send gates (pepsi-stage-block-language(1), pepsi-stage-anti-spam(1)) forward it. This keeps the postmaster mailbox reachable as RFC 5321 §4.5.1 requires, but it happens only when ``<Postmaster>`` was the transaction’s sole recipient. A message addressed to the postmaster and an ordinary mailbox is committed without the bypass and passes the gates like any other, because otherwise a spammer could exempt a real victim’s mail simply by adding a <Postmaster> RCPT beside it.

When SRS is configured (the shared [pepsi-srs] section; see pepsi-stage-srs(1)), a recipient in the SRS domain whose local-part is a valid Sender Rewriting Scheme token is decoded back to the original sender and accepted for relay to that sender. This happens even though the sender’s domain is not one that Pepsi serves, because the valid signature authorises the relay, and it is how bounces to mail that Pepsi relayed find their way back to the original senders. A forged or expired token is rejected (550), without saying which of the two it was. Because accepting such a recipient authorises a relay, that accept/reject pair is an online oracle over the SRS signature; a connection that presents three invalid SRS recipients is therefore logged at warn and closed with 421, so a search for a valid token costs one connection per three guesses and is visible to abuse monitoring.

A copy that an alias or a ~/.forward sent off-site carries a forward return address instead (fwd+<sealed>=<tag> in the SRS domain; see pepsi-stage-srs(1)). Ingress accepts a recipient of that shape only when the envelope sender is <>, the address verifies under the current or a PREVIOUS_SECRET_FILE secret and it is younger than [pepsi-srs] MAX_AGE_DAYS; any other case is answered 550 5.1.1 like a forged SRS address and counts towards the same limit of three. Such a report travels alone: a second recipient beside it, of either kind, gets 452 4.5.3. The report is not delivered or relayed. At the end of data, ingress logs its Reporting-MTA, Final-Recipient, Action, Status and Diagnostic-Code fields and stores a row at the bounce stage. From that row, the bounce stage writes this host’s own DSN to the original sender: the address that the sender used as Final-Recipient, a generic diagnostic of the report’s status class, and the sender’s own addressing fields from the returned header block (none for a message that arrived encrypted). The bounce stage is the BOUNCE_STAGE of the stage running pepsi-stage-srs(1), else a stage named bounce running pepsi-stage-bounce(1), else the first stage running pepsi-stage-bounce(1). A report with Action: delivered, relayed or expanded is dropped; anything that is not a delivery-status report counts as a failure. The row is marked state.forward_return. With no bounce stage configured, the report is dropped and start-up warns about it.

Receipt of a message is confirmed to the client (250) only after the message has been durably committed to the database; if the database is unavailable the client receives a transient error (451) and is expected to retry.

As required by RFC 5321 §4.4, pepsi-ingress prepends a Received: trace header to every accepted message, naming the connecting client (HELO/EHLO name, reverse-DNS and IP), this server, the transport used (SMTP, ESMTP, ESMTPS, ESMTPA or ESMTPSA per RFC 3848 — see Authentication below) and the time of receipt; a for clause names the recipient only for a single-recipient transaction. The header is added before authentication so that the ARC seal (added later by pepsi-stage-arc(1)) covers it.

On a listener with RECEIVED_PRIVACY, the from clause is left out altogether, so the header reads Received: by <HOSTNAME> (pepsi-ingress) with ESMTPSA …. This is the default for a SUBMISSION listener, the local submission socket included. The submitter’s IP address, reverse name and EHLO name (usually their machine’s) are thus not revealed to every recipient and archive, as draft-josefsson-email-received-privacy proposes. The client’s User-Agent and X-Mailer fields are removed with it. The by clause that MAX_SELF_HOPS counts, the protocol keyword, the TLS comment and the for clause are written unchanged, and the journal still records the client for abuse handling. RECEIVED_PRIVACY = no restores the full clause on a submission listener; yes applies it to an MX listener.

For an encrypted session the ESMTPS keyword on its own does not record which TLS version and cipher were negotiated. As recommended by RFC 8314 §4.3, pepsi-ingress therefore appends the negotiated parameters as a comment after the with keyword, e.g.:

by mail.example.org (pepsi-ingress) with ESMTPS
    (version=TLSv1_3 cipher=TLS13_AES_128_GCM_SHA256)

These values are the same TLS parameters recorded in the message state under origin.tls (see pepsi.state(7)); the comment includes the version and the cipher as far as the TLS stack reports them.

An X-Pepsi-List-Hops: header (the mailing-list loop counter) is removed from every message arriving on an unauthenticated session, since a sender could otherwise reset the counter; an authenticated session’s copy is kept. Every Bcc: and Resent-Bcc: field is removed from every message, whether it was submitted or arrived from outside. Under RFC 5322 section 3.6.3, blind recipients are removed before sending; the envelope already carries them. In submitted mail, a field that the client left in would show the hidden recipients to everyone else. In mail from outside, the field means nothing to a recipient, while a mail client that includes it in Reply-All would send the reply to an address that the user never saw, quoting what Pepsi decrypted. The fields are removed after SPF/DKIM/DMARC, so a signature covering them is checked on the bytes that were signed.

Multiple SMTP streams are processed concurrently. Several listeners can be configured, each bound to its own TCP port, UNIX-domain socket, or a socket inherited from a systemd parent through socket activation, and each with its own transport mode. All behaviour is driven by an INI-style configuration file (see pepsi.conf(5)).

The database schema is installed by pepsi-setup(1), which applies the migrations of every component to the shared pepsi schema; pepsi-ingress itself has no schema-initialization command.

95.1.1.1.3.1. SMTP extensions

The EHLO response advertises exactly these keywords, in this order:

SIZE <MAX_MESSAGE_SIZE>
8BITMIME
SMTPUTF8
PIPELINING
CHUNKING
DSN
ENHANCEDSTATUSCODES
RRVS

SIZE (RFC 1870) announces [pepsi-ingress] MAX_MESSAGE_SIZE, which is a server-wide setting rather than a per-listener one. A DATA body that goes over it is read on to its end and answered 552 5.3.4, so the session stays usable; but once a further MAX_MESSAGE_SIZE octets have arrived without the end-of-data marker, the server answers 552 5.3.4 at once and closes the connection (RFC 1870 section 6.2), as it does for a BDAT chunk that is too large on its own.

At the end of data the top-level header block is bounded as well: more than MAX_HEADER_FIELDS (default 1000) fields, or one field larger than MAX_HEADER_FIELD_SIZE (default 100 KiB, counted unfolded) is answered 552 5.3.4 and the message not stored, on every listener. The mail store behind Pepsi parses every field of every message, and the Dovecot advisories CVE-2024-23184 and CVE-2024-23185 ask the MTA in front to bound them. Header blocks of attached messages are not counted; they stay bounded by MAX_MESSAGE_SIZE.

The lines of a DATA body must end in CRLF: a bare LF anywhere is answered 500 5.6.0 and the connection closed, and so is a dot that a bare CR frames as an end-of-data marker (<CR>.<CR>, or <CR>. / .<CR> next to a CRLF). RFC 5321 section 2.3.8 forbids bare CR and LF in a body, and a receiver that took either for a line ending would see the message end there and read the rest of the body as a second transaction (SMTP smuggling). Other bare CRs are accepted and relayed unchanged.

Three more keywords are conditional. STARTTLS (RFC 3207) is advertised on a listener that has TLS material while the session is still cleartext, that is, with MODE = starttls, since MODE = tls is encrypted from the first byte. REQUIRETLS (RFC 8689) is advertised only once the session is TLS-protected (see Require TLS), and AUTH PLAIN LOGIN (RFC 4954) only on an already-encrypted session whose listener configures a SASL_TYPE backend.

Nothing else is offered. BINARYMIME in particular is neither advertised nor accepted (see 8-bit and internationalised content); VRFY is answered with the non-committal 252 and EXPN is declined with 502, since RFC 5321 §7.3 makes disclosing list membership an information leak rather than a service.

Some command lines are really part of an HTTP request: a request line (GET, POST or CONNECT with any arguments, or HEAD, PUT, DELETE, OPTIONS, TRACE or PATCH ending in an HTTP/ version) or a Host: or User-Agent: header line. Such a line is answered once with 554 5.5.0, the connection is closed, and the event is logged. The line comes from a cross-protocol attack, in which a web page makes a browser post to the SMTP port or an HTTP proxy is asked to connect to it, and answering it with an ordinary 500 would let the request body that follows run as SMTP commands. Other lines that are not commands at all are answered 500; the tenth in a session is answered 421 4.7.0 Too many unrecognized commands and the connection closed (a known command with a bad argument, 501, does not count). The limit is fixed: a mail client does not send ten unknown verbs, while another protocol aimed at the port does.

The same attack can arrive inside TLS: a browser lured into a TLS connection to the SMTP port completes the handshake with the mail server’s certificate. A TLS ClientHello whose ALPN offer names only HTTP protocols (http/1.1, h2, h3 and their relatives) is therefore refused with a no_application_protocol alert and logged. A ClientHello without ALPN, or offering smtp or any other identifier beside HTTP ones, proceeds; ingress selects no protocol, since mail clients built on a generic TLS stack may offer anything or nothing. The server name a client asks for (SNI) is not enforced: MTAs send the MX name, the domain, or nothing.

95.1.1.1.3.2. Authentication

Before a message is stored, pepsi-ingress authenticates it, so that receivers downstream can still see the verdict that Pepsi reached at the boundary, even after Pepsi has relayed the mail and broken the original SPF and DKIM alignment. For each accepted message it:

  1. verifies SPF (on the MAIL FROM identity, using the connecting client’s IP), DKIM and DMARC; and

  2. prepends an Authentication-Results header reporting these results, with the [pepsi-ingress] HOSTNAME as the authserv-id, and records the rendered result text under state.origin.ar_results.

ARC is handled separately: ingress does not seal the message, and the chain verdict that the row records does not come from ingress. The pepsi-stage-arc(1) pipeline stage verifies any inbound ARC chain and adds the fresh ARC set (AAR/AMS/AS) as the [pepsi] ARC_DOMAIN identity. It reads the session context that ingress recorded in the row’s state: the authserv-id, client IP, HELO/EHLO, and the ar_results fragment. Reusing that fragment lets the stage build the AAR without re-running SPF/DKIM/DMARC, so the authentication checks happen exactly once, and it keeps the ARC signing keys out of the SMTP front end. The one ARC question ingress asks is the override described next.

The verification is fail-open: a DNS failure or unparseable message never rejects the mail; it is recorded as temperror/none and accepted. Only when DMARC_ENFORCE is set does a definite DMARC failure under a quarantine/reject policy cause a 550 rejection, and only for an unauthenticated session: submitted mail is not signed until a later stage, and its From: is governed by the submission rules below. The option’s compiled-in default is off, so a configuration that does not mention it keeps accepting such mail for the final receiver to judge (and the ARC stage seals the failing result). pepsi-setup(1) --wizard writes DMARC_ENFORCE = yes for a new installation, while an existing pepsi.conf keeps whatever it says; pepsi-setup(1) warns about a configuration that leaves the option unset or off while a served domain publishes p=reject. The SPF/DKIM/DMARC verdicts are stored in the row’s state.auth object (as spf/dkim/dmarc/arc), and the authserv-id under state.origin; the arc verdict starts as none and is filled in later by the ARC stage. The DNS lookups happen synchronously in the DATA phase, so a slow resolver delays the 250.

Mailing lists and forwarders break DMARC for the mail they relay, and a receiver that enforces it would lose that mail. ARC (RFC 8617) is how such a hop passes on what it saw when it took the message, and ARC_TRUSTED_SEALERS lists the hops whose word the operator accepts. A message that fails DMARC under DMARC_ENFORCE is accepted all the same when two conditions hold: it carries an ARC chain that validates (cv=pass recomputed from the signatures, never read from the chain’s own cv= tag), and the d= of the ARC-Seal with the highest instance, that is, of the ADMD that sealed last, is one of the listed domains. Only the last sealer counts: validating a chain checks the newest ARC-Message-Signature and every seal, and a seal signs the ARC fields rather than the message, so the last sealer is the only ADMD that a validated chain proves to have handled these bytes. A trusted forwarder sealing over a chain that some unknown hop started is still that forwarder’s word; an unknown hop sealing over a trusted forwarder’s set is not. The accepted message records the sealer as state.auth.arc_override while state.auth.dmarc keeps reading fail, so a later stage can tell the two apart. The list is empty by default: an unknown sealer proves nothing. The chain is checked only for a message that would otherwise be refused, and it is checked whatever the list holds: the 550 refusal is logged with the chain’s last sealer, as arc-sealer=<domain> when the chain validates and as a claim when it does not. Those log lines name the forwarders and lists whose mail DMARC_ENFORCE turns away, so the operator finds candidates for ARC_TRUSTED_SEALERS there (grep arc-sealer= over the ingress log).

A From: naming mailboxes in several domains is checked against the DMARC policy of each of those domains (RFC 7489 section 6.6.1), at most 10 of them, concurrently under the same deadline. The message passes DMARC only if every domain passes, and it is a failure that DMARC_ENFORCE acts on if any domain’s policy asks for one. Each domain gets its own dmarc= result in Authentication-Results. Two further cases are refused under DMARC_ENFORCE, because DMARC cannot be applied to them: a message with no author domain at all (no From:, or one with no address, such as an empty group) is refused 550 5.6.0, and one whose From: names more than 10 domains 550 5.7.1, since only the first 10 were evaluated. Both refusals apply to unauthenticated sessions only; an authenticated sender’s From: is governed by the submission rules below.

Some signatures that verify are still not a DKIM pass. An rsa-sha1 signature is reported permerror (RFC 8301: verifiers must not consider one valid, since SHA-1 collisions can be manufactured), and a signature under a key whose DNS record carries t=y is reported neutral (RFC 6376 section 3.6.1: a signer in testing mode must be treated like unsigned mail). Neither counts towards DMARC alignment or towards state.auth.dkim = pass, which is what a whitelist row’s dkim_required reads. state.auth.dkim also applies the From: domain’s DMARC alignment mode: under adkim=s only a signature whose d= is exactly that domain counts, so it never says pass for a message that failed DMARC for want of an aligned signature. SPF stops at two void lookups (a, mx, ptr or exists terms answered NXDOMAIN or with no records) and returns permerror, as RFC 7208 section 4.6.4 recommends, so a record cannot make every verifier send ten queries for names that do not exist.

The work is bounded, because the number of signatures is the sender’s choice and each costs a DNS lookup and a public-key verification. At most MAX_DKIM_SIGNATURES (default 10) DKIM-Signature fields are verified. Those whose d= is the From: domain or a parent or child of it come first, since they are the only ones that DMARC can use, so padding a message with signatures cannot push the one that matters out. SPF and the selected signatures are checked concurrently under one deadline of VERIFY_TIMEOUT (default 20 s), and DMARC under a second one, so a message never holds its session in verification for more than twice that. A check that misses its deadline is recorded as temperror for that check alone: a timed-out signature whose domain does not align with the From: domain is one that DMARC ignores, so a forger cannot slow their own DNS down to turn a DMARC failure into something DMARC_ENFORCE does not act on.

A display name can claim an address the sender does not own: From: "ceo@example.com" <mallory@example.net> is legal syntax, and many mail clients show only the name. On mail from an unauthenticated session, ingress therefore looks for an address in the display text of each From: mailbox, that is, in the name before the <...> address and in every comment. It judges that text as a client renders it: with RFC 2047 encoded-words decoded, NFKC-normalised (so the full-width and small commercial at count as @), and with invisible and bidirectional control characters removed. If it finds one that is not the mailbox’s own address (compared case-insensitively, so "bob@example.net" <bob@example.net> is fine), the message is marked, not refused or rewritten: an X-Pepsi-Warning: display-name-claims-other-address field is prepended, and the claimed address is recorded as state.auth.display_name_mismatch. Any X-Pepsi-Warning field that the sender wrote is removed first, so every such field comes from Pepsi. Authenticated submissions are refused instead (see Submission identity below).

Removing the reordering characters is right for that comparison, but it ignores what they do: a right-to-left override shows \u202Eelpmaxe.knab@oec as ceo@bank.example, and zero-width characters or a Hangul filler hide text or make a name look blank. A From: field (encoded-words decoded) carrying a bidirectional embedding, override or isolate control, a directional mark or an invisible character is therefore marked with X-Pepsi-Warning: from-has-bidi-or-invisible-characters, and the field is delivered as received. The zero-width joiner and non-joiner and the variation selectors do not count, since Persian and Indic names and emoji need them.

An attachment file name (Content-Disposition filename or Content-Type name, RFC 2231 and RFC 2047 decoded, in any MIME part, attached messages included) that carries the same characters can show a different extension from the one that the file has (invoice<RLO>fdp.exe reads as invoiceexe.pdf); such a message is marked with X-Pepsi-Warning: attachment-name-has-bidi-or-invisible-characters, and the name is delivered as received. A message whose MIME structure cannot be parsed is not marked.

A From: domain that renders like one of the ACCEPTED_DOMAINS without being one is marked with X-Pepsi-Warning: from-domain-resembles-served-domain, however the sender’s own domain authenticated. Such a domain has the same UTS #39 skeleton as a served one, as in examp1e.org or with a Cyrillic e (U+0435) for a Latin one. This warning is a header field only: it does not put TAG_EXTERNAL on the subject (see Marking mail from outside), because that tag means that a claim to a served domain was not proven.

95.1.1.1.3.3. Ambiguous MIME structure

Everything after ingress parses a message again: the filter behind pepsi-stage-milter(1), the content filter of pepsi-stage-list-post(1) and the recipient’s mail client. Where its MIME structure is malformed, RFC 2045 and RFC 2046 leave the reading to the parser, so a filter can scan something other than what the reader is shown (the filter takes one Content-Type field and the client another; the filter never matches a boundary that the client salvages). MIME_ANOMALIES settles this at DATA, on the bytes as received, in three ways:

  • The hard classes have no right reading and are refused 554 5.6.0: an empty boundary= on a multipart, a NUL byte in any MIME entity’s header block, two Content-Type or two Content-Transfer-Encoding fields on one entity that differ, a boundary that is or contains an RFC 2047 encoded-word, and two differing copies of a message-header Date, Subject, To, Reply-To or Sender field, which RFC 5322 section 3.6 allows once: mail clients show one copy or the other, and a DKIM signature that names the field once covers only the bottom one, so a copy added above a signed field passes DKIM while the reader may be shown it.

  • The marked class is the same conflict for Cc, which some mail clients produce when the user adds a second Cc: line: the message is stored as received and gets X-Pepsi-Warning: duplicate-header-cc.

  • The soft classes are shapes the standards already say how to decode, and the message is rewritten to that one reading before it is stored, so every later parser sees the same structure: a transfer encoding that is none of the five RFC 2045 encodings (RFC 2045 section 6.4: the entity is application/octet-stream and its octets are taken as they stand); whitespace between a quoted-printable soft break’s = and the line end (section 6.7: deleted); characters outside the base64 alphabet (section 6.8: ignored); a multipart with delimiters but no close delimiter (RFC 2046 section 5.1.1: the last part ends with the enclosing entity, so the close delimiter is written); a delimiter line of a multipart’s own boundary after its close delimiter (the epilogue, which section 5.1.1 says to ignore, is dropped, so the “part” some readers would show there is gone; an epilogue without such a line is kept); a second identical Content-Type or Content-Transfer-Encoding field (dropped); and a second identical copy of a message-header Date, Subject, To, Cc, Reply-To, Sender, Message-ID, In-Reply-To or References field (equal after unfolding and collapsing whitespace; the first copy is kept). Differing Message-ID, In-Reply-To or References fields are left as they are: they steer threading, not what the reader is told. Only the message’s own header block counts for these fields, not that of an attached message or a body part. A second From: is refused before any of this (550 5.6.0), and every Bcc: is removed. A multipart/signed, multipart/encrypted, PGP/MIME or S/MIME entity and everything inside it is never rewritten, because a signature covers the encoded octets and ciphertext is opaque anyway; a hard class inside one still refuses the message, though.

The order is verify, normalise, seal. SPF, DKIM and DMARC are assessed on the bytes as received (a signature is judged on what it signed), so the message’s own DKIM signature may no longer verify at the next hop after the rewrite; that is what the ARC seal is for, and the seal has to cover what is stored. A message that carries an ARC chain is therefore stored as it arrived and marked state.mime_normalise; pepsi-stage-arc(1) verifies that chain over the original bytes, rewrites, and seals the rewritten message. A message without a chain, and a submission (never ARC-sealed), is rewritten by ingress itself. Who rewrote is recorded as state.mime_normalised and the classes found as state.mime_anomalies. With MIME_ANOMALIES = enforce and no stage running pepsi-stage-arc, ingress warns at start: a chain-carrying message then keeps its anomalies.

MIME_ANOMALIES = log counts and logs every class and stores the message as received; a message with differing copies of one of the six header fields above gets X-Pepsi-Warning: duplicate-header-<field> (the field name in lower case: duplicate-header-date, -subject, -to, -cc, -reply-to, -sender) instead of being refused. The warning is written on mail from unauthenticated sessions only, like the other X-Pepsi-Warning values (see “Marking mail from outside” below). The telemetry keys mime-hard-anomaly and mime-soft-anomaly count messages with a class of each kind under either setting, and mime-duplicate-header-mark counts messages marked for a header conflict.

Whether the default costs legitimate mail was measured before it was chosen: 97,891 messages received over several years in three working mailboxes, dominated by mailing-list, research and project mail, were scanned with a parser that repairs nothing (a bare LF cannot be measured from stored mail and is refused at DATA in any case).

Class

Messages

Share

Hard classes (empty boundary, NUL in a MIME header, conflicting duplicate fields, encoded-word boundary)

0

0

Soft classes, together

28

0.03 %

of which: identical duplicate Content-Type or Content-Transfer-Encoding fields

7

0.007 %

of which: multipart without a close delimiter

20

0.02 %

of which: base64 with characters outside the alphabet

1

0.001 %

of which: misspelled transfer encoding; whitespace after a soft break

0

0

Not one message in the sample would have been refused, and the rewrite would have touched about one in 3,500, most of them a missing close delimiter that every client already reads as closed. Shapes outside these classes (a header line with no field name, an invalid quoted-printable escape, raw 8-bit bytes in a quoted-printable part, an unparseable Content-Type, a multipart whose boundary never occurs in its body) are stored as received; they were about one message in 1,250 of the sample. The delimiter-after-close class is not part of this measurement.

The header-field classes were measured separately, on 24,096 messages: the public SpamAssassin ham corpus (4,150 messages) and 19,946 messages from the 2024 and 2025 archives of eleven GNU mailing lists, chosen because they are public and carry full headers.

Copies of a message-header field

Messages

Share

Differing Date, Subject, To, Reply-To or Sender

0

0

Differing Cc

6

0.025 %

Identical copies of any of the nine fields

1

0.004 %

Differing Message-ID or In-Reply-To (left alone)

2

0.008 %

The six Cc conflicts were legitimate messages from two correspondents, four of them written with Gnus, which keeps the extra Cc: lines a user types; that is why the field is marked rather than refused.

95.1.1.1.3.4. Marking mail from outside

Authentication is recorded, not enforced (except under DMARC_ENFORCE), so a message from the internet whose From: is at one of the ACCEPTED_DOMAINS is delivered like a colleague’s unless its domain’s DMARC policy refuses it. After the checks above, pepsi-ingress therefore marks, on every message from an unauthenticated session:

  • X-Pepsi-Warning: from-ambiguous — a From: that cannot be read one way only (the strict reading of the submission gate refuses it: an encoded-word or obsolete-syntax address, text after the angle-addr, a second angle-addr, a group), or that names mailboxes in more than one domain, whatever the authentication results: clients disagree on which author such a field shows.

  • X-Pepsi-Warning: served-domain-not-authenticated — a From: mailbox at a served domain, with neither a DMARC pass, a DKIM pass aligned with that domain, nor an SPF pass whose MAIL FROM domain aligns with it. A From: naming several domains is vouched for by a DMARC pass alone.

  • X-Pepsi-Warning: served-sender-not-authenticated — a Sender: mailbox (any Sender: field) at a served domain, with neither a passing DKIM signature nor an SPF pass whose MAIL FROM domain aligns with it. A Sender: at another domain is not marked.

  • X-Pepsi-Warning: dmarc-fail-not-enforced — DMARC evaluated to fail and the message was accepted anyway: DMARC_ENFORCE is off, or the domain publishes p=none. A failure a sealer in ARC_TRUSTED_SEALERS vouched for is not marked.

Each of these warnings also puts the TAG_EXTERNAL tag (default [external]) at the front of the Subject, where a mail client shows it; a message with no Subject gets one holding the tag alone, and a second Subject field is dropped with the rewrite. Before ingress decides on the tag, every message from outside has copies of the tag removed from the front of its subject, judged as a client renders it (RFC 2047 encoded-words decoded, look-alike characters folded, invisible and bidirectional controls removed), so a sender cannot write the tag themselves; the documented [external] is removed even when TAG_EXTERNAL sets another tag. Nothing else in the subject is touched; a sender’s own [Signed contract] prefix stays unless a pepsi-stage-decrypt(1) stage later removes it. The values written are listed in state.auth.warnings (see pepsi.state(7)). EXTERNAL_SUBJECT_TAG = no leaves the subject alone and still writes the header fields. A stranger writing from their own domain earns no mark beyond from-ambiguous, whatever their results: the tag says that a claim to be one of us was not proven, that the reader may be shown another author than the one authenticated, or that the sender’s domain disowned the message, and nothing more. The rewrite breaks a sender’s DKIM signature over Subject, which is why it runs after verification and before the ARC seal.

95.1.1.1.3.5. Delivery Status Notifications (DSN)

pepsi-ingress advertises the DSN extension (RFC 3461) in its EHLO response and accepts its parameters: RET and ENVID on MAIL FROM and NOTIFY and ORCPT on RCPT TO. Their syntax is validated: an invalid RET/NOTIFY value, a NOTIFY=NEVER combined with other keywords, or a malformed ENVID/ORCPT xtext is rejected with 501. The accepted values are stored in the row’s state.dsn (message-level ret/envid plus a per-recipient array of notify/orcpt). The stage pipeline honours them: the relay stages propagate the parameters to the next hop when it also advertises DSN, and pepsi-stage-bounce(1) generates a failure bounce only when the recipient’s NOTIFY requests it (FAILURE, the default when absent), echoing ENVID/ORCPT into the DSN. Every stage must preserve state.dsn.

95.1.1.1.3.6. Require-Recipient-Valid-Since (RRVS)

pepsi-ingress advertises the RRVS extension (RFC 7293) and accepts its RCPT TO parameter, RRVS=<date-time>[;C|R]: the sender knew the intended recipient to own the address at that time (an RFC 3339 date-time without fractional seconds) and does not want the message delivered to anybody who got the address later. A malformed value is answered 501 5.5.4. The optional letter is the no-support action for a relay whose next hop does not advertise RRVS: R (the default) refuses the recipient, C continues.

For a recipient at a served domain, the address is mapped to a login as for the quota check below (local part, sub-address stripped at [pepsi] RECIPIENT_DELIMITER, lower-cased; no alias resolution) and looked up in the login assignment record (pepsi.login_assignment, on which pepsi-ingress holds SELECT only; see pepsi-setup(1), The login assignment record). The recipient is refused with 550 5.7.17 Mailbox owner has changed, whatever the no-support action, if the login has a recorded change of owner after the requested time, if passwd now gives it a different uid from the record, or if the record says that the login was gone. A login with one owner as far as Pepsi knows passes for any date (RFC 7293 sections 9 and 13.2), so the answer says nothing about an address that was never recycled; role addresses of RFC 2142 (postmaster, abuse, info and the rest) are never tested. Every uncertainty (no record, no such login, a database or passwd error) accepts the recipient, and the local delivery stage takes the request up again. A refusal counts towards MAX_INVALID_RECIPIENTS, which meters the probing that RFC 7293 section 13.1 warns about.

The accepted value is stored verbatim under state.dsn.rcpt[i].rrvs, parallel to rcpt_to like NOTIFY, so every split keeps it with its recipient and an alias target (a new destination) does not inherit it. The relay stages pass it on to a next hop that advertises RRVS; towards one that does not, R fails the recipient with 5.7.19 (a DSN) and C continues with the request written as a Require-Recipient-Valid-Since: header field. pepsi-stage-relay-to-maildir(1) and pepsi-stage-dot-forward(1) honour both forms at local delivery.

95.1.1.1.3.7. Require TLS (REQUIRETLS)

pepsi-ingress implements both halves of RFC 8689. The REQUIRETLS extension is advertised, and its MAIL FROM parameter accepted, only on a session that is TLS-protected, by implicit TLS or after STARTTLS. That is the one requirement of RFC 8689 §2 that the receiving side can see; whether the client validated our name and certificate before asking is its own obligation, and invisible here. On a cleartext session the parameter is answered 530 5.7.10: advertising the extension promises to carry the requirement onward, and a message that has already crossed one hop in the clear cannot be given that promise. The parameter takes no value; REQUIRETLS=... is an unknown parameter (555 5.5.4). The local submission socket is a UNIX socket, so pepsi-sendmail(1) cannot request it.

A message that arrived with the parameter is tagged state.tls_required = "required" (see pepsi.state(7)); every row the pipeline splits or clones from it inherits the tag, as §4.1 requires of aliasing. A message that arrived without the parameter but carrying exactly one TLS-Required: No header field is tagged "no": the originator asks that the recipient domain’s DANE and MTA-STS policy be treated as advisory. Two such fields, or any other value, are malformed and mean nothing, because reading them as an opt-out would let anyone downgrade a recipient’s policy with a single line. With the parameter present the field is ignored and left in the message (§4.1). What each tag does at the next hop is described in pepsi-stage-relay-to-internet(1) and pepsi-stage-relay-to-smarthost(1); a bounce of a tagged message is tagged itself and returns headers only (pepsi-stage-bounce(1)).

95.1.1.1.3.8. 8-bit and internationalised content

pepsi-ingress advertises 8BITMIME (RFC 6152) and SMTPUTF8 (RFC 6531) in its EHLO response, so a message may carry raw 8-bit octets in its body and UTF-8 in its headers and envelope. The BODY= parameter on MAIL FROM is accepted and recorded (state.origin.body_8bit); only 7BIT and 8BITMIME are valid, and BINARYMIME is not advertised and is rejected with 501. The relay stages re-advertise BODY=8BITMIME / SMTPUTF8 to a next hop that supports them, and downgrade the message when it does not: an 8-bit body towards a non-8BITMIME hop is MIME-re-encoded to a 7-bit content-transfer-encoding, and UTF-8 headers towards a non-SMTPUTF8 hop are rewritten as RFC 2047 encoded-words, or RFC 2231 for a MIME parameter such as an attachment’s filename (a non-ASCII address there cannot be downgraded and is bounced). A message whose body cannot be converted at all, because it is malformed beyond what the re-encoder can repair, is bounced rather than sent 8-bit, as RFC 6152 §3 requires. See pepsi-stage-relay-to-internet(1).

95.1.1.1.3.9. ESMTP parameter validation

pepsi-ingress validates the MAIL FROM/RCPT TO parameters strictly. The recognised parameters are SIZE, BODY and SMTPUTF8 (and AUTH) on MAIL FROM and the DSN and RRVS parameters above; a SIZE= value that is not a non-negative integer is rejected with 501 (RFC 1870 §6.1) rather than silently dropped. A parameter that the server does not implement is rejected with 555 5.5.4 (RFC 5321 §4.1.1.11); it is not silently ignored. The one exception is the RFC 4954 AUTH= parameter on MAIL FROM (which an authenticated client may attach because AUTH is advertised): it is accepted and ignored rather than rejected, and Pepsi does not propagate the asserted identity onward.

95.1.1.1.3.10. Client authentication

Each listener can authenticate its clients, marking accepted mail as locally originated. A session is authenticated when any one of four per-listener mechanisms accepts it:

  • MYNETWORKS — the connecting IP is within one of a whitespace/comma separated list of trusted IPv4/IPv6 CIDR networks (a bare address is taken as a /32 or /128 host). An entry outside loopback must be bound by SENDER_MAP (see Sender bindings below), or pepsi-ingress refuses to start.

  • SASL — a SASL_TYPE backend (currently dovecot, via the SASL_PATH auth-client socket) accepts an AUTH exchange. AUTH (mechanisms PLAIN and LOGIN) is advertised and accepted only on a TLS-protected session (implicit TLS or after STARTTLS); a cleartext AUTH attempt is refused with 504 5.5.4 (RFC 4954 §4, which deprecates the 538 reply for this).

  • TLS client certificate — the client presents a certificate that is either a pinned key (its SubjectPublicKeyInfo SHA-256, 64 hex chars, is listed in TLS_AUTH_CLIENT) or validates to one of the CA certificates in TLS_AUTH_CLIENT_CA, and SENDER_MAP binds that key or CA to the addresses it may send as. An unbound certificate authenticates nothing. See Client certificates below.

  • AUTH_PEERCRED — on a UNIX-domain socket, the kernel-attested uid of the peer (SO_PEERCRED) is resolved to a login and fed to the USERNAME_MAP machinery, so a caller can only send as itself. Default ``yes`` for a ``SERVE = unix`` listener (set AUTH_PEERCRED = no to turn it off); refused outright on a TCP listener, where a peer has no kernel-attested identity. This is what authenticates the local submission socket that pepsi-sendmail(1) uses, and it sets the RFC 3848 ESMTPA keyword. For a SERVE = systemd listener it is accepted but never inferred, since the family lives in the unit; a warning is logged if the inherited descriptor turns out to be TCP.

SASL_TYPE, TLS_AUTH_CLIENT and TLS_AUTH_CLIENT_CA require a TLS listener (MODE = tls or starttls). An authenticated session is recorded with state.local_origin = true (otherwise false) and is permitted to relay to any domain, not only the served domains. A session that carries an identity also sets the RFC 3848 A in the trace header’s with keyword: ESMTPSA over TLS, and plain ESMTPA for the cleartext UNIX submission socket, which is where locally submitted mail (pepsi-sendmail(1), cron) comes from. SASL AUTH carries an identity, and so does AUTH_PEERCRED on a UNIX socket, but MYNETWORKS and a client certificate do not. Filter on both keywords, not only ESMTPSA. An unrecognised client certificate never aborts the handshake; it simply leaves the session unauthenticated.

95.1.1.1.3.11. Client certificates

A listener with TLS_AUTH_CLIENT or TLS_AUTH_CLIENT_CA set requests a client certificate during the handshake, naming the configured CAs as hints, from a client that offers TLS 1.3. TLS 1.2 sends the certificate, and the person or device it names, in the clear, so a TLS 1.2 client is served without a certificate request (logged at info) and can authenticate with AUTH or not at all; TLS_AUTH_CLIENT_TLS12 = yes on the listener requests the certificate under TLS 1.2 too, for a device that speaks nothing newer. The handshake never fails on an unrecognised certificate: the decision is made afterwards, and a client whose certificate authenticates nothing can still AUTH or, on an MX listener, send to the served domains unauthenticated. Two forms are recognised:

  • A pinned key. TLS_AUTH_CLIENT lists the SHA-256 of the DER SubjectPublicKeyInfo of individual client keys. The pin is the key: ingress does not consult what the certificate around it says (names, dates, usages), since a self-signed certificate says only what its holder wrote. Compute a pin with openssl x509 -in cert.pem -noout -pubkey | openssl pkey -pubin -outform DER | openssl dgst -sha256.

  • A CA. TLS_AUTH_CLIENT_CA names a PEM file of CA certificates (each must be a CA permitted to sign certificates, and currently valid; the file is checked when the configuration is parsed, so by pepsi-setup(1) too). A presented certificate is recognised when it builds an RFC 5280 path to one of them through the intermediates that the client sends. The path check covers validity dates, basicConstraints with pathLenConstraint, keyUsage, name and policy constraints, the rule that an unrecognised critical extension is a refusal, and key strength. pathLenConstraint applies to the CA’s own certificate too, so a CA that limited itself to issuing end-entity certificates cannot be made to vouch for a sub-CA. The leaf must further carry an extendedKeyUsage naming id-kp-clientAuth (an absent extension or anyExtendedKeyUsage does not do), the digitalSignature bit, and must not itself be a CA. A CA’s key hash listed in ``TLS_AUTH_CLIENT`` authorises nothing and is logged: an anchor given by hash alone has no checkable constraints, since whoever holds a chain could wrap the CA’s public key in a certificate of their own writing, without the path length or name constraint the real one carries.

Revocation is checked against the lists that pepsi-keydisc(1) keeps in pepsi.crl_cache. Every certificate on the path that names a CRL distribution point must be covered by a current list that its issuer signed, and a listed serial is a refusal; a certificate that names no distribution point has no list to consult. The distribution points of every path that reaches a configured CA are registered with the fetcher (the CA bundle’s own at start-up), so the first connection under a new issuer finds no list yet: on a submission listener its MAIL FROM is answered 451 4.7.0 (try again later) rather than 530, and the client succeeds once pepsi-keydisc has fetched the list, within its five-minute tick. Unlike the S/MIME verifier, which reports an unknown revocation status and goes on, this check fails closed: a CA that publishes lists that nobody can fetch admits nobody. A deployment that uses TLS_AUTH_CLIENT_CA therefore runs pepsi-keydisc.

What a certificate is worth is decided by SENDER_MAP (Sender bindings below): the key cert:<pin> names the addresses that the session may send as, where the pin is that of the pinned key or of the CA that the path reached. A certificate that the map does not bind authenticates nothing: the session stays unauthenticated, and the refusal is logged with the key to add. pepsi-setup(1) validate (and so run) refuses a configuration with a pin or CA that the map does not bind, so an installation cannot carry a listener entry that admits nobody; pepsi-ingress itself starts and warns, so that such an entry does not take down a running system. A CA-issued certificate that names mailboxes (an rfc822Name in its subject alternative name, or failing that the subject’s emailAddress) may send only as those of its mailboxes that the binding permits: with cert:<CA pin> * every certificate under the CA sends as its own mailbox and nothing else, and a certificate authenticates nothing if the binding permits none of its mailboxes. A certificate that names no mailbox gets the CA’s whole grant. A pinned key is the operator’s statement and is not confined by its certificate’s names.

A certificate session is recorded with state.origin.auth_method = client-cert; its From: is never bound (state.origin.from_bound stays false), since a certificate identifies no account that could speak for an address.

95.1.1.1.3.12. Message submission (RFC 6409)

A listener carrying SUBMISSION = yes is treated as a Message Submission Agent (RFC 6409) rather than an MX:

  • Authentication is mandatory. An unauthenticated MAIL FROM is refused with 530 5.7.0 Authentication required; the client must first satisfy one of the Client authentication mechanisms above. The flag therefore requires at least one configured mechanism (SASL_TYPE, TLS_AUTH_CLIENT, TLS_AUTH_CLIENT_CA, MYNETWORKS or AUTH_PEERCRED); a submission listener with none is a configuration error, refused when the file is parsed, and so both by pepsi-setup(1) and by the server itself at start-up. It also requires a TLS-protected MODE (tls or starttls), except on a local socket, i.e. SERVE = unix or a SERVE = systemd listener that inherits one, where there is no network to protect. The shipped local submission socket is exactly that: MODE = plain with SUBMISSION = yes and AUTH_PEERCRED. The rule is only deferred, not dropped: a plaintext submission listener that turns out at bind time to have inherited a network socket makes pepsi-ingress refuse to start.

  • Submission fixups are applied to every accepted message: a missing Date: header is added (§8.2) and a missing Message-ID: is generated as <random@HOSTNAME> (§8.3). Headers that are already present are left untouched, and the fixups run before the Received: trace header is prepended, so the added fields are covered by the downstream ARC seal and DKIM signature.

  • The submitter is withheld from the trace header (RECEIVED_PRIVACY, on by default for a submission listener): no from clause, and no User-Agent/X-Mailer. See The Received trace header above.

The flag has no effect on an MX listener; leave it off (the default) for port 25.

95.1.1.1.3.13. Submission identity (RFC 6409 §6 / §8.1)

A session that carries a username is bound to the set of e-mail addresses that the username is allowed to use. Two of the four mechanisms above carry one: a SASL AUTH exchange (the authcid), and AUTH_PEERCRED on a UNIX socket (the login the kernel-reported uid resolves to). Both are subject to everything in this section. MYNETWORKS is not, because it authenticates an address rather than an account, unless SENDER_MAP binds it (see Sender bindings below); then the two checks below apply to it too. A TLS client certificate is always bound: it authenticates only what SENDER_MAP binds it to, so the two checks always apply to it.

By default the username alice is mapped to the single address alice@HOSTNAME (the [pepsi-ingress] HOSTNAME domain); the optional USERNAME_MAP file overrides this mapping. Each non-blank, non-comment line is:

username: addr1@example.org addr2@example.org

a # begins a comment, the key is the SASL username (before the first :), and the value is the whitespace/comma separated list of allowed addresses, which may be empty. Usernames are matched case-insensitively and addresses are lower-cased. The file is re-read whenever its modification time changes (checked on each authentication), so edits take effect without a restart; a missing or unreadable file is treated as empty (every user falls back to the default).

An allowed address may use a * wildcard (a *-glob matched against the candidate address), so alice: *@example.org lets alice use any address at example.org and a bare * permits any address at all. A wildcard entry names no single canonical identity, so it is skipped for the Sender: fixup below (the first concrete, wildcard-free address is the canonical identity, if any). pepsi-setup syntax-checks a configured USERNAME_MAP at install time (see pepsi-setup(1)). The wildcard is a glob, not a regular expression: write *@example.org, never .*@example.org (a literal dot followed by a glob, which matches nothing, so the user would be denied every address that the entry was meant to grant). Setup rejects such a pattern and names the glob you meant.

The mapping has three outcomes for a username:

  • listed with addresses — exactly those addresses (and wildcard patterns) are allowed; the first concrete (wildcard-free) one is the canonical identity used for the Sender: fixup;

  • listed with no addresses — the user is denied: even though SASL accepted the credentials, the AUTH command is refused with 535 5.7.8 and the session stays unauthenticated. On a peer-credential session there is no command to refuse, so the session simply never authenticates, and on a submission listener its first MAIL FROM is then answered 530 5.7.0. This is how a system account (www-data, say) is excluded from submitting at all;

  • not listed (or no USERNAME_MAP configured) — the default username@HOSTNAME.

Given that set, two checks run on such a submission:

  • Envelope and header identity (§6). The MAIL FROM envelope sender and the message From: address must each be one of the allowed addresses, otherwise the message is refused with 550 5.7.1 (at MAIL FROM and at end-of-DATA respectively). The null sender <> is exempt; a message with no From:, or one that cannot be read unambiguously (below), is refused with 550 5.6.0. RFC 5322 §3.6.2 makes From: a mailbox list, so a value may legally name several mailboxes, and every one of them must be an allowed address, not merely one. Checking a single mailbox would be no check at all, because mail readers display the first while a permitted one could sit anywhere in the list. Each mailbox is read the way a mail client reads it: quoted strings and RFC 5322 comments are skipped while the <...> address is located, and comments are removed from the address. So ceo@example.com (<alice@example.org>) is checked as ceo@example.com, the address that every client shows, and not as the address in the comment. Every mailbox must also parse strictly as an RFC 5322 mailbox, because the shapes that do not are the ones mail clients resolve differently (CERT/CC VU#517845): text other than comments and whitespace after the <...> address (<alice@example.org>:<ceo@example.com>), a second <...> address, a display name that is not a phrase (ceo@example.com <alice@example.org>), group syntax, a source route, and an RFC 2047 encoded-word (=?...?=) inside the address are all refused with 550 5.6.0 rather than read as their first <...>. An encoded-word in the display name is legal and accepted. Finally, a display name (or comment) that names an address other than its own mailbox’s is refused with 550 5.6.0: "ceo@example.com" <alice@example.org> would show the reader an address that Alice may not use. The text is judged as rendered, as described under Authentication above (encoded-words decoded, look-alike @ signs folded). A name that holds the mailbox’s own address is allowed, in any letter case, as in "alice@example.org" <alice@example.org>. A mailing list’s “via” rewriting happens later, in the list stages, and is not affected.

  • Sender fixup (§8.1). The Sender: field is the MSA’s, not the client’s: an address that a client puts there is subject to no identity check on any path, and Pepsi would go on to DKIM-sign it as a claim about who sent the message. So whenever the account has a canonical identity, an existing Sender: is replaced or removed, which §8.1 explicitly permits (“The MSA MAY add or replace the ‘Sender’ field”).

    When the From: address is an allowed address that differs from the canonical identity, or names more than one mailbox, a Sender: header naming the canonical identity is prepended. For the multi-mailbox case, RFC 5322 §3.6.2 requires a Sender: to be present, and §8.1 is what lets the MSA supply it. When From: is a single mailbox naming the canonical identity, a Sender: is redundant with it (§3.6.2: “SHOULD NOT be used if it is redundant with the ‘From:’ field”) and is removed instead.

    A user granted only wildcard patterns has no single canonical identity to assert, so neither rule applies and an existing Sender: is left alone: there is no identity against which it could be proved wrong. Like the other fixups this happens before the trace header, so the result is covered by the ARC seal and DKIM signature.

These checks apply to every session that carries a username, whether it came from SASL AUTH or from AUTH_PEERCRED, and to every session that SENDER_MAP binds. A MYNETWORKS session that the map does not bind has no grant to check against.

95.1.1.1.3.14. Sender bindings for networks and certificates

A MYNETWORKS peer outside loopback and a TLS client certificate authenticate nothing until they are bound; a loopback peer may send as any address, since loopback is this host. The [pepsi-ingress] SENDER_MAP file names the addresses that a network or a certificate may use. Each non-blank, non-comment line is a key followed by its allowed addresses:

# network or certificate      allowed senders
192.0.2.10                     alerts@example.org
2001:db8:1::/64                *@example.org
cert:<64 hex digits>           backup@example.org *@example.net
cert:<64 hex digits of a CA>   *

A network key is a CIDR network or a bare address (a /32 or /128 host); a certificate key is cert: followed by the SHA-256 SPKI hash of a pinned client key, exactly as written in TLS_AUTH_CLIENT, or of a CA certificate in TLS_AUTH_CLIENT_CA (pepsi-ingress logs each CA’s key at start-up). The addresses use the USERNAME_MAP syntax (an exact address, a *@domain wildcard, or a bare * for every address), and every key must list at least one.

A concrete entry beats a wildcard, across keys. An address that one key names exactly is claimed: a wildcard under any other key does not reach it. In the example, a certificate under the CA may send as anything except backup@example.org, which only the pinned backup key may use, and alerts@example.org, which only the alerts host may. This is what lets one cert:<CA> * line serve a whole organisation: each certificate is confined to its own mailbox (Client certificates above), and the addresses that belong to specific systems are listed once, under the key that owns them.

A MYNETWORKS session is bound by the most specific network key that contains the peer address. A certificate session is bound by the key under which it was recognised, and that key decides before the network does (a certificate identifies a key, a network only an address). A bound session goes through the MAIL FROM and From: checks of the previous section, with the same replies (550 5.7.1, 550 5.6.0) and the same Sender: fixup; its state.origin.from_bound stays false, because a network or a certificate identifies no account that could speak for an address. A certificate that no key matches is refused. pepsi-ingress refuses to start with a MYNETWORKS entry outside loopback that no single key covers whole: otherwise every host in it could send as any address, unauthenticated, and have the mail DKIM-signed for every served domain. That is the shape of a relay that admits a cloud provider’s shared egress range. The key may be wider than the entry (192.0.2.0/24 covers 192.0.2.10), and a bare * keeps the unrestricted behaviour as an explicit decision. Such a * for a network wider than one host is warned about at every start (and by pepsi-setup validate): every machine that is or later joins that network may send signed mail as any address of every served domain, the configuration the EchoSpoofing campaign abused. A loopback entry (127.0.0.0/8, ::1, in any spelling) needs no binding and keeps the unrestricted behaviour, which is what the wizard’s TRUST_LOOPBACK relies on.

Unlike USERNAME_MAP, the file is read once at start-up (restart to apply an edit), and pepsi-ingress refuses to start on any error in it: an unreadable file, a malformed key, a key listed twice, a key with no address, or an invalid address. A line that it skipped would leave the network that it was meant to bind free to send as anybody. pepsi-setup(1) checks the file, warns about keys that no listener’s MYNETWORKS, TLS_AUTH_CLIENT or TLS_AUTH_CLIENT_CA can match, and refuses a pin, a CA or a non-loopback network that the file does not bind.

Beside the section 6 check, ingress records how the From: was allowed, as state.origin.from_bound: true exactly when From: names a single mailbox that matched a concrete (wildcard-free) entry of the account’s allowed addresses, or the default username@HOSTNAME; false otherwise, and always false for a session with no username. Being permitted to send as an address is enough to send; being bound to it is what lets a submission speak for it. pepsi-stage-encrypt(1) registers the key that a user’s mail client advertises, or runs an e-mail key command, only for a bound From: (or a MYNETWORKS/client-certificate relay): a *@example.org grant lets one account send as its colleagues, and must not let it plant a key for them. pepsi-setup(1) warns about accounts that hold wildcard grants.

95.1.1.1.3.15. Local submission socket

One listener is never configured: the local submission socket that pepsi-sendmail(1) connects to, and through it /usr/sbin/sendmail, cron and anything else that posts mail locally. pepsi-ingress serves it unconditionally, because providing that path is a property of being a mail server rather than a feature to switch on. It is not an optional listener section, because that would make the facility depend on three separate things agreeing (the section existing, its UNIXPATH matching the client’s socket, and the runtime directory being writable), each easy to get wrong with the same silent symptom: local mail disappears.

The path is [pepsi-sendmail] SOCKET (default /run/pepsi/submission.sock), read from that one option by both ends, so the client and the server cannot name different sockets. Everything else is fixed, because none of it is a choice: the listener is called local-submission in the log, and is MODE = plain with SUBMISSION = yes and AUTH_PEERCRED. When it is bound here rather than inherited from pepsi-ingress.socket it is created mode 0666; the permissive mode grants nothing, because opening the socket conveys no authority: the kernel supplies the caller’s uid, and USERNAME_MAP decides what it may send as.

An explicit [pepsi-ingress-listener-*] section that serves the same path wins and nothing is synthesised beside it, so an operator who wants different options there (a stricter mode, a UNIXPATH_GROUP, no peer credentials) writes one. Failing to bind it is fatal, as for every other listener: a server that runs with only some of what it was asked to serve is the failure that this arrangement exists to remove. The one way to switch it off is SOCKET = none, which also makes pepsi-sendmail(1) refuse to run; with that sentinel set and no listener sections at all, the server would listen on nothing and refuses to start.

95.1.1.1.3.16. Mailbox quota at RCPT

When a recipient is on one of the served domains, pepsi-ingress may refuse it in the SMTP session because the mailbox is known to be full — 452 4.2.2 or 552 5.2.2 according to [pepsi] MAILBOX_OVER_QUOTA. Refusing here rather than accepting and bouncing later keeps the sending MTA on the line, so it tells its user, and Pepsi generates no backscatter to an envelope sender that may well be forged.

Four properties make that safe to do from a database row.

No resolution. The recipient’s local part is lower-cased, stripped of any sub-address at [pepsi] RECIPIENT_DELIMITER, and compared exactly to a passwd login. Aliases, ~/.forward files and the passwd database itself belong to the delivery stage; pepsi-ingress guesses at none of them, so an address that is not spelled like a login simply matches nothing and is accepted.

No measurement. pepsi-ingress cannot read a 0700 Maildir, and must never gain the pepsi-maildir group that would let it run the helper that can. It reads figures that somebody else wrote, and holds only SELECT on the table.

Only a fresh measurement counts. The running usage estimate is deliberately not consulted: it over-counts, and refusing on it would shut a mailbox whose owner has since emptied it. The mailbox would stay shut for good, since with every message refused no delivery would ever run to measure it again. A measurement older than [pepsi] MAILBOX_QUOTA_MAX_AGE accepts the message and lets the delivery path take a fresh look; pepsi-quota(1) reconcile keeps at-limit accounts measured.

Every uncertainty accepts. No row, no measurement and a database error all mean accept, in keeping with the rest of inbound processing.

The domainless <Postmaster> mailbox is accepted regardless, because RFC 5321 §4.5.1 requires it to stay reachable.

Set [pepsi] MAILBOX_QUOTA_RCPT_CHECK = no to skip the lookup entirely and leave all enforcement to delivery time.

95.1.1.1.3.17. Unknown recipients at RCPT

A recipient on a served domain that nothing on this host would accept is refused in the SMTP session with 550 5.1.1, for the same reason as a full mailbox: the sending MTA tells its own user, instead of Pepsi bouncing the message later to an envelope sender that spam forges (backscatter, the quickest way onto a blocklist). [pepsi-ingress] VERIFY_RECIPIENTS (default auto) controls it.

pepsi-ingress does not run the pipeline to find out. It asks whether anything that can make an address real vouches for it:

  • a local account, resolved exactly as the Maildir and ~/.forward stages resolve it;

  • an alias, matched by the aliases stage’s own code;

  • a mailing list;

  • postmaster@, abuse@ and the control address of any stage that answers one;

  • the MDA behind an LMTP stage, or the backend behind a gateway route, asked with MAIL FROM:<> and RCPT TO and no message.

Which of these apply to which served domain is derived from the [stage-*] sections at start-up; pepsi-setup run prints the result. A domain is refused-when-unknown only when every way its mail can go has something that can answer. A catch-all alias, a stage running a program that Pepsi does not know, or a backend that nobody may ask leaves the domain open. A local part is compared the way delivery compares it (NFC and Unicode case folding, so ÄBC@, äbc@ and aU+0308bc@ are one mailbox), against service addresses and recipient-list entries alike.

Every uncertainty accepts: an alias map or recipient list that cannot be read, a database error, a probe that fails, times out or is refused for any reason but “no such mailbox”, or more than 16 probes in flight. An address is refused only when every source that applies has said no. The pipeline’s own handling of unknown mailboxes stays behind this, for the cases it lets through.

A local part with % (the percent hack, user%other.example@) or ! (a UUCP bang path, other!user@) at a served domain is refused 550 5.1.3 unless a source above vouches for the address: a domain that is not verified, or whose sources could not answer, would pass it to a back end that may still honour these forms and deliver to a third party. A source that says no gives the ordinary 550 5.1.1. There is no option; verify the recipients of a domain whose addresses need such characters.

A “yes” from a probe is cached for an hour and a “no” for five minutes, so a new mailbox is reachable within minutes. After MAX_INVALID_RECIPIENTS (default 10) unknown recipients a session is closed with 421. A dictionary attack then costs connections, which the connection limits meter, rather than a lookup per guess.

VRFY still answers 252 for every address: RCPT already tells a sender whether an address exists, as it does at every MTA, and a second, cheaper way to ask would only serve address harvesting.

95.1.1.1.3.18. IP blocklists

For an unauthenticated session from the network, ingress looks the client address up once, in one indexed query, in the IP blocklists that pepsi-reputation(1) downloaded ([pepsi-reputation-list-*], pepsi.conf(5)). Only lists confirmed current within their MAX_AGE are consulted. Nobody outside the host is asked: a DNS blocklist query per connection would tell the list operator which servers mail this host.

The lists naming the client are recorded under state.origin.ip_blocklist (pepsi.state(7)), where pepsi-stage-if(1) can route on them. A list with ACTION = reject also makes ingress refuse the session’s recipients with 554 5.7.1 … client host [ADDRESS] is listed by NAME, except <postmaster>, which RFC 5321 keeps reachable and through which a listed sender can reach a human.

A lookup that fails or takes longer than two seconds, and a deployment where no list is current, consult nothing: the mail is accepted and nothing is recorded, so “unknown” never reads as “clean”.

95.1.1.1.3.19. Reverse DNS

The client’s reverse DNS is validated once per session (RFC 8601 iprev: a PTR name that resolves back to the address) and recorded as state.origin.iprev and in the Received: header. With IPREV_ACTION = reject, a definite fail refuses the recipients of an unauthenticated session with 550 5.7.25 Reverse DNS validation failed (RFC 7372), except <postmaster>, on any listener that is not a submission listener. A temperror or permerror never refuses. The default, none, only records: broken reverse DNS is evidence about a sender’s DNS, not about its message, and small sites have it.

95.1.1.1.3.20. Milters

A milter is a mail filter that speaks the sendmail/Postfix filter protocol: a spam or virus scanner, a policy daemon, a greylister. The milters a listener runs ([pepsi-ingress] MILTERS, or the listener’s own MILTERS; each configured in a [pepsi-ingress-milter-*] section, pepsi.conf(5)) are consulted inside the SMTP session, so their refusal is the reply the client gets. A 5xx is reported by the sending MTA to its user; a 4xx is retried, which is how greylisting works (pepsi-greylist(1) is the greylisting milter that ships with Pepsi). Nothing is accepted that would later be bounced to a sender who may be forged. By default only listeners that are not submission listeners run milters.

Ingress opens one connection to each milter when the client first greets, and keeps it for the whole session. The milter is told about the connection and HELO/EHLO, every MAIL (with its ESMTP parameters), every recipient that Pepsi itself accepted (with NOTIFY/ORCPT/RRVS), DATA (or the first BDAT chunk) and, at the end of the data, the header block, the body and the end of the message. Pepsi’s own checks always come first: a milter is never asked about a recipient or a message that Pepsi refuses anyway, and what it is shown at the end is the message as Pepsi would store it, with Pepsi’s Authentication-Results field and any X-Pepsi-Warning fields already added, so a filter can build on those verdicts. A milter that asked for it (SMFIP_RCPT_REJ) is also told about the recipients that Pepsi refused, with Pepsi’s reply. A message that was refused or abandoned (RSET) is closed with SMFIC_ABORT before the next MAIL. The macros (i names the token of the row the message will become) are listed in pepsi.conf(5).

The milters are asked in list order, and each sees the message as the ones before it left it. What a verdict does:

  • REJECT and TEMPFAIL (or a reply code of their class) refuse the recipient when given at RCPT, and the transaction or the message when given at MAIL, DATA, the headers, the body or the end of the message. The milter’s own reply text is passed on when it is a well-formed 4xx/5xx reply of the verdict’s class (several lines allowed); any other text is replaced by 451 4.7.1 … or 550 5.7.1 …, so a filter cannot put an accept, or a forged second reply line, on the wire.

  • A refusal at the connection or HELO is not answered there: every later MAIL of the session gets it, like Postfix’s smtpd_delay_reject.

  • ACCEPT ends that milter’s part in the message (or, when given at the connection or HELO, in the session); the other milters are still asked, as under Postfix. OpenDKIM, often the first milter, answers ACCEPT, and the spam filter after it must still see the message.

  • DISCARD accepts the message with 250 and stores nothing.

  • At the end of the message, a milter may change header fields and the body, and, when ALLOW_ACTIONS grants it, the recipients and the envelope sender. A recipient it adds must be one that ingress would have accepted from this client; a message whose recipients it all deletes is accepted and not stored. SMFIR_QUARANTINE stores the message at the quarantine stage (pepsi-stage-quarantine(1)) instead of init.

Changes to the content of a message that carries an ARC chain are applied too, but the chain must still be verified over the bytes that its sealers signed: the message as received is then kept beside the edited one (workqueue.arc_original_body_id, state.arc_original), and pepsi-stage-arc(1) verifies the chain over it and seals the stored message. Ingress warns at start-up when a milter may change messages and no stage runs pepsi-stage-arc(1).

What each milter did is recorded in state.ingress_milter (its name, its verdict and the modifications it made; pepsi.state(7)), and every refusal is logged with the milter’s name and reply. A milter that cannot be reached, times out or breaks the protocol is handled as its ON_FAILURE says. By default (accept) it is consulted no more in that session and the mail is accepted: a crashed filter must not stop all inbound mail.

95.1.1.1.3.21. Queue admission control

pepsi-ingress stops accepting mail while the queue, or the disk under it, is at a limit set in [pepsi] (see pepsi.conf(5)):

  • MAX_QUEUE_ROWS — queued messages (default one million recipient rows);

  • MAX_QUEUE_BYTES — queued header blocks plus distinct bodies (default unlimited);

  • MIN_FREE_SPACE — free space on the filesystem of FREE_SPACE_PATH (default 1 GiB on /var/lib/postgresql).

The answer is 452 4.3.1 Insufficient system storage, a temporary refusal, given at RCPT, at DATA (or the first BDAT chunk, whose octets are still read so the session stays framed) and once more after the end of data, when the message’s own size is known and a single message that would cross MAX_QUEUE_BYTES or MIN_FREE_SPACE is refused on its own. The sending MTA keeps the message and retries, while the queue that is already there drains; the throttle lifts by itself. Local submission is treated alike, and pepsi-sendmail(1) turns the 452 into EX_TEMPFAIL, so cron retries.

The check is cheap: the queue is measured (the pepsi.queue_usage() function, two sequential scans) at most once per QUEUE_CHECK_INTERVAL (default 10 s) for the whole server, and every command in between is answered from that figure. pepsi-ingress needs no access to queued mail for it, only to the generated size columns header_octets and workqueue_body.octets. Every uncertainty admits: a failed measurement, or a probe path that does not exist (a database on another host), leaves mail flowing.

95.1.1.1.3.22. Overload protection

Several mechanisms keep a flood of connections from exhausting the server, including clients that complete the TCP handshake and then go silent without ever closing. They operate on a source range: a single IPv4 address (a /32), or the /32 prefix of an IPv6 address. Local (UNIX-socket) connections form one range of their own, which is exempt from the rate limit and from the server-wide eviction and is bounded by its own ceiling instead: a local submitter is a user of this machine, and pepsi-sendmail must not be turned away because a remote host is busy.

  • Per-command timeouts (RFC 5321 §4.5.3.2). A session that does not send its next command within COMMAND_TIMEOUT (default 300 s), or the next block of a DATA/BDAT body within DATA_TIMEOUT (default 180 s), is closed with a 421.

  • TLS handshake timeout. A TLS handshake, on an implicit-TLS listener before the greeting or after STARTTLS, must complete within TLS_HANDSHAKE_TIMEOUT (default 30 s); otherwise the connection is closed without a reply (there is no channel to send one on). A handshake is a few round trips for a working client, while the server spends a private-key operation and connection state on each one, so a peer that opens connections and stalls or trickles its ClientHello holds a slot for this long rather than for a whole COMMAND_TIMEOUT.

  • Session deadline. Every byte that a client sends resets the per-read timeouts, so they never end a session that keeps trickling; SESSION_TIMEOUT (default 30 m, 0 s disables) bounds the whole session from the moment it connects. Past it, the next read (a command, an AUTH continuation, a block of a body) is answered 421 4.4.2 Session time limit exceeded and the connection closed. This is what keeps a client from parking thousands of transactions just before the end of DATA, at this host and others, to complete them in one instant.

  • Connection ceiling with eviction. The server admits at most min(MAX_CONNECTIONS, MAX_OPEN_SOCKETS) concurrent connections. MAX_OPEN_SOCKETS guards against file-descriptor exhaustion; when unset it is derived from the soft RLIMIT_NOFILE minus RESERVED_SOCKETS (default 64, held back for the database pool, listeners, stdio and DNS sockets). When the ceiling is reached and a new connection arrives, the server makes room by closing the longest-idle connection in the range whose total idle time is largest (a 421, then close), so the greediest source loses its most-idle slot first. “Idle” is time a connection spends blocked awaiting client input, between commands or between the blocks of a DATA/BDAT body, but not time spent processing. A client that trickles its body a byte at a time therefore counts as idle and can be evicted at any point of the transfer; every byte it sends resets DATA_TIMEOUT, so the timeout alone would not end such a connection.

  • Per-range ceiling. One source range may hold at most MAX_CONNECTIONS_PER_IP (default 16) connections at once, and all local connections together at most MAX_LOCAL_CONNECTIONS (default 32). The rate limit below does not bound concurrency on its own: one connection a second, each kept busy, fills any ceiling in minutes, and eviction reclaims only idle connections. Without the local ceiling, one local user could hold every slot and starve remote SMTP. Within the local ceiling, one peer uid (as SO_PEERCRED reports it) may hold at most half of MAX_LOCAL_CONNECTIONS (at least one), so a single local account cannot take every local slot and make the pepsi-sendmail of other users, cron’s included, fail; root and the service accounts are not exempt. Two or more accounts acting together could still fill the local ceiling between them, so when it is full a new local connection from a uid that holds fewer local connections than the heaviest uid evicts that uid’s longest-idle connection, provided it has sent no complete command line for 5 seconds; the evicted session is answered 421 4.3.2. pepsi-sendmail reads its whole message before it connects and never pauses that long, so a legitimate local client is not the one evicted, while held-open connections cannot keep the ceiling full. A new connection from the heaviest uid itself is refused. A connection over any of these is refused like a rate-limited one. 0 disables either ceiling (and, for the local range, the per-uid share and the eviction with it).

In addition, accepted new connections are rate-limited per source range by a token bucket: CONN_RATE_PER_SECOND (default 1) refill rate with a CONN_RATE_BURST (default 1) burst. A connection over the rate gets a best-effort 421 and is then closed, holding a slot for the duration of that write. This is deliberate: it keeps a flood of rate-limited connections from spawning unbounded reject tasks that each pin a descriptor outside MAX_OPEN_SOCKETS. When the rate limit trips while the descriptor ceiling is already reached, no slot is taken and the connection is closed with no reply at all, since writing the 421 would itself use up the descriptor that the server is trying to conserve. (On an implicit-TLS listener the refusing 421 is likewise omitted, since no plaintext may precede the handshake; the connection is simply closed.)

Within and across sessions:

  • Messages per session. A session may start at most MAX_MESSAGES_PER_SESSION (default 100) mail transactions (RSET does not reset the count); the next MAIL is answered 421 and the connection closed, so a sender with more to deliver reconnects, and the rate limit meters the reconnections.

  • Recipients per transaction. At most 1000 RCPT TO are accepted in one transaction (RFC 5321 §4.5.3.1.8 asks for at least 100); every further one is answered 452 4.5.3 and the client sends it in a later transaction.

  • Routing loops. A message that has already passed through this host’s ingress MAX_SELF_HOPS (default 5) times is refused at the end of data with 554 5.4.6. The count comes from the Received: fields that ingress itself writes. The refusal turns a loop, in which an address on our own domain is relayed to our own MX again and again, into one bounce by the stage that tried to relay it.

  • More than one From: field. A message whose header block carries two or more From: fields is refused at the end of data with 550 5.6.0, on every listener. RFC 5322 §3.6 allows one; with two, mail clients disagree about which they show, while DMARC alignment, the submission identity check and the signature binding all read the first, so a sender could have one address checked and another displayed.

  • Password guessing. Three failed AUTH attempts close a session. Across sessions, a source range may fail AUTH at most AUTH_FAILURES_PER_HOUR (default 20) times in a token bucket refilling at that rate; once it is spent, every further AUTH from the range is answered 421 and the connection closed without the SASL backend being asked, until the bucket refills.

  • Password guessing per account. A guesser spread over many addresses stays under every per-range budget, so failures are also counted per account (its authentication id, compared case-insensitively), from all sources together: ACCOUNT_AUTH_FAILURES_PER_HOUR (default 10). Once an account has collected them, an AUTH for it waits ACCOUNT_AUTH_DELAY (default 20 s) before the SASL backend is asked, and such attempts are checked one at a time, so the account is guessed at no faster than once per delay however many connections carry the guesses. An attempt that would queue longer than three delays is answered 454 4.7.0 without being checked. The account is never locked, because a lock would let anybody who knows an account name shut its owner out. A source range that authenticated as the account within the last 30 days is not delayed at all.

  • Local submission rate. A UNIX-socket session authenticated by AUTH_PEERCRED is limited per uid, across its sessions, to LOCAL_MESSAGES_PER_MINUTE (default 60) messages with a burst of LOCAL_MESSAGE_BURST (default 120). A MAIL over the rate is answered 451 4.7.1, which pepsi-sendmail(1) turns into EX_TEMPFAIL.

  • Recipients per account. A session authenticated by SASL AUTH is limited per authentication id (compared case-insensitively), across its sessions, to USER_RECIPIENTS_PER_HOUR (default 500) accepted recipients with a burst of USER_RECIPIENT_BURST (default 500). A RCPT over the rate is answered 450 4.7.1, so the client keeps the recipient and retries later. This is what bounds a stolen password: the thief may connect from anywhere, but every message is charged to the account. Only accepted recipients count, and <postmaster> is never refused. Sessions authenticated by MYNETWORKS or a client certificate are not metered here.

0 disables any of these five. The cross-session counters live in the server’s memory, so a restart forgets them.

95.1.1.1.3.23. Privilege dropping

The SMTP ports (25/465/587) are privileged, so pepsi-ingress is often started as root. It does not, however, serve as root: once every configured listener has been bound (and any TLS key material read), the process drops to the unprivileged service account pepsi-ingress, dropping the supplementary groups and switching to that account’s group and user id before accepting a single connection. The one supplementary group it keeps is that of a milter socket: for each milter reached over a UNIX socket, the group that owns the socket, when the pepsi-ingress account is a member of it in /etc/group. That is how access to a milter’s socket is granted (adduser pepsi-ingress clamav, say); the Debian package makes the account a member of pepsi-greylist. A socket that does not exist when ingress starts is not considered, so start the milter first. The account must therefore exist before the server is started as root; create it (for example useradd --system --no-create-home --shell /usr/sbin/nologin pepsi-ingress) as part of installation.

If the drop cannot be completed while running as root — most often because the pepsi-ingress account does not exist — the server logs an error and exits without serving, rather than risk running as root. When started by a non-root user no privilege change is performed (the server simply runs as the invoking user); it will never run as root.

95.1.1.1.3.24. TLS key material

The TLS_CERT/TLS_KEY of every MODE = tls/starttls listener is read once, at start-up, before the privilege drop above.

Under systemd the unit runs as the unprivileged pepsi-ingress user from the outset and never holds root, so it cannot open certbot’s root-only /etc/letsencrypt/{live,archive}. pepsi-setup(1) therefore writes a drop-in /etc/systemd/system/pepsi-ingress.service.d/10-tls-credentials.conf with one LoadCredential= entry per file: systemd opens them as root at unit start and hands the service private copies under $CREDENTIALS_DIRECTORY, which pepsi-ingress consults before falling back to reading the configured path itself. Re-run pepsi-setup run after adding, moving or removing a certificate so the drop-in is regenerated. Because credentials are materialised when the unit starts, a renewed certificate is served only after a restart; the certbot deploy hook that pepsi-setup installs performs that restart. Started directly (as root, dropping privileges after binding), the server reads the files itself and no credential is involved. See pepsi-httpd(1), which describes the same mechanism in full.

Unlike pepsi-httpd, which serves many certificates and skips one it cannot load, a listener here has exactly one: if it cannot be read there is nothing to fall back to, and the server exits rather than silently offer no TLS on a port that the configuration says is encrypted.

95.1.1.1.4. Commands

serve

Bind every configured [pepsi-ingress-listener-*] socket and serve SMTP connections until interrupted. Requires that the schema has been installed with pepsi-setup(1).

95.1.1.1.5. Global Options

These global options precede the subcommand (a trailing flag is rejected).

-c FILE, –config FILE

Read the configuration from FILE instead of searching the default locations (see FILES).

-L LOGLEVEL, –log LOGLEVEL

Set the logging verbosity. LOGLEVEL is one of error, warn, info, debug or trace (default: [pepsi] LOG, else info).

-v, –verbose

Show log messages from all sources, including third-party libraries that are filtered out by default.

-h, –help

Print a usage summary and exit.

-V, –version

Print the version and exit.

95.1.1.1.6. Signals

SIGINT

Initiate shutdown: the process stops serving and exits 0. Sessions still in progress are not drained, and need not be: a message is confirmed to its client (250) only once it has been committed, so an interrupted session either has its message safely in the queue or was never told otherwise, and the sending MTA retries.

SIGTERM

Not caught: the default disposition terminates the process, which is safe for the same reason. This is what systemctl stop pepsi-ingress sends.

95.1.1.1.7. Exit Status

0

Successful completion (including a clean shutdown of serve).

1

An error occurred, for example a malformed configuration file, a failed database connection, or a listener that could not be bound. The reason is written to the log.

78

The installed database schema does not match this binary (not installed, older, newer or modified); run pepsi-setup(1) of the same release.

95.1.1.1.8. Environment

XDG_CONFIG_HOME, HOME

Used to locate the default configuration file when –config is not given (see FILES).

LISTEN_FDS, LISTEN_PID, LISTEN_FDS_FIRST_FD

Honoured for systemd socket activation. A listener configured with SERVE = systemd adopts the file descriptor passed by systemd at the index given by its FD_INDEX option. LISTEN_FDS_FIRST_FD gives the number of the first passed descriptor and defaults to 3 (SD_LISTEN_FDS_START); it is read for the benefit of supervisors other than systemd that set it. LISTEN_FDNAMES is not consulted: a FileDescriptorName= names a whole .socket unit’s descriptors rather than one ListenStream=, so it could not tell these listeners apart. The local submission socket is instead found by its bound address — see below.

The shipped pepsi-ingress.socket passes four: ports 25, 465 and 587, which the listener sections claim by FD_INDEX 0, 1 and 2, and the local submission socket /run/pepsi/submission.sock, which is claimed differently (see below). Binding that UNIX socket in the unit rather than in the server is deliberate: systemd creates it as root before the service starts, so the unprivileged pepsi-ingress never needs to create anything in /run/pepsi, a directory that several services share and that no unit declares as its RuntimeDirectory= (the package’s tmpfiles entry creates it).

The local submission socket has no FD_INDEX and no listener section. pepsi-ingress serves it unconditionally (from [pepsi-sendmail] SOCKET) and finds the descriptor by asking the kernel which of the passed sockets is bound to that path. An index would be a position among the unit’s ListenStream= entries and would therefore shift whenever an SMTP port is added or removed; the bound address cannot drift out of step with anything. If no passed descriptor matches, the server binds the path itself. That is what happens off systemd, and it is why failing to bind the path is fatal there.

Every other descriptor passed must be claimed by some listener section. One that is not is reported with a warning at start-up naming its index, because systemd keeps accepting connections on it that nothing will ever answer. A client then blocks until its own read timeout expires (two minutes, for pepsi-sendmail(1)) rather than being refused at once: both defer the message, but the block stalls the caller for every message. If you remove a listener section, remove its ListenStream= from the unit too.

JOURNAL_STREAM

When set (i.e. when running under systemd), timestamps are emitted in UTC without a local time-zone offset.

95.1.1.1.9. Files

When –config is not given, the first existing file from the following list is used:

  • $XDG_CONFIG_HOME/pepsi.conf

  • $HOME/.config/pepsi.conf

  • /etc/pepsi/pepsi.conf

  • /etc/pepsi.conf

Every Pepsi component shares the same configuration file, so this is the same list that each one searches.

95.1.1.1.10. Examples

Install the schema (once, with pepsi-setup) and start serving:

pepsi-setup   -c /etc/pepsi/pepsi.conf
pepsi-ingress -c /etc/pepsi/pepsi.conf serve

Check which domains mail is accepted for (with pepsi-config(1)):

pepsi-config -c /etc/pepsi/pepsi.conf get pepsi-ingress ACCEPTED_DOMAINS

Dump the merged configuration with source annotations:

pepsi-config -c /etc/pepsi/pepsi.conf dump --diagnostics

95.1.1.1.11. See Also

The claims that these mechanisms uphold are in the threat model of the Pepsi manual (“A remote sender”, “A local shell user”, “What a security indicator means”, “Availability”); the mechanisms are described under “The privilege split”, “The submission identity”, “Unknown recipients and backscatter”, “A login that changes owner” and “Resource limits” in its security chapter.

pepsi-config(1), pepsi.conf(5), pepsi-setup(1), pepsi-dispatch(1), pepsi-sendmail(1), pepsi.state(7), systemd.socket(5)

95.1.1.1.12. Bugs

Report bugs to the Pepsi issue tracker.