dehydrated on FreeBSD

This describes how to setup dehydrated on a FreeBSD system to have your Let's Encrypt certificates updated automatically. It works for single hostname and multidomain certificates only. For verification, the http-01 protocol is used. Apache serves both the live websites, as well as the verification challenges. With slight modifications, one can adopt this for other webservers as well.

Installation

Either install the package:

# pkg install dehydrated

Or install the port, which I prefer since it allows you to deselect Build and/or install documentation, which I barely need on a server:

# cd /usr/ports/security/dehydrated
# make install clean

Configuration

Place your domain names for which you want to receive an SSL certificate in /usr/local/etc/dehydrated/domains.txt, e.g.:
```
www.your-domain.invalid
www.your-other-domain.invalid webmail-your-other-domain.invalid
```
The first line denotes a single hostname certificate, the second entry a multidomain certificate.
Edit /usr/local/etc/dehydrated/config, uncomment and set HOOK to $BASEDIR/hook.sh, as well as AUTO_CLEANUP to yes:
```
HOOK="$BASEDIR/hook.sh"
AUTO_CLEANUP="yes"
```

Edit /usr/local/etc/dehydrated/hook.sh, and add and extend the following functions:

#!/usr/local/bin/bash

RESTART_FLAG="$BASEDIR/restart_apache"

sendemail() {
    subject="$1"

    (cat <<EOF; cat) | sendmail -t
From: root
To: root
Subject: $subject

EOF
}

lookup() {
    local domain="$1"
    local domains_txt="$BASEDIR/domains.txt"
    local error
    local ssldir
    local tokendir
    local tokenfile

    local mainname=`awk '{if (/(^| )'"$domain"'($| )/) { print $1; }}' "$domains_txt"`
    if [ -z "$mainname" ]; then
        error="Domain $domain not found in $domains_txt"
        (cat <<EOF; cat "$domains_txt") | sendemail "$error"
Content of $domains_txt:
EOF
        echo "$error" >&2
        exit 1
    fi

    tokendir="/www/$mainname/htdocs/.well-known/acme-challenge"

    if [ -z "$3" ]; then
        # clean challenge
        rm "$tokendir/$2"
    elif [ -z "$4" ]; then
        # deploy challenge
        tokenfile="$tokendir/$2"
        oldmask=`umask`
        umask 0026
        mkdir -p "$tokendir"
        umask "$oldmask"
        echo "$3" > "$tokenfile"
        chmod 0644 "$tokenfile"
    else
        # deploy cert
        ssldir="/www/$mainname/ssl"
        cp "$2" "$ssldir/$mainname.key"
        cp "$3" "$ssldir/$mainname.crt"
        cp "$4" "$ssldir/$mainname.chain"
        touch "$RESTART_FLAG"
    fi
}

deploy_challenge() {
    local DOMAIN="${1}" TOKEN_FILENAME="${2}" TOKEN_VALUE="${3}"

    lookup "$DOMAIN" "$TOKEN_FILENAME" "$TOKEN_VALUE"
}

clean_challenge() {
    local DOMAIN="${1}" TOKEN_FILENAME="${2}" TOKEN_VALUE="${3}"

    lookup "$DOMAIN" "$TOKEN_FILENAME"
}

deploy_cert() {
    local DOMAIN="${1}" KEYFILE="${2}" CERTFILE="${3}" FULLCHAINFILE="${4}" CHAINFILE="${5}" TIMESTAMP="${6}"

    lookup "$DOMAIN" "$KEYFILE" "$CERTFILE" "$CHAINFILE"
}

invalid_challenge() {
    local DOMAIN="${1}" RESPONSE="${2}"

    cat <<EOF | sendemail "Validation of $DOMAIN failed"
Response:
$RESPONSE
EOF
}

request_failure() {
    local STATUSCODE="${1}" REASON="${2}" REQTYPE="${3}" HEADERS="${4}"

    cat <<EOF | sendemail "Request of $DOMAIN failed"
Status code:
$STATUSCODE

Reason:
$REASON

Request type:
$REQTYPE

Headers:
$HEADERS
EOF
}

exit_hook() {
  if [ -f "$RESTART_FLAG" ]; then
    service apache24 graceful
    rm "$RESTART_FLAG"
  fi
}

This assumes that

your websites reside under the /www directory, which each website having is own directory
this directory as well as the private key file, the certificate, and the CA certificate are named after its hostname (the first column of each row in domains.txt)
each website's content is served from the subdirectory htdocs, with at least htdocs/.well-known/acme-challenge being accessible via http
the private key, the certificate, and the CA certificate are expected in a subdirectory named ssl
you run Apache 2.4 as webserver
root can receive emails

For example, if your domains.txt contains

www.your-other-domain.invalid webmail-your-other-domain.invalid

then challenges will be placed as text files in the directory /www/www.your-other-domain.invalid/htdocs/.well-known/acme-challenge. Afterwards, you will get three files

/www/www.your-other-domain.invalid/ssl/www.your-other-domain.invalid.key
/www/www.your-other-domain.invalid/ssl/www.your-other-domain.invalid.crt
/www/www.your-other-domain.invalid/ssl/www.your-other-domain.invalid.chain

with www.your-other-domain.invalid.crt being a multidomain certificate, and www.your-other-domain.invalid.chain containing the CA and intermediate certificates.

On your webserver, redirect any requests on port 80 to port 443, but still serve .well-known via http, e.g. in your Apache's vhost configuration for www.your-domain.invalid:

<VirtualHost :80>
    ServerName www.your-domain.invalid
    DocumentRoot /www/www.your-domain.invalid/htdocs
    RedirectMatch 301 ^/(?!.well-known/) https://www.your-domain.invalid/
    <Directory /www/www.your-domain.invalid/htdocs>
        Require all granted
    </Directory>
</VirtualHost>
<VirtualHost :443>
    ServerName www.your-domain.invalid
    DocumentRoot /www/www.your-domain.invalid/htdocs
    <Directory /www/www.your-domain.invalid/htdocs>
        Require all granted
    </Directory>
    SSLEngine on
    SSLCertificateChainFile /www/www.your-domain.invalid/ssl/www.your-domain.invalid.chain
    SSLCertificateFile /www/www.your-domain.invalid/ssl/www.your-domain.invalid.crt
    SSLCertificateKeyFile /www/www.your-domain.invalid/ssl/www.your-domain.invalid.key
</VirtualHost>

Make /usr/local/etc/dehydrated/hook.sh executable:

# chmod 0755 /usr/local/etc/dehydrated/hook.sh

Add this to /etc/periodic.conf:
```
weekly_dehydrated_enable="YES"
```

Once register your account:

# /usr/local/bin/dehydrated --register --accept-terms

You can now wait until the next weekly cycle of periodic, or request the certificates manually:
```
# /usr/local/etc/periodic/weekly/000.dehydrated
```