OpenBSD Web and Email Server

Secure Web Server #

In order to secure the data transmitted between the webserver and the client, we need SSL. There are multiple types of SSL certificates and they mostly differ in the way the identity of the requester is verified. For example, banks will usually choose the strictest verification method as it will show prominently in the browsers searchbar or omnibox. Since these verification methods take time and effort, they are more costly the more work has to be put in.

The most basic form of authentication is the so-called domain-level verification: if you control the domain, you’re allowed to receive an SSL certificate. Let’s Encrypt is a project that allows domain owners to receive such a domain-level verified certificate for free and we’ll use their service in this tutorial.

You are expected to have root privileges for all commands below.

ACME Configuration #

First we need to edit the /etc/acme-client.conf file that is already present on the system:

Comment in the section that was commented out
Change example.com to the domain name you want to secure
Add any alternative names like www.example.com

authority letsencrypt { api url “ https://acme-v02.api.letsencrypt.org/directory" account key “/etc/acme/letsencrypt-privkey.pem” }

authority letsencrypt-staging { api url “ https://acme-staging-v02.api.letsencrypt.org/directory" account key “/etc/acme/letsencrypt-staging-privkey.pem” }

domain example.org { alternative names { www.example.org mail.example.org } domain key “/etc/ssl/private/example.org.key” domain certificate “/etc/ssl/example.org.crt” domain full chain certificate “/etc/ssl/example.org.fullchain.pem” #Test with the staging server to avoid aggressive rate-limiting. #sign with letsencrypt-staging sign with letsencrypt }

Create the necessary directories

mkdir -p -m 700 /etc/acme
mkdir -p -m 700 /etc/ssl/acme/private
mkdir -p -m 755 /var/www/acme

Let’s Encrypt will make a verification request so we need to update /etc/httpd.conf to be able to handle these requests:

In OpenBSD 6.4 the syntax for stripping changed.

For OpenBSD version 6.4 and later

server "www.example.com" {
  listen on * port 80
  root "/htdocs/www.example.com"
  location "/.well-known/acme-challenge/*" {
    root "/acme"
    request strip 2
  }
}

server "example.com" {
  listen on * port 80
  block return 301 "http://www.example.com$REQUEST_URI"
}

Next, we need to check the configuration and reload or restart the daemon

httpd -n && rcctl restart httpd

We now can run the acme-client to create a new account and a key

acme-client -v example.com

The final lines of the output should be something like:

acme-client: /etc/ssl/example.com.crt: created
acme-client: /etc/ssl/example.com.pem: created

The certificates are valid for 90 days to we need to setup a cronjob to renew. We will run it daily but only once the end of the validity comes in sight, will the certificates actually be renewed.

crontab -e

insert a line like:

05 3 * * * acme-client example.com && rcctl reload httpd

httpd configuration #

We now have everything we need to correctly configure httpd to run SSL. Change the httpd.conf file to look like this.

For OpenBSD version 6.4 and later

server "example.org" {
  listen on * tls port 443
  root "/htdocs/example.org"
  tls {
    certificate "/etc/ssl/example.org.fullchain.pem"
    key "/etc/ssl/private/example.org.key"
  }
  location "/.well-known/acme-challenge/*" {
    root "/acme"
    request strip 2
  }
}

server "www.example.org" {
  listen on * tls port 443
  tls {
    certificate "/etc/ssl/example.org.fullchain.pem"
    key "/etc/ssl/private/example.org.key"
  }
  block return 301 "https://example.org$REQUEST_URI"
}

server "example.org" {
  listen on * port 80
  block return 301 "https://example.org$REQUEST_URI"
}

server "www.example.org" {
  listen on * port 80
  block return 301 "https://example.org$REQUEST_URI"
}

types {
  include "/usr/share/misc/mime.types"   
}

Restart httpd:

httpd -n && rcctl restart httpd

SSL verification #

A quick test can be done directly in-browser or www.sslcheck.nl.
A more extensive check can be done via ssllabs.com

Additional domains #

First, we need to move the existing certificate out of the way. Skipping this step will result in an error.

mv /etc/ssl/example.com.crt /etc/ssl/example.com.crt.bak

Edit /etc/acme-client.conf and add more alternative names

alternative names { www.example.com example1.com www.example1.com }

Update httpd.conf accordingly:

server "www.example1.com" {
  listen on * tls port 443
  root "/htdocs/www.example1.com"
  tls {
    certificate "/etc/ssl/example.com.pem"
    key "/etc/ssl/private/example.com.key"
  }
  location "/.well-known/acme-challenge/*" {
    root { "/acme", strip 2 }
  }
}

Run the acme client again

acme-client -Fv example.com

And restart httpd

httpd -n && rcctl restart httpd

Email Server #

This tutorial demonstrates a full-featured email server running on OpenBSD using OpenSMTPD, Dovecot, and Rspamd. OpenSMTPD is the default mail server for OpenBSD.

Slighty modified version of original vultr documentation. https://docs.vultr.com/an-openbsd-e-mail-server-using-opensmtpd-dovecot-rspamd-and-rainloop

Set up secure web server first to get ssl keys. https://www.openbsdhandbook.com/services/webserver/ssl/

Preliminary Steps #

Verify the server’s outbound port status.

Set up your user account to perform tasks as root.

su -
usermod -G wheel <username>
echo "permit nopass keepenv :wheel" > /etc/doas.conf
exit

Set up the package repository for OpenBSD.

doas su
echo "https://cdn.openbsd.org/pub/OpenBSD" > /etc/installurl
exit

Add the required packages.

doas pkg_add opensmtpd-extras opensmtpd-filter-rspamd dovecot dovecot-pigeonhole rspamd redis

Configure OpenSMTPD #

By default, OpenSMTPD only listens on localhost. It must be explicitly configured to listen on external interfaces. It should be configured to use virtual users instead of system users for security.

Backup the default smtpd.conf file and create a new one from scratch.

cd /etc/mail
mv smtpd.conf smtpd.conf.default

Create a new smtpd.conf as shown below. Replace example.com with your domain. This initial configuration does not activate the rspamd filter while testing OpenSMTP. The spam filter will be activated later. (This example assumes existing certs. Modify as needed).

pki "mail" cert "/etc/ssl/example.com.fullchain.pem"
pki "mail" key "/etc/ssl/private/example.com.key"

table aliases file:/etc/mail/aliases
table credentials passwd:/etc/mail/credentials
table virtuals file:/etc/mail/virtuals

#filter "rspamd" proc-exec "/usr/local/libexec/smtpd/filter-rspamd"

listen on all tls pki "mail" hostname "mail.example.com"
listen on egress port port 465 smpts pki "mail" hostname "mail.example.com" auth <credentials>

action "local_mail" mbox alias <aliases>
action "domain_mail" maildir "/var/vmail/example.com/%{dest.user:lowercase}" virtual <virtuals>
action "outbound" relay

match from any for domain "example.com" action "domain_mail"
match from local for local action "local_mail"

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

Create the Credentials File #

OpenSMTPD and Dovecot can share an authentication database. This database resembles the system password file in format, with two extra fields for Dovecot. The two special fields define the virtual home directory and the mail location. Passwords are in blowfish format. This tutorial creates three example users.

Generate the passwords and concatenate them to the /etc/mail/credentials file.

doas su
smtpctl encrypt example_password1 >> /etc/mail/credentials
smtpctl encrypt example_password2 >> /etc/mail/credentials
smtpctl encrypt example_password3 >> /etc/mail/credentials
exit

The output looks similar to this:

$2b$10$_EXAMPLE_PASSWORD1_3JbO4Ns2jJNZQfTS45MAnKi.IPrkKITyTa6
$2b$10$_EXAMPLE_PASSWORD2_YKD.K0kQ2oylOmQ9SBUb0hIopBsmNxYPb4e
$2b$10$_EXAMPLE_PASSWORD3_IvRu4xbeOqOJJXlgEAKuS5sIrBvfdPvEzeq

Edit /etc/mail/credentials to add the required fields. Each line maps to a system account, vmail, with UID and GID of 2000. Replace example.com with your domain. Replace the example passwords with the passwords you generated in the previous step. The virtual user name is the complete email address.

john@example.com:$2b$10$_EXAMPLE_PASSWORD1_C3JbO4Ns2jJNZQfTS45MAnKi.IPrkKITyTa6:vmail:2000:2000:/var/vmail/example.com/john::userdb_mail=maildir:/var/vmail/example.com/john
adam@example.com:$2b$10$_EXAMPLE_PASSWORD2_YKD.K0kQ2oylOmQ9SBUb0hIopBsmNxYPb4e:vmail:2000:2000:/var/vmail/example.com/adam::userdb_mail=maildir:/var/vmail/example.com/adam
natalie@example.com:$2b$10$_EXAMPLE_PASSWORD3_IvRu4xbeOqOJJXlgEAKuS5sIrBvfdPvEzeq:vmail:2000:2000:/var/vmail/example.com/natalie::userdb_mail=maildir:/var/vmail/example.com/natalie

Create Virtual Mail Account and Set Security #

Set /etc/mail/credentials permissions to read-only for _smtpd and _dovecot system users.
Create the vmail system user, group, and home directory.
When you create the vmail system user, you will receive the following warning: useradd: Warning: home directory '/var/vmail' doesn't exist, and -m was not specified. This is expected. This avoids cluttering the directory with dot files from /etc/skel. They are not required because the vmail account does not allow login.
```
  doas chmod 0440 /etc/mail/credentials
  doas chown _smtpd:_dovecot /etc/mail/credentials
  doas useradd -c "Virtual Mail Account" -d /var/vmail -s /sbin/nologin -u 2000 -g =uid -L staff vmail
  doas mkdir /var/vmail
  doas chown vmail:vmail /var/vmail
```

Create the Virtual User Mapping #

Create /etc/mail/virtuals to define the valid email addresses.

The first four lines assign john@example.com aliases for abuse, hostmaster, postmaster, and webmaster.
The last three lines map the email addresses to the vmail account. OpenSMTPD will deliver the messages to /var/vmail/example.com/<user>.

Mail delivery attempted for addresses not defined in this file will be bounced with a Delivery Status Notification.

  abuse@example.com: john@example.com
  hostmaster@example.com: john@example.com
  postmaster@example.com: john@example.com
  webmaster@example.com: john@example.com
  john@example.com: vmail
  adam@example.com: vmail
  natalie@example.com: vmail

Create Public/Private Keys for OpenSMTPD #

This example uses a self-signed certificate. Use a valid signed certificate if you have one. When prompted for the common name, be sure it matches the FQDN of the server. This example uses mail.example.com. If using existing certificates, skip this step.

doas su
cd /etc/ssl
openssl genrsa -out private/mail.key 4096
openssl req -x509 -new -nodes -key private/mail.key -out mail.crt -days 3650 -sha256
chmod 0400 /etc/ssl/private/mail.key
exit

Test the Server #

Use the OpenSMTPD configuration syntax checker. If no problems are found, restart the smtpd daemon.

doas smtpd -n
doas rcctl restart smtpd

From an outside mail account, send a test email to one of the users.

OpenSMTPD will create the maildir folder structure below /var/vmail and deliver the mail to /var/vmail/example.com/<username>/new.
As the root user, browse to this location and verifiy you have a file named similar to this: 1576339842.4d64757b.example.com:2,.

Review the contents of the file, including all of the mail headers, to verify the email delivery works properly.

  Return-Path: <n0244e80da3-54b1ed125c5342fc-adam===example.org@bounce.example.org>
  Delivered-To: adam@example.com
  Received: from spruce-goose-ba.twitter.com (spruce-goose-ba.twitter.com [199.59.150.96])
      by mail.example.com (OpenSMTPD) with ESMTPS id 75b514d3 (TLSv1.2:ECDHE-RSA-AES256-GCM-    SHA384:256:NO)
      for <adam@example.com>;
      Sat, 14 Dec 2019 11:10:40 -0500 (EST)
  DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=twitter.com;
      s=dkim-201406; t=1576339839;
      bh=jhKB5/w9v87GaXSuizT576ntJ/72gvLRDhsqmGQQrCE=;
      h=Date:From:To:Subject:MIME-Version:Content-Type:List-Unsubscribe:
      Message-ID;
      b=TWn/QVUJ1VDlWiweWoanwHLABCL1nqmm0+TBzh3PjmYNm0quRMXB7QL2ykzHGME5A
      DTz/JFHa0cOvQsrdhxxbjOLFKimK0nF+Ou5kI+2HzTzfVNZS0qGnTVP/tZyaIsWjjl
      an5EiR6HFOHG4iClOOEOJW4oLDEZfPTefrlW+378bmHGIRUNDvVKrbXKunL9fJFAb3
      JSrhWQNwbrF/aARFzw4nKfb1I7vTRSrN1eXE5JxzGwI2XAjqDIWdR5ExwUNbJH5ZPs
      wQ85j8KLZEEgQkbH9CypgeUMJWsVK95FqOCCaqKMS10M7intGMb3aeiiFcB7yDHi9t
      u7rVESm4eGp/g==
  X-MSFBL: DM7pSZns+YDRgNEmGNre9aPjZTtc1tDlN97w5rQDBts=|eyJ1IjoibWF0dEBnb2J
      sYWNrY2F0LmNvbUBpaWQjIzU0YjFlZDEyNWM1MzQyZmNiNThiMzVmNzI0NDZlMGF
      mQHVzYiMjNkAyNDRAMTA4MjgwNTAxMDYzNzk1MDk3NkAwQDA4MjY5ZWI4OTI3YzR
      kNTFiNTZkMjY3YzY2OGRmN2IwY2Y4M2ExZGIiLCJyIjoibWF0dEBnb2JsYWNrY2F
      0LmNvbSIsImciOiJCdWxrIiwiYiI6InNtZjEtYmd4LTM0LXNyMS1CdWxrLjE4NiJ
      9
  Date: Sat, 14 Dec 2019 16:10:39 +0000
  ...

Configure Dovecot IMAP #

Dovecot requires the ability to have a larger number of files open for reading and writing than the default class allows. Failing to do this will cause errors that are difficult to troubleshoot.

Define a login class for the Dovecot daemon. At the bottom of /etc/login.conf add the following lines.

dovecot:\
    :openfiles-cur=1024:\
    :openfiles-max=2048:\
    :tc=daemon:

Create the Dovecot Configuration File #

Create /etc/dovecot/local.conf.

auth_mechanisms = plain
first_valid_uid = 2000
first_valid_gid = 2000
mail_location = maildir:/var/vmail/%d/%n
mail_plugin_dir = /usr/local/lib/dovecot
managesieve_notify_capability = mailto
managesieve_sieve_capability = fileinto reject envelope encoded-character vacation subaddress comparator-i;ascii-numeric relational regex  imap4flags copy include variables body enotify environment mailbox date index ihave duplicate mime foreverypart extracttext imapsieve vnd.dovecot.imapsieve
mbox_write_locks = fcntl
mmap_disable = yes
namespace inbox {
  inbox = yes
  location =
  mailbox Archive {
  auto = subscribe
  special_use = \Archive
  }
  mailbox Drafts {
  auto = subscribe
  special_use = \Drafts
  }
  mailbox Junk {
  auto = subscribe
  special_use = \Junk
  }
  mailbox Sent {
  auto = subscribe
  special_use = \Sent
  }
  mailbox Trash {
  auto = subscribe
  special_use = \Trash
  }
  prefix =
}
passdb {
  args = scheme=CRYPT username_format=%u /etc/mail/credentials
  driver = passwd-file
  name =
}
plugin {
  imapsieve_mailbox1_before = file:/usr/local/lib/dovecot/sieve/report-spam.sieve
  imapsieve_mailbox1_causes = COPY
  imapsieve_mailbox1_name = Junk
  imapsieve_mailbox2_before = file:/usr/local/lib/dovecot/sieve/report-ham.sieve
  imapsieve_mailbox2_causes = COPY
  imapsieve_mailbox2_from = Junk
  imapsieve_mailbox2_name = *
  sieve = file:~/sieve;active=~/.dovecot.sieve
  sieve_global_extensions = +vnd.dovecot.pipe +vnd.dovecot.environment
  sieve_pipe_bin_dir = /usr/local/lib/dovecot/sieve
  sieve_plugins = sieve_imapsieve sieve_extprograms
}
protocols = imap sieve
service imap-login {
  inet_listener imap {
  port = 0
  }
}
service managesieve-login {
  inet_listener sieve {
  port = 4190
  }
  inet_listener sieve_deprecated {
  port = 2000
  }
}
ssl_cert = </etc/ssl/mail.crt
ssl_key = </etc/ssl/private/mail.key
userdb {
  args = username_format=%u /etc/mail/credentials
  driver = passwd-file
  name =
}
protocol imap {
  mail_plugins = " imap_sieve"
}

Dovecot Bug Fix #

There is a bug in Dovecot where the ssl_cert and ssl_key settings do not get overridden in the local.conf file so we have to comment them out. If you miss this step, Dovecot will fail to start correctly.

Edit /etc/dovecot/conf.d/10-ssl.conf as shown.

...
# PEM encoded X.509 SSL/TLS certificate and private key. They're opened before
# dropping root privileges, so keep the key file unreadable by anyone but
# root. Included doc/mkcert.sh can be used to easily generate self-signed
# certificate, just make sure to update the domains in dovecot-openssl.cnf
#ssl_cert = </etc/ssl/dovecotcert.pem
#ssl_key = </etc/ssl/private/dovecot.pem
...

Create the Sieve Scripts #

Sieve scripts train Rspamd on spam and ham. Moving email into and out of the junk folder triggers an event to train Rspamd.

These files are located at /usr/local/lib/dovecot/sieve.

Create the report-ham.sieve file.

require ["vnd.dovecot.pipe", "copy", "imapsieve", "environment", "variables"];

if environment :matches "imap.mailbox" "*" {
  set "mailbox" "${1}";
}

if string "${mailbox}" "Trash" {
  stop;
}

if environment :matches "imap.user" "*" {
  set "username" "${1}";
}

pipe :copy "sa-learn-ham.sh" [ "${username}" ];

Create the report-spam.sieve file.

require ["vnd.dovecot.pipe", "copy", "imapsieve", "environment", "variables"];

if environment :matches "imap.user" "*" {
  set "username" "${1}";
}

pipe :copy "sa-learn-spam.sh" [ "${username}" ];

Compile the files.

sievec report-ham.sieve
sievec report-spam.sieve

Create the following two shell scripts in /usr/local/lib/dovecot/sieve

Add the following to sa-learn-ham.sh

#!/bin/sh
exec /usr/local/bin/rspamc -d "${1}" learn_ham

Add the following to sa-learn-spam.sh

#!/bin/sh
exec /usr/local/bin/rspamc -d "${1}" learn_spam

Make the files executable.

chmod 0755 sa-learn-ham.sh
chmod 0755 sa-learn-spam.sh

Enable and start Dovecot.

rcctl enable dovecot
rcctl start dovecot

Check that Dovecot started properly.

ps ax | grep dovecot

88005 ??  I        0:00.11 /usr/local/sbin/dovecot
69640 ??  I        0:00.03 dovecot/anvil
91207 ??  I        0:00.03 dovecot/log
98178 ??  I        0:00.19 dovecot/config
34712 ??  I        0:00.06 dovecot/stats
96674 ??  I        0:00.03 dovecot/imap-login
 8891 ??  S        0:00.02 dovecot/imap

Verify Dovecot can correctly read /etc/mail/credentials

doveadm user john@example.com

field    value
uid      2000
gid      2000
home /var/vmail/example.com/john
mail maildir:/var/vmail/example.com/john

Verify a mail user can log in.

doveadm auth login john@example.com

Password: ********
passdb: john@example.com auth succeeded
extra fields:
  user=john@example.com

userdb extra fields:
  john@example.com
  mail=maildir:/var/vmail/example.com/john
  uid=2000
  gid=2000
  home=/var/vmail/example.com/john
  auth_mech=PLAIN

Set up Rspamd #

This is a basic Rspamd configuration, refer to the offical documentation for more details. This example creates a definition for our domain to enable DKIM signing.

Create a public/private keypair in /etc/mail/dkim and set the correct permissions.

doas su
mkdir /etc/mail/dkim
cd /etc/mail/dkim
openssl genrsa -out example.com.key 2048
openssl rsa -in example.com.key -pubout -out public.key
chmod 0440 example.com.key
chown root:_rspamd example.com.key

Create a DNS record for DKIM containing the public key. Refer to your DNS provider for details of how to create a DKIM record. Copy the contents from /etc/mail/dkim/public.key and paste it after the p= part of the DKIM record as shown below. Note this example also creates an SPF record.

default._domainkey.example.com. IN TXT "v=DKIM1;k=rsa;p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQClcuK3FV3Ug64li8iFsuJ2ykgb7FMZsujk9uG79ppPUp57vCfjzO7F+HBfx5qIwvlGxv2IJXK86FZwhpUX+HFCDUtfB2z0ZNGerWcZfNzM1w1Bru/fdMd2tCYkiHEa5RWIkLfs/Fm+neXxRZfAG2UDWmAghNbgzYv7xViwgufDIQIDAQAB"
example.com. IN TXT "v=spf1 a ip4:192.0.2.1 mx ~all"

Create a DMARC record.

_dmarc.example.com. IN TXT "v=DMARC1;p=none;pct=100;rua=mailto:postmaster@example.com"

Create the /etc/rspamd/local.d/dkim_signing.conf configuration file.

The selector="default"; line is derived from the first part of the DKIM DNS record (default._domainkey....) created above.

  domain {
      example.com {
          path = "/etc/mail/dkim/example.com.key";
          selector = "default";
      }
  }

Enable and start Rspamd.

doas rcctl enable redis rspamd
doas rcctl start redis rspamd

Change the lines below in /etc/mail/smtpd.conf and restart OpenSMTPD to enable Rspamd.

...
listen on all tls pki "mail" hostname "mail.example.com" filter "rspamd"
listen on egress port 465 smtps pki "mail" hostname "mail.example.com" \
  auth <credentials> filter "rspamd"
...
rcctl restart smtpd

Test the mail server with POP3 or IMAP email client. If you do not require webmail, stop here.

Secure Web Server #

ACME Configuration #

httpd configuration #

SSL verification #

Additional domains #

Email Server #

Preliminary Steps #

Configure OpenSMTPD #

Create the Credentials File #

Create Virtual Mail Account and Set Security #

Create the Virtual User Mapping #

Create Public/Private Keys for OpenSMTPD #

Test the Server #

Configure Dovecot IMAP #

Set the Login Class #

Create the Dovecot Configuration File #

Dovecot Bug Fix #

Create the Sieve Scripts #

Set up Rspamd #