Zum Inhalt

CertBot

Inhalt

  • Certbot 4.2.0
  • Let’s Encrypt ACME
  • Webroot-Modus für HTTP-01
  • automatische Zertifikatserneuerung über FreeBSD periodic
  • Deploy-Hooks nach erfolgreicher Erneuerung

Einleitung

Dieses HowTo beschreibt die Installation und Konfiguration von Certbot auf FreeBSD 15+.

Certbot wird in diesem HowTo bewusst im Webroot-Modus betrieben. Das ist für eine bereits laufende Apache-Instanz die sauberere Lösung, weil Certbot die Challenge-Dateien direkt unter /.well-known/acme-challenge/ ablegt und Apache sie ausliefert. Die Apache-Konfiguration bleibt dabei vollständig manuell und kontrolliert.

Voraussetzungen

Für dieses HowTo muss Apache bereits installiert und funktionsfähig sein.

Zu den Voraussetzungen für dieses HowTo siehe bitte: Hosting System

Zusätzlich gilt für dieses HowTo:

  • Apache ist installiert und läuft bereits.
  • Apache liefert /.well-known/acme-challenge/ korrekt aus.
  • Für HTTP-01 muss Port 80/TCP von außen erreichbar sein.
  • Für Wildcard-Zertifikate ist dieses HowTo nicht geeignet; dafür ist DNS-01 erforderlich.

Vorbereitungen

Vor der Installation müssen die DNS-Auflösung, die Webroot-Struktur und die Certbot-Verzeichnisse vorbereitet werden.

DNS Records

Für dieses HowTo müssen zuvor die benötigten Hostnamen auf den Webserver zeigen.

Text Only
example.com.             IN  A       __IPADDR4__
example.com.             IN  AAAA    __IPADDR6__

www.example.com.         IN  A       __IPADDR4__
www.example.com.         IN  AAAA    __IPADDR6__

mail.example.com.        IN  A       __IPADDR4__
mail.example.com.        IN  AAAA    __IPADDR6__

devnull.example.com.     IN  A       __IPADDR4__
devnull.example.com.     IN  AAAA    __IPADDR6__

Gruppen / Benutzer / Passwörter

Für dieses HowTo sind keine zusätzlichen Systemgruppen, Systembenutzer oder separaten Passwörter erforderlich.

Verzeichnisse / Dateien

Für dieses HowTo müssen zuvor folgende Verzeichnisse angelegt werden, sofern sie noch nicht existieren.

Bash
mkdir -p /var/db/letsencrypt
install -d -m 0700 /var/log/letsencrypt

mkdir -p /usr/local/etc/letsencrypt
mkdir -p /usr/local/etc/letsencrypt/certs
mkdir -p /usr/local/etc/letsencrypt/renewal-hooks
mkdir -p /usr/local/etc/letsencrypt/renewal-hooks/pre
mkdir -p /usr/local/etc/letsencrypt/renewal-hooks/post
mkdir -p /usr/local/etc/letsencrypt/renewal-hooks/deploy

mkdir -p /usr/local/www/.well-known/acme-challenge

Zusätzliche Dateien müssen vor der Installation noch nicht vorbereitet werden. Die eigentlichen Konfigurationsdateien werden im Abschnitt Konfiguration angelegt.

Installation

Wir installieren security/py-certbot und dessen Abhängigkeiten.

Bash
mkdir -p /var/db/ports/textproc_py-snowballstemmer
cat <<'EOF' > /var/db/ports/textproc_py-snowballstemmer/options
_OPTIONS_READ=py311-snowballstemmer-3.0.1
_FILE_COMPLETE_OPTIONS_LIST=PYSTEMMER
OPTIONS_FILE_SET+=PYSTEMMER

EOF

mkdir -p /var/db/ports/security_py-certbot
cat <<'EOF' > /var/db/ports/security_py-certbot/options
_OPTIONS_READ=py311-certbot-4.2.0
_FILE_COMPLETE_OPTIONS_LIST=MANPAGES
OPTIONS_FILE_SET+=MANPAGES

EOF

portmaster -w -B -g -U --force-config security/py-certbot -n

Dienst in rc.conf eintragen

Nicht erforderlich.

Certbot ist kein dauerhaft laufender Dienst mit eigenem rc.d-Service. Die automatische Erneuerung erfolgt in diesem HowTo über den FreeBSD-Periodic-Mechanismus.

Konfiguration

Konfigurationsdatei cli.ini

Die zentrale Certbot-Konfiguration liegt unter /usr/local/etc/letsencrypt/cli.ini. Für dieses Setup ist Webroot die richtige Standardwahl.

Bash
cat <<'EOF' > /usr/local/etc/letsencrypt/cli.ini
config-dir = /usr/local/etc/letsencrypt
work-dir = /var/db/letsencrypt
logs-dir = /var/log/letsencrypt

server = https://acme-v02.api.letsencrypt.org/directory
email = admin@example.com

text = true
agree-tos = true
no-eff-email = true
non-interactive = true

authenticator = webroot
webroot-path = /usr/local/www
preferred-challenges = http-01

key-type = ecdsa
elliptic-curve = secp384r1
rsa-key-size = 3072

