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 ; 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  -d * --email your.e@mail.address --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

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 -d * --email your.e@mail.address --preferred-challenges dns


certbot-auto will now output something similar

Please deploy a DNS TXT record under the name with the following value:


Before continuing, verify the record is deployed.


So please go to your DNS Server and create the following entry:     IN      TXT      FgeTB81JPaGJgdueVs2dfasGaBxqfetBl-4AkAZbw

Verify the entry in another console window by writing:

dig TXT +short
host -t txt

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
"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:
Donating to EFF:

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: