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:
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 email@example.com --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 firstname.lastname@example.org --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:
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
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
- Congratulations! Your certificate and chain have been saved at:
Your key file has been saved at:
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
- 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