#pre-hook = /usr/local/etc/letsencrypt/renewal-hooks/pre/hook.sh
#post-hook = /usr/local/etc/letsencrypt/renewal-hooks/post/hook.sh
#deploy-hook = /usr/local/etc/letsencrypt/renewal-hooks/deploy/hook.sh
EOF

ECDSA ist für dieses Setup die sinnvolle Standardwahl, solange keine bewusst sehr alten HTTPS-Clients unterstützt werden müssen.

Deploy-Hook einrichten

Der Deploy-Hook wird nur nach erfolgreicher Zertifikatserneuerung ausgeführt. In diesem HowTo übernimmt er das Neubauen der benötigten PEM-Dateien und das anschließende Neuladen der betroffenen TLS-Dienste.

Bash
cat <<'EOF' > /usr/local/etc/letsencrypt/renewal-hooks/deploy/hook.sh
#!/bin/sh
set -eu
mkdir -p /usr/local/etc/letsencrypt/certs

cat /usr/local/etc/letsencrypt/live/devnull.example.com/fullchain.pem \
    /usr/local/etc/letsencrypt/live/devnull.example.com/privkey.pem \
    > /usr/local/etc/letsencrypt/certs/devnull.example.com.pem
cat /usr/local/etc/letsencrypt/live/www.example.com/fullchain.pem \
    /usr/local/etc/letsencrypt/live/www.example.com/privkey.pem \
    > /usr/local/etc/letsencrypt/certs/www.example.com.pem
cat /usr/local/etc/letsencrypt/live/mail.example.com/fullchain.pem \
    /usr/local/etc/letsencrypt/live/mail.example.com/privkey.pem \
    > /usr/local/etc/letsencrypt/certs/mail.example.com.pem
chmod 640 /usr/local/etc/letsencrypt/certs/*.pem
service haproxy reload
service nginx reload
service apache24 reload
service dovecot reload
service postfix reload
EOF
chmod 750 /usr/local/etc/letsencrypt/renewal-hooks/deploy/hook.sh

FreeBSD-Periodic konfigurieren

Für dieses Webroot-Setup genügt der Weekly-Periodic-Job mit Deploy-Hook und den gewünschten Certbot-Argumenten.

Bash
cat <<'EOF' >> /etc/periodic.conf
weekly_certbot_enable="YES"
weekly_certbot_deploy_hook="/usr/local/etc/letsencrypt/renewal-hooks/deploy/hook.sh"
weekly_certbot_custom_args="--config-dir /usr/local/etc/letsencrypt --work-dir /var/db/letsencrypt --logs-dir /var/log/letsencrypt"
EOF

Test vor der ersten Ausstellung

Vor der ersten Zertifikatsausstellung muss geprüft werden, ob Apache die ACME-Challenge-Dateien wirklich ausliefert.

Bash
apachectl configtest
service apache24 reload

echo "ok" > /usr/local/www/.well-known/acme-challenge/test.txt
fetch -qo - http://www.example.com/.well-known/acme-challenge/test.txt
rm -f /usr/local/www/.well-known/acme-challenge/test.txt

Wenn der letzte Abruf ok liefert, ist der kritische Pfad für HTTP-01 korrekt verdrahtet.

Zertifikate ausstellen

Für dieses Beispiel bleiben die Zertifikatsgruppen wie folgt aufgeteilt:

  • devnull.example.com
  • mail.example.com
  • www.example.com zusammen mit example.com
Bash
certbot register

certbot certonly -d devnull.example.com
certbot certonly -d mail.example.com
certbot certonly -d www.example.com -d example.com

certonly ist hier absichtlich gewählt. Certbot beschafft nur die Zertifikate; die Apache-Konfiguration bleibt vollständig manuell.

Konfiguration prüfen

Vor dem produktiven Einsatz sollte zuerst ein trockener Erneuerungstest durchgeführt werden.

Bash
certbot renew --dry-run
certbot certificates

Datenbanken

Für dieses HowTo sind keine Datenbanken erforderlich.

Zusatzsoftware

Ausnahmefall: Standalone-Modus

Falls vorübergehend noch kein Webserver auf Port 80 betrieben wird, kann Certbot im Standalone-Modus verwendet werden.

Bash
certbot register --standalone
certbot certonly --standalone -d subdomain.example.com

Sobald Apache produktiv auf Port 80 läuft, sollte wieder auf den Webroot-Modus gewechselt werden.

Ausnahmefall: Apache-Plugin

Optional existiert auf FreeBSD zusätzlich der separate Port security/py-certbot-apache.

Dieses HowTo verwendet das Apache-Plugin trotzdem nicht, weil die Apache-Konfiguration hier bewusst manuell und nachvollziehbar bleiben soll.

Aufräumen

Temporäre Dateien aus dem eigentlichen Setup fallen in diesem HowTo nicht an. Die Testdatei unter /.well-known/acme-challenge/ wurde bereits im Testschritt wieder entfernt.

Zusatzsoftware Installation

Nicht erforderlich.

Zusatzsoftware Konfiguration

Nicht erforderlich.

Abschluss

Certbot ist nun eingerichtet und kann für Ausstellung, Prüfung und Erneuerung von Zertifikaten verwendet werden.

Bash
certbot certificates
periodic weekly

Für spätere Änderungen und Funktionstests:

Bash
certbot renew --dry-run
certbot renew
service apache24 reload

Referenzen