Renewing Let’s Encrypt wildcard certificates is generally a massive pain. You need to be able to automatically update DNS records for the domain – which is fine if you use a DNS provider that has an official Let’s Encrypt DNS plugin, but less so if you use a DNS provider that doesn’t – such as Hurricane Electric.
Side note – I’m not particularly interested in arguments for and against wildcard certs. If you’re reading this, you’ve obviously come to the conclusion that they’re probably fine and you just want them automated like the rest of your Let’s Encrypt certs!
This post assumes the following:
- You are obtaining wildcard certificates from Let’s Encrypt
- Your DNS is hosted with Hurricane Electric
- Your ACME client for Let’s Encrypt is Certbot
- You have shell access to your server
Obtain a new Let’s Encrypt wildcard certificate
Note: if you’ve already got a wildcard certificate, you can mostly skip this bit – but skim this section to make sure you’ve done everything you need to do!
1. Request wildcard certificate
Here’s the command-line incantation to request a new wildcard certificate:
sudo certbot certonly --cert-name example.com-wildcard -d '*.example.com' --manual --preferred-challenges dns Couple things to note here:
- I’m not including the base domain in the certificate here – I wouldn’t be able to automate it if I did, as I’d end up needing two TXT records for the same hostname. My solution was to separate the base domain out into its own certificate, which works perfectly for me.
- I’m specifying a certificate name. This is important, as otherwise it ends up trying to name it the same as the base domain – which is no good if you have a cert for the base domain as well.
Run the Certbot wizard – it will soon ask you to create a TXT record!
2. Create TXT record
The Certbot wizard will ask you to create a record, something like the following:
Please deploy a DNS TXT record under the name
_acme-challenge.example.com with the following value:
qwertyuiop-1234567890Log into the Hurricane Electric DNS console, select your domain and create a new TXT record with the following settings:
| Name | _acme-challenge.example.com |
| Text data | qwertyuiop-1234567890 |
| TTL (Time to live) | 5 minutes (300) |
Don’t check the Enable entry for dynamic dns box yet! Save the record and complete the Certbot wizard. Your certificate should now be issued, and you can configure your Apache / Nginx / etc server as appropriate.
Set up renewal scripts
1. Create DDNS TXT record key
As of current writing, the various Hurricane Electric DNS plugins for Certbot that I’ve seen all log into the actual account – which is horrendous from a security perspective. You don’t want a script to have full control over all of your domain records!
Thankfully, Hurricane Electric now allow TXT records to be updated with a key that only has control over just that one record.
Go back to the _acme-challenge TXT record for your domain, check the box to enable the entry for dynamic dns and Update. This enables the DDNS feature – you should now see an “arrow circle” symbol for that record:
Click the arrow circle symbol to generate a new DDNS key (save this key somewhere – this is the last time you’ll see it in the Hurricane Electric interface!)
For the purposes of this example, I’ll assume that the generated key looks something like ‘qwertyuiop123456’.
2. Add manual authentication script
Copy and paste the following into /etc/letsencrypt/he-dns-update.sh:
#!/bin/bash
# Do we have everything we need?
if [[ -z "$CERTBOT_DOMAIN" ]] || [[ -z "$CERTBOT_VALIDATION" ]]; then
echo '$CERTBOT_DOMAIN and $CERTBOT_VALIDATION environment variables required.'
exit 1
fi
# Add all HE TXT record DDNS keys to the txt_key object
# Remember to protect this script file - chmod 700!
declare -A txt_key
txt_key['_acme-challenge.example.com']='qwertyuiop123456'
# Create a FQDN based on $CERTBOT_DOMAIN
HE_DOMAIN="_acme-challenge.$CERTBOT_DOMAIN"
# Update HE DNS record
curl -s -X POST "https://dyn.dns.he.net/nic/update" -d "hostname=$HE_DOMAIN" -d "password=${txt_key[$HE_DOMAIN]}" -d "txt=$CERTBOT_VALIDATION"
# Sleep to make sure the change has time to propagate over to DNS
sleep 30As the comment suggests – protect this file from prying eyes by using chmod 700. If you have multiple wildcard certificates, you can add in extra entries to the txt_key object.
3. Add post deployment script
As much as you can manually restart services after the new certificate has been issued, you can automate that as well. Copy and paste the following into /etc/letsencrypt/renewal-hooks/deploy/restart-services.sh:
#!/bin/sh
set -e
for domain in $RENEWED_DOMAINS; do
case $domain in
*.example.com)
systemctl restart apache2
;;
*.example.com.au)
systemctl restart nginx
systemctl restart postfix
;;
*)
esac
doneUpdate the script to restart specific services for particular domains as required. I recommend chmod’ing this file to 755 – unlike the previous script, there’s nothing sensitive here!
Request Let’s Encrypt wildcard renewal
We’re going to force a renewal of the certificate here – this will test the two scripts above, plus update the renewal config so that the certificate will automatically renew in the future. If your certificate is due for renewal already, you don’t need to include the –force-renewal flag. Run the following command:
sudo certbot renew --cert-name example.com-wildcard --manual --manual-auth-hook /etc/letsencrypt/he-dns-update.sh --preferred-challenges dns --force-renewalCheck that:
- There are no errors in the Certbot logs,
- The certificate renewed successfully, and
- All services restarted appropriately
If everything worked – your Let’s Encrypt wildcard certificates should now renew automagically!
