1 .\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
2 .\" Copyright (C) 2000-2003 Internet Software Consortium.
4 .\" Permission to use, copy, modify, and distribute this software for any
5 .\" purpose with or without fee is hereby granted, provided that the above
6 .\" copyright notice and this permission notice appear in all copies.
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
9 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
10 .\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
11 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
12 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
13 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
14 .\" PERFORMANCE OF THIS SOFTWARE.
16 .\" $Id: nsupdate.8,v 1.24.2.2.2.5 2004/03/08 09:04:15 marka Exp $
18 .TH "NSUPDATE" "8" "Jun 30, 2000" "BIND9" ""
20 nsupdate \- Dynamic DNS update utility
23 \fBnsupdate\fR [ \fB-d\fR ] [ \fB [ -y \fIkeyname:secret\fB ] [ -k \fIkeyfile\fB ] \fR ] [ \fB-t \fItimeout\fB\fR ] [ \fB-u \fIudptimeout\fB\fR ] [ \fB-r \fIudpretries\fB\fR ] [ \fB-v\fR ] [ \fBfilename\fR ]
27 is used to submit Dynamic DNS Update requests as defined in RFC2136
29 This allows resource records to be added or removed from a zone
30 without manually editing the zone file.
31 A single update request can contain requests to add or remove more than one
34 Zones that are under dynamic control via
36 or a DHCP server should not be edited by hand.
38 conflict with dynamic updates and cause data to be lost.
40 The resource records that are dynamically added or removed with
42 have to be in the same zone.
43 Requests are sent to the zone's master server.
44 This is identified by the MNAME field of the zone's SOA record.
50 operate in debug mode.
51 This provides tracing information about the update requests that are
52 made and the replies received from the name server.
54 Transaction signatures can be used to authenticate the Dynamic DNS
56 These use the TSIG resource record type described in RFC2845 or the
57 SIG(0) record described in RFC3535 and RFC2931.
58 TSIG relies on a shared secret that should only be known to
59 \fBnsupdate\fR and the name server.
60 Currently, the only supported encryption algorithm for TSIG is
61 HMAC-MD5, which is defined in RFC 2104.
62 Once other algorithms are defined for TSIG, applications will need to
63 ensure they select the appropriate algorithm as well as the key when
64 authenticating each other.
69 statements would be added to
71 so that the name server can associate the appropriate secret key
72 and algorithm with the IP address of the
73 client application that will be using TSIG authentication.
74 SIG(0) uses public key cryptography. To use a SIG(0) key, the public
75 key must be stored in a KEY record in a zone served by the name server.
78 \fI/etc/named.conf\fR.
85 option (with an HMAC-MD5 key) to provide the shared secret needed to generate
86 a TSIG record for authenticating Dynamic DNS update requests.
87 These options are mutually exclusive.
92 reads the shared secret from the file
94 whose name is of the form
95 \fIK{name}.+157.+{random}.private\fR.
98 \fIK{name}.+157.+{random}.key\fR
99 must also be present. When the
101 option is used, a signature is generated from
102 \fIkeyname:secret.\fR
104 is the name of the key,
107 is the base64 encoded shared secret.
110 option is discouraged because the shared secret is supplied as a command
111 line argument in clear text.
112 This may be visible in the output from
114 or in a history file maintained by the user's shell.
116 The \fB-k\fR may also be used to specify a SIG(0) key used
117 to authenticate Dynamic DNS update requests. In this case, the key
118 specified is not an HMAC-MD5 key.
122 uses UDP to send update requests to the name server unless they are too
123 large to fit in a UDP request in which case TCP will be used.
128 use a TCP connection.
129 This may be preferable when a batch of update requests is made.
131 The \fB-t\fR option sets the maximum time a update request can
132 take before it is aborted. The default is 300 seconds. Zero can be used
133 to disable the timeout.
135 The \fB-u\fR option sets the UDP retry interval. The default is
136 3 seconds. If zero the interval will be computed from the timeout interval
137 and number of UDP retries.
139 The \fB-r\fR option sets the number of UDP retries. The default is
140 3. If zero only one update request will be made.
147 Each command is supplied on exactly one line of input.
148 Some commands are for administrative purposes.
149 The others are either update instructions or prerequisite checks on the
150 contents of the zone.
151 These checks set conditions that some name or set of
152 resource records (RRset) either exists or is absent from the zone.
153 These conditions must be met if the entire update request is to succeed.
154 Updates will be rejected if the tests for the prerequisite conditions fail.
156 Every update request consists of zero or more prerequisites
157 and zero or more updates.
158 This allows a suitably authenticated update request to proceed if some
159 specified resource records are present or missing from the zone.
160 A blank input line (or the \fBsend\fR command) causes the
161 accumulated commands to be sent as one Dynamic DNS update request to the
164 The command formats and their meaning are as follows:
166 \fBserver servername [ port ]\fR
167 Sends all dynamic update requests to the name server
169 When no server statement is provided,
171 will send updates to the master server of the correct zone.
172 The MNAME field of that zone's SOA record will identify the master
173 server for that zone.
175 is the port number on
177 where the dynamic update requests get sent.
178 If no port number is specified, the default DNS port number of 53 is
181 \fBlocal address [ port ]\fR
182 Sends all dynamic update requests using the local
184 When no local statement is provided,
186 will send updates using an address and port chosen by the system.
188 can additionally be used to make requests come from a specific port.
189 If no port number is specified, the system will assign one.
192 Specifies that all updates are to be made to the zone
196 statement is provided,
198 will attempt determine the correct zone to update based on the rest of the input.
200 \fBclass classname\fR
201 Specify the default class.
202 If no \fIclass\fR is specified the default class is
205 \fBkey name secret\fR
206 Specifies that all updates are to be TSIG signed using the
207 \fIkeyname\fR \fIkeysecret\fR pair.
208 The \fBkey\fR command
209 overrides any key specified on the command line via
210 \fB-y\fR or \fB-k\fR.
212 \fBprereq nxdomain domain-name\fR
213 Requires that no resource record of any type exists with name
216 \fBprereq yxdomain domain-name\fR
219 exists (has as at least one resource record, of any type).
221 \fBprereq nxrrset domain-name [ class ] type\fR
222 Requires that no resource record exists of the specified
229 is omitted, IN (internet) is assumed.
231 \fBprereq yxrrset domain-name [ class ] type\fR
232 This requires that a resource record of the specified
240 is omitted, IN (internet) is assumed.
242 \fBprereq yxrrset domain-name [ class ] type data\fI...\fB\fR
245 from each set of prerequisites of this form
251 are combined to form a set of RRs. This set of RRs must
252 exactly match the set of RRs existing in the zone at the
260 are written in the standard text representation of the resource record's
263 \fBupdate delete domain-name [ ttl ] [ class ] [ type [ data\fI...\fB ] ]\fR
264 Deletes any resource records named
270 is provided, only matching resource records will be removed.
271 The internet class is assumed if
275 is ignored, and is only allowed for compatibility.
277 \fBupdate add domain-name ttl [ class ] type data\fI...\fB\fR
278 Adds a new resource record with the specified
285 Displays the current message, containing all of the prerequisites and
286 updates specified since the last send.
289 Sends the current message. This is equivalent to entering a blank line.
294 Lines beginning with a semicolon are comments and are ignored.
297 The examples below show how
299 could be used to insert and delete resource records from the
302 Notice that the input in each example contains a trailing blank line so that
303 a group of commands are sent as one dynamic update request to the
304 master name server for
309 > update delete oldhost.example.com A
310 > update add newhost.example.com 86400 A 172.16.1.1
316 \fBoldhost.example.com\fR
319 \fBnewhost.example.com\fR
320 it IP address 172.16.1.1 is added.
321 The newly-added record has a 1 day TTL (86400 seconds)
325 > prereq nxdomain nickname.example.com
326 > update add nickname.example.com 86400 CNAME somehost.example.com
331 The prerequisite condition gets the name server to check that there
332 are no resource records of any type for
333 \fBnickname.example.com\fR.
334 If there are, the update request fails.
335 If this name does not exist, a CNAME for it is added.
336 This ensures that when the CNAME is added, it cannot conflict with the
337 long-standing rule in RFC1034 that a name must not exist as any other
338 record type if it exists as a CNAME.
339 (The rule has been updated for DNSSEC in RFC2535 to allow CNAMEs to have
340 RRSIG, DNSKEY and NSEC records.)
343 \fB/etc/resolv.conf\fR
344 used to identify default name server
346 \fBK{name}.+157.+{random}.key\fR
347 base-64 encoding of HMAC-MD5 key created by
348 \fBdnssec-keygen\fR(8).
350 \fBK{name}.+157.+{random}.private\fR
351 base-64 encoding of HMAC-MD5 key created by
352 \fBdnssec-keygen\fR(8).
363 \fBdnssec-keygen\fR(8).
366 The TSIG key is redundantly stored in two separate files.
367 This is a consequence of nsupdate using the DST library
368 for its cryptographic operations, and may change in future