commit 223782286d53663ffda4769cf900a212aae38f7ca07bb96290d4c58e2e01f393 from: Tracey Emery date: Fri Nov 20 17:32:09 2026 UTC initial import commit - /dev/null commit + 223782286d53663ffda4769cf900a212aae38f7ca07bb96290d4c58e2e01f393 blob - /dev/null blob + 05c00e099d2e86252215fa3527f99f0669b04eae14cfc13ad1d1cb1d44272fb5 (mode 644) --- /dev/null +++ README.md @@ -0,0 +1,429 @@ +# OpenBSD Mail Server Setup & Migration Guide + +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`, ``, 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 +```dns +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) +```dns + MX 0 mx1.example.com. + MX 10 mx2.example.com. +``` + +### SPF & DMARC (for every hosted domain) +```dns + 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 +```sh +pkg_add dovecot dovecot-pigeonhole rspamd redis \ + 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: +```sh +echo "mx1.example.com" > /etc/mail/mailname +``` + +### Create the Virtual Mail User & Directories +```sh +useradd -m -s /sbin/nologin -d /home/vmail vmail +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 +```conf +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`: +```sh +httpd -n && rcctl enable httpd && rcctl start httpd +``` + +### Configure `/etc/acme-client.conf` +```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 +```sh +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`: +```cron +~ 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: +```sh +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: +```sh +awk '!/^---/' /etc/mail/dkim/2026.pub | tr -d '\n'; echo +``` + +Publish this TXT record in DNS for **every** hosted domain you send mail from: +```dns +2026._domainkey TXT "v=DKIM1; k=rsa; p=" +``` + +--- + +## 5. Configure OpenSMTPD (`/etc/mail/`) + +### Create Lookup Tables + +1. **`/etc/mail/domains`** — one hosted domain per line: + ```text + example.com + example.net + ``` + +2. **`/etc/mail/passwd`** — virtual user credentials. Generate password hashes with `smtpctl encrypt`: + ```text + user@example.com:$2b$10$... + ``` + Set ownership and permissions so both `_smtpd` and `_dovecot` have read-only access (while `root` can still edit it): + ```sh + chown _smtpd:_dovecot /etc/mail/passwd + chmod 440 /etc/mail/passwd + ``` + +3. **`/etc/mail/virtuals`** — map incoming addresses and aliases to virtual mailboxes: + ```text + 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: +```conf +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: +```sh +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: +```conf +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: +```sh +mv /etc/dovecot/dovecot.conf /etc/dovecot/dovecot.conf.orig +``` + +Create a clean `/etc/dovecot/dovecot.conf`: +```conf +protocols = imap lmtp + +ssl = required +ssl_cert = /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: +```conf +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: +```conf +backup_mx { + ip = [""]; + apply { + symbols_disabled = ["R_SPF_FAIL", "R_SPF_SOFTFAIL"]; + } +} +``` + +Validate the Rspamd configuration: +```sh +rspamadm configtest +``` + +--- + +## 8. Firewall & Services (Primary Server) + +1. Allow inbound TCP ports `25`, `80` (ACME), `465`, `587`, and `993` in `/etc/pf.conf`: + ```conf + pass in on egress proto tcp to port { 25, 80, 465, 587, 993 } + ``` + Validate and reload PF: + ```sh + pfctl -nf /etc/pf.conf && pfctl -f /etc/pf.conf + ``` + +2. Enable and start the mail stack (start `redis` before `rspamd`): + ```sh + 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`. + +1. Set `/etc/mail/mailname` to your backup MX hostname: + ```sh + echo "mx2.example.com" > /etc/mail/mailname + ``` + +2. Generate a random queue encryption key: + ```sh + openssl rand -hex 16 + ``` + +3. Replace `/etc/mail/smtpd.conf` with the minimal backup configuration: + ```conf + queue compression + queue encryption + queue 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" + ``` + +4. Allow inbound TCP port `25` in `/etc/pf.conf`, then validate, enable, and restart `smtpd`: + ```sh + 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: +```muttrc +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-Spam` headers, and Sieve routing. +- [ ] Send a test email outbound to verify SPF, DKIM, and DMARC alignment (check raw headers on the receiving side). +- [ ] Temporarily stop `smtpd` on the primary server (`rcctl stop smtpd`), send an external test email to confirm `mx2` queues it (`smtpctl show queue`), then restart `smtpd` on 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.pem` includes all three SANs (`openssl x509 -in /etc/ssl/mail.example.com.fullchain.pem -noout -text | grep DNS:`).