How to use Certbot to c reate LetsEncrypt Wildcard Certificates using ACME API version 2

Here’s my documentation on how i got my wildcard working from Letsencrypt via the newly released API v2.

Please note that we already got the backported certbot version installed on our servers !.

 

First, you’ll need a client that is capable of the new API version 2. Here’s a list of clients and their capabilities.

For certbot using wildcards, you’ll a version higher than 0.22.0 is required (Certbot >= 0.22.0).

 

Certbot Installation (latest version >0.22)

So, how do i get certbot running on my system ?

We are running nearly everything on debian, so the following was tested on debian only, but should work on other unix’es as well.

The easiest thing might be to use certbot-auto since it will always stay on the latest version.

So here’s how to go (based on the original manual):

mkdir /opt/certbot/ ; cd /opt/certbot/ ; wget https://dl.eff.org/certbot-auto ; chmod a+x certbot-auto ; ./certbot-auto

This will create a directory (/opt/certbot) download the certbot-auto script and run the certbot-auto script.

It might happen that the certbot-auto script will ask you to install some missing dependencies via the apt package manager. This should be approved by hitting “y”.

The following NEW packages will be installed:
... 
After this operation, XX MB of additional disk space will be used.
Do you want to continue? [Y/n] y

So after successfully solving all the dependencies, we’re now able to check the version:

/opt/certbot/certbot-auto --version

Should return

certbot 0.22.0 (or higher !)

 

This works while we still have our “old” certbot installed from debian backported packages:

/usr/bin/certbot --version
certbot 0.10.2

 

Obtaining a Wildcard Cert

So, let’s get us a wildcard certificate now !

By firing this line, certbot will start the manual certificate obtaining process

/opt/certbot/certbot-auto certonly --manual --server https://acme-v02.api.letsencrypt.org/directory  -d *.yourdomain.ninja --email your.e@mail.address --preferred-challenges dns

 

For Staging reasons you can use the following endpoint (similar to –dry-run)

https://acme-staging-v02.api.letsencrypt.org/directory

But please be aware that there currently is a bug within certbot (and apiv2 usage) that we can not run –dry-run (do nothing) against –server https://acme-staging-v02.api.letsencrypt.org/directory

For testing issues we recommend the following line:

Adding the “–config-dir /tmp/certbot-testing/” argument will give us some safer environment to test.

/opt/certbot/certbot-auto certonly --manual --config-dir /tmp/certbot-testing/ --server https://acme-staging-v02.api.letsencrypt.org/directory -d *.yourdomain.ninja --email your.e@mail.address --preferred-challenges dns

 

certbot-auto will now output something similar

-------------------------------------------------------------------------------
Please deploy a DNS TXT record under the name
_acme-challenge.yourdomain.ninja with the following value:

FgeTB81JPaGJgdueVs2dfasGaBxqfetBl-4AkAZbw

Before continuing, verify the record is deployed.
-------------------------------------------------------------------------------

 

So please go to your DNS Server and create the following entry:

_acme-challenge.yourdomain.ninja     IN      TXT      FgeTB81JPaGJgdueVs2dfasGaBxqfetBl-4AkAZbw

Verify the entry in another console window by writing:

dig _acme-challenge.yourdomain.ninja TXT +short
or 
host -t txt _acme-challenge.yourdomain.ninja

Both should return the AUTH token you just setup. Please keep in mind that a DNS change might take some time – maybe even hours (depending on your server configuration) !!

 

If we’re sure that the entry is set – we hit ENTER in the certbot-auto console window

Waiting for verification...
Cleaning up challenges


IMPORTANT NOTES:
- Congratulations! Your certificate and chain have been saved at:
/your/config/path/.letsencrypt_certs/live/yourdomain.ninja/fullchain.pem
Your key file has been saved at:
/your/config/path/.letsencrypt_certs/live/yourdomain.ninja/privkey.pem
Your cert will expire on 2018-06-13. To obtain a new or tweaked
version of this certificate in the future, simply run certbot-auto
again. To non-interactively renew *all* of your certificates, run
"certbot-auto renew"
- Your account credentials have been saved in your Certbot
configuration directory at /your/config/path/.letsencrypt_certs You should
make a secure backup of this folder now. This configuration
directory will also contain certificates and private keys obtained
by Certbot so making regular backups of this folder is ideal.
- If you like Certbot, please consider supporting our work by:

Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate
Donating to EFF: https://eff.org/donate-le

Cool – we’re done !!!

 

Renewal and automation

Since we’ve chosen –manual as a flag, we have to modify the DNS TXT entry for _acme-challenge upon every renewal.

This is quite odd, so there are a lot of DNS plugins available for certbot-auto:

certbot-dns-cloudflare
certbot-dns-cloudxns
certbot-dns-digitalocean
certbot-dns-dnsimple
certbot-dns-dnsmadeeasy
certbot-dns-google
certbot-dns-luadns
certbot-dns-nsone
certbot-dns-rfc2136
certbot-dns-route53

which you’re able to use right out of the box. For usage please read the corresponding documentation here.

 

FootNotes

A tool offering more DNS Provider support is the Acme Bash Script which can be found here: https://github.com/Neilpang/acme.sh