Adding upstream version 1:9.16.44.upstream/1%9.16.44upstream

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

1 files changed, 385 insertions, 0 deletions

diff --git a/doc/man/nsupdate.1in b/doc/man/nsupdate.1in
new file mode 100644
index 0000000..5a2d02f
--- /dev/null
+++ b/doc/man/nsupdate.1in
@@ -0,0 +1,385 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "NSUPDATE" "1" "@RELEASE_DATE@" "@BIND9_VERSION@" "BIND 9"
+.SH NAME
+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]
+.SH DESCRIPTION
+.sp
+\fBnsupdate\fP is used to submit Dynamic DNS Update requests, as defined in
+\fI\%RFC 2136\fP, to a name server. This allows resource records to be added or
+removed from a zone without manually editing the zone file. A single
+update request can contain requests to add or remove more than one
+resource record.
+.sp
+Zones that are under dynamic control via \fBnsupdate\fP or a DHCP server
+should not be edited by hand. Manual edits could conflict with dynamic
+updates and cause data to be lost.
+.sp
+The resource records that are dynamically added or removed with
+\fBnsupdate\fP must be in the same zone. Requests are sent to the
+zone\(aqs primary server, which is identified by the MNAME field of the
+zone\(aqs SOA record.
+.sp
+Transaction signatures can be used to authenticate the Dynamic DNS
+updates. These use the TSIG resource record type described in \fI\%RFC 2845\fP,
+the SIG(0) record described in \fI\%RFC 2535\fP and \fI\%RFC 2931\fP, or GSS\-TSIG as
+described in \fI\%RFC 3645\fP\&.
+.sp
+TSIG relies on a shared secret that should only be known to \fBnsupdate\fP
+and the name server. For instance, suitable \fBkey\fP and \fBserver\fP
+statements are added to \fB/etc/named.conf\fP so that the name server
+can associate the appropriate secret key and algorithm with the IP
+address of the client application that is using TSIG
+authentication. \fBddns\-confgen\fP can generate suitable
+configuration fragments. \fBnsupdate\fP uses the \fB\-y\fP or \fB\-k\fP options
+to provide the TSIG shared secret; these options are mutually exclusive.
+.sp
+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.
+.sp
+GSS\-TSIG uses Kerberos credentials. Standard GSS\-TSIG mode is switched
+on with the \fB\-g\fP flag. A non\-standards\-compliant variant of GSS\-TSIG
+used by Windows 2000 can be switched on with the \fB\-o\fP flag.
+.SH OPTIONS
+.INDENT 0.0
+.TP
+.B \fB\-4\fP
+This option sets use of IPv4 only.
+.TP
+.B \fB\-6\fP
+This option sets use of IPv6 only.
+.TP
+.B \fB\-d\fP
+This option sets debug mode, which provides tracing information about the update
+requests that are made and the replies received from the name server.
+.TP
+.B \fB\-D\fP
+This option sets extra debug mode.
+.TP
+.B \fB\-i\fP
+This option forces interactive mode, even when standard input is not a terminal.
+.TP
+.B \fB\-k keyfile\fP
+This option indicates the file containing the TSIG authentication key. Keyfiles may be in
+two formats: a single file containing a \fBnamed.conf\fP\-format \fBkey\fP
+statement, which may be generated automatically by \fBddns\-confgen\fP;
+or a pair of files whose names are of the format
+\fBK{name}.+157.+{random}.key\fP and
+\fBK{name}.+157.+{random}.private\fP, which can be generated by
+\fBdnssec\-keygen\fP\&. The \fB\-k\fP option can 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.
+.TP
+.B \fB\-l\fP
+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
+overridden). Connections to the local server use a TSIG key
+found in \fB/var/run/named/session.key\fP, which is automatically
+generated by \fBnamed\fP if any local \fBprimary\fP zone has set
+\fBupdate\-policy\fP to \fBlocal\fP\&. The location of this key file can be
+overridden with the \fB\-k\fP option.
+.TP
+.B \fB\-L level\fP
+This option sets the logging debug level. If zero, logging is disabled.
+.TP
+.B \fB\-p port\fP
+This option sets the port to use for connections to a name server. The default is
+53.
+.TP
+.B \fB\-P\fP
+This option prints the list of private BIND\-specific resource record types whose
+format is understood by \fBnsupdate\fP\&. See also the \fB\-T\fP option.
+.TP
+.B \fB\-r udpretries\fP
+This option sets the number of UDP retries. The default is 3. If zero, only one update
+request is made.
+.TP
+.B \fB\-t timeout\fP
+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.
+.TP
+.B \fB\-T\fP
+This option prints the list of IANA standard resource record types whose format is
+understood by \fBnsupdate\fP\&. \fBnsupdate\fP exits after the lists
+are printed. The \fB\-T\fP option can be combined with the \fB\-P\fP
+option.
+.sp
+Other types can be entered using \fBTYPEXXXXX\fP where \fBXXXXX\fP is the
+decimal value of the type with no leading zeros. The rdata, if
+present, is parsed using the UNKNOWN rdata format, (<backslash>
+<hash> <space> <length> <space> <hexstring>).
+.TP
+.B \fB\-u udptimeout\fP
+This option sets the UDP retry interval. The default is 3 seconds. If zero, the
+interval is computed from the timeout interval and number of UDP
+retries.
+.TP
+.B \fB\-v\fP
+This option specifies that TCP should be used even for small update requests. By default, \fBnsupdate\fP 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 is used. TCP may
+be preferable when a batch of update requests is made.
+.TP
+.B \fB\-V\fP
+This option prints the version number and exits.
+.TP
+.B \fB\-y [hmac:]keyname:secret\fP
+This option sets the literal TSIG authentication key. \fBkeyname\fP is the name of the key,
+and \fBsecret\fP is the base64 encoded shared secret. \fBhmac\fP is the
+name of the key algorithm; valid choices are \fBhmac\-md5\fP,
+\fBhmac\-sha1\fP, \fBhmac\-sha224\fP, \fBhmac\-sha256\fP, \fBhmac\-sha384\fP, or
+\fBhmac\-sha512\fP\&. If \fBhmac\fP is not specified, the default is
+\fBhmac\-md5\fP, or if MD5 was disabled, \fBhmac\-sha256\fP\&.
+.sp
+NOTE: Use of the \fB\-y\fP 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 ps1 or in a history file maintained by
+the user\(aqs shell.
+.UNINDENT
+.SH INPUT FORMAT
+.sp
+\fBnsupdate\fP reads input from \fBfilename\fP or standard input. Each
+command is supplied on exactly one line of input. Some commands are for
+administrative purposes; others are either update instructions or
+prerequisite checks on the contents of the zone. These checks set
+conditions that some name or set of resource records (RRset) either
+exists or is absent from the zone. These conditions must be met if the
+entire update request is to succeed. Updates are rejected if the
+tests for the prerequisite conditions fail.
+.sp
+Every update request consists of zero or more prerequisites and zero or
+more updates. This allows a suitably authenticated update request to
+proceed if some specified resource records are either present or missing from
+the zone. A blank input line (or the \fBsend\fP command) causes the
+accumulated commands to be sent as one Dynamic DNS update request to the
+name server.
+.sp
+The command formats and their meanings are as follows:
+.INDENT 0.0
+.TP
+.B \fBserver servername port\fP
+This command sends all dynamic update requests to the name server \fBservername\fP\&.
+When no server statement is provided, \fBnsupdate\fP sends updates
+to the primary server of the correct zone. The MNAME field of that
+zone\(aqs SOA record identify the primary server for that zone.
+\fBport\fP is the port number on \fBservername\fP where the dynamic
+update requests are sent. If no port number is specified, the default
+DNS port number of 53 is used.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This command has no effect when GSS\-TSIG is in use.
+.UNINDENT
+.UNINDENT
+.TP
+.B \fBlocal address port\fP
+This command sends all dynamic update requests using the local \fBaddress\fP\&. When
+no local statement is provided, \fBnsupdate\fP sends updates using
+an address and port chosen by the system. \fBport\fP can also
+be used to force requests to come from a specific port. If no port number
+is specified, the system assigns one.
+.TP
+.B \fBzone zonename\fP
+This command specifies that all updates are to be made to the zone \fBzonename\fP\&.
+If no \fBzone\fP statement is provided, \fBnsupdate\fP attempts to
+determine the correct zone to update based on the rest of the input.
+.TP
+.B \fBclass classname\fP
+This command specifies the default class. If no \fBclass\fP is specified, the default
+class is \fBIN\fP\&.
+.TP
+.B \fBttl seconds\fP
+This command specifies the default time\-to\-live, in seconds, for records to be added. The value
+\fBnone\fP clears the default TTL.
+.TP
+.B \fBkey hmac:keyname secret\fP
+This command specifies that all updates are to be TSIG\-signed using the
+\fBkeyname\fP\-\fBsecret\fP pair. If \fBhmac\fP is specified, it sets
+the signing algorithm in use. The default is \fBhmac\-md5\fP; if MD5
+was disabled, the default is \fBhmac\-sha256\fP\&. The \fBkey\fP command overrides any key
+specified on the command line via \fB\-y\fP or \fB\-k\fP\&.
+.TP
+.B \fBgsstsig\fP
+This command uses GSS\-TSIG to sign the updates. This is equivalent to specifying
+\fB\-g\fP on the command line.
+.TP
+.B \fBoldgsstsig\fP
+This command uses the Windows 2000 version of GSS\-TSIG to sign the updates. This is
+equivalent to specifying \fB\-o\fP on the command line.
+.TP
+.B \fBrealm [realm_name]\fP
+When using GSS\-TSIG, this command specifies the use of \fBrealm_name\fP rather than the default realm
+in \fBkrb5.conf\fP\&. If no realm is specified, the saved realm is
+cleared.
+.TP
+.B \fBcheck\-names [yes_or_no]\fP
+This command turns on or off check\-names processing on records to be added.
+Check\-names has no effect on prerequisites or records to be deleted.
+By default check\-names processing is on. If check\-names processing
+fails, the record is not added to the UPDATE message.
+.TP
+.B \fBprereq nxdomain domain\-name\fP
+This command requires that no resource record of any type exist with the name
+\fBdomain\-name\fP\&.
+.TP
+.B \fBprereq yxdomain domain\-name\fP
+This command requires that \fBdomain\-name\fP exist (as at least one resource
+record, of any type).
+.TP
+.B \fBprereq nxrrset domain\-name class type\fP
+This command requires that no resource record exist of the specified \fBtype\fP,
+\fBclass\fP, and \fBdomain\-name\fP\&. If \fBclass\fP is omitted, IN (Internet)
+is assumed.
+.TP
+.B \fBprereq yxrrset domain\-name class type\fP
+This command requires that a resource record of the specified \fBtype\fP,
+\fBclass\fP and \fBdomain\-name\fP exist. If \fBclass\fP is omitted, IN
+(internet) is assumed.
+.TP
+.B \fBprereq yxrrset domain\-name class type data\fP
+With this command, the \fBdata\fP from each set of prerequisites of this form sharing a
+common \fBtype\fP, \fBclass\fP, and \fBdomain\-name\fP are combined to form
+a set of RRs. This set of RRs must exactly match the set of RRs
+existing in the zone at the given \fBtype\fP, \fBclass\fP, and
+\fBdomain\-name\fP\&. The \fBdata\fP are written in the standard text
+representation of the resource record\(aqs RDATA.
+.TP
+.B \fBupdate delete domain\-name ttl class type data\fP
+This command deletes any resource records named \fBdomain\-name\fP\&. If \fBtype\fP and
+\fBdata\fP are provided, only matching resource records are removed.
+The Internet class is assumed if \fBclass\fP is not supplied. The
+\fBttl\fP is ignored, and is only allowed for compatibility.
+.TP
+.B \fBupdate add domain\-name ttl class type data\fP
+This command adds a new resource record with the specified \fBttl\fP, \fBclass\fP, and
+\fBdata\fP\&.
+.TP
+.B \fBshow\fP
+This command displays the current message, containing all of the prerequisites and
+updates specified since the last send.
+.TP
+.B \fBsend\fP
+This command sends the current message. This is equivalent to entering a blank
+line.
+.TP
+.B \fBanswer\fP
+This command displays the answer.
+.TP
+.B \fBdebug\fP
+This command turns on debugging.
+.TP
+.B \fBversion\fP
+This command prints the version number.
+.TP
+.B \fBhelp\fP
+This command prints a list of commands.
+.UNINDENT
+.sp
+Lines beginning with a semicolon (;) are comments and are ignored.
+.SH EXAMPLES
+.sp
+The examples below show how \fBnsupdate\fP can be used to insert and
+delete resource records from the \fBexample.com\fP zone. Notice that the
+input in each example contains a trailing blank line, so that a group of
+commands is sent as one dynamic update request to the primary name
+server for \fBexample.com\fP\&.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# nsupdate
+> update delete oldhost.example.com A
+> update add newhost.example.com 86400 A 172.16.1.1
+> send
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Any A records for \fBoldhost.example.com\fP are deleted, and an A record
+for \fBnewhost.example.com\fP with IP address 172.16.1.1 is added. The
+newly added record has a TTL of 1 day (86400 seconds).
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# nsupdate
+> prereq nxdomain nickname.example.com
+> update add nickname.example.com 86400 CNAME somehost.example.com
+> send
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The prerequisite condition tells the name server to verify that there are
+no resource records of any type for \fBnickname.example.com\fP\&. If there
+are, the update request fails. If this name does not exist, a CNAME for
+it is added. This ensures that when the CNAME is added, it cannot
+conflict with the long\-standing rule in \fI\%RFC 1034\fP that a name must not
+exist as any other record type if it exists as a CNAME. (The rule has
+been updated for DNSSEC in \fI\%RFC 2535\fP to allow CNAMEs to have RRSIG,
+DNSKEY, and NSEC records.)
+.SH FILES
+.INDENT 0.0
+.TP
+.B \fB/etc/resolv.conf\fP
+Used to identify the default name server
+.TP
+.B \fB/var/run/named/session.key\fP
+Sets the default TSIG key for use in local\-only mode
+.TP
+.B \fBK{name}.+157.+{random}.key\fP
+Base\-64 encoding of the HMAC\-MD5 key created by \fBdnssec\-keygen\fP\&.
+.TP
+.B \fBK{name}.+157.+{random}.private\fP
+Base\-64 encoding of the HMAC\-MD5 key created by \fBdnssec\-keygen\fP\&.
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fI\%RFC 2136\fP, \fI\%RFC 3007\fP, \fI\%RFC 2104\fP, \fI\%RFC 2845\fP, \fI\%RFC 1034\fP, \fI\%RFC 2535\fP, \fI\%RFC 2931\fP,
+\fBnamed(8)\fP, \fBddns\-confgen(8)\fP, \fBdnssec\-keygen(8)\fP\&.
+.SH BUGS
+.sp
+The TSIG key is redundantly stored in two separate files. This is a
+consequence of \fBnsupdate\fP using the DST library for its cryptographic
+operations, and may change in future releases.
+.SH AUTHOR
+Internet Systems Consortium
+.SH COPYRIGHT
+2023, Internet Systems Consortium
+.\" Generated by docutils manpage writer.
+.