Overview
This guide walks through setting up a complete, production-ready OpenBSD mail environment: a primary server running OpenSMTPD, Dovecot, Sieve, Rspamd, Redis, and DKIM, paired with a minimal, base-only OpenBSD backup MX server.
Replace example.com / example.net, <PRIMARY_IP>, and with your own domains and IP addresses throughout.
1. DNS Prerequisites
Before configuring the servers, create the required DNS records for your primary mail host (mx1.example.com), backup MX (mx2.example.com), and every hosted domain.
A Records
mx1 A
mail A
smtp A
mx2 A
PTR (Reverse DNS)
Configure with your ISP or hosting provider so it resolves back to mx1.example.com.
MX Records (for every hosted domain)
MX 0 mx1.example.com.
MX 10 mx2.example.com.
SPF & DMARC (for every hosted domain)
TXT "v=spf1 ip4: -all"
_dmarc TXT "v=DMARC1; p=none; rua=mailto:dmarc@example.com"
(You will add the DKIM TXT record for each domain in Step 4 after generating the key.)
2. Primary Server Preparation
Install Required Packages
pkg_add dovecot dovecot-pigeonhole rspamd \
opensmtpd-filter-rspamd opensmtpd-filter-dkimsign opensmtpd-table-passwd
Set the Mail Hostname (mailname)
Set /etc/mail/mailname so OpenSMTPD announces mx1.example.com in EHLO, matching your PTR record:
echo "mx1.example.com" > /etc/mail/mailname
Create the Virtual Mail User & Directories
useradd -m -s /sbin/nologin -d /home/vmail vmail # set /home/vmail to your chosen path
mkdir -p /etc/mail/dkim /etc/dovecot/sieve
chown _dkimsign:_dkimsign /etc/mail/dkim
chmod 700 /etc/mail/dkim
3. TLS Certificates (httpd & acme-client)
Issuing a single SAN certificate covering mail.example.com, smtp.example.com, and mx1.example.com avoids TLS/SNI mismatches across IMAP, SMTP submission, and inbound MX delivery.
Minimal /etc/httpd.conf for HTTP-01 Challenges
server "mail.example.com" {
listen on * port 80
alias "smtp.example.com"
alias "mx1.example.com"
location "/.well-known/acme-challenge/*" {
root "/acme"
request strip 2
}
location * {
block return 302 "https://$HTTP_HOST$REQUEST_URI"
}
}
Enable and start httpd:
httpd -n && rcctl enable httpd && rcctl start httpd
Configure /etc/acme-client.conf
authority letsencrypt {
api url "https://acme-v02.api.letsencrypt.org/directory"
account key "/etc/acme/letsencrypt-privkey.pem"
}
domain mail.example.com {
alternative names { smtp.example.com mx1.example.com }
domain key "/etc/ssl/private/mail.example.com.key"
domain full chain certificate "/etc/ssl/mail.example.com.fullchain.pem"
sign with letsencrypt
}
Pull the Initial Certificate
acme-client -v mail.example.com
Schedule Automated Renewals
Add a daily check to root’s crontab (crontab -e) so renewals automatically restart smtpd and reload dovecot:
~ 2 * * * acme-client mail.example.com && rcctl restart smtpd && rcctl reload dovecot
4. Generate DKIM Key & Publish DNS
Generate a 2048-bit RSA keypair for DKIM signing:
openssl genrsa -out /etc/mail/dkim/2026.key 2048
openssl rsa -in /etc/mail/dkim/2026.key -pubout -out /etc/mail/dkim/2026.pub
chown _dkimsign:_dkimsign /etc/mail/dkim/2026.key
chmod 600 /etc/mail/dkim/2026.key
Extract the single-line public key string:
awk '!/^---/' /etc/mail/dkim/2026.pub | tr -d '\n'; echo
Publish this TXT record in DNS for every hosted domain you send mail from:
2026._domainkey TXT "v=DKIM1; k=rsa; p="
5. Configure OpenSMTPD (/etc/mail/)
Create Lookup Tables
-
/etc/mail/domains— one hosted domain per line:example.com example.net -
/etc/mail/passwd— virtual user credentials. Generate password hashes withsmtpctl encrypt:user@example.com:$2b$10$...Set ownership and permissions so both
_smtpdand_dovecothave read-only access (whilerootcan still edit it):chown _smtpd:_dovecot /etc/mail/passwd chmod 440 /etc/mail/passwd -
/etc/mail/virtuals— map incoming addresses and aliases to virtual mailboxes:user@example.com user@example.com alias@example.com user@example.com user@example.net user@example.com
Configure /etc/mail/smtpd.conf
Repeat -d in filter dkimsign for every domain you send mail from:
pki mail.example.com cert "/etc/ssl/mail.example.com.fullchain.pem"
pki mail.example.com key "/etc/ssl/private/mail.example.com.key"
table aliases db:/etc/mail/aliases.db
table domains file:/etc/mail/domains
table passwd passwd:/etc/mail/passwd
table virtuals file:/etc/mail/virtuals
filter check_rdns phase connect match !rdns junk
filter check_fcrdns phase connect match !fcrdns junk
filter rspamd proc-exec "filter-rspamd"
filter dkimsign proc-exec "filter-dkimsign -d example.com -d example.net -s 2026 -k /etc/mail/dkim/2026.key" user _dkimsign group _dkimsign
smtp max-message-size 50M
listen on lo0
listen on egress port 25 tls pki mail.example.com \
filter { check_rdns, check_fcrdns, rspamd }
listen on egress port 465 smtps pki mail.example.com auth \
filter dkimsign
listen on egress port 587 tls-require pki mail.example.com auth \
filter dkimsign
action "local_mail" mbox alias
action "lmtp_deliver" lmtp "/var/dovecot/lmtp" rcpt-to virtual
action "outbound" relay
match from any for domain action "lmtp_deliver"
match from local for local action "local_mail"
match from auth for any action "outbound"
match from local for any action "outbound"
Validate the configuration:
smtpd -n
6. Configure Dovecot & Sieve (/etc/dovecot/)
Increase File Descriptor Limits
Create /etc/login.conf.d/dovecot so Dovecot does not hit OpenBSD’s default daemon open-file limits:
dovecot:\
:openfiles-cur=1024:\
:openfiles-max=2048:\
:tc=daemon:
Self-Contained /etc/dovecot/dovecot.conf
Back up the stock configuration to avoid conflicts with conf.d/* defaults:
mv /etc/dovecot/dovecot.conf /etc/dovecot/dovecot.conf.orig
Create a clean /etc/dovecot/dovecot.conf:
protocols = imap lmtp
ssl = required
ssl_cert =
Global Spam-to-Junk Sieve Rule
Create /etc/dovecot/sieve/spam-to-junk.sieve:
require ["fileinto"];
if header :contains "X-Spam" "Yes" {
fileinto "Junk";
stop;
}
Compile the Sieve script and validate Dovecot:
sievec /etc/dovecot/sieve/spam-to-junk.sieve
doveconf -n > /dev/null
7. Configure Rspamd & Redis (/etc/rspamd/local.d/)
Connect Rspamd to Redis
Create /etc/rspamd/local.d/redis.conf to enable Bayes learning, greylisting, and ratelimiting:
servers = "127.0.0.1";
Whitelist Backup MX from SPF Failures
Create /etc/rspamd/local.d/settings.conf so queued mail forwarded from mx2 is not penalized for SPF mismatches:
backup_mx {
ip = [""];
apply {
symbols_disabled = ["R_SPF_FAIL", "R_SPF_SOFTFAIL"];
}
}
Validate the Rspamd configuration:
rspamadm configtest
8. Firewall & Services (Primary Server)
-
Allow inbound TCP ports
25,80(ACME),465,587, and993in/etc/pf.conf:pass in on egress proto tcp to port { 25, 80, 465, 587, 993 }Validate and reload PF:
pfctl -nf /etc/pf.conf && pfctl -f /etc/pf.conf -
Enable and start the mail stack (start
redisbeforerspamd):rcctl enable redis rspamd dovecot smtpd rcctl start redis rspamd dovecot rcctl restart smtpd
9. Backup MX Server Setup (mx2)
The backup MX requires no third-party packages, Dovecot, Rspamd, or TLS certificates—only OpenBSD’s base smtpd.
-
Set
/etc/mail/mailnameto your backup MX hostname:echo "mx2.example.com" > /etc/mail/mailname -
Generate a random queue encryption key:
openssl rand -hex 16 -
Replace
/etc/mail/smtpd.confwith the minimal backup configuration:queue compression queue encryptionqueue ttl 7d table aliases db:/etc/mail/aliases.db table hosted_domains { example.com, example.net } smtp max-message-size 50M listen on lo0 listen on egress action "local" mbox alias action "outbound" relay action "backup_mx" relay backup mx mx2.example.com match from any for domain action "backup_mx" match from local for local action "local" match from local for any action "outbound" -
Allow inbound TCP port
25in/etc/pf.conf, then validate, enable, and restartsmtpd:pfctl -nf /etc/pf.conf && pfctl -f /etc/pf.conf smtpd -n && rcctl enable smtpd && rcctl restart smtpd
10. Mail Client Configuration
Use the following settings in your mail client:
| Setting | Value |
|---|---|
| Username | Full email address (user@example.com) |
| IMAP Server | mail.example.com, Port 993 (SSL/TLS) |
| SMTP Server | smtp.example.com, Port 465 (SMTPS) or 587 (STARTTLS) |
NeoMutt Snippet (neomuttrc)
Define folder before spoolfile, trash, record, and postponed so the + shortcut expands correctly:
set folder = "imaps://mail.example.com"
set spoolfile = "+INBOX"
set trash = "+Trash"
set record = "+Sent"
set postponed = "+Drafts"
11. Post-Migration Verification Checklist
- Send a test email from an external provider (e.g., Gmail) to verify inbound delivery,
X-Spamheaders, and Sieve routing. - Send a test email outbound to verify SPF, DKIM, and DMARC alignment (check raw headers on the receiving side).
- Temporarily stop
smtpdon the primary server (rcctl stop smtpd), send an external test email to confirmmx2queues it (smtpctl show queue), then restartsmtpdon the primary to verify delivery and confirm Rspamd didn’t flag SPF. - Test certificate renewal dry-run and verify
/etc/ssl/mail.example.com.fullchain.pemincludes all three SANs (openssl x509 -in /etc/ssl/mail.example.com.fullchain.pem -noout -text | grep DNS:).