diff options
Diffstat (limited to 'usr.sbin/bind/bin/nsupdate/nsupdate.8')
| -rw-r--r-- | usr.sbin/bind/bin/nsupdate/nsupdate.8 | 341 |
1 files changed, 341 insertions, 0 deletions
diff --git a/usr.sbin/bind/bin/nsupdate/nsupdate.8 b/usr.sbin/bind/bin/nsupdate/nsupdate.8 new file mode 100644 index 00000000000..9d469db25bc --- /dev/null +++ b/usr.sbin/bind/bin/nsupdate/nsupdate.8 @@ -0,0 +1,341 @@ +.\" +.\" Copyright (C) 2000, 2001 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.TH "NSUPDATE" "8" "Jun 30, 2000" "BIND9" "" +.SH NAME +nsupdate \- Dynamic DNS update utility +.SH SYNOPSIS +.sp +\fBnsupdate\fR [ \fB-d\fR ] [ \fB [ -y \fIkeyname:secret\fB ] [ -k \fIkeyfile\fB ] \fR ] [ \fB-v\fR ] [ \fBfilename\fR ] +.SH "DESCRIPTION" +.PP +\fBnsupdate\fR +is used to submit Dynamic DNS Update requests as defined in RFC2136 +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'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. +.PP +Transaction signatures can be used to authenticate the Dynamic DNS +updates. +These use the TSIG resource record type described in RFC2845. +The signatures rely 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 +\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. +\fBnsupdate\fR +does not read +\fI/etc/named.conf\fR. +.PP +\fBnsupdate\fR +uses the +\fB-y\fR +or +\fB-k\fR +option to provide the shared secret needed to generate a TSIG record +for authenticating Dynamic DNS update requests. +These options are mutually exclusive. +With the +\fB-k\fR +option, +\fBnsupdate\fR +reads the shared secret from the file +\fIkeyfile\fR, +whose name is of the form +\fIK{name}.+157.+{random}.private\fR. +For historical +reasons, the file +\fIK{name}.+157.+{random}.key\fR +must also be present. When the +\fB-y\fR +option is used, a signature is generated from +\fIkeyname:secret.\fR +\fIkeyname\fR +is the name of the key, +and +\fIsecret\fR +is the base64 encoded shared secret. +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 +By default +\fBnsupdate\fR +uses UDP to send update requests to the name server. +The +\fB-v\fR +option makes +\fBnsupdate\fR +use a TCP connection. +This may be preferable when a batch of update requests is made. +.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: +.TP +\fBserver servername [ port ]\fR +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's 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. +.TP +\fBlocal address [ port ]\fR +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 choosen 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. +.TP +\fBzone zonename\fR +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. +.TP +\fBkey name secret\fR +Specifies that all updates are to be TSIG signed using the +\fIkeyname\fR \fIkeysecret\fR pair. +The \fBkey\fR command +overrides any key specified on the command line via +\fB-y\fR or \fB-k\fR. +.TP +\fBprereq nxdomain domain-name\fR +Requires that no resource record of any type exists with name +\fIdomain-name\fR. +.TP +\fBprereq yxdomain domain-name\fR +Requires that +\fIdomain-name\fR +exists (has as at least one resource record, of any type). +.TP +\fBprereq nxrrset domain-name [ class ] type\fR +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. +.TP +\fBprereq yxrrset domain-name [ class ] type\fR +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. +.TP +\fBprereq yxrrset domain-name [ class ] type data\fI...\fB\fR +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's +RDATA. +.TP +\fBupdate delete domain-name [ ttl ] [ class ] [ type [ data\fI...\fB ] ]\fR +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. +.TP +\fBupdate add domain-name ttl [ class ] type data\fI...\fB\fR +Adds a new resource record with the specified +\fIttl\fR, +\fIclass\fR +and +\fIdata\fR. +.TP +\fBshow\fR +Displays the current message, containing all of the prerequisites and +updates specified since the last send. +.TP +\fBsend\fR +Sends the current message. This is equivalent to entering a blank line. +.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 +.nf +# nsupdate +> update delete oldhost.example.com A +> update add newhost.example.com 86400 A 172.16.1.1 +> +.sp +.fi +.PP +Any A records for +\fBoldhost.example.com\fR +are deleted. +and an A record for +\fBnewhost.example.com\fR +it IP address 172.16.1.1 is added. +The newly-added record has a 1 day TTL (86400 seconds) +.sp +.nf +# nsupdate +> prereq nxdomain nickname.example.com +> update add nickname.example.com 86400 CNAME somehost.example.com +> +.sp +.fi +.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 RFC1034 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 RFC2535 to allow CNAMEs to have +SIG, KEY and NXT records.) +.SH "FILES" +.TP +\fB/etc/resolv.conf\fR +used to identify default name server +.TP +\fBK{name}.+157.+{random}.key\fR +base-64 encoding of HMAC-MD5 key created by +\fBdnssec-keygen\fR(8). +.TP +\fBK{name}.+157.+{random}.private\fR +base-64 encoding of HMAC-MD5 key created by +\fBdnssec-keygen\fR(8). +.SH "SEE ALSO" +.PP +\fBRFC2136\fR, +\fBRFC3007\fR, +\fBRFC2104\fR, +\fBRFC2845\fR, +\fBRFC1034\fR, +\fBRFC2535\fR, +\fBnamed\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. |