dehydrated-nsupdate(1)

Name
dehydrated-nsupdate - dehydrated hook for dns-01 verification

Synopsis
dehydrated-nsupdate

Description

dehydrated is a client for ACME-based Certificate Authorities, such as LetsEncrypt. It can be used to request and obtain TLS certificates from an ACME-based certificate authority.

The dehydrated-nsupdate hook implements the dns-01 verification. It is typically run together with dehydrated-hook as:

/etc/dehydrated/hook.d/deploy_challenge.nsupdate
/etc/dehydrated/hook.d/clean_challenge.nsupdate

Features

dehydrated-nsupdate has the following features:

  Automatic nameserver detection (IPv4 and IPv6)

dehydrated-nsupdate automatically finds and updates all authoritative nameservers for a given record by looking up the records in the DNS by itself, supporting IPv6-only, IPv4-only, and dual-stacked environments.

  Proper CNAME support

dehydrated-nsupdate follows CNAMEs delegating the TXT record update to another zone.

  Handling nameserver subzone shortcuts

dehydrated-nsupdate correctly handles authoritative nameserver answers that (wrongly) give shortcut answers for their own zones when using multiple authoritative subzones on the same nameservers.

  TSIG support

dehydrated-nsupdate uses TSIG, if provided, to authenticate itself to the nameserver. Additionally to a global TSIG to be used for all record updates, separate TSIGs can individually be specified per record, per zone, and per nameserver.

  Proper removal of TXT records

dehydrated-nsupdate removes records after succesfull verification.

  bind9-dnsutils and knot-dnsutils support

dehydrated-nsupdate works with both nsupdate (bind9) and knsupdate (knot).

  IDN handling

dehydrated-nsupdate works with IDN domains by not expanding the punycode to update the correct records.

Usage

dehydrated-hook(1) is a prerequisite for dehydrated-nsupdate.

  Installation
sudo echo CHALLENGETYPE="dns-01" > /etc/dehydrated/conf.d/zz-challengetype.sh
sudo ln -s /usr/bin/dehydrated-nsupdate /etc/dehydrated/hook.d/deploy_challenge.nsupdate
sudo ln -s /usr/bin/dehydrated-nsupdate /etc/dehydrated/hook.d/clean_challenge.nsupdate

  Removal
sudo rm -f /etc/dehydrated/conf.d/zz-challengetype.sh
sudo rm -f /etc/dehydrated/hook.d/deploy_challenge.nsupdate
sudo rm -f /etc/dehydrated/hook.d/clean_challenge.nsupdate

Configuration

Depending on the nameserver requirements, dehydrated-nsupdate can send record updates either unauthenticated or using a TSIG (recommended).

A TSIG file consists of one single line containing the key (nsupdate/knsupdate do not allow comments), e.g.:

hmac-sha512:example:/LXPy6U8HAWA+QmvulZWm0owsQgNf8qJ5MNLTvirzvVtDb+PzLKoBmVHjnL6TUffkvRYa7Do448dSIrAuJ1G/A==

Instead of using a global TSIG for all record update, specific TSIGs can be used individually per record, zone, and nameserver.

The lookup hierarchy is the following (first match wins):

/etc/dehydrated/tsig/${record}.key
/etc/dehydrated/tsig/${zone}.key
/etc/dehydrated/tsig/${nameserver}.key
/etc/dehydrated/tsig.key

TSIG_KEYFILE variable in /etc/default/dehydrated-nsupdate/*
TSIG_KEYFILE variable in /etc/default/dehydrated-nsupdate

In order to explicitly not use a TSIG for a specific record, zone, or nameserver, an empty keyfile or a keyfile with only comments can be used, e.g.:

echo "# disabled" > /etc/dehydrated/tsig/ns1.example.org.key

Files

The following files are used:

    /etc/dehydrated/tsig.key:
        default location for global TSIG key to be used.

    /etc/dehydrated/tsig/${record}.key, /etc/dehydrated/tsig/${zone}.key, /etc/dehydrated/tsig/${nameserver}.key:
        default locations for specific TSIG keys to be used individually per record, zone, or nameserver.

    /etc/default/dehydrated-nsupdate, /etc/default/dehydrated-nsupdate.d/*:
        configuration file, currently only used for TSIG_KEYFILE variable pointing to the location of the global TSIG key to be used (default: /etc/dehydrated/tsig.key).

See also
dehydrated(1),
dehydrated-cron(1),
dehydrated-hook(1).

Homepage

More information about dehydrated-tools-extra can be found on the homepage (<https://open-infrastructure.net>).

Contact

Bug reports, feature requests, help, patches, support and everything else are welcome on <https://git.open-infrastructure.net>.

Debian specific bugs can also be reported in the Debian Bug Tracking System (<https://bugs.debian.org>).

Authors

dehydrated-tools-extra was written by Daniel Baumann <<daniel@debian.org>>.