Let's Encrypt SSL DNS validation
Using Mythic Beasts DNS API to validate Let's Encrypt SSL certificates
This page gives a step-by-step guide for issuing Let's Encrypt SSL certificates with DNS validation (dns-01) using our DNS API.
If you have a hosting account with us, you don't need to follow this guide. Support for Let's Encrypt is fully automated for hosting accounts, and you can enable a certificate for your website using our control panel.
Let's Encrypt is a service providing free SSL certificates, using domain validation to ensure that certificates are issued only to the legitimate owner of a domain. Let's Encrypt provide a number of options for performing domain validation. If you only need certificates for a web server, it's simpler to use the default web validation. For other applications, for example if you need a certificate for a mail server, DNS-based validation is ideal. It requires specific TXT records to be inserted into the DNS zone for a domain. This can be fully automated using our DNS API, as described on this page.
1. Enable DNS API for your domain
Log into the Mythic Beasts customer control panel, click on My Domains and then on the domain in question, and then the DNS API link in the Nameservers and DNS section.
This page will prompt you to set a password for the DNS API for your domain.
2. Install dehydrated
Our code is a hook for the dehydrated client. Dehydrated is packaged for Debian: it's available in the main stretch repo, and jessie-backports. The latter will also work on wheezy at a pinch.
You'll also need the dig utility.
apt-get install dehydrated dnsutils
3. Download the Mythic Beasts hook script
The hook script is a script that makes the necessary requests to our DNS API. Download it to /etc/dehydrated
:
cd /etc/dehydrated wget https://github.com/mythic-beasts/letsencrypt-mythic-dns01/raw/master/letsencrypt-mythic-dns01.sh chmod 0700 letsencrypt-mythic-dns01.shThere is also a Perl version of the script, or you can clone the git repo
4. Configure required certificates
Create /etc/dehydrated/domains.txt
containing one
line for each certificate required. Each line should start with the
name of the domain, followed by any aliases (alternate names) that you want
included in the certificate under that domain. For example:
example.com www.example.com example.net www.example.net subdomain.example.net
5. Create password file
Create /etc/dehydrated/dnsapi.config.txt
containing the DNS API passwords for
your domain(s). This file should have one domain per line, with the name of the
domain and the password separated by a space:
example.com myS3cretPassword example.net myOtherS3ret
It is recommended to limit access to this file:
chmod 0600 dnsapi.config.txt
If you want to put this file elsewhere, put the path to the file in
MYTHIC_DNS_CONFIG
6. Configure dehydrated to use the hook script
echo HOOK=/etc/dehydrated/letsencrypt-mythic-dns01.sh > /etc/dehydrated/conf.d/hook.sh echo CHALLENGETYPE=dns-01 >> /etc/dehydrated/conf.d/hook.sh
You should also configure your email address. Let's Encrypt will email a warning if a certificate is nearing its expiry date and has not been renewed.
echo CONTACT_EMAIL=me@example.com > /etc/dehydrated/conf.d/mail.sh
7. (optional) Test with the Let's Encrypt staging service
The Let's Encrypt API limits the number of certificates that you can issue each week. For testing, you may wish to use the staging service. To do this:
echo CA=https://acme-staging.api.letsencrypt.org/directory > /etc/dehydrated/conf.d/staging.sh echo BASEDIR=/tmp/dehydrated >> /etc/dehydrated/conf.d/staging.sh mkdir /tmp/dehydrated
Once you have finished testing, delete this file.
8. Generate initial certificates
Invoke dehydrated:
dehydrated -c
This can take a little while to run, especially if you have multiple names in the certificate. Our DNS API only updates new records once a minute, and we have to wait separately for each challenge to go live.
If successful, the requested SSL certificates are placed in
/var/lib/dehydrated/certs
9. Configure certificate renewal
You will need to arrange for dehydrated -c
to run regularly. It will renew any certificates that are due to expire in the next 30 days.
cat > /etc/cron.daily/dehydrated <<EOF #!/bin/sh exec /usr/bin/dehydrated -c >>/var/log/dehydrated-cron.log 2>&1 EOF chmod 0755 /etc/cron.daily/dehydrated cat > /etc/logrotate.d/dehydrated <<EOF /var/log/dehydrated-cron.log { rotate 12 monthly missingok notifempty delaycompress compress } EOF