diff options
Diffstat (limited to 'bin/nsupdate/nsupdate.1')
| -rw-r--r-- | bin/nsupdate/nsupdate.1 | 524 |
1 files changed, 524 insertions, 0 deletions
diff --git a/bin/nsupdate/nsupdate.1 b/bin/nsupdate/nsupdate.1 new file mode 100644 index 0000000..28f6191 --- /dev/null +++ b/bin/nsupdate/nsupdate.1 @@ -0,0 +1,524 @@ +.\" Copyright (C) 2000-2012, 2014-2019 Internet Systems Consortium, Inc. ("ISC") +.\" +.\" This Source Code Form is subject to the terms of the Mozilla Public +.\" License, v. 2.0. If a copy of the MPL was not distributed with this +.\" file, You can obtain one at http://mozilla.org/MPL/2.0/. +.\" +.hy 0 +.ad l +'\" t +.\" Title: nsupdate +.\" Author: +.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/> +.\" Date: 2014-04-18 +.\" Manual: BIND9 +.\" Source: ISC +.\" Language: English +.\" +.TH "NSUPDATE" "1" "2014\-04\-18" "ISC" "BIND9" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +nsupdate \- Dynamic DNS update utility +.SH "SYNOPSIS" +.HP \w'\fBnsupdate\fR\ 'u +\fBnsupdate\fR [\fB\-d\fR] [\fB\-D\fR] [\fB\-i\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 +is used to submit Dynamic DNS Update requests as defined in RFC 2136 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\&. +.PP +Zones that are under dynamic control via +\fBnsupdate\fR +or a DHCP server should not be edited by hand\&. Manual edits could conflict with dynamic updates and cause data to be lost\&. +.PP +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\*(Aqs master server\&. This is identified by the MNAME field of the zone\*(Aqs SOA record\&. +.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\&. +.PP +TSIG relies on a shared secret that should only be known to +\fBnsupdate\fR +and the name server\&. For instance, suitable +\fBkey\fR +and +\fBserver\fR +statements would be added to +/etc/named\&.conf +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 +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 +\-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 +\-i +.RS 4 +Force interactive mode, even when standard input is not a terminal\&. +.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 +named\&.conf\-format +\fBkey\fR +statement, which may be generated automatically by +\fBddns\-confgen\fR, or a pair of files whose names are of the format +K{name}\&.+157\&.+{random}\&.key +and +K{name}\&.+157\&.+{random}\&.private, 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\&. +.RE +.PP +\-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 +/var/run/named/session\&.key, 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 +/dev/random +or equivalent device, the default source of randomness is keyboard input\&. +randomdev +specifies the name of a character device or file containing random data to be used instead of the default\&. The special value +keyboard +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, (<backslash> <hash> <space> <length> <space> <hexstring>)\&. +.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 +is the base64 encoded shared secret\&. +\fIhmac\fR +is the name of the key algorithm; valid choices are +hmac\-md5, +hmac\-sha1, +hmac\-sha224, +hmac\-sha256, +hmac\-sha384, or +hmac\-sha512\&. If +\fIhmac\fR +is not specified, the default is +hmac\-md5 +or if MD5 was disabled +hmac\-sha256\&. +.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\*(Aqs shell\&. +.RE +.SH "INPUT FORMAT" +.PP +\fBnsupdate\fR +reads input from +\fIfilename\fR +or standard input\&. Each command is supplied on exactly one line of input\&. Some commands are for administrative purposes\&. The 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 will be rejected if the tests for the prerequisite conditions fail\&. +.PP +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 present or missing from the zone\&. A blank input line (or the +\fBsend\fR +command) causes the accumulated commands to be sent as one Dynamic DNS update request to the name server\&. +.PP +The command formats and their meaning are as follows: +.PP +\fBserver\fR {servername} [port] +.RS 4 +Sends all dynamic update requests to the name server +\fIservername\fR\&. When no server statement is provided, +\fBnsupdate\fR +will send updates to the master server of the correct zone\&. The MNAME field of that zone\*(Aqs SOA record will identify the master server for that zone\&. +\fIport\fR +is the port number on +\fIservername\fR +where the dynamic update requests get sent\&. If no port number is specified, the default DNS port number of 53 is used\&. +.RE +.PP +\fBlocal\fR {address} [port] +.RS 4 +Sends all dynamic update requests using the local +\fIaddress\fR\&. When no local statement is provided, +\fBnsupdate\fR +will send updates using an address and port chosen by the system\&. +\fIport\fR +can additionally be used to make requests come from a specific port\&. If no port number is specified, the system will assign one\&. +.RE +.PP +\fBzone\fR {zonename} +.RS 4 +Specifies that all updates are to be made to the zone +\fIzonename\fR\&. If no +\fIzone\fR +statement is provided, +\fBnsupdate\fR +will attempt determine the correct zone to update based on the rest of the input\&. +.RE +.PP +\fBclass\fR {classname} +.RS 4 +Specify the default class\&. If no +\fIclass\fR +is specified, the default class is +\fIIN\fR\&. +.RE +.PP +\fBttl\fR {seconds} +.RS 4 +Specify the default time to live for records to be added\&. The value +\fInone\fR +will clear the default ttl\&. +.RE +.PP +\fBkey\fR [hmac:] {keyname} {secret} +.RS 4 +Specifies that all updates are to be TSIG\-signed using the +\fIkeyname\fR\fIsecret\fR +pair\&. If +\fIhmac\fR +is specified, then it sets the signing algorithm in use; the default is +hmac\-md5 +or if MD5 was disabled +hmac\-sha256\&. The +\fBkey\fR +command overrides any key specified on the command line via +\fB\-y\fR +or +\fB\-k\fR\&. +.RE +.PP +\fBgsstsig\fR +.RS 4 +Use GSS\-TSIG to sign the updated\&. This is equivalent to specifying +\fB\-g\fR +on the command line\&. +.RE +.PP +\fBoldgsstsig\fR +.RS 4 +Use the Windows 2000 version of GSS\-TSIG to sign the updated\&. This is equivalent to specifying +\fB\-o\fR +on the command line\&. +.RE +.PP +\fBrealm\fR {[realm_name]} +.RS 4 +When using GSS\-TSIG use +\fIrealm_name\fR +rather than the default realm in +krb5\&.conf\&. If no realm is specified the saved realm is cleared\&. +.RE +.PP +\fBcheck\-names\fR {[yes_or_no]} +.RS 4 +Turn 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 will not be added to the UPDATE message\&. +.RE +.PP +\fB[prereq]\fR\fB nxdomain\fR {domain\-name} +.RS 4 +Requires that no resource record of any type exists with name +\fIdomain\-name\fR\&. +.RE +.PP +\fB[prereq]\fR\fB yxdomain\fR {domain\-name} +.RS 4 +Requires that +\fIdomain\-name\fR +exists (has as at least one resource record, of any type)\&. +.RE +.PP +\fB[prereq]\fR\fB nxrrset\fR {domain\-name} [class] {type} +.RS 4 +Requires that no resource record exists of the specified +\fItype\fR, +\fIclass\fR +and +\fIdomain\-name\fR\&. If +\fIclass\fR +is omitted, IN (internet) is assumed\&. +.RE +.PP +\fB[prereq]\fR\fB yxrrset\fR {domain\-name} [class] {type} +.RS 4 +This requires that a resource record of the specified +\fItype\fR, +\fIclass\fR +and +\fIdomain\-name\fR +must exist\&. If +\fIclass\fR +is omitted, IN (internet) is assumed\&. +.RE +.PP +\fB[prereq]\fR\fB yxrrset\fR {domain\-name} [class] {type} {data...} +.RS 4 +The +\fIdata\fR +from each set of prerequisites of this form sharing a common +\fItype\fR, +\fIclass\fR, and +\fIdomain\-name\fR +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 +\fItype\fR, +\fIclass\fR, and +\fIdomain\-name\fR\&. The +\fIdata\fR +are written in the standard text representation of the resource record\*(Aqs RDATA\&. +.RE +.PP +\fB[update]\fR\fB del\fR\fB[ete]\fR {domain\-name} [ttl] [class] [type\ [data...]] +.RS 4 +Deletes any resource records named +\fIdomain\-name\fR\&. If +\fItype\fR +and +\fIdata\fR +is provided, only matching resource records will be removed\&. The internet class is assumed if +\fIclass\fR +is not supplied\&. The +\fIttl\fR +is ignored, and is only allowed for compatibility\&. +.RE +.PP +\fB[update]\fR\fB add\fR {domain\-name} {ttl} [class] {type} {data...} +.RS 4 +Adds a new resource record with the specified +\fIttl\fR, +\fIclass\fR +and +\fIdata\fR\&. +.RE +.PP +\fBshow\fR +.RS 4 +Displays the current message, containing all of the prerequisites and updates specified since the last send\&. +.RE +.PP +\fBsend\fR +.RS 4 +Sends the current message\&. This is equivalent to entering a blank line\&. +.RE +.PP +\fBanswer\fR +.RS 4 +Displays the answer\&. +.RE +.PP +\fBdebug\fR +.RS 4 +Turn on debugging\&. +.RE +.PP +\fBversion\fR +.RS 4 +Print version number\&. +.RE +.PP +\fBhelp\fR +.RS 4 +Print a list of commands\&. +.RE +.PP +Lines beginning with a semicolon are comments and are ignored\&. +.SH "EXAMPLES" +.PP +The examples below show how +\fBnsupdate\fR +could be used to insert and delete resource records from the +\fBexample\&.com\fR +zone\&. Notice that the input in each example contains a trailing blank line so that a group of commands are sent as one dynamic update request to the master name server for +\fBexample\&.com\fR\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +# nsupdate +> update delete oldhost\&.example\&.com A +> update add newhost\&.example\&.com 86400 A 172\&.16\&.1\&.1 +> send +.fi +.if n \{\ +.RE +.\} +.PP +Any A records for +\fBoldhost\&.example\&.com\fR +are deleted\&. And an A record for +\fBnewhost\&.example\&.com\fR +with IP address 172\&.16\&.1\&.1 is added\&. The newly\-added record has a 1 day TTL (86400 seconds)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +# nsupdate +> prereq nxdomain nickname\&.example\&.com +> update add nickname\&.example\&.com 86400 CNAME somehost\&.example\&.com +> send +.fi +.if n \{\ +.RE +.\} +.PP +The prerequisite condition gets the name server to check that there are no resource records of any type for +\fBnickname\&.example\&.com\fR\&. 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 RFC 1034 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 RFC 2535 to allow CNAMEs to have RRSIG, DNSKEY and NSEC records\&.) +.SH "FILES" +.PP +\fB/etc/resolv\&.conf\fR +.RS 4 +used to identify default name server +.RE +.PP +\fB/var/run/named/session\&.key\fR +.RS 4 +sets the default TSIG key for use in local\-only mode +.RE +.PP +\fBK{name}\&.+157\&.+{random}\&.key\fR +.RS 4 +base\-64 encoding of HMAC\-MD5 key created by +\fBdnssec-keygen\fR(8)\&. +.RE +.PP +\fBK{name}\&.+157\&.+{random}\&.private\fR +.RS 4 +base\-64 encoding of HMAC\-MD5 key created by +\fBdnssec-keygen\fR(8)\&. +.RE +.SH "SEE ALSO" +.PP +RFC 2136, +RFC 3007, +RFC 2104, +RFC 2845, +RFC 1034, +RFC 2535, +RFC 2931, +\fBnamed\fR(8), +\fBddns-confgen\fR(8), +\fBdnssec-keygen\fR(8)\&. +.SH "BUGS" +.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 "AUTHOR" +.PP +\fBInternet Systems Consortium, Inc\&.\fR +.SH "COPYRIGHT" +.br +Copyright \(co 2000-2012, 2014-2019 Internet Systems Consortium, Inc. ("ISC") +.br |