From bd8299d7b501234263a6aee98049f879b1c700b7 Mon Sep 17 00:00:00 2001 From: Aram Sargsyan Date: Wed, 21 Sep 2022 15:05:11 +0000 Subject: [PATCH] Document nsupdate options related to DoT Add documentation for the newly implemented DoT feature of the nsupdate program. --- bin/nsupdate/nsupdate.rst | 48 +++++++++++++++++++++++++++++++++- doc/man/nsupdate.1in | 54 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 100 insertions(+), 2 deletions(-) diff --git a/bin/nsupdate/nsupdate.rst b/bin/nsupdate/nsupdate.rst index 17ab96d421..8ce42b2f66 100644 --- a/bin/nsupdate/nsupdate.rst +++ b/bin/nsupdate/nsupdate.rst @@ -19,7 +19,7 @@ nsupdate - dynamic DNS update utility Synopsis ~~~~~~~~ -:program:`nsupdate` [**-d**] [**-D**] [**-i**] [**-L** level] [ [**-g**] | [**-o**] | [**-l**] | [**-y** [hmac:]keyname:secret] | [**-k** keyfile] ] [**-t** timeout] [**-u** udptimeout] [**-r** udpretries] [**-v**] [**-T**] [**-P**] [**-V**] [ [**-4**] | [**-6**] ] [filename] +:program:`nsupdate` [**-d**] [**-D**] [**-i**] [**-L** level] [ [**-g**] | [**-o**] | [**-l**] | [**-y** [hmac:]keyname:secret] | [**-k** keyfile] ] [ [**-S**] [**-K** tlskeyfile] [**-E** tlscertfile] [**-A** tlscafile] [**-H** tlshostname] [-O] ] [**-t** timeout] [**-u** udptimeout] [**-r** udpretries] [**-v**] [**-T**] [**-P**] [**-V**] [ [**-4**] | [**-6**] ] [filename] Description ~~~~~~~~~~~ @@ -71,6 +71,15 @@ Options This option sets use of IPv6 only. +.. option:: -A tlscafile + + This option specifies the file of the certificate authorities (CA) certificates + (in PEM format) in order to verify the remote server TLS certificate when + using DNS-over-TLS (DoT), to achieve Strict or Mutual TLS. When used, it will + override the certificates from the global certificates store, which are + otherwise used by default when :option:`-S` is enabled. This option can not + be used in conjuction with :option:`-O`, and it implies :option:`-S`. + .. option:: -C Overrides the default `resolv.conf` file. This is only intended for testing. @@ -84,10 +93,23 @@ Options This option sets extra debug mode. +.. option:: -E tlscertfile + + This option sets the certificate(s) file for authentication for the + DNS-over-TLS (DoT) transport to the remote server. The certificate + chain file is expected to be in PEM format. This option implies :option:`-S`, + and can only be used with :option:`-K`. + .. option:: -g This option enables standard GSS-TSIG mode. +.. option:: -H tlshostname + + This option makes :program:`nsupdate` use the provided hostname during remote + server TLS certificate verification. Otherwise, the DNS server name + is used. This option implies :option:`-S`. + .. option:: -i This option forces interactive mode, even when standard input is not a terminal. @@ -104,6 +126,13 @@ Options key used to authenticate Dynamic DNS update requests. In this case, the key specified is not an HMAC-MD5 key. +.. option:: -K tlskeyfile + + This option sets the key file for authenticated encryption for the + DNS-over-TLS (DoT) transport with the remote server. The private key file is + expected to be in PEM format. This option implies :option:`-S`, and can only + be used with :option:`-E`. + .. option:: -l This option sets local-host only mode, which sets the server address to localhost @@ -123,6 +152,14 @@ Options This option enables a non-standards-compliant variant of GSS-TSIG used by Windows 2000. +.. option:: -O + + This option enables Opportunistic TLS. When used, the remote peer's TLS + certificate will not be verified. This option should be used for debugging + purposes only, and it is not recommended to use it in production. This + option can not be used in conjuction with :option:`-A`, and it implies + :option:`-S`. + .. option:: -p port This option sets the port to use for connections to a name server. The default is @@ -138,6 +175,15 @@ Options This option sets the number of UDP retries. The default is 3. If zero, only one update request is made. +.. option:: -S + + This option indicates whether to use DNS-over-TLS (DoT) when querying + name servers specified by ``server servername port`` syntax in the input + file, and the primary server discovered through a SOA request. When the + :option:`-K` and :option:`-E` options are used, then the specified TLS + client certificate and private key pair are used for authentication + (Mutual TLS). This option implies :option:`-v`. + .. option:: -t timeout This option sets the maximum time an update request can take before it is aborted. The diff --git a/doc/man/nsupdate.1in b/doc/man/nsupdate.1in index d83bd49ccd..621d1e65e7 100644 --- a/doc/man/nsupdate.1in +++ b/doc/man/nsupdate.1in @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] nsupdate \- dynamic DNS update utility .SH SYNOPSIS .sp -\fBnsupdate\fP [\fB\-d\fP] [\fB\-D\fP] [\fB\-i\fP] [\fB\-L\fP level] [ [\fB\-g\fP] | [\fB\-o\fP] | [\fB\-l\fP] | [\fB\-y\fP [hmac:]keyname:secret] | [\fB\-k\fP keyfile] ] [\fB\-t\fP timeout] [\fB\-u\fP udptimeout] [\fB\-r\fP udpretries] [\fB\-v\fP] [\fB\-T\fP] [\fB\-P\fP] [\fB\-V\fP] [ [\fB\-4\fP] | [\fB\-6\fP] ] [filename] +\fBnsupdate\fP [\fB\-d\fP] [\fB\-D\fP] [\fB\-i\fP] [\fB\-L\fP level] [ [\fB\-g\fP] | [\fB\-o\fP] | [\fB\-l\fP] | [\fB\-y\fP [hmac:]keyname:secret] | [\fB\-k\fP keyfile] ] [ [\fB\-S\fP] [\fB\-K\fP tlskeyfile] [\fB\-E\fP tlscertfile] [\fB\-A\fP tlscafile] [\fB\-H\fP tlshostname] [\-O] ] [\fB\-t\fP timeout] [\fB\-u\fP udptimeout] [\fB\-r\fP udpretries] [\fB\-v\fP] [\fB\-T\fP] [\fB\-P\fP] [\fB\-V\fP] [ [\fB\-4\fP] | [\fB\-6\fP] ] [filename] .SH DESCRIPTION .sp \fBnsupdate\fP is used to submit Dynamic DNS Update requests, as defined in @@ -83,6 +83,16 @@ This option sets use of IPv6 only. .UNINDENT .INDENT 0.0 .TP +.B \-A tlscafile +This option specifies the file of the certificate authorities (CA) certificates +(in PEM format) in order to verify the remote server TLS certificate when +using DNS\-over\-TLS (DoT), to achieve Strict or Mutual TLS. When used, it will +override the certificates from the global certificates store, which are +otherwise used by default when \fI\%\-S\fP is enabled. This option can not +be used in conjuction with \fI\%\-O\fP, and it implies \fI\%\-S\fP\&. +.UNINDENT +.INDENT 0.0 +.TP .B \-C Overrides the default \fIresolv.conf\fP file. This is only intended for testing. .UNINDENT @@ -99,11 +109,26 @@ This option sets extra debug mode. .UNINDENT .INDENT 0.0 .TP +.B \-E tlscertfile +This option sets the certificate(s) file for authentication for the +DNS\-over\-TLS (DoT) transport to the remote server. The certificate +chain file is expected to be in PEM format. This option implies \fI\%\-S\fP, +and can only be used with \fI\%\-K\fP\&. +.UNINDENT +.INDENT 0.0 +.TP .B \-g This option enables standard GSS\-TSIG mode. .UNINDENT .INDENT 0.0 .TP +.B \-H tlshostname +This option makes \fBnsupdate\fP use the provided hostname during remote +server TLS certificate verification. Otherwise, the DNS server name +is used. This option implies \fI\%\-S\fP\&. +.UNINDENT +.INDENT 0.0 +.TP .B \-i This option forces interactive mode, even when standard input is not a terminal. .UNINDENT @@ -122,6 +147,14 @@ the key specified is not an HMAC\-MD5 key. .UNINDENT .INDENT 0.0 .TP +.B \-K tlskeyfile +This option sets the key file for authenticated encryption for the +DNS\-over\-TLS (DoT) transport with the remote server. The private key file is +expected to be in PEM format. This option implies \fI\%\-S\fP, and can only +be used with \fI\%\-E\fP\&. +.UNINDENT +.INDENT 0.0 +.TP .B \-l This option sets local\-host only mode, which sets the server address to localhost (disabling the \fBserver\fP so that the server address cannot be @@ -144,6 +177,15 @@ used by Windows 2000. .UNINDENT .INDENT 0.0 .TP +.B \-O +This option enables Opportunistic TLS. When used, the remote peer\(aqs TLS +certificate will not be verified. This option should be used for debugging +purposes only, and it is not recommended to use it in production. This +option can not be used in conjuction with \fI\%\-A\fP, and it implies +\fI\%\-S\fP\&. +.UNINDENT +.INDENT 0.0 +.TP .B \-p port This option sets the port to use for connections to a name server. The default is 53. @@ -162,6 +204,16 @@ request is made. .UNINDENT .INDENT 0.0 .TP +.B \-S +This option indicates whether to use DNS\-over\-TLS (DoT) when querying +name servers specified by \fBserver servername port\fP syntax in the input +file, and the primary server discovered through a SOA request. When the +\fI\%\-K\fP and \fI\%\-E\fP options are used, then the specified TLS +client certificate and private key pair are used for authentication +(Mutual TLS). This option implies \fI\%\-v\fP\&. +.UNINDENT +.INDENT 0.0 +.TP .B \-t timeout This option sets the maximum time an update request can take before it is aborted. The default is 300 seconds. If zero, the timeout is disabled.