.. Open Infrastructure: service-tools .. Copyright (C) 2014-2022 Daniel Baumann .. .. SPDX-License-Identifier: GPL-3.0+ .. .. This program is free software: you can redistribute it and/or modify .. it under the terms of the GNU General Public License as published by .. the Free Software Foundation, either version 3 of the License, or .. (at your option) any later version. .. .. This program is distributed in the hope that it will be useful, .. but WITHOUT ANY WARRANTY; without even the implied warranty of .. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .. GNU General Public License for more details. .. .. You should have received a copy of the GNU General Public License .. along with this program. If not, see . =================== dehydrated-nsupdate =================== --------------------------------------- dehydrated hook for dns-01 verification --------------------------------------- :manual section: 1 :manual group: Open Infrastructure 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 service-tools and the Open Infrastructure project can be found on the homepage (https://open-infrastructure.net). Contact ======= Bug reports, feature requests, help, patches, support and everything else are welcome on the Open Infrastructure Software Mailing List . Debian specific bugs can also be reported in the Debian Bug Tracking System (https://bugs.debian.org). Authors ======= service-tools were written by Daniel Baumann and others.