3. Getting started on a cheap VPS¶
This chapter is a walkthrough from start to finish. It starts from a freshly rented virtual private server and a domain name that you have just registered. It ends with a first e-mail received and delivered into a local mailbox, and with a proper bounce sent back for anything that cannot be delivered. The other chapters explain each piece in depth; this one puts them together.
3.1. What we will build¶
A small mail host that accepts mail for example.org on the standard SMTP port
and delivers each message into the recipient’s local Maildir on the same
server. If it cannot deliver a message locally, for example because the
recipient is unknown or the mailbox is full or unwritable, it turns the message
into a real bounce (a delivery-status notification) and sends it back to the
original sender, rather than letting it disappear silently into the queue. The
inbound pipeline is short:
inbound SMTP -> [stage-init] -> [stage-local]
(pepsi-ingress) pepsi-stage-arc pepsi-stage-relay-to-maildir
(record the (deliver to the user's
inbound verdict) ~/Maildir/new/)
and whatever it cannot deliver is signed and mailed back to the sender over a short outbound path:
[stage-bounce] -> [stage-sign] -> [stage-internet]
pepsi-stage-bounce pepsi-stage-dkim-sign pepsi-stage-relay-to-internet
(build the DSN) (sign the bounce) (send it to the sender's MX)
Replace example.org with your own domain and alice with a real account
name throughout. Because the host also sends these bounces, DKIM-signed and
from an SPF-authorised address, this setup publishes the sender-authentication
records that let receivers trust its outgoing mail: DKIM, SPF and
DMARC. A host that only receives mail would not need them. (MTA-STS and
TLS reporting harden inbound TLS and need the HTTPS server running; they
are left out here and added later as optional hardening, see
Next steps.) A final section reuses exactly the same outbound path to
add an authenticated submission port, so that your own users can send through
the host too.
Note
Scope. This is the simplest realistic deployment: it receives mail, delivers it locally and bounces what it cannot deliver. For a forwarding host (ARC + SRS + DKIM re-signing on the way back out) see Introduction and pepsi-stage-relay-to-internet, and Next steps for how to grow this host into one.
Pepsi delivers into a Maildir but ships no IMAP/POP server, so once mail
has landed you read it on the box itself (mutt, mail) until you add a
mailbox server such as Dovecot. See Next steps.
3.2. Prerequisites¶
A VPS with a public, static IPv4 address (and ideally an IPv6 address) and root access. We use
203.0.113.7/2001:db8::25as placeholders.A registered domain whose DNS you can edit (
example.org).TCP port 25 must reach the VPS both ways. Inbound port 25 carries the mail you receive; outbound port 25 lets the host send bounces back to senders. Many budget providers block outbound port 25 by default. If bounces never leave the queue, that is the usual cause; ask the provider to open the port. If inbound mail never arrives, check that the MX record names the host and that neither the provider nor the host’s firewall blocks inbound port 25. (If outbound 25 cannot be unblocked, send the bounces through a smarthost instead — see pepsi-stage-relay-to-smarthost.)
Reverse DNS (PTR). Set the VPS’s PTR record to
mail.example.org. You do this in the control panel of the VPS provider, not in your domain’s zone. The record must name the same host that you announce inEHLO: many receivers compare the two and refuse the session when they differ (HELO host does not match rDNS). This mistake is easy to make on a machine that answers to several names.pepsi-setup runwarns about every sending address whosePTRis missing, unconfirmed or names a different host, andpepsi-setup --wizardproposes thePTRname as the hostname for exactly this reason.The build prerequisites from Installation: a Rust toolchain, PostgreSQL, and (for automatic TLS)
certbot. Install them with your platform’s package manager.
3.3. Step 1 — Delegate DNS and place the base records¶
Pepsi contains no DNS server; you publish records wherever your domain’s zone is authoritative. You have two choices, and “delegation” means different things for each:
Host the zone at a DNS provider (your registrar, or a service such as a managed DNS host). Here the registrar already delegates
example.orgto that provider’s name servers; you only add records in their panel. This is the simplest path.Run your own authoritative name server (BIND, NSD, Knot, …) on the VPS or elsewhere. Then at the registrar you set
example.org’sNSrecords to your name servers and, if a name server is itself insideexample.org, add the matching glueA/AAAArecords at the registrar so the delegation can be resolved:; at the registrar (delegation + glue) example.org. NS ns1.example.org. ns1.example.org. A 203.0.113.7
Either way, once the zone is under your control, add the two records that the mail host needs immediately:
; the mail host's address
mail.example.org. A 203.0.113.7
mail.example.org. AAAA 2001:db8::25
; mail for the domain goes to that host
example.org. MX 10 mail.example.org.
Note
The remaining records — SPF, DKIM and DMARC — are added in
Step 6 — Publish the remaining records and verify after pepsi-setup has generated the DKIM key and
printed the exact text to publish. (MTA-STS and TLS-reporting records are only
added if you enable those optional features — see Next steps.) Add
the A/AAAA record now, though: the automatic TLS certificate in Step 5
requires mail.example.org to already resolve to this VPS.
3.4. Step 2 — Install Pepsi¶
This walkthrough builds and installs from a source checkout, so that every step
is visible. On Debian and derivatives you can instead install the .deb, whose
postinst does Steps 2 and 3 for you — see the Debian package tab of
Installation and the Debian packages chapter; the rest of this chapter
applies unchanged.
Fetch the vendored submodule first, then install binaries, SQL and the sample config in one step:
git submodule update --init --recursive
make install PREFIX=/usr SYSCONFDIR=/etc
This installs the pepsi-* binaries, the SQL migrations and a reference
/etc/pepsi/pepsi.conf.sample (never a live pepsi.conf: Step 4 writes
that). Run make install as root, so that the local-delivery helper can be
installed with its privileges (next step). Installation explains what
each step does, and Database schema lifecycle how the database schema evolves.
3.5. Step 3 — Prepare the system¶
Local delivery writes into other users’ home directories, so Pepsi separates privileges with dedicated service users and a tightly scoped setuid helper. The account names are compiled in; they are not just a convention, so create them exactly as written (use your platform’s tools for users and groups):
pepsi— the service user that the dispatcher and every stage worker run as;pepsi-ingress— the SMTP server’s own account (it refuses to start as root when this account does not exist);pepsi-owner— the bootstrap account thatpepsi-setupdrops to when it is run as root, and the owner of the database schema;a
pepsi-maildirgroup that gates the delivery helper.
Installation lists the full set (including the accounts for the web console, the key store and the other privileged helpers); the four above are what this walkthrough uses.
The delivery path has two privilege bits, which make install sets
automatically when run as root and the pepsi-maildir group already exists;
otherwise set them by hand:
pepsi-helper-maildir-writer(1) must be setuid-root and group-restricted (
chown root:pepsi-maildir … ; chmod 4750 …), andpepsi-stage-relay-to-maildir must be setgid
pepsi-maildirand owned bypepsi(chown pepsi:pepsi-maildir … ; chmod 2550 …). This is what lets the unprivilegedpepsiworker exec the helper; nothing else can.
See those two chapters for the rationale, and The privilege split for the privilege split as a whole.
Create the database. Pepsi connects over the local socket under the name of the
system user that runs it (peer authentication), so each of those accounts
needs a login role of its own: the server connects as pepsi-ingress, the
stages as pepsi, and pepsi-setup installs and owns the schema as
pepsi-owner. Create the full set of roles, not only the three that this
walkthrough runs as. pepsi-setup run grants rights to every one of them, and
it does its database work as pepsi-owner, which cannot create roles, so a
missing role stops it with permission denied to create role. Run the
following as the postgres superuser; the database name matches CONFIG =
postgres:///pepsi below:
for r in pepsi-owner pepsi pepsi-ingress pepsi-httpd pepsi-whitelist \
pepsi-config pepsi-crypto pepsi-keydisc pepsi-telemetry; do
createuser "$r" # createuser takes one role name at a time
done
createdb -O pepsi-owner pepsi
Finally, create at least one local mailbox account to receive mail:
useradd --create-home alice
3.6. Step 4 — Write the configuration¶
All components read one file, /etc/pepsi/pepsi.conf. The sample that Step 2
installed is a full-featured reference that wires optional stages. For this
walkthrough you want a minimal configuration instead, one that only delivers
locally and sends bounces. There are two equivalent ways to produce it: let
pepsi-setup generate it from a few answers, or write it by hand. Both build
the same pipeline. (The format and every option are
described in Configuration and pepsi.conf(5).)
pepsi-setup --wizard runs a short interview, writes a complete and
already-validated /etc/pepsi/pepsi.conf, and then offers to run the
provisioning of Step 5 for you. Start it:
pepsi-setup --wizard
Answer the prompts as follows. Press Enter to accept a [default]; the
prompts not listed here can all keep their defaults (they are no for this
minimal host):
Mail direction this host serves —
inboundMail server hostname (MX / EHLO name) —
mail.example.org. The default is the name that reverse DNS gives for this host’s public address. If that is notmail.example.org, fix thePTRrecord before you go further, rather than overriding the default here.Domain(s) we accept mail for —
example.orgPostmaster address — accept the default (
postmaster@example.org)Public sending IP address(es) for SPF —
203.0.113.7 2001:db8::25PostgreSQL connection string — accept the default (
postgres:///pepsi)Deliver mail for local system accounts into their Maildir —
yesAlso relay recipients local delivery does not handle to a smarthost —
noServe an MTA-STS policy over HTTPS —
no(optional hardening, added later; see Next steps)Send and advertise SMTP TLS Reports (TLSRPT, RFC 8460) —
no
The wizard validates the result, writes the file, and asks whether to run
the full setup now: answer yes to fold Step 5 into this step, or no
to run pepsi-setup run yourself afterwards. Your answers are recorded in
a [pepsi-wizard] section, so re-running the wizard pre-fills them.
The file it writes builds the same inbound path as the hand-written one in
the other tab: ARC, then Maildir delivery, with the bounce, signing and
Internet stages behind it. It adds a few defaults that suit production
(DANE = strict, message lifetimes). It differs in one deliberate way.
The hand-written configuration sends [stage-local]’s NEXT_STAGE to
the bounce path, so everything that local delivery cannot consume is
bounced. The wizard instead points UNKNOWN_MAILBOX_STAGE at the bounce
path (for an unknown user of one of our own domains). For the recipients
that are not an error, such as an alias that expands to an address
elsewhere or a ~/.forward to another provider, it gives the stage an
unconditional SRS and relay tail (srs → dkim-sign-relay →
internet). It also delivers to any regular login account; add
TARGETS = alice to [stage-local] to restrict delivery to named
accounts.
The same interview without a terminal. pepsi-setup questions prints
it as JSON — every question’s identifier, shape, default and help text —
and pepsi-setup --wizard --answers answers.json answers it from a file
of those identifiers. It is the interactive interview with the prompts
supplied, not a second implementation, so the branches and the per-field
validation are the ones above. That is also the model that the browser
setup renders; see the “Setting up in a browser” section of Installation.
Write /etc/pepsi/pepsi.conf with the following:
[pepsi]
# Prefix of the DKIM selectors (pepsi-YYYYMM, pepsi-YYYYMM-ed25519).
DKIM_SELECTOR = pepsi
# Identity that signs the ARC seal recording the inbound verdict.
ARC_DOMAIN = example.org
# This minimal host does not serve an MTA-STS policy (that needs the
# HTTPS server), so do not advertise one. See "Next steps" to add it.
MTA_STS_MODE = none
[pepsi-postgres]
CONFIG = postgres:///pepsi
[pepsi-ingress]
HOSTNAME = mail.example.org
ACCEPTED_DOMAINS = example.org
# The MX listener on port 25. MODE = starttls with no TLS_CERT/TLS_KEY
# lets pepsi-setup fill in the certbot certificate paths (Step 5).
[pepsi-ingress-listener-mx]
SERVE = tcp
BIND_TO = 0.0.0.0
PORT = 25
MODE = starttls
# New messages enter here. ARC-seal the SPF/DKIM/DMARC verdict Pepsi
# computed at the boundary, then hand the message to local delivery.
[stage-init]
PROGRAM = pepsi-stage-arc
NEXT_STAGE = local
# Deliver to a local user's Maildir. By default any regular login account
# (the /etc/login.defs UID range) may receive mail, so 'alice' is already
# covered; set TARGETS to restrict delivery to an allow-list (e.g.
# TARGETS = alice). Anything not deliverable here is sent to the bounce
# path: an unknown recipient via NEXT_STAGE, a mailbox that fails to
# accept it via BOUNCE_STAGE.
[stage-local]
PROGRAM = pepsi-stage-relay-to-maildir
SERVER_NAME = mail.example.org
NEXT_STAGE = bounce
BOUNCE_STAGE = bounce
# --- Outbound bounce path: turn an undeliverable message into a DSN and
# mail it back to the original sender. Three short stages: build, sign,
# send.
# Rewrite the message in place into an (unsigned) RFC 3464 bounce
# addressed to the original sender, then hand it to the signer.
[stage-bounce]
PROGRAM = pepsi-stage-bounce
SERVER_NAME = mail.example.org
NEXT_STAGE = sign
# DKIM-sign the bounce so it authenticates at the sender's server.
[stage-sign]
PROGRAM = pepsi-stage-dkim-sign
NEXT_STAGE = internet
# Deliver the signed bounce directly to the sender's mail exchanger.
[stage-internet]
PROGRAM = pepsi-stage-relay-to-internet
SERVER_NAME = mail.example.org
# Read by pepsi-setup to build the SPF record authorising this host to
# send (the bounces above, and any outbound mail you add later).
# PUBLIC_IP is a per-STAGE option: pepsi-setup finds it by walking the
# [stage-*] sections and keeping the relays, never by a section named
# after the program -- with no relay stage setting it the record is a
# bare "v=spf1 -all", which makes our own mail fail SPF.
PUBLIC_IP = 203.0.113.7 2001:db8::25
A message for a recipient that is not a permitted local mailbox is turned
into a bounce and mailed back to the sender, rather than failing
silently. Mail for an unknown @example.org recipient follows
[stage-local]’s NEXT_STAGE to the bounce path. Mail for a known
mailbox that cannot be written (full disk, wrong permissions) is retried
and then bounced via BOUNCE_STAGE. Both point at the same [stage-bounce].
Note that NEXT_STAGE here goes to the bounce stage, not to
[stage-internet]. This host serves only local mailboxes, so every
recipient that it cannot deliver is an unknown user of our own domain.
Relaying such mail onward would look up example.org’s MX, find this
very host and send the mail straight back to us: a loop. On a real
forwarder, an alias may legitimately expand to an address elsewhere.
Turning this host into one is a separate step (Next steps); there
NEXT_STAGE
does reach a relay, and UNKNOWN_MAILBOX_STAGE keeps unknown local users
on the bounce path (see pepsi-stage-relay-to-maildir).
3.7. Step 5 — Provision the schema, keys and certificate¶
If you used the wizard in Step 4 and answered yes to “run setup now”, this is already done. You can re-run the command below at any time to capture the DNS records again, because it is idempotent. Otherwise, run the bootstrap tool once and capture the DNS records that it prints:
pepsi-setup -c /etc/pepsi/pepsi.conf run > pepsi-dns.zone
This validates the configuration and installs the pepsi schema. It
has the signing daemon pepsi-dkim generate the DKIM and ARC keys for
each domain, and it obtains the TLS certificate for mail.example.org via
certbot; for this, the A record from Step 1 must be live and inbound
port 80 must be reachable. Finally, it prints the remaining DNS records to
pepsi-dns.zone. It is idempotent and safe to re-run.
If you would rather manage the certificate yourself, pass --no-certbot and set
TLS_CERT/TLS_KEY in the listener section. The full provisioning workflow
is in pepsi-setup and Installation.
3.8. Step 6 — Publish the remaining records and verify¶
Open pepsi-dns.zone and publish the records it lists in your zone:
the DKIM public keys (
pepsi-YYYYMM._domainkey.example.organdpepsi-YYYYMM-ed25519._domainkey.example.orgTXT, named after the month in which the keys were made),the SPF policy listing this host’s sending addresses, and
a DMARC policy (
_dmarc.example.orgTXT).
(Only these are printed for the minimal host; an MTA-STS or TLS-reporting record appears here too once you enable those features — see Next steps.)
The suggested DMARC policy is v=DMARC1; p=reject; adkim=s. It asks
receivers to refuse mail that claims your domain but fails authentication, and
it accepts only a DKIM signature made by exactly your domain, never by one of
its subdomains. Pepsi signs all of its own mail that way, so that mail passes.
If another service also sends as your domain (a newsletter tool, a ticket
system), first make it sign with aligned DKIM or list it in SPF, and publish
p=none (monitoring only) until it does; drop adkim=s if it signs as a
subdomain. SPF alignment stays relaxed; add aspf=s once every service that
sends as your domain uses an envelope sender in exactly that domain. Add
rua=mailto:<address> so that the aggregate reports reach you. While the
policy stays at p=none, every subdomain stays at none too.
pepsi-setup then recommends sp=reject; np=reject, since a subdomain that
nobody sends mail as can refuse forgeries at once. It also suggests a wildcard
*.example.org. TXT "v=spf1 -all", commented out: first check that no other
TXT record is expected under the wildcard. Publish the records by hand, and
carefully. Receivers silently discard a DMARC record that does not parse, so a
domain whose policy is one missing ; away from valid looks protected but is
not. The check below is there to catch this.
Two more blocks appear once this host does end-to-end cryptography, and both are about letting correspondents find your users’ keys (Key management):
an
openpgpkey.example.orgA/AAAA record pointing at this host. The advanced method of the Web Key Directory needs it, and every current client tries that method first.pepsi-setupalso asks certbot to cover that name, so publish the record before the next certificate is issued. The direct method on the apex works without the record, so a missing record makes key lookup worse but does not break it;an
OPENPGPKEY(RFC 7929) orSMIMEA(RFC 8162) record per published identity. Publish these only if your zone is DNSSEC-signed. Without DNSSEC, whoever can answer queries for the zone can supply the key, which is no better than having no key at all. The Web Key Directory needs no DNSSEC, because HTTPS authenticates the domain itself.
Once DNS has propagated, check what is live against what Pepsi expects:
pepsi-setup -c /etc/pepsi/pepsi.conf check
This check only informs: it exits with 0 whatever it finds, unless you give it
--fail-on-findings. It flags a missing or mismatched DKIM or SPF record (and
MTA-STS, once enabled), so that you can fix the zone before you rely on it. It
also validates the DMARC record strictly and reports a record that receivers
would ignore as [INVALID], naming the offending tag. Of all the failures in
this list, this is the one that produces no bounce, no log line and no
complaint from anyone.
3.9. Step 7 — Start the services¶
Two long-lived processes run continuously, each under its own account:
pepsi-ingress serve— the inbound SMTP server, which drops to thepepsi-ingressuser, andpepsi-dispatch serve— the stage coordinator (exactly one per host), which runs aspepsiand starts every stage worker as that user.
Run each under your platform’s service/process manager so they start at boot and
restart on failure. The stage programs themselves are spawned by the dispatcher;
you never start them by hand. Binding port 25 needs privilege, so either start
pepsi-ingress as root or use socket activation. Started as root, it binds
its listeners and then drops to the pepsi-ingress account before it serves
a connection. Do not grant it a file capability instead: in the release layout,
pepsi-ingress is a symlink to the one multi-call binary, so the capability
would apply to every program folded into that binary. See Installation and
pepsi-ingress.
3.10. Step 8 — Send the first e-mail¶
From an account on another provider, send a message to alice@example.org (or
use a tool such as swaks --to alice@example.org --server mail.example.org).
Watch it move through the pipeline:
pepsi-status -c /etc/pepsi/pepsi.conf
A delivered message is removed from the queue, so a healthy run shows an empty backlog and an incremented delivery counter. Confirm the mail actually landed:
ls /home/alice/Maildir/new/
mutt -f /home/alice/Maildir # or: mail
If the file is there, you have received your first e-mail.
3.11. Step 9 — Open the console (optional)¶
Everything above is visible in a browser as well. Add an administrative listener bound to loopback:
[pepsi-httpd-listener-admin]
SERVE = tcp
BIND_TO = 127.0.0.1
PORT = 8443
MODE = plain
ADMIN = yes
You also need an account to sign in with. Over the local socket, a member of
the pepsi-admin group needs no account, but a browser cannot open a UNIX
socket, so create one and reach the listener through an SSH tunnel:
ssh -L 8443:127.0.0.1:8443 root@mail.example.org
Then open http://127.0.0.1:8443/ui. The dashboard shows the same queue that
pepsi-status printed, the configuration pages show where each value came
from, and the audit log records every change made from any surface. See
The administration console for the page reference and The administrative API for the API that the
console uses. The console does not start or stop services: to restart a
component, you still use systemctl.
3.12. Sending mail too: add a submission port¶
So far the host only receives. To let your own users send mail through it
from a mail client (Thunderbird, Evolution, KMail, or K-9 Mail on a phone), add
an authenticated
submission listener and an outbound delivery path. A client authenticates
with a username and password; pepsi-ingress then records the message with
state.local_origin = true, which both allows it to relay to any domain (not
only example.org) and lets the pipeline tell it apart from inbound mail.
Open inbound TCP ports 465 and/or 587 on the VPS firewall, the same way you opened port 25.
3.12.1. Route inbound and outbound apart¶
You already built an outbound delivery path for the bounces — [stage-sign] →
[stage-internet], with the SPF record covering this host. Authenticated
submissions reuse exactly that path; you only need to route them onto it.
Outbound mail must take a different path from inbound mail, and getting this
wrong causes a mail loop. If you simply pointed [stage-init] at
[stage-sign], inbound mail would be signed and relayed back out instead of
being delivered locally. Instead, branch on state.local_origin at the entry
point with a pepsi-stage-if stage: locally originated
(authenticated) mail goes to the outbound path, and everything else to the
inbound path. The split must come before pepsi-stage-arc. ARC preserves
an upstream sender’s authentication across your forwarding hop, so it is
meaningless for mail that your own users originate, and it must never touch
that mail. [stage-sign] authenticates it instead, and ARC-sealing it would
only publish the submission’s own SPF fail. So make the router the [stage-init] entry stage and move ARC
onto the inbound branch:
# Entry: split by direction FIRST. Authenticated submissions (local_origin =
# true) are outbound and reuse the signing path; everything else is inbound and
# goes through ARC. This only moves the stage; it never changes the message.
[stage-init]
PROGRAM = pepsi-stage-if
STATE_PATH = local_origin
VALUE = true
TRUE_STAGE = sign # outbound: our users' mail (reuses the bounce path)
FALSE_STAGE = arc # inbound: ARC-seal, then deliver locally
# ARC now sits on the inbound branch (received mail only), feeding local
# delivery just as [stage-init] used to.
[stage-arc]
PROGRAM = pepsi-stage-arc
NEXT_STAGE = local
[stage-sign], [stage-internet] and the PUBLIC_IP line are already in
your configuration from the bounce path, so submissions share them unchanged.
[stage-arc] is the former [stage-init] body (unchanged but renamed), and
[stage-local] is unchanged too — its NEXT_STAGE/BOUNCE_STAGE still
bounce mail to unknown local users rather than relaying it anywhere. (The ARC
stage also skips any state.local_origin message by itself, so a misplaced
ARC stage cannot seal a submission; keeping it off the outbound branch still
saves a wasted hop.)
Note
The outbound path needs outbound port 25 (see Prerequisites), which budget
providers often block. If yours is blocked, deliver through an upstream
smarthost instead: replace [stage-internet] with a
pepsi-stage-relay-to-smarthost stage and define the smarthost — see
pepsi-stage-relay-to-smarthost. To return non-delivery reports
when an MX refuses your users’ outgoing mail, give [stage-internet] a
BOUNCE_STAGE = bounce as well.
3.12.2. Provide a password backend (Dovecot)¶
A submission listener needs a way to check passwords. Pepsi keeps no password
database of its own; it verifies credentials through a Dovecot SASL socket.
Install Dovecot and configure it to authenticate your accounts (the system users
you created, or virtual users). Pepsi’s inbound server runs as the unprivileged
pepsi-ingress user, which cannot open Dovecot’s shared, root-only
auth-client socket, so give it a dedicated listener that it owns, in
/etc/dovecot/conf.d/10-pepsi.conf:
service auth {
unix_listener auth-client-pepsi {
mode = 0600
user = pepsi-ingress
}
}
You do not have to write this by hand: pepsi-setup run detects an unreachable
socket and offers to install exactly this drop-in (validating it with doveconf
and reloading Dovecot), or prints it if it cannot.
Dovecot is also what you would add to let clients read their Maildirs over IMAP (Next steps). Its full configuration is beyond this guide; see the Dovecot documentation.
3.12.3. Add the submission listeners¶
Add an implicit-TLS listener on 465 (recommended for clients) and/or a STARTTLS
listener on 587. SUBMISSION = yes makes authentication mandatory and applies
the RFC 6409 fixups (a missing Date:/Message-ID: is added);
SASL_TYPE/SASL_PATH wire in Dovecot. Authentication is only ever offered
over TLS. As with the MX listener, leaving TLS_CERT/TLS_KEY unset lets
pepsi-setup install the mail.example.org certificate automatically:
# Port 465: implicit TLS.
[pepsi-ingress-listener-submissions]
SERVE = tcp
BIND_TO = 0.0.0.0
PORT = 465
MODE = tls
SUBMISSION = yes
SASL_TYPE = dovecot
SASL_PATH = /run/dovecot/auth-client-pepsi
# Port 587: cleartext upgraded with STARTTLS.
[pepsi-ingress-listener-submission]
SERVE = tcp
BIND_TO = 0.0.0.0
PORT = 587
MODE = starttls
SUBMISSION = yes
SASL_TYPE = dovecot
SASL_PATH = /run/dovecot/auth-client-pepsi
Re-run the bootstrap so the new listeners’ certificates and the updated SPF record are picked up, then restart the services:
pepsi-setup -c /etc/pepsi/pepsi.conf run > pepsi-dns.zone
Publish the updated records (the SPF record now lists this host) and re-verify with
pepsi-setup -c /etc/pepsi/pepsi.conf check.
3.12.4. Connect a mail client¶
In the client’s account settings, configure the outgoing (SMTP) server:
Server / host:
mail.example.orgPort / security:
465with implicit TLS (SSL/TLS), or587with STARTTLSAuthentication: normal password
Username / password: the account Dovecot expects (e.g.
aliceoralice@example.org) and its password
If you also set up Dovecot for IMAP, point the incoming server at the same host (IMAP, port 993, TLS). Send a test message to an address at another provider and confirm that it left the queue:
pepsi-status -c /etc/pepsi/pepsi.conf
Then check that it arrived. Whether other servers accept your outgoing mail depends on the same DNS hygiene as receiving: correct reverse DNS (PTR), the SPF record listing this host, and DKIM signing, all configured above. A brand-new IP address is sometimes greylisted on first contact, so a short delay on the very first message is normal.
3.13. Troubleshooting¶
- Nothing arrives
Check that the
MXrecord resolves tomail.example.organd that theA/AAAArecord of that name points at the VPS. Confirm that inbound port 25 is open (test from another host) and that reverse DNS (PTR) is set. Watch the ingress log.- A message is stuck or
failed Inspect it with pepsi-status and pepsi-queue. A recipient that is not in
TARGETSor has no account is bounced back to the sender (watch[stage-bounce]and[stage-internet]), not left in the queue. Atimeoutor paused row often means a filesystem problem in the recipient’s home (e.g. a full disk); such a row is retried before it bounces. A bounce that itself sticks usually means outbound port 25 is blocked (see below).- The certificate step failed
certbotneedsmail.example.orgto already resolve to this VPS and inbound port 80 reachable. Fix DNS/port 80 and re-runpepsi-setup … run, or use--no-certbotand supplyTLS_CERT/TLS_KEYyourself.- “Permission denied” on delivery
The privilege bits from Step 3 are wrong: the helper must be
4750 root:pepsi-maildirand the relay-to-maildir stage2550pepsi:pepsi-maildir. Re-runmake installas root with the group and thepepsiaccount present, or set them by hand.- A client cannot authenticate or send
Authentication is offered only over TLS — use port 465 (implicit TLS) or 587 with STARTTLS and “normal password”. A
530reply means the session was unauthenticated. Check that thepepsi-ingressuser can read the Dovecot auth socket (SASL_PATH), and that Dovecot accepts the credentials.pepsi-ingressis the account that the SMTP server drops to, and the one that the drop-in above names.- Outgoing mail is stuck
Direct internet delivery needs outbound port 25; if the provider blocks it, switch
[stage-internet]to a smarthost (see the note above). Inspect stuck rows with pepsi-status and pepsi-queue.
3.14. Next steps¶
Read mail remotely. Add an IMAP server (e.g. Dovecot) pointed at the same
~/Maildirso mail clients can fetch it; Pepsi handles only delivery into the Maildir. If you already added Dovecot for submission authentication above, enabling IMAP is a small additional step.Turn this into a forwarder. Insert pepsi-stage-srs on the inbound path so mail re-sent to a third party passes SPF, re-using the outbound relay (
[stage-sign]→[stage-internet]) already in this configuration (Introduction).Customise the bounces. The bounce path is already wired in; you can localise or brand the DSN text with a
BOUNCE_MESSAGEtemplate — see pepsi-stage-bounce.Harden inbound TLS (MTA-STS + TLS reporting). Tell other senders to use validated TLS toward your MX by serving an MTA-STS policy, and collect TLS Reports (RFC 8460). Both need the HTTPS server (pepsi-httpd) running and a certificate for each
mta-sts.<domain>; the easiest way to add them is to re-runpepsi-setup --wizardand answer yes to the two transport-security questions (it pre-fills your earlier answers).Filter and protect. Add language blocking, sender whitelisting or the pay-to-send paywall — see Supported Features and the per-stage chapters.
Front an existing Exchange or Microsoft 365 deployment. Pepsi can sit in front of and behind Exchange as a transparent crypto gateway, so users get S/MIME and OpenPGP without any change to their mail programs. That is a different topology from the one above, and it has its own chapter, Microsoft Exchange as a gateway. Mail is routed to Exchange rather than delivered locally, which makes loop prevention mandatory rather than advisable.