diff --git a/bin/nsupdate/nsupdate.1 b/bin/nsupdate/nsupdate.1 index ca5ae4595c..a97c41b809 100644 --- a/bin/nsupdate/nsupdate.1 +++ b/bin/nsupdate/nsupdate.1 @@ -1,4 +1,4 @@ -.\" Copyright (C) 2004-2012, 2014 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2004-2012, 2014, 2015 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2000-2003 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and/or distribute this software for any @@ -33,7 +33,7 @@ nsupdate \- Dynamic DNS update utility .SH "SYNOPSIS" .HP 9 -\fBnsupdate\fR [\fB\-d\fR] [\fB\-D\fR] [[\fB\-g\fR] | [\fB\-o\fR] | [\fB\-l\fR] | [\fB\-y\ \fR\fB\fI[hmac:]\fR\fIkeyname:secret\fR\fR] | [\fB\-k\ \fR\fB\fIkeyfile\fR\fR]] [\fB\-t\ \fR\fB\fItimeout\fR\fR] [\fB\-u\ \fR\fB\fIudptimeout\fR\fR] [\fB\-r\ \fR\fB\fIudpretries\fR\fR] [\fB\-R\ \fR\fB\fIrandomdev\fR\fR] [\fB\-v\fR] [\fB\-T\fR] [\fB\-P\fR] [\fB\-V\fR] [filename] +\fBnsupdate\fR [\fB\-d\fR] [\fB\-D\fR] [\fB\-L\ \fR\fB\fIlevel\fR\fR] [[\fB\-g\fR] | [\fB\-o\fR] | [\fB\-l\fR] | [\fB\-y\ \fR\fB\fI[hmac:]\fR\fIkeyname:secret\fR\fR] | [\fB\-k\ \fR\fB\fIkeyfile\fR\fR]] [\fB\-t\ \fR\fB\fItimeout\fR\fR] [\fB\-u\ \fR\fB\fIudptimeout\fR\fR] [\fB\-r\ \fR\fB\fIudpretries\fR\fR] [\fB\-R\ \fR\fB\fIrandomdev\fR\fR] [\fB\-v\fR] [\fB\-T\fR] [\fB\-P\fR] [\fB\-V\fR] [filename] .SH "DESCRIPTION" .PP \fBnsupdate\fR @@ -47,53 +47,148 @@ The resource records that are dynamically added or removed with \fBnsupdate\fR have to be in the same zone. Requests are sent to the zone's master server. This is identified by the MNAME field of the zone's SOA record. .PP -The -\fB\-d\fR -option makes -\fBnsupdate\fR -operate in debug mode. This provides tracing information about the update requests that are made and the replies received from the name server. +Transaction signatures can be used to authenticate the Dynamic DNS updates. These use the TSIG resource record type described in RFC 2845 or the SIG(0) record described in RFC 2535 and RFC 2931 or GSS\-TSIG as described in RFC 3645. .PP -The -\fB\-D\fR -option makes +TSIG relies on a shared secret that should only be known to \fBnsupdate\fR -report additional debugging information to -\fB\-d\fR. -.PP -The -\fB\-L\fR -option with an integer argument of zero or higher sets the logging debug level. If zero, logging is disabled. -.PP -Transaction signatures can be used to authenticate the Dynamic DNS updates. These use the TSIG resource record type described in RFC 2845 or the SIG(0) record described in RFC 2535 and RFC 2931 or GSS\-TSIG as described in RFC 3645. TSIG relies on a shared secret that should only be known to -\fBnsupdate\fR -and the name server. Currently, the only supported encryption algorithm for TSIG is HMAC\-MD5, which is defined in RFC 2104. Once other algorithms are defined for TSIG, applications will need to ensure they select the appropriate algorithm as well as the key when authenticating each other. For instance, suitable +and the name server. For instance, suitable \fBkey\fR and \fBserver\fR statements would be added to \fI/etc/named.conf\fR -so that the name server can associate the appropriate secret key and algorithm with the IP address of the client application that will be using TSIG authentication. SIG(0) uses public key cryptography. To use a SIG(0) key, the public key must be stored in a KEY record in a zone served by the name server. +so that the name server can associate the appropriate secret key and algorithm with the IP address of the client application that will be using TSIG authentication. You can use +\fBddns\-confgen\fR +to generate suitable configuration fragments. \fBnsupdate\fR -does not read -\fI/etc/named.conf\fR. +uses the +\fB\-y\fR +or +\fB\-k\fR +options to provide the TSIG shared secret. These options are mutually exclusive. +.PP +SIG(0) uses public key cryptography. To use a SIG(0) key, the public key must be stored in a KEY record in a zone served by the name server. .PP GSS\-TSIG uses Kerberos credentials. Standard GSS\-TSIG mode is switched on with the \fB\-g\fR flag. A non\-standards\-compliant variant of GSS\-TSIG used by Windows 2000 can be switched on with the \fB\-o\fR flag. +.SH "OPTIONS" .PP -\fBnsupdate\fR -uses the -\fB\-y\fR -or +\-d +.RS 4 +Debug mode. This provides tracing information about the update requests that are made and the replies received from the name server. +.RE +.PP +\-D +.RS 4 +Extra debug mode. +.RE +.PP +\-k \fIkeyfile\fR +.RS 4 +The file containing the TSIG authentication key. Keyfiles may be in two formats: a single file containing a +\fInamed.conf\fR\-format +\fBkey\fR +statement, which may be generated automatically by +\fBddns\-confgen\fR, or a pair of files whose names are of the format +\fIK{name}.+157.+{random}.key\fR +and +\fIK{name}.+157.+{random}.private\fR, which can be generated by +\fBdnssec\-keygen\fR. The \fB\-k\fR -option to provide the shared secret needed to generate a TSIG record for authenticating Dynamic DNS update requests, default type HMAC\-MD5. These options are mutually exclusive. +may also be used to specify a SIG(0) key used to authenticate Dynamic DNS update requests. In this case, the key specified is not an HMAC\-MD5 key. +.RE .PP -When the -\fB\-y\fR -option is used, a signature is generated from -[\fIhmac:\fR]\fIkeyname:secret.\fR +\-l +.RS 4 +Local\-host only mode. This sets the server address to localhost (disabling the +\fBserver\fR +so that the server address cannot be overridden). Connections to the local server will use a TSIG key found in +\fI/var/run/named/session.key\fR, which is automatically generated by +\fBnamed\fR +if any local master zone has set +\fBupdate\-policy\fR +to +\fBlocal\fR. The location of this key file can be overridden with the +\fB\-k\fR +option. +.RE +.PP +\-L \fIlevel\fR +.RS 4 +Set the logging debug level. If zero, logging is disabled. +.RE +.PP +\-p \fIport\fR +.RS 4 +Set the port to use for connections to a name server. The default is 53. +.RE +.PP +\-P +.RS 4 +Print the list of private BIND\-specific resource record types whose format is understood by +\fBnsupdate\fR. See also the +\fB\-T\fR +option. +.RE +.PP +\-r \fIudpretries\fR +.RS 4 +The number of UDP retries. The default is 3. If zero, only one update request will be made. +.RE +.PP +\-R \fIrandomdev\fR +.RS 4 +Where to obtain randomness. If the operating system does not provide a +\fI/dev/random\fR +or equivalent device, the default source of randomness is keyboard input. +\fIrandomdev\fR +specifies the name of a character device or file containing random data to be used instead of the default. The special value +\fIkeyboard\fR +indicates that keyboard input should be used. This option may be specified multiple times. +.RE +.PP +\-t \fItimeout\fR +.RS 4 +The maximum time an update request can take before it is aborted. The default is 300 seconds. Zero can be used to disable the timeout. +.RE +.PP +\-T +.RS 4 +Print the list of IANA standard resource record types whose format is understood by +\fBnsupdate\fR. +\fBnsupdate\fR +will exit after the lists are printed. The +\fB\-T\fR +option can be combined with the +\fB\-P\fR +option. +.sp +Other types can be entered using "TYPEXXXXX" where "XXXXX" is the decimal value of the type with no leading zeros. The rdata, if present, will be parsed using the UNKNOWN rdata format, ( ). +.RE +.PP +\-u \fIudptimeout\fR +.RS 4 +The UDP retry interval. The default is 3 seconds. If zero, the interval will be computed from the timeout interval and number of UDP retries. +.RE +.PP +\-v +.RS 4 +Use TCP even for small update requests. By default, +\fBnsupdate\fR +uses UDP to send update requests to the name server unless they are too large to fit in a UDP request in which case TCP will be used. TCP may be preferable when a batch of update requests is made. +.RE +.PP +\-V +.RS 4 +Print the version number and exit. +.RE +.PP +\-y \fI[hmac:]\fR\fIkeyname:secret\fR +.RS 4 +Literal TSIG authentication key. \fIkeyname\fR is the name of the key, and \fIsecret\fR @@ -108,96 +203,14 @@ hmac\-sha384, or hmac\-sha512. If \fIhmac\fR is not specified, the default is -hmac\-md5. NOTE: Use of the +hmac\-md5. +.sp +NOTE: Use of the \fB\-y\fR option is discouraged because the shared secret is supplied as a command line argument in clear text. This may be visible in the output from \fBps\fR(1) or in a history file maintained by the user's shell. -.PP -With the -\fB\-k\fR -option, -\fBnsupdate\fR -reads the shared secret from the file -\fIkeyfile\fR. Keyfiles may be in two formats: a single file containing a -\fInamed.conf\fR\-format -\fBkey\fR -statement, which may be generated automatically by -\fBddns\-confgen\fR, or a pair of files whose names are of the format -\fIK{name}.+157.+{random}.key\fR -and -\fIK{name}.+157.+{random}.private\fR, which can be generated by -\fBdnssec\-keygen\fR. The -\fB\-k\fR -may also be used to specify a SIG(0) key used to authenticate Dynamic DNS update requests. In this case, the key specified is not an HMAC\-MD5 key. -.PP -\fBnsupdate\fR -can be run in a local\-host only mode using the -\fB\-l\fR -flag. This sets the server address to localhost (disabling the -\fBserver\fR -so that the server address cannot be overridden). Connections to the local server will use a TSIG key found in -\fI/var/run/named/session.key\fR, which is automatically generated by -\fBnamed\fR -if any local master zone has set -\fBupdate\-policy\fR -to -\fBlocal\fR. The location of this key file can be overridden with the -\fB\-k\fR -option. -.PP -By default, -\fBnsupdate\fR -uses UDP to send update requests to the name server unless they are too large to fit in a UDP request in which case TCP will be used. The -\fB\-v\fR -option makes -\fBnsupdate\fR -use a TCP connection. This may be preferable when a batch of update requests is made. -.PP -The -\fB\-p\fR -sets the default port number to use for connections to a name server. The default is 53. -.PP -The -\fB\-t\fR -option sets the maximum time an update request can take before it is aborted. The default is 300 seconds. Zero can be used to disable the timeout. -.PP -The -\fB\-u\fR -option sets the UDP retry interval. The default is 3 seconds. If zero, the interval will be computed from the timeout interval and number of UDP retries. -.PP -The -\fB\-r\fR -option sets the number of UDP retries. The default is 3. If zero, only one update request will be made. -.PP -The -\fB\-R \fR\fB\fIrandomdev\fR\fR -option specifies a source of randomness. If the operating system does not provide a -\fI/dev/random\fR -or equivalent device, the default source of randomness is keyboard input. -\fIrandomdev\fR -specifies the name of a character device or file containing random data to be used instead of the default. The special value -\fIkeyboard\fR -indicates that keyboard input should be used. This option may be specified multiple times. -.PP -Other types can be entered using "TYPEXXXXX" where "XXXXX" is the decimal value of the type with no leading zeros. The rdata, if present, will be parsed using the UNKNOWN rdata format, ( ). -.PP -The -\fB\-T\fR -and -\fB\-P\fR -options print out lists of non\-meta types for which the type\-specific presentation formats are known. -\fB\-T\fR -prints out the list of IANA\-assigned types. -\fB\-P\fR -prints out the list of private types specific to -\fBnamed\fR. These options may be combined. -\fBnsupdate\fR -will exit after the lists are printed. -.PP -The \-V option causes -\fBnsupdate\fR -to print the version number and exit. +.RE .SH "INPUT FORMAT" .PP \fBnsupdate\fR @@ -483,7 +496,7 @@ RFC 2931, .PP The TSIG key is redundantly stored in two separate files. This is a consequence of nsupdate using the DST library for its cryptographic operations, and may change in future releases. .SH "COPYRIGHT" -Copyright \(co 2004\-2012, 2014 Internet Systems Consortium, Inc. ("ISC") +Copyright \(co 2004\-2012, 2014, 2015 Internet Systems Consortium, Inc. ("ISC") .br Copyright \(co 2000\-2003 Internet Software Consortium. .br diff --git a/bin/nsupdate/nsupdate.html b/bin/nsupdate/nsupdate.html index be1b1b9c81..47f977a546 100644 --- a/bin/nsupdate/nsupdate.html +++ b/bin/nsupdate/nsupdate.html @@ -1,5 +1,5 @@