Setting up mail in OpenBSD

The ability to send mail from the terminal is expected of anyone who participates in the OpenBSD community. After a fresh install, the first message waiting in your mailbox explains how to configure mail and ends with this request:

If you wish to ensure that OpenBSD runs better on your machines, please do us a favor (after you have your mail system configured!) and type something like:

# (dmesg; sysctl hw.sensors) | \
   mail -s "Your System Description" dmesg@openbsd.org

so that we can see what kinds of configurations people are running.

The man pages for smtpd(8) and mail(1) cover everything required. This post is a condensed version. It configures outgoing mail only, which is enough to send dmesg(8) output, terminal logs for bug reports, and patches built with git format-patch.

Add your SMTP credentials#

Obtain SMTP credentials from your email provider, then become root with su and create /etc/mail/secrets with one line:

identifier my@email.com:MySecretKey

identifier is an arbitrary label that smtpd.conf uses to look up the entry. Replace my@email.com with your account address and MySecretKey with your SMTP password or app key.

Restrict the secrets file#

The file contains a credential, so restrict it to root and the _smtpd group:

chown root:_smtpd /etc/mail/secrets
chmod 640 /etc/mail/secrets

Configure smtpd#

Edit /etc/mail/smtpd.conf so that it resembles the following:

table aliases file:/etc/mail/aliases
table secrets file:/etc/mail/secrets

listen on socket
listen on lo0

action "local_mail" mbox alias <aliases>
action "relay" relay host smtp+tls://identifier@smtp.email.com:587 auth <secrets>

match from local for local action "local_mail"
match from local for any action "relay"

Two changes matter. The table secrets line at the top loads the credentials file, and the relay action replaces the default outbound rule with your provider's SMTP server. The user portion of the relay URL must match the identifier in /etc/mail/secrets. For a secrets entry of iambob bob@gmail.com:12345, the relay host becomes smtp+tls://iambob@smtp.gmail.com:587.

Port 587 is the standard submission port and most providers use it, but confirm with your provider's documentation.

Validate the configuration and restart#

Check the configuration for errors, then restart the daemon:

# Check the config for errors
smtpd -n

# Restart smtpd
rcctl restart smtpd

Set the From header#

Press Ctrl+D to return to your regular user account and add the following line to ~/.mailrc:

set from="my@email.com"

Without it, mail(1) sets the sender to username@hostname, which the relay rejects during SMTP authentication.

Test#

Send yourself a message:

echo foo | mail -s bar my@email.com

Then send your system information to the OpenBSD developers. Use the subject line to describe your hardware. This is the command I ran for my latest workstation build:

(dmesg; sysctl hw.sensors) | mail -s "Gigabyte B650M K, Ryzen 7 7700X, RX 6750XT. Had to disable Re-Size BAR Support for amdgpu to init" dmesg@openbsd.org

If a message fails to send, check /var/log/maillog. It records each step of delivery, including authentication failures and relay errors.