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:
verifies SPF (on the
MAIL FROMidentity, using the connecting client’s IP), DKIM and DMARC; andprepends an
Authentication-Resultsheader reporting these results, with the[pepsi-ingress] HOSTNAMEas theauthserv-id, and records the rendered result text understate.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 emptyboundary=on a multipart, a NUL byte in any MIME entity’s header block, twoContent-Typeor twoContent-Transfer-Encodingfields on one entity that differ, a boundary that is or contains an RFC 2047 encoded-word, and two differing copies of a message-headerDate,Subject,To,Reply-ToorSenderfield, 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 secondCc:line: the message is stored as received and getsX-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-streamand 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 identicalContent-TypeorContent-Transfer-Encodingfield (dropped); and a second identical copy of a message-headerDate,Subject,To,Cc,Reply-To,Sender,Message-ID,In-Reply-ToorReferencesfield (equal after unfolding and collapsing whitespace; the first copy is kept). DifferingMessage-ID,In-Reply-ToorReferencesfields 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 secondFrom:is refused before any of this (550 5.6.0), and everyBcc:is removed. Amultipart/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 |
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 |
0 |
0 |
Differing |
6 |
0.025 % |
Identical copies of any of the nine fields |
1 |
0.004 % |
Differing |
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— aFrom: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— aFrom:mailbox at a served domain, with neither a DMARCpass, a DKIMpassaligned with that domain, nor an SPFpasswhoseMAIL FROMdomain aligns with it. AFrom:naming several domains is vouched for by a DMARCpassalone.X-Pepsi-Warning: served-sender-not-authenticated— aSender:mailbox (anySender:field) at a served domain, with neither a passing DKIM signature nor an SPFpasswhoseMAIL FROMdomain aligns with it. ASender:at another domain is not marked.X-Pepsi-Warning: dmarc-fail-not-enforced— DMARC evaluated tofailand the message was accepted anyway:DMARC_ENFORCEis off, or the domain publishesp=none. A failure a sealer inARC_TRUSTED_SEALERSvouched 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
/32or/128host). An entry outside loopback must be bound bySENDER_MAP(see Sender bindings below), or pepsi-ingress refuses to start.SASL — a
SASL_TYPEbackend (currentlydovecot, via theSASL_PATHauth-client socket) accepts anAUTHexchange.AUTH(mechanismsPLAINandLOGIN) is advertised and accepted only on a TLS-protected session (implicit TLS or afterSTARTTLS); a cleartextAUTHattempt is refused with504 5.5.4(RFC 4954 §4, which deprecates the538reply for this).TLS client certificate — the client presents a certificate that is either a pinned key (its
SubjectPublicKeyInfoSHA-256, 64 hex chars, is listed inTLS_AUTH_CLIENT) or validates to one of the CA certificates inTLS_AUTH_CLIENT_CA, andSENDER_MAPbinds 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 theUSERNAME_MAPmachinery, so a caller can only send as itself. Default ``yes`` for a ``SERVE = unix`` listener (setAUTH_PEERCRED = noto 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 3848ESMTPAkeyword. For aSERVE = systemdlistener 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_CLIENTlists the SHA-256 of the DERSubjectPublicKeyInfoof 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 withopenssl x509 -in cert.pem -noout -pubkey | openssl pkey -pubin -outform DER | openssl dgst -sha256.A CA.
TLS_AUTH_CLIENT_CAnames 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,basicConstraintswithpathLenConstraint,keyUsage, name and policy constraints, the rule that an unrecognised critical extension is a refusal, and key strength.pathLenConstraintapplies 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 anextendedKeyUsagenamingid-kp-clientAuth(an absent extension oranyExtendedKeyUsagedoes not do), thedigitalSignaturebit, 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 FROMis refused with530 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,MYNETWORKSorAUTH_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-protectedMODE(tlsorstarttls), except on a local socket, i.e.SERVE = unixor aSERVE = systemdlistener that inherits one, where there is no network to protect. The shipped local submission socket is exactly that:MODE = plainwithSUBMISSION = yesandAUTH_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 missingMessage-ID:is generated as<random@HOSTNAME>(§8.3). Headers that are already present are left untouched, and the fixups run before theReceived: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): nofromclause, and noUser-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
AUTHcommand is refused with535 5.7.8and 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 firstMAIL FROMis then answered530 5.7.0. This is how a system account (www-data, say) is excluded from submitting at all;not listed (or no
USERNAME_MAPconfigured) — the defaultusername@HOSTNAME.
Given that set, two checks run on such a submission:
Envelope and header identity (§6). The
MAIL FROMenvelope sender and the messageFrom:address must each be one of the allowed addresses, otherwise the message is refused with550 5.7.1(atMAIL FROMand at end-of-DATArespectively). The null sender<>is exempt; a message with noFrom:, or one that cannot be read unambiguously (below), is refused with550 5.6.0. RFC 5322 §3.6.2 makesFrom: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. Soceo@example.com (<alice@example.org>)is checked asceo@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 with550 5.6.0rather 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 with550 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 existingSender: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, aSender:header naming the canonical identity is prepended. For the multi-mailbox case, RFC 5322 §3.6.2 requires aSender:to be present, and §8.1 is what lets the MSA supply it. WhenFrom:is a single mailbox naming the canonical identity, aSender: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
~/.forwardstages 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:<>andRCPT TOand 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:
REJECTandTEMPFAIL(or a reply code of their class) refuse the recipient when given atRCPT, and the transaction or the message when given atMAIL,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-formed4xx/5xxreply of the verdict’s class (several lines allowed); any other text is replaced by451 4.7.1 …or550 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
HELOis not answered there: every laterMAILof the session gets it, like Postfix’ssmtpd_delay_reject.ACCEPTends that milter’s part in the message (or, when given at the connection orHELO, in the session); the other milters are still asked, as under Postfix. OpenDKIM, often the first milter, answersACCEPT, and the spam filter after it must still see the message.DISCARDaccepts the message with250and 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_QUARANTINEstores the message at the quarantine stage (pepsi-stage-quarantine(1)) instead ofinit.
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 ofFREE_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 aDATA/BDATbody withinDATA_TIMEOUT(default 180 s), is closed with a421.TLS handshake timeout. A TLS handshake, on an implicit-TLS listener before the greeting or after
STARTTLS, must complete withinTLS_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 wholeCOMMAND_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 sdisables) bounds the whole session from the moment it connects. Past it, the next read (a command, anAUTHcontinuation, a block of a body) is answered421 4.4.2 Session time limit exceededand the connection closed. This is what keeps a client from parking thousands of transactions just before the end ofDATA, 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_SOCKETSguards against file-descriptor exhaustion; when unset it is derived from the softRLIMIT_NOFILEminusRESERVED_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 (a421, 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 aDATA/BDATbody, 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 resetsDATA_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 mostMAX_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 (asSO_PEERCREDreports it) may hold at most half ofMAX_LOCAL_CONNECTIONS(at least one), so a single local account cannot take every local slot and make thepepsi-sendmailof other users, cron’s included, fail;rootand 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 answered421 4.3.2.pepsi-sendmailreads 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.0disables 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 (RSETdoes not reset the count); the nextMAILis answered421and 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 TOare accepted in one transaction (RFC 5321 §4.5.3.1.8 asks for at least 100); every further one is answered452 4.5.3and 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 with554 5.4.6. The count comes from theReceived: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 with550 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
AUTHattempts close a session. Across sessions, a source range may failAUTHat mostAUTH_FAILURES_PER_HOUR(default 20) times in a token bucket refilling at that rate; once it is spent, every furtherAUTHfrom the range is answered421and 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, anAUTHfor it waitsACCOUNT_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 answered454 4.7.0without 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_PEERCREDis limited per uid, across its sessions, toLOCAL_MESSAGES_PER_MINUTE(default 60) messages with a burst ofLOCAL_MESSAGE_BURST(default 120). AMAILover the rate is answered451 4.7.1, which pepsi-sendmail(1) turns intoEX_TEMPFAIL.Recipients per account. A session authenticated by SASL
AUTHis limited per authentication id (compared case-insensitively), across its sessions, toUSER_RECIPIENTS_PER_HOUR(default 500) accepted recipients with a burst ofUSER_RECIPIENT_BURST(default 500). ARCPTover the rate is answered450 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 byMYNETWORKSor 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,debugortrace(default:[pepsi] LOG, elseinfo).- -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-ingresssends.
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 = systemdadopts the file descriptor passed by systemd at the index given by itsFD_INDEXoption.LISTEN_FDS_FIRST_FDgives the number of the first passed descriptor and defaults to3(SD_LISTEN_FDS_START); it is read for the benefit of supervisors other than systemd that set it.LISTEN_FDNAMESis not consulted: aFileDescriptorName=names a whole.socketunit’s descriptors rather than oneListenStream=, 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.socketpasses four: ports 25, 465 and 587, which the listener sections claim byFD_INDEX0, 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 unprivilegedpepsi-ingressnever needs to create anything in/run/pepsi, a directory that several services share and that no unit declares as itsRuntimeDirectory=(the package’s tmpfiles entry creates it).The local submission socket has no
FD_INDEXand no listener section.pepsi-ingressserves 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’sListenStream=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.