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:
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 firstname.lastname@example.org --preferred-challenges dns
For Staging reasons you can use the following endpoint (similar to –dry-run)
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 email@example.com --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:
which you’re able to use right out of the box. For usage please read the corresponding documentation here.
A tool offering more DNS Provider support is the Acme Bash Script which can be found here: https://github.com/Neilpang/acme.sh