Merge branch 'vendor/BINUTILS220' into bu220
[dragonfly.git] / contrib / bind-9.3 / bin / nsupdate / nsupdate.html
1 <!--
2  - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
3  - Copyright (C) 2000-2003 Internet Software Consortium.
4  - 
5  - Permission to use, copy, modify, and distribute this software for any
6  - purpose with or without fee is hereby granted, provided that the above
7  - copyright notice and this permission notice appear in all copies.
8  - 
9  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11  - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15  - PERFORMANCE OF THIS SOFTWARE.
16 -->
17 <!-- $Id: nsupdate.html,v 1.9.2.3.2.15 2006/06/29 13:02:30 marka Exp $ -->
18 <html>
19 <head>
20 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
21 <title>nsupdate</title>
22 <meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
23 </head>
24 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
25 <a name="id2482688"></a><div class="titlepage"></div>
26 <div class="refnamediv">
27 <h2>Name</h2>
28 <p>nsupdate &#8212; Dynamic DNS update utility</p>
29 </div>
30 <div class="refsynopsisdiv">
31 <h2>Synopsis</h2>
32 <div class="cmdsynopsis"><p><code class="command">nsupdate</code>  [<code class="option">-d</code>] [[<code class="option">-y <em class="replaceable"><code>keyname:secret</code></em></code>] |  [<code class="option">-k <em class="replaceable"><code>keyfile</code></em></code>]] [<code class="option">-t <em class="replaceable"><code>timeout</code></em></code>] [<code class="option">-u <em class="replaceable"><code>udptimeout</code></em></code>] [<code class="option">-r <em class="replaceable"><code>udpretries</code></em></code>] [<code class="option">-v</code>] [filename]</p></div>
33 </div>
34 <div class="refsect1" lang="en">
35 <a name="id2549461"></a><h2>DESCRIPTION</h2>
36 <p>
37 <span><strong class="command">nsupdate</strong></span>
38 is used to submit Dynamic DNS Update requests as defined in RFC2136
39 to a name server.
40 This allows resource records to be added or removed from a zone
41 without manually editing the zone file.
42 A single update request can contain requests to add or remove more than one
43 resource record.
44 </p>
45 <p>
46 Zones that are under dynamic control via
47 <span><strong class="command">nsupdate</strong></span>
48 or a DHCP server should not be edited by hand.
49 Manual edits could
50 conflict with dynamic updates and cause data to be lost.
51 </p>
52 <p>
53 The resource records that are dynamically added or removed with
54 <span><strong class="command">nsupdate</strong></span>
55 have to be in the same zone.
56 Requests are sent to the zone's master server.
57 This is identified by the MNAME field of the zone's SOA record.
58 </p>
59 <p>
60 The
61 <code class="option">-d</code>
62 option makes
63 <span><strong class="command">nsupdate</strong></span>
64 operate in debug mode.
65 This provides tracing information about the update requests that are
66 made and the replies received from the name server.
67 </p>
68 <p>
69 Transaction signatures can be used to authenticate the Dynamic DNS
70 updates.
71 These use the TSIG resource record type described in RFC2845 or the
72 SIG(0) record described in RFC3535 and RFC2931.
73 TSIG relies on a shared secret that should only be known to
74 <span><strong class="command">nsupdate</strong></span> and the name server.
75 Currently, the only supported encryption algorithm for TSIG is
76 HMAC-MD5, which is defined in RFC 2104.
77 Once other algorithms are defined for TSIG, applications will need to
78 ensure they select the appropriate algorithm as well as the key when
79 authenticating each other.
80 For instance suitable
81 <span class="type">key</span>
82 and
83 <span class="type">server</span>
84 statements would be added to
85 <code class="filename">/etc/named.conf</code>
86 so that the name server can associate the appropriate secret key
87 and algorithm with the IP address of the
88 client application that will be using TSIG authentication.
89 SIG(0) uses public key cryptography.  To use a SIG(0) key, the public
90 key must be stored in a KEY record in a zone served by the name server.
91 <span><strong class="command">nsupdate</strong></span>
92 does not read
93 <code class="filename">/etc/named.conf</code>.
94 </p>
95 <p>
96 <span><strong class="command">nsupdate</strong></span>
97 uses the
98 <code class="option">-y</code>
99 or
100 <code class="option">-k</code>
101 option (with an HMAC-MD5 key) to provide the shared secret needed to generate
102 a TSIG record for authenticating Dynamic DNS update requests.
103 These options are mutually exclusive.
104 With the
105 <code class="option">-k</code>
106 option,
107 <span><strong class="command">nsupdate</strong></span>
108 reads the shared secret from the file
109 <em class="parameter"><code>keyfile</code></em>,
110 whose name is of the form 
111 <code class="filename">K{name}.+157.+{random}.private</code>.
112 For historical
113 reasons, the file 
114 <code class="filename">K{name}.+157.+{random}.key</code>
115 must also be present.  When the
116 <code class="option">-y</code>
117 option is used, a signature is generated from
118 <em class="parameter"><code>keyname:secret.</code></em>
119 <em class="parameter"><code>keyname</code></em>
120 is the name of the key,
121 and
122 <em class="parameter"><code>secret</code></em>
123 is the base64 encoded shared secret.
124 Use of the
125 <code class="option">-y</code>
126 option is discouraged because the shared secret is supplied as a command
127 line argument in clear text.
128 This may be visible in the output from
129 <span class="citerefentry"><span class="refentrytitle">ps</span>(1
130 )</span>
131 or in a history file maintained by the user's shell.
132 </p>
133 <p>
134 The <code class="option">-k</code> may also be used to specify a SIG(0) key used
135 to authenticate Dynamic DNS update requests.  In this case, the key
136 specified is not an HMAC-MD5 key.
137 </p>
138 <p>
139 By default
140 <span><strong class="command">nsupdate</strong></span>
141 uses UDP to send update requests to the name server unless they are too
142 large to fit in a UDP request in which case TCP will be used.
143 The
144 <code class="option">-v</code>
145 option makes
146 <span><strong class="command">nsupdate</strong></span>
147 use a TCP connection.
148 This may be preferable when a batch of update requests is made.
149 </p>
150 <p>The <code class="option">-t</code> option sets the maximum time a update request can
151 take before it is aborted.  The default is 300 seconds.  Zero can be used
152 to disable the timeout.
153 </p>
154 <p>The <code class="option">-u</code> option sets the UDP retry interval.  The default is
155 3 seconds.  If zero the interval will be computed from the timeout interval
156 and number of UDP retries.
157 </p>
158 <p>The <code class="option">-r</code> option sets the number of UDP retries. The default is
159 3.  If zero only one update request will be made.
160 </p>
161 </div>
162 <div class="refsect1" lang="en">
163 <a name="id2549686"></a><h2>INPUT FORMAT</h2>
164 <p>
165 <span><strong class="command">nsupdate</strong></span>
166 reads input from
167 <em class="parameter"><code>filename</code></em>
168 or standard input.
169 Each command is supplied on exactly one line of input.
170 Some commands are for administrative purposes.
171 The others are either update instructions or prerequisite checks on the
172 contents of the zone.
173 These checks set conditions that some name or set of
174 resource records (RRset) either exists or is absent from the zone.
175 These conditions must be met if the entire update request is to succeed.
176 Updates will be rejected if the tests for the prerequisite conditions fail.
177 </p>
178 <p>
179 Every update request consists of zero or more prerequisites
180 and zero or more updates.
181 This allows a suitably authenticated update request to proceed if some
182 specified resource records are present or missing from the zone.
183 A blank input line (or the <span><strong class="command">send</strong></span> command) causes the
184 accumulated commands to be sent as one Dynamic DNS update request to the
185 name server.
186 </p>
187 <p>
188 The command formats and their meaning are as follows:
189 </p>
190 <div class="variablelist"><dl>
191 <dt><span class="term">
192 <div class="cmdsynopsis"><p><code class="command">server</code>  {servername} [port]</p></div>
193 </span></dt>
194 <dd><p>
195 Sends all dynamic update requests to the name server
196 <em class="parameter"><code>servername</code></em>.
197 When no server statement is provided,
198 <span><strong class="command">nsupdate</strong></span>
199 will send updates to the master server of the correct zone.
200 The MNAME field of that zone's SOA record will identify the master
201 server for that zone.
202 <em class="parameter"><code>port</code></em>
203 is the port number on
204 <em class="parameter"><code>servername</code></em>
205 where the dynamic update requests get sent.
206 If no port number is specified, the default DNS port number of 53 is
207 used.
208 </p></dd>
209 <dt><span class="term">
210 <div class="cmdsynopsis"><p><code class="command">local</code>  {address} [port]</p></div>
211 </span></dt>
212 <dd><p>
213 Sends all dynamic update requests using the local
214 <em class="parameter"><code>address</code></em>.
215
216 When no local statement is provided,
217 <span><strong class="command">nsupdate</strong></span>
218 will send updates using an address and port chosen by the system.
219 <em class="parameter"><code>port</code></em>
220 can additionally be used to make requests come from a specific port.
221 If no port number is specified, the system will assign one.
222 </p></dd>
223 <dt><span class="term">
224 <div class="cmdsynopsis"><p><code class="command">zone</code>  {zonename}</p></div>
225 </span></dt>
226 <dd><p>
227 Specifies that all updates are to be made to the zone
228 <em class="parameter"><code>zonename</code></em>.
229 If no
230 <em class="parameter"><code>zone</code></em>
231 statement is provided,
232 <span><strong class="command">nsupdate</strong></span>
233 will attempt determine the correct zone to update based on the rest of the input.
234 </p></dd>
235 <dt><span class="term">
236 <div class="cmdsynopsis"><p><code class="command">class</code>  {classname}</p></div>
237 </span></dt>
238 <dd><p>
239 Specify the default class.
240 If no <em class="parameter"><code>class</code></em> is specified the default class is
241 <em class="parameter"><code>IN</code></em>.
242 </p></dd>
243 <dt><span class="term">
244 <div class="cmdsynopsis"><p><code class="command">key</code>  {name} {secret}</p></div>
245 </span></dt>
246 <dd><p>
247 Specifies that all updates are to be TSIG signed using the
248 <em class="parameter"><code>keyname</code></em> <em class="parameter"><code>keysecret</code></em> pair.
249 The <span><strong class="command">key</strong></span> command
250 overrides any key specified on the command line via
251 <code class="option">-y</code> or <code class="option">-k</code>.
252 </p></dd>
253 <dt><span class="term">
254 <div class="cmdsynopsis"><p><code class="command">prereq nxdomain</code>  {domain-name}</p></div>
255 </span></dt>
256 <dd><p>
257 Requires that no resource record of any type exists with name
258 <em class="parameter"><code>domain-name</code></em>.
259 </p></dd>
260 <dt><span class="term">
261 <div class="cmdsynopsis"><p><code class="command">prereq yxdomain</code>  {domain-name}</p></div>
262 </span></dt>
263 <dd><p>
264 Requires that
265 <em class="parameter"><code>domain-name</code></em>
266 exists (has as at least one resource record, of any type).
267 </p></dd>
268 <dt><span class="term">
269 <div class="cmdsynopsis"><p><code class="command">prereq nxrrset</code>  {domain-name} [class] {type}</p></div>
270 </span></dt>
271 <dd><p>
272 Requires that no resource record exists of the specified
273 <em class="parameter"><code>type</code></em>,
274 <em class="parameter"><code>class</code></em>
275 and
276 <em class="parameter"><code>domain-name</code></em>.
277 If
278 <em class="parameter"><code>class</code></em>
279 is omitted, IN (internet) is assumed.
280 </p></dd>
281 <dt><span class="term">
282 <div class="cmdsynopsis"><p><code class="command">prereq yxrrset</code>  {domain-name} [class] {type}</p></div>
283 </span></dt>
284 <dd><p>
285 This requires that a resource record of the specified
286 <em class="parameter"><code>type</code></em>,
287 <em class="parameter"><code>class</code></em>
288 and
289 <em class="parameter"><code>domain-name</code></em>
290 must exist.
291 If
292 <em class="parameter"><code>class</code></em>
293 is omitted, IN (internet) is assumed.
294 </p></dd>
295 <dt><span class="term">
296 <div class="cmdsynopsis"><p><code class="command">prereq yxrrset</code>  {domain-name} [class] {type} {data...}</p></div>
297 </span></dt>
298 <dd><p>
299 The
300 <em class="parameter"><code>data</code></em>
301 from each set of prerequisites of this form
302 sharing a common
303 <em class="parameter"><code>type</code></em>,
304 <em class="parameter"><code>class</code></em>,
305 and 
306 <em class="parameter"><code>domain-name</code></em>
307 are combined to form a set of RRs.  This set of RRs must
308 exactly match the set of RRs existing in the zone at the
309 given 
310 <em class="parameter"><code>type</code></em>,
311 <em class="parameter"><code>class</code></em>,
312 and 
313 <em class="parameter"><code>domain-name</code></em>.
314 The
315 <em class="parameter"><code>data</code></em>
316 are written in the standard text representation of the resource record's
317 RDATA.
318 </p></dd>
319 <dt><span class="term">
320 <div class="cmdsynopsis"><p><code class="command">update delete</code>  {domain-name} [ttl] [class] [type [data...]]</p></div>
321 </span></dt>
322 <dd><p>
323 Deletes any resource records named
324 <em class="parameter"><code>domain-name</code></em>.
325 If
326 <em class="parameter"><code>type</code></em>
327 and
328 <em class="parameter"><code>data</code></em>
329 is provided, only matching resource records will be removed.
330 The internet class is assumed if
331 <em class="parameter"><code>class</code></em>
332 is not supplied.  The
333 <em class="parameter"><code>ttl</code></em>
334 is ignored, and is only allowed for compatibility.
335 </p></dd>
336 <dt><span class="term">
337 <div class="cmdsynopsis"><p><code class="command">update add</code>  {domain-name} {ttl} [class] {type} {data...}</p></div>
338 </span></dt>
339 <dd><p>
340 Adds a new resource record with the specified
341 <em class="parameter"><code>ttl</code></em>,
342 <em class="parameter"><code>class</code></em>
343 and
344 <em class="parameter"><code>data</code></em>.
345 </p></dd>
346 <dt><span class="term">
347 <div class="cmdsynopsis"><p><code class="command">show</code> </p></div>
348 </span></dt>
349 <dd><p>
350 Displays the current message, containing all of the prerequisites and
351 updates specified since the last send.
352 </p></dd>
353 <dt><span class="term">
354 <div class="cmdsynopsis"><p><code class="command">send</code> </p></div>
355 </span></dt>
356 <dd><p>
357 Sends the current message.  This is equivalent to entering a blank line.
358 </p></dd>
359 <dt><span class="term">
360 <div class="cmdsynopsis"><p><code class="command">answer</code> </p></div>
361 </span></dt>
362 <dd><p>
363 Displays the answer.
364 </p></dd>
365 </dl></div>
366 <p>
367 </p>
368 <p>
369 Lines beginning with a semicolon are comments and are ignored.
370 </p>
371 </div>
372 <div class="refsect1" lang="en">
373 <a name="id2550382"></a><h2>EXAMPLES</h2>
374 <p>
375 The examples below show how
376 <span><strong class="command">nsupdate</strong></span>
377 could be used to insert and delete resource records from the
378 <span class="type">example.com</span>
379 zone.
380 Notice that the input in each example contains a trailing blank line so that
381 a group of commands are sent as one dynamic update request to the
382 master name server for
383 <span class="type">example.com</span>.
384
385 </p>
386 <pre class="programlisting">
387 # nsupdate
388 &gt; update delete oldhost.example.com A
389 &gt; update add newhost.example.com 86400 A 172.16.1.1
390 &gt; send
391 </pre>
392 <p>
393 </p>
394 <p>
395 Any A records for
396 <span class="type">oldhost.example.com</span>
397 are deleted.
398 and an A record for
399 <span class="type">newhost.example.com</span>
400 it IP address 172.16.1.1 is added.
401 The newly-added record has a 1 day TTL (86400 seconds)
402 </p>
403 <pre class="programlisting">
404 # nsupdate
405 &gt; prereq nxdomain nickname.example.com
406 &gt; update add nickname.example.com 86400 CNAME somehost.example.com
407 &gt; send
408 </pre>
409 <p>
410 </p>
411 <p>
412 The prerequisite condition gets the name server to check that there
413 are no resource records of any type for
414 <span class="type">nickname.example.com</span>.
415
416 If there are, the update request fails.
417 If this name does not exist, a CNAME for it is added.
418 This ensures that when the CNAME is added, it cannot conflict with the
419 long-standing rule in RFC1034 that a name must not exist as any other
420 record type if it exists as a CNAME.
421 (The rule has been updated for DNSSEC in RFC2535 to allow CNAMEs to have
422 RRSIG, DNSKEY and NSEC records.)
423 </p>
424 </div>
425 <div class="refsect1" lang="en">
426 <a name="id2550426"></a><h2>FILES</h2>
427 <div class="variablelist"><dl>
428 <dt><span class="term"><code class="constant">/etc/resolv.conf</code></span></dt>
429 <dd><p>
430 used to identify default name server
431 </p></dd>
432 <dt><span class="term"><code class="constant">K{name}.+157.+{random}.key</code></span></dt>
433 <dd><p>
434 base-64 encoding of HMAC-MD5 key created by
435 <span class="citerefentry"><span class="refentrytitle">dnssec-keygen</span>(8)</span>.
436 </p></dd>
437 <dt><span class="term"><code class="constant">K{name}.+157.+{random}.private</code></span></dt>
438 <dd><p>
439 base-64 encoding of HMAC-MD5 key created by
440 <span class="citerefentry"><span class="refentrytitle">dnssec-keygen</span>(8)</span>.
441 </p></dd>
442 </dl></div>
443 </div>
444 <div class="refsect1" lang="en">
445 <a name="id2549061"></a><h2>SEE ALSO</h2>
446 <p>
447 <span class="citerefentry"><span class="refentrytitle">RFC2136</span></span>,
448 <span class="citerefentry"><span class="refentrytitle">RFC3007</span></span>,
449 <span class="citerefentry"><span class="refentrytitle">RFC2104</span></span>,
450 <span class="citerefentry"><span class="refentrytitle">RFC2845</span></span>,
451 <span class="citerefentry"><span class="refentrytitle">RFC1034</span></span>,
452 <span class="citerefentry"><span class="refentrytitle">RFC2535</span></span>,
453 <span class="citerefentry"><span class="refentrytitle">RFC2931</span></span>,
454 <span class="citerefentry"><span class="refentrytitle">named</span>(8)</span>,
455 <span class="citerefentry"><span class="refentrytitle">dnssec-keygen</span>(8)</span>.
456 </p>
457 </div>
458 <div class="refsect1" lang="en">
459 <a name="id2549132"></a><h2>BUGS</h2>
460 <p>
461 The TSIG key is redundantly stored in two separate files.
462 This is a consequence of nsupdate using the DST library
463 for its cryptographic operations, and may change in future
464 releases.
465 </p>
466 </div>
467 </div></body>
468 </html>