Let's Encrypt

PDNS Manager allows you to easily use the service of the fully automated CA Let's Encrypt or any other ACME compiliant CA by using the dehydrated client in combination with the PDNS Manager API.

Getting required components

The software depends on the following tools:

On Debian you can install those using:

sudo apt-get install openssl jq curl git

Afterwards, change into the directory you want the tools located at and issue the following command:

git clone --recurse-submodules https://github.com/loewexy/pdns-acme

Initializing the Software

Switch to the directory of pdns-acme and run:

./pdns-acme init

Add domain to use

Issue:

./pdns-acme key

and copy the output to your clipboard.

In the next step, open a browser and login to your PDNS Manager instance. Add a record to your domain with the name _acme-challenge.<yourdomain>, type TXT and content none. Use a Priority of 0 and a TTL of 60.

Afterwards, click on key icon, which is the last icon in the row of the record. Click on Key. Enter a description like ACME and paste the public key from your clipboard into the field. Confirm with Save.

Configure pdns-acme

Copy the example configuration:

cp pdns-acme.json.example pdns-acme.json

Open the file pdns-acme.json with an editor of your choice. In the config section adjust the path of your PDNS Manager installation and the deploy-wait value. The deploy-wait parameter determines how long the script should wait for the DNS servers to get the right results. This value depends on your nameserver setup. The default of 120 should do well for most setups. After these changes, the section looks like the following:

"config": {
        "server": "https://<yourdomain>/",
        "deploy-wait": 300
    }

Add domain names to the config

In the section domains you must add an entry for every name you want to have on any certificate. It is, as can be seen from the example, a dictionary mapping domain names to the record ids of the matching _acme-challenge. record.

Configure certificates

In the section certs you can configure which certificates are generated. It is a dictionary where the key is the primary ceritificate name, the value is a dictionary, which can have two properties. "alias" stores an array of strings with alternative domain names. "hook" can be a string or array of strings, with commands executed if the certificate was changed. This can be used e.g. to restart a webserver using the certificate.

Run pdns-acme

Now you can issue

./pdna-acme cron

to start the process. If there are no errors you will have a directory "certs" with your certificates.

Automate renewal

For automatic renewal of your certificates, add an entry to /etc/crontab as follows:

0 2     * * *   root    /root/pdns-acme/pdns-acme cron

Advanced options

You can use other options, which dehydrated supports. Those can be looked up in its documentation. Config options can be put in a file called "dehydrated.config" in the pdns-acme directory. Its content will be appended to the config generated by pdns-acme.