Hosting a HUGO site on OpenBSD.Amsterdam with OpenBSD, httpd, and relayd

Intended Audience

This guide is intended for anyone who wishes to setup a hugo website runing on OpenBSD using httpd and relayd.

OpenBSD.Amsterdam - A short plug for my hosting provider

This server is hosted on OpenBSD.Amsterdam. They have really been a pleasure to work with, and they give back to The OpenBSD Foundation and at under 6 euros per month it’s a great value. If you really care about OpenBSD and want it to continue in the future, I think donations or using services where part of your money goes to the project is a great start.

OpenBSD Amsterdam gives back 10 euros per VM and 15 euros per VM on every renewal to The OpenBSD Foundation.

Mischa was really helpful and was a pleasure to work with.

OpenBSD Amsterdam - https://openbsd.amsterdam

The OpenBSD Foundation - https://www.openbsdfoundation.org

Document Scope

This document assumes that you already have an OpenBSD server properly installed, configured, and setup to your liking complete with name resolution, PF configuration and so on. Those topics will be outside the scope of this document although these topics will likely be covered later in other documents.

This document will focus instead on setting up OpenBSD’s httpd server, relayd, SSL certificates, and so on.

acme-client, httpd, and relayd

The OpenBSD project has some beautifully designed software and tools. One lovely piece of software is httpd. It is a very simple, very lightweight http server. It has basic functionality and isn’t too feature rich. It’s lack of features is intentional. This is why we will need to pair it with relayd . Many things can be accomplished with relayd. We will be using it to manage headers and so on. This will be discussed later in this document. The acme-client is OpenBSD’s own client for generating and keeping Let’s Encrypt certificates up-to-date. We will also be discussing this later in this document.

For now let’s have a look at the official documentation:

httpd manpage - https://man.openbsd.org/httpd.8

httpd.conf manpage - https://man.openbsd.org/httpd.conf.5

relayd manpage - https://man.openbsd.org/relayd.8

relayd.conf manpage - https://man.openbsd.org/relayd.conf.5

acme-client manpage - https://man.openbsd.org/acme-client.1

acme-client.conf manpage - https://man.openbsd.org/acme-client.conf.5

Required Software

Most of the required software is in OpenBSD base ( httpd, relayd ). I will discuss the importance of base in other articles, but that is outside the scope of this article.

hugo–extended

You will need to install hugo. We will be setting it up and configuring it later but let’s go ahead and get the prerequisites done.

/usr/sbin/pkg_add -vi hugo--extended

httpd

Fire up your favorite editor ( I will be discussing in other articles why you should be using VI ) and edit the /etc/httpd.conf file. Here you will want to enter the basics just to test your setup.

server "example.com" {
  listen on * port 80
  root "/htdocs/www.example.com"
}

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

Save your config.

The httpd daemon is chrooted to /var/www by default. It is there where we will need to create the document root directory structure.

mkdir -p /var/www/htdocs/example.com

Let’s check our configs to make sure they are sane.

httpd -n

You should see something like: configuration ok

The httpd daemon can be enabled and started as follows:

rcctl enable httpd
rcctl start httpd

You may try placing an index.html file or something in your document root structure to test if the server is working. That is actually the only reason for this portion of the document. To test functionality of the httpd sever and to ensure that your PF rules are allowing traffic. Ideally you will want to bind the httpd server to specific interfaces / IPs and we will do that later.

acme-client

Next we will be getting those sweet SSL certificates so that our site can actually be useful in the 21st century. For that we will be using OpenBSD’s easy to use acme-client.

As aforementioned we will not be covering setting up DNS in this guide. That said please double-check to make sure that you have proper CAA records setup for your domain. These CAA records allow your domain SSL certs to be managed by Let’s Encrypt.

example.com. 300 IN   CAA   0 issue "letsencrypt.org"

You may check your domain as follows:

/usr/bin/dig CAA example.com @9.9.9.9

Let’s edit our /etc/acme-client.conf with our favorite editor and setup something like this:

authority letsencrypt {
        api url "https://acme-v02.api.letsencrypt.org/directory"
        account key "/etc/acme/letsencrypt-privkey.pem"
        contact "mailto:example.email@example.com"
}

domain example.com {
        domain key "/etc/ssl/private/example.com.key"
        domain full chain certificate "/etc/ssl/example.com.fullchain.pem"
        sign with letsencrypt
}

Create the directory structure:

    mkdir -p -m 755 /var/www/acme

Update the /etc/httpd.conf file to handle verification requests from Let’s Encrypt. It should be similar to this:

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

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

Check the configuration and restart httpd:

# httpd -n
configuration ok
# rcctl restart httpd
httpd(ok)
httpd(ok)
#

Now, let’s run the acme-client to create new account and domain keys.

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

To renew the certificates automagically we add a crontab entry.

### Keep SSL Certs Up-To-Date ### 
0       0       *       *       *       /usr/local/sbin/acme.sh

–in progress–