OpenSMTPD Mail Server

Synopsis #

OpenSMTPD is the default mail transfer agent (MTA) in OpenBSD. Its smtpd(8) daemon handles local delivery, outgoing relays, authenticated submission, and mail for virtual domains. The examples below configure these roles, TLS, and separately packaged mail filters.

Features #

• Secure by default, with privilege separation and sane defaults
• Local delivery to system users
• Relay via authenticated submission or smarthost
• Full IPv6 and TLS support
• Filtering and address rewriting
• Virtual user/domain support
• Integration with filter-* plugins and extras packages

Enabling smtpd #

To enable and start the smtpd service at boot:

doas rcctl enable smtpd
doas rcctl start smtpd

The daemon will read its configuration from /etc/mail/smtpd.conf.

Basic Configuration #

A minimal smtpd.conf(5) file enabling local delivery and outgoing mail might look like this:

listen on lo0

action "local" mbox
action "outbound" relay

match from local for local action "local"
match from local for any action "outbound"

This configuration:

• Listens only on the loopback interface
• Defines one action for local mailbox delivery and one action for outbound relay
• Allows local users to send mail to other local users
• Relays outbound mail from local users to other systems using DNS

To apply changes:

doas smtpd -n && doas rcctl restart smtpd

Accepting Mail from the Internet #

To receive mail from the outside world:

pki example.org cert "/etc/mail/certs/example.org.crt"
pki example.org key "/etc/mail/certs/example.org.key"

listen on egress tls pki example.org

action "inbound" maildir
match from any for domain example.org action "inbound"

This example:

• Defines the certificate and key used by the listener
• Listens on the external interface with TLS enabled
• Accepts mail from the internet for the domain example.org
• Delivers it to ~/Maildir in the recipient’s home directory

To use TLS, a valid certificate must be placed under /etc/mail/certs/:

doas mkdir -p /etc/mail/certs
doas cp fullchain.pem /etc/mail/certs/example.org.crt
doas cp privkey.pem /etc/mail/certs/example.org.key

Ensure permissions are correct:

doas sh -c 'chown root:_smtpd /etc/mail/certs/*'
doas sh -c 'chmod 640 /etc/mail/certs/*'

Then define the certificate using the pki block in smtpd.conf:

pki example.org cert "/etc/mail/certs/example.org.crt"
pki example.org key "/etc/mail/certs/example.org.key"

Outgoing Mail via Smarthost #

To relay all outgoing mail through a remote mail server (e.g., ISP or upstream relay):

table secrets file:/etc/mail/secrets
action "relay" relay host smtp+tls://upstream@smtp.example.net:587 auth <secrets>
match from local for any action "relay"

Define the authentication secret in /etc/mail/secrets:

upstream username:replace-with-provider-password

Secure the file:

doas chmod 600 /etc/mail/secrets
doas chown root:_smtpd /etc/mail/secrets

Virtual Domains and Users #

To receive mail for domains not mapped to system users, use virtual aliases:

Define Table for Virtual Mappings #

Create /etc/mail/virtuals:

info@example.org      alice
admin@example.org     bob
contact@example.org   contactuser

Use this text file directly as a file: table. The destinations must be existing local accounts.

Update smtpd.conf #

table aliases file:/etc/mail/virtuals

action "virtuals" mbox virtual <aliases>
match from any for domain example.org action "virtuals"

Filtering Mail #

Use filter blocks to reject selected senders or attach an external mail filter.

Greylisting #

Greylisting temporarily rejects messages and accepts later retries. Configure an external filter that tracks these retries, following its package documentation, then attach it to the listener.

Blocking Specific Senders or Addresses #

Create a table:

table badsenders file:/etc/mail/badsenders.txt

With contents:

spammer@example.com
junk@example.net

Then:

filter "blocklist" phase mail-from match mail-from <badsenders> reject "550 Sender blocked"
listen on egress filter "blocklist"

External Filters #

Install the individual integration required by the deployment. For Rspamd:

doas pkg_add opensmtpd-filter-rspamd

Follow its installed package README and the Rspamd chapter . Filter declarations must precede the listener that uses them. Merge listener options such as TLS and filtering into one listener definition; the fragments above are alternatives, not a complete combined mail-server configuration.

Local Delivery Options #

OpenSMTPD can deliver to either mbox (traditional mailbox format) or maildir (per-message file format). Set the method in an action and select it from a match rule:

action "inbound" maildir
match from any for domain example.org action "inbound"

The default Maildir is ~/Maildir; mbox delivery uses /var/mail/user. Verify recipient accounts, directory permissions, and actual delivery before accepting external mail.

Administrative Commands #

Use smtpctl(8) to manage the mail system:

doas smtpctl show stats

Show statistics for messages processed, sessions handled, and more.

doas smtpctl show queue

List the mail queue.

doas smtpctl schedule all

Immediately attempt to send all queued messages.

doas smtpctl remove <msg-id>

Remove a specific message from the queue.

doas smtpctl log verbose

Enable verbose logging for debugging.

Logging and Troubleshooting #

Logs are written to /var/log/maillog. Tail the log for real-time updates:

doas tail -f /var/log/maillog

For additional diagnostics:

doas rcctl stop smtpd
doas smtpd -dv

Runs smtpd in the foreground with verbose debugging after stopping the regular service. When finished, exit the debug process and use doas rcctl start smtpd.

Summary of Key Configuration Files #

All changes to smtpd.conf or related tables require validation and a restart:

doas smtpd -n && doas rcctl restart smtpd