Pre and Post Validation Hooks with Certbot

Fri 28th May 2021 By David T. Sadler.

I have a wildcard certificate for the domain davidtsadler.com that was issued by Let's Encrypt and I want to setup a cron job that periodically runs the certbot command to automatically renew it before it expires.

Now because its a wildcard certificate I have to use the DNS-01 challenge to validate that I control the domain name. Normally certbot is able to handle this validation during the renewing through a plugin that supports a dns provider. By using a plugin certbot is able to add and remove the required TXT dns records. Typically this is done through an API that the dns provider has to allow users to manage their dns entries. By suppling certbot with the credentials for the API a user is proving that they own the domain.

Since I am using Mail-in-a-Box for my dns there are no plugins available for certbot so instead I can use the pre and post validation hooks. These hooks are paths to scripts that will be called when certbot performs a DNS-01 challenge in manual mode. The pre auth hook is called at the start of the validation and in your script you can perform whatever steps are needed to pass the validation. It is here where you can call an API to add any dns entries. The post cleanup hook is where you can clean up any changes brought about by the auth hook.

Mail-in-a-Box provides an API for managing dns records that can be called by using curl. So my auth script will add a TXT record that is then removed by the cleanup script. Credentials for the API are the email and password of an existing user on the Mail-in-a-Box server.

When certbot calls the scripts it passes various environment variables so that they can be read by the scripts. Of which CERTBOT_VALIDATION is used to get the value of the TXT record, and CERTBOT_DOMAIN to obtain the domain name that is been validated.

The auth script is shown below.

#!/bin/sh

EMAIL=username@example.com
PASSWORD='super strong password'

# Create TXT record
curl -s -X POST -d "$CERTBOT_VALIDATION" --user $EMAIL:$PASSWORD https://examplemailinaboxserver.com/admin/dns/custom/_acme-challenge.$CERTBOT_DOMAIN/txt

# Make sure the change has time to propagate over to DNS
sleep 25

Below is the cleanup script.

#!/bin/sh

EMAIL=username@example.com
PASSWORD='super strong password'

# Delete TXT record
curl -s -X DELETE -d "$CERTBOT_VALIDATION" --user $EMAIL:$PASSWORD https://examplemailinaboxserver.com/admin/dns/custom/_acme-challenge.$CERTBOT_DOMAIN/txt

With these scripts I can setup the below cron job to call certbot.

0 0 * * * /usr/bin/certbot renew --preferred-challenges=dns -q --manual-auth-hook /path/to/auth.sh --manual-cleanup-hook /path/to/cleanup.sh  > /dev/null 2>&1

Links

I don't have comments as I don't want to manage them. You can however contact me at the below address if you want to.

License

Copyright © 2021 David T. Sadler.