Merging upstream version 20220614.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 88 insertions, 39 deletions

diff --git a/dehydrated/share/man/dehydrated-nsupdate.1.rst b/dehydrated/share/man/dehydrated-nsupdate.1.rst
index db58d5c..059a269 100644
--- a/dehydrated/share/man/dehydrated-nsupdate.1.rst
+++ b/dehydrated/share/man/dehydrated-nsupdate.1.rst
@@ -36,15 +36,12 @@ Synopsis
 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.
+**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:
+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
@@ -52,32 +49,87 @@ Features
 
 **dehydrated-nsupdate** has the following features:
 
-| **automatic nameserver detection**
-| **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.
+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
+------------
 
-| **proper CNAME support**
-| **dehydrated-nsupdate** follows CNAMEs delegating the TXT record creation to
-| another zone.
+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.
 
-| **handling nameserver subzone shortcuts**
-| **dehydrated-nsupdate** correctly handles authoritative nameserver
-| answers that give shortcut answers for their own zones when using
-| multiple subzones.
+Proper removal of TXT records
+-----------------------------
 
-| **TSIG support**
-| **dehydrated-nsupdate** uses TSIG, if provided, to authenticate
-| itself to the nameserver.
+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
+=====
 
-| **proper removal of TXT records**
-| **dehydrated-nsupdate** removes records after succesfull verification.
+dehydrated-hook(1) is a prerequisite for dehydrated-nsupdate.
 
-| **bind9-dnsutils and knot-dnsutils support*
-| **dehydrated-nsupdate** works with both nsupdate (bind9) and knsupdate (knot).
+Installation
+------------
 
-| **IDN handling**
-| **dehydrated-nsupdate** works with IDN domains by not expanding the punycode.
+| 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 (earliest 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
 =====
@@ -85,11 +137,13 @@ Files
 The following files are used:
 
 /etc/dehydrated/tsig.key:
-  default location for the TSIG key to be used.
+  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 tsig.key file to be used (default: /etc/dehydrated/tsig.key).
+/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
 ========
@@ -101,21 +155,16 @@ See also
 Homepage
 ========
 
-More information about service-tools and the Open Infrastructure project can be
-found on the homepage (https://open-infrastructure.net).
+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
-<software@lists.open-infrastructure.net>.
+Bug reports, feature requests, help, patches, support and everything else are welcome on the Open Infrastructure Software Mailing List <software@lists.open-infrastructure.net>.
 
-Debian specific bugs can also be reported in the Debian Bug Tracking System
-(https://bugs.debian.org).
+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
-<daniel.baumann@open-infrastructure.net> and others.
+service-tools were written by Daniel Baumann <daniel.baumann@open-infrastructure.net> and others.