ddns-tsig hook for dehydrated

This repository contains a python hook for the dehydrated project, a Let's Encrypt/ACME client implemented as a shell script. This hook uses the dnspython API to perform dynamic DNS updates and queries to verify. The DNS challenge is outlined in the ACME protocol. To successfully complete this challenge, the client creates a temporary TXT record containing a secret token for the given domain name, thereby proving ownership of the domain.

Required Python libraries

dnspython - a DNS toolkit used for queries, zone transfers, and dynamic updates
(optional) iscpy - an ISC config file parser (only needed when reading keys from an extra file)

Installation

Download the files for installation

$ git clone https://github.com/lukas2511/dehydrated.git
$ mkdir -p dehydrated/hooks/ddns-tsig
$ git clone https://github.com/eferdman/dehydrated-hook-ddns-tsig.git dehydrated/hooks/ddns-tsig

Configuration

The script reads a configuration file as specified via the cmdline (using the --config flag), falling back to these default config files:

$(pwd)/dehydrated-hook-ddns-tsig.conf
/etc/dehydrate/dehydrated-hook-ddns-tsig.conf
/usr/local/etc/dehydrate/dehydrated-hook-ddns-tsig.conf

The configuration file uses a simple INI-style syntax, where you can set the parameters for each domain separately (by creating a section named after the domain), with default values in the [DEFAULT] section.

The following parameters can be set:

name_server_ip the DNS server IP that will serve the ACME challenge (required)
TTL time-to-live value for the challenge (default: 300)
wait time - in seconds - to wait before verifying that the challenge is really deployed/deleted; use negative values to skip the check (default: 5)
verbosity verbosity of the script: use negative values to suppress more messages (default: 0)
key_name name of the key to use for authentication with the DNS server (required, see below)
key_secret the base64-encoded key secret (required, see below)
key_algorithm the hashing algorithm of the key (default: hmac-md5)
dns_rewrite a regular expression to rewrite the DNS record used to publish the challenge (default: no rewriting)

A complete example can be found in the dehydrated-hook-ddns-tsig.conf file.

Using an extra key file

If you do not want to specify key name and key secret in the config file, you can provide that information in an extra file.

The script reads the name of this key file from the environmental variable DDNS_HOOK_KEY_FILE

$ export DDNS_HOOK_KEY_FILE="path/to/key/file.key"

The file must be formatted in an rndc/bind compatible way, e.g. like:

key "testkey" {
   secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
   algorithm = hmac-md5;
};

Only when using this method for acquiring the key, you must have iscpy installed.

Usage

See the dehydrated script for more options.

$ cd dehydrated
$ ./dehydrated -c --challenge dns-01 --domain myblog.com --hook ./hooks/ddns-tsig/dehydrated-hook-ddns-tsig.py

Or to test the script directly:

$ python dehydrated-hook-ddns-tsig.py deploy_challenge yourdomain.com - "Hello World"
$ python dehydrated-hook-ddns-tsig.py clean_challenge yourdomain.com - "Hello World"

Contribute

Please open an issue or submit a pull request.

eferdman / dehydrated-hook-ddns-tsig