OpenBSD comes with three great tools out of the box:

• httpd(8) - an HTTP daemon
• relayd(8) - a relay daemon
• acme-client(1) - a client for Automatic Certificate Management Environment (ACME)

With those free things, we can serve static webpages over TLS. While you most likely already use NGINX or Apache¹, those solutions are complex. They work amazingly in enterprise environments where you have people with doctorates in NGINX configuration, but most real-world examples don’t need that complexity. A static blog most likely doesn’t.

Let’s set it up.

Due to security concerns, OpenBSD comes with doas(1) instead of sudo(1). Copy `/etc/examples/doas.conf` file to `/etc/doas.conf`. For all intends, and purposes, from now on doas(1) will work the same as sudo(1).

When the system boots for the very first time, ports 80 and 443 are closed, and only the SSH port is open. This alone was a nice surprise for me. But it gets better: since all utilities are part of the OSes, they work together perfectly.

Assuming your domain is already pointing at the correct IPs, let’s start listening for unencrypted HTTP traffic. I will use “michal.sapka.me” as the domain in all examples.

First, Open /etc/httpd.conf in your favorite editor and add

server "michal.sapka.me" {
   listen on * port 80
   root "/htdocs/michal-sapka-me"
}

Then create a simple HTML file under /var/www/htdocs/michal-sapka-me/index.html.

Httpd(8) works chrooted to var/www, so it threats this directory as root. This makes the “root” option shorter to write, but it also means that the process doesn’t have access to anything outside of var/www. Even if an attacker can break in via the daemon, he will be locked in the www folder, so there is no risk to the rest of the system. As I said, OpenBSD is secure by default².

All we need to do now it to enable the daemon via the handy rcctl(8) tool.

$ doas rcctl enable httpd

and to start it

$ doas rcctl start httpd

And boom. Opening http://michal.sapka.me shows on our site both on IPv4 and IPv6. One thing to note here is the limitation of up to HTTP 1.1. HTTP 2 is not yet supported.

Let’s add TLS, so we have this cute lock icon. For this, we will request a certificate from Let’s Encrypt using acme-client(1). If you used certbot, this will look familiar - just tidier.

First, let’s add config to /etc/acme-client.conf

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

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.api.letsencrypt.org/directory"
        account key "/etc/acme/letsencrypt-staging-privkey.pem"
}

domain michal.sapka.me {
       domain key "/etc/ssl/private/michal.sapka.me.key"
       domain full chain certificate "/etc/ssl/michal.sapka.me.crt"
       sign with letsencrypt
}

Lines 1-9 tell our acme-client(1) how to talk with Let’s Encrypt, while lines 11-15 allow us to request a certificate for our domain. OpenBSD comes preconfigured for Let’s Encrypt, so we just enable provided settings.

Nice! Next, we need to allow Let’s Encrypt challenges. Acme-client(1) will manage all required files, and Let’s Encrypt can read them via httpd(8). Again, like cogs in a well-oiled machine. By default, acme-client(1) will write to /var/www/acme, so we need to redirect /.well-known/acme-challenge/* there. Let’s change our httpd.conf:

server "michal.sapka.me" {
   listen on * port 80
   root "/htdocs/michal-sapka-me"

   location "/.well-known/acme-challenge/*" {
      root "/acme"
      request strip 2
    }
}

We can now either restart httpd(8) or reload it. Let’s for the latter.

$ doas rcctl reload httpd

Now we can request the certificates

$ doas rcctl reload httpd
$ doas acme-client -v michal.sapka.me

OpenBSDs supplied tools don’t print unnecessary information to the user, so we add the -v to see what’s happening. Assuming everything went fine, let’s start serving the page with TLS!

For this, we will use relayd(8). We could use only httpd(8), but moving it one layer up is easier. Relayd(8) also gives us nice options for changing headers or moving some locations to a different process, like we will do with Plaroxy soon. This also shows us the big difference between this simple solution and NGINX: while NGINX shovels everything into one process and config, OpenBSD splits it into narrow focus areas.

Let’s open /etc/relayd.conf and add:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

table <httpd> { 127.0.0.1 }

http protocol "https" {
    tls keypair "michal.sapka.me"

    match request quick header "Host" value "michal.sapka.me" forward to <httpd>
}

relay "https" {
    listen on 0.0.0.0 port 443 tls
    protocol https
    forward to <httpd> port 8080

}
relay "https6" {
    listen on :: port 443 tls
    protocol https
    forward to <httpd> port 8080
}

Now, I won’t go into much detail here, but what happens here is:

1. We create two relays, one for ipv4 and one for ipv6. One relay can listen on a single port for given IP. Each relay uses protocol “https” to modify and steer the request to a given process.
2. Both relays set up forwarding to httpd (IP taken from the table on the head of the file) on port 8080.
3. https protocol adds a TLS key pair for the session. We’ve got the files from Let’s Encrypt in the step above.
4. We then test each request, and if the host matches “michal.sapka.me” it will be forwarded to httpd(8).

You can also see that relayd(8) can listen on a given IP or all IPs (:: in case of IPv6)

But our httpd(8) listens only on port 80! Let’s fix that by changing the `httpd.conf` file:

server "michal.sapka.me" {
   listen on * port 8080

We also need to redirect HTTP to HTTPS. Since we use Relayd(8) only for HTTPS, this will be done in httpd(8). Let’s add a second server to our `httpd.conf`:

server "michal.sapka.me" {
        listen on * port 80
        location * {
                block return 301 "https://$HTTP_HOST$REQUEST_URI"
        }
}

Now, when the user enters the site, the flow will look like:

1. httpd(8) will respond to :80 requests and return a 301 redirect to HTTPS
2. relayd(8) will catch the request to :443 and forward it on port :8080 to httpd(8)
3. httpd(8) will serve our site and pass the response to relayd(8) again
4. relayd(8) can modify headers before returning the response to the client.

Talking about modifying headers, let’s apply some extra security! We can expand our https protocol with the following:

# Return HTTP/HTML error pages to the client
   return error
   match request header set "X-Forwarded-For" value "$REMOTE_ADDR"
   match request header set "X-Forwarded-By" value "$SERVER_ADDR:$SERVER_PORT"
   match response header remove "Server"
   match response header append "Strict-Transport-Security" value "max-age=31536000; includeSubDomains"
   match response header append "X-Frame-Options" value "SAMEORIGIN"
   match response header append "X-XSS-Protection" value "1; mode=block"
   match response header append "X-Content-Type-Options" value "nosniff"
   match response header append "Referrer-Policy" value "strict-origin"
   match response header append "Content-Security-Policy" value "default-src https:; style-src 'self' \
     'unsafe-inline'; font-src 'self' data:; script-src 'self' 'unsafe-inline' 'unsafe-eval'"
   match response header append "Permissions-Policy" value "accelerometer=(), camera=(), \
     geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()"

   # set recommended tcp options
   tcp { nodelay, sack, socket buffer 65536, backlog 100 }

   # set up certs
   tls { no tlsv1.0, ciphers "HIGH:!aNULL:!SSLv3:!DSS:!ECDSA:!RSA:-ECDH:ECDHE:+SHA384:+SHA256" }

I won’t discuss details here as each header has a dedicated MDM webdoc. Most of the headers here are considered a standard.

Besides adding headers, we configure TLS here, disabling weak ciphers and old TLS versions and adding some standard config.

Lastly, we can automate refreshing the certificate via cron(8):

0~59 0~23 * * 1 acme-client michal.sapka.me &&  rcctl reload relayd

It looks almost like a normal cron. The “059” and “029” parts are unique to OpenBSD: Cron(8) will evenly split all tasks between specified time boxes so that no two jobs run simultaneously.

We now have created a fully working web server without any 3rd party packages. All OpenBSD provided, all secure, all simple, all cool as ice.

To further your knowledge, you can challenge the assumption that BSD has the best doc and read man pages for httpd.conf(5), relayd.conf(5), and acme-client.conf(5).

I also can’t recommend enough “Httpd and Relayd Mastery” by Michael W. Lucas³