Dehydrated
This is a short and opinionated guide, please consult the upstream documentation for dehydrated and the project’s wiki for further details.
Before you start
The following explanations assume that you placed the netdb_config.ini from NETVS at either
$USER/.config/netdb_client.ini or in the working directory where the ACME client is run from.
An example for the config file can
be found in the netdb-client repository
For other options to pass the API token (via environment variable or command line argument),
please consult the help of the acme4netvs hooks with -h.
Warning
If you are still testing certificate requests via ACME, please always use the staging endpoint of Lets Encrypt. This will generate certificates that are not trusted by browsers, but will not trigger any rate limits of the production endpoint. If you trigger rate limiting, this might affect other users at KIT negatively. Be nice 🙂
Installation
First, you need to install dehydrated. For most Linux distributions, dehydrated is available via the main package sources and can be installed via the respective package manager.
Examples:
- Debian/Ubuntu:
apt install dehydrated - Fedora:
dnf install dehydrated - Arch:
pacman install dehydrated
If it is not available for your distribution, dehydrated ist just a bash script. It can be downloaded from the dehydrated git repository.
Setup
You need a configration file for dehydrated.
Packaged version of dehydrated often include a basic config file in the path /etc/dehydrated/config.
A full list of paths that are checked for the config can be found in the official dehydrated documentation.
Make sure that the config file contains the following content if the rest of these instructions should work without adaptation:
CONFIG_D=/etc/dehydrated/conf.d
BASEDIR=/var/lib/dehydrated
WELLKNOWN="${BASEDIR}/acme-challenges"
DOMAINS_TXT="/etc/dehydrated/domains.txt"
Key Type
Dehydrated creates Elliptic Curve (EC) certificates by default.
They have shorter keys and make the TLS handshake more efficient.
They are broadly supported, but very old clients may have problems with them.
If you have problems and need to use classic RSA certificates, use --algo rsa as command line argument or add KEY_ALGO=rsa to the dehydrated config file.
Domain
Either you generate a fresh /etc/dehydrated/domains.txt file or you copy a well documented example file from /usr/share/doc/dehydrated/examples/domains.txt. Comment out all examples and insert your domain, e.g. acme4netvs-doku.le.uni-beispiel.de for which the certificate should be generated.
Single Hook
For getting started you then only have to add two more lines to /etc/dehydrated/config. With the hook paramater you define the location of the acme4netvs binary. Also you have to change the challenge type.
Multiple Hooks
Copy the well documented /usr/share/doc/dehydrated/examples/hook.sh to /etc/dehydrated and configure the hook parameter accordingly to:
deploy_challenge()
and at the end of clean_challenge()
If you wish to do something after successful certificate generation add the appropiate commands at the end of the function deploy_cert(), for example the restart of a service like nginx
Register account
For testing
> dehydrated --register --accept-terms --ca letsencrypt-test
# INFO: Using main config file /etc/dehydrated/config
+ Generating account key...
+ Registering account key with ACME server...
+ Fetching account URL...
+ Done!
For production certificates
> dehydrated --register --accept-terms
# INFO: Using main config file /etc/dehydrated/config
+ Generating account key...
+ Registering account key with ACME server...
+ Fetching account URL...
+ Done!
Request and renew certificates
For testing
For production certificates
Warning
For kit.edu domains, creating the DNS challenge currently takes about 20 minutes for each domain in the certificate.
acme4netvs waits for all DNS servers to actually have the challenge available and will output “Challenge is NOT yet available on <DNS-Server-Name>.” periodically.
This is expected behaviour for now.
In the future, KIT’s DNS servers will allow for real-time updates, deploying a challenge will then only take a few seconds.
Output:
# INFO: Using main config file /etc/dehydrated/config
acme4netvs 2022/10/12 14:11:02 👎 operation »this_hookscript_is_broken__dehydrated_is_working_fine__please_ignore_unknown_hooks_in_your_script« is not implemented in this plugin
acme4netvs 2022/10/12 14:11:02 👎 operation »startup_hook« is not implemented in this plugin
+ Creating chain cache directory /var/lib/dehydrated/chains
Processing acme4netvs-doku.le.uni-beispiel.de
+ Creating new directory /var/lib/dehydrated/certs/acme4netvs-doku.le.uni-beispiel.de ...
acme4netvs 2022/10/12 14:11:02 👎 operation »this_hookscript_is_broken__dehydrated_is_working_fine__please_ignore_unknown_hooks_in_your_script« is not implemented in this plugin
+ Signing domains...
+ Generating private key...
+ Generating signing request...
+ Requesting new certificate order from CA...
+ Received 1 authorizations URLs from the CA
+ Handling authorization for acme4netvs-doku.le.uni-beispiel.de
+ 1 pending challenge(s)
+ Deploying challenge tokens...
acme4netvs 2022/10/12 14:11:05 ✨ Using config file /root/.config/netdb_client.ini
acme4netvs 2022/10/12 14:11:05 🚀 NETVS client created (baseURI: »www-net.scc.kit.edu«, apiVersion: »3.2«)
acme4netvs 2022/10/12 14:11:05 ✨ [acme4netvs-doku.le.uni-beispiel.de] Creating domain record
acme4netvs 2022/10/12 14:11:05 ✨ [acme4netvs-doku.le.uni-beispiel.de] Creating _acme-challenge domain record
acme4netvs 2022/10/12 14:11:05 ✨ [acme4netvs-doku.le.uni-beispiel.de] Creating _acme-challenge TXT record
acme4netvs 2022/10/12 14:11:06 ✨ [acme4netvs-doku.le.uni-beispiel.de] has nameservers ns-t-1.kit-dns.eu., ns-t-2.kit-dns.de.
acme4netvs 2022/10/12 14:11:06 ✨ Waiting for 2 parallel nameserver checks
acme4netvs 2022/10/12 14:11:06 ✨ [acme4netvs-doku.le.uni-beispiel.de] Started new goroutine to check DNS challenge on ns-t-1.kit-dns.eu.
acme4netvs 2022/10/12 14:11:06 ✨ [acme4netvs-doku.le.uni-beispiel.de] Started new goroutine to check DNS challenge on ns-t-2.kit-dns.de.
acme4netvs 2022/10/12 14:11:06 ✅ [acme4netvs-doku.le.uni-beispiel.de] Challenge is available on ns-t-1.kit-dns.eu. (after 503.29067ms)
acme4netvs 2022/10/12 14:11:06 ✅ [acme4netvs-doku.le.uni-beispiel.de] Challenge is available on ns-t-2.kit-dns.de. (after 503.818431ms)
acme4netvs 2022/10/12 14:11:06 👍 [acme4netvs-doku.le.uni-beispiel.de] Nameserver checks are done
+ Responding to challenge for acme4netvs-doku.le.uni-beispiel.de authorization...
+ Challenge is valid!
+ Cleaning challenge tokens...
acme4netvs 2022/10/12 14:11:09 ✨ Using config file /root/.config/netdb_client.ini
acme4netvs 2022/10/12 14:11:09 🚀 NETVS client created (baseURI: »www-net.scc.kit.edu«, apiVersion: »3.2«)
acme4netvs 2022/10/12 14:11:10 ✨ [acme4netvs-doku.le.uni-beispiel.de] Removing _acme-challenge TXT record
acme4netvs 2022/10/12 14:11:10 👍 [acme4netvs-doku.le.uni-beispiel.de] Removed challenge eTWxFrX-Rg9M8HiA9RnkAZjjrKXP2c4XPKXFGO6hb8Q
+ Requesting certificate...
+ Checking certificate...
+ Done!
+ Creating fullchain.pem...
acme4netvs 2022/10/12 14:11:12 👎 operation »sync_cert« is not implemented in this plugin
acme4netvs 2022/10/12 14:11:12 👎 operation »deploy_cert« is not implemented in this plugin
+ Done!
acme4netvs 2022/10/12 14:11:12 👎 operation »exit_hook« is not implemented in this plugin
ls -la /var/lib/dehydrated/certs/acme4netvs-doku.le.uni-beispiel.de/
total 32
drwx------ 2 root root 4096 Oct 12 14:11 .
drwx------ 3 root root 4096 Oct 12 14:11 ..
-rw------- 1 root root 562 Oct 12 14:11 cert-1665576662.csr
-rw------- 1 root root 1501 Oct 12 14:11 cert-1665576662.pem
lrwxrwxrwx 1 root root 19 Oct 12 14:11 cert.csr -> cert-1665576662.csr
lrwxrwxrwx 1 root root 19 Oct 12 14:11 cert.pem -> cert-1665576662.pem
-rw------- 1 root root 2772 Oct 12 14:11 chain-1665576662.pem
lrwxrwxrwx 1 root root 20 Oct 12 14:11 chain.pem -> chain-1665576662.pem
-rw------- 1 root root 4273 Oct 12 14:11 fullchain-1665576662.pem
lrwxrwxrwx 1 root root 24 Oct 12 14:11 fullchain.pem -> fullchain-1665576662.pem
-rw------- 1 root root 359 Oct 12 14:11 privkey-1665576662.pem
lrwxrwxrwx 1 root root 22 Oct 12 14:11 privkey.pem -> privkey-1665576662.pem
Automate certificate renewal
Make sure that either a systemd timer or a cron entry is present to request certificates regularly.
The default suggestion is to run dehydrated -c once a day.