diff options
Diffstat (limited to 'doc/man/nsupdate.1in')
| -rw-r--r-- | doc/man/nsupdate.1in | 437 |
1 files changed, 437 insertions, 0 deletions
diff --git a/doc/man/nsupdate.1in b/doc/man/nsupdate.1in new file mode 100644 index 0000000..b80f329 --- /dev/null +++ b/doc/man/nsupdate.1in @@ -0,0 +1,437 @@ +.\" 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@" "@PACKAGE_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@sysconfdir@/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. \fI\%ddns\-confgen\fP can generate suitable +configuration fragments. \fBnsupdate\fP uses the \fI\%\-y\fP or \fI\%\-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 \fI\%\-g\fP flag. A non\-standards\-compliant variant of GSS\-TSIG +used by Windows 2000 can be switched on with the \fI\%\-o\fP flag. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-4 +This option sets use of IPv4 only. +.UNINDENT +.INDENT 0.0 +.TP +.B \-6 +This option sets use of IPv6 only. +.UNINDENT +.INDENT 0.0 +.TP +.B \-C +Overrides the default \fIresolv.conf\fP file. This is only intended for testing. +.UNINDENT +.INDENT 0.0 +.TP +.B \-d +This option sets debug mode, which provides tracing information about the update +requests that are made and the replies received from the name server. +.UNINDENT +.INDENT 0.0 +.TP +.B \-D +This option sets extra debug mode. +.UNINDENT +.INDENT 0.0 +.TP +.B \-g +This option enables standard GSS\-TSIG mode. +.UNINDENT +.INDENT 0.0 +.TP +.B \-i +This option forces interactive mode, even when standard input is not a terminal. +.UNINDENT +.INDENT 0.0 +.TP +.B \-k keyfile +This option indicates the file containing the TSIG authentication key. Keyfiles may be in +two formats: a single file containing a \fI\%named.conf\fP\-format \fBkey\fP +statement, which may be generated automatically by \fI\%ddns\-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 +\fI\%dnssec\-keygen\fP\&. The \fI\%\-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. +.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 +overridden). Connections to the local server use a TSIG key +found in \fB@runstatedir@/session.key\fP, which is automatically +generated by \fI\%named\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 \fI\%\-k\fP option. +.UNINDENT +.INDENT 0.0 +.TP +.B \-L level +This option sets the logging debug level. If zero, logging is disabled. +.UNINDENT +.INDENT 0.0 +.TP +.B \-o +This option enables a non\-standards\-compliant variant of GSS\-TSIG +used by Windows 2000. +.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. +.UNINDENT +.INDENT 0.0 +.TP +.B \-P +This option prints the list of private BIND\-specific resource record types whose +format is understood by \fBnsupdate\fP\&. See also the \fI\%\-T\fP option. +.UNINDENT +.INDENT 0.0 +.TP +.B \-r udpretries +This option sets the number of UDP retries. The default is 3. If zero, only one update +request is made. +.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 for TCP mode. For UDP mode, +the option \fI\%\-u\fP takes precedence over this option, unless the option \fI\%\-u\fP +is set to zero, in which case the interval is computed from the \fI\%\-t\fP timeout interval +and the number of UDP retries. For UDP mode, the timeout can not be disabled, and will +be rounded up to 1 second in case if both \fI\%\-t\fP and \fI\%\-u\fP are set to zero. +.UNINDENT +.INDENT 0.0 +.TP +.B \-T +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 \fI\%\-T\fP option can be combined with the \fI\%\-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>). +.UNINDENT +.INDENT 0.0 +.TP +.B \-u udptimeout +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. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v +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. +.UNINDENT +.INDENT 0.0 +.TP +.B \-V +This option prints the version number and exits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-y [hmac:]keyname:secret +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 \fI\%\-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 \fI\%\-y\fP or \fI\%\-k\fP\&. +.TP +.B \fBgsstsig\fP +This command uses GSS\-TSIG to sign the updates. This is equivalent to specifying +\fI\%\-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 \fI\%\-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 [boolean]\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@runstatedir@/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 \fI\%dnssec\-keygen\fP\&. +.TP +.B \fBK{name}.+157.+{random}.private\fP +Base\-64 encoding of the HMAC\-MD5 key created by \fI\%dnssec\-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, +\fI\%named(8)\fP, \fI\%dnssec\-keygen(8)\fP, \fI\%tsig\-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. +. |