]> CyberLeo.Net >> Repos - FreeBSD/releng/9.2.git/blob - contrib/bind9/bin/nsupdate/nsupdate.html
- Copy stable/9 to releng/9.2 as part of the 9.2-RELEASE cycle.
[FreeBSD/releng/9.2.git] / contrib / bind9 / bin / nsupdate / nsupdate.html
1 <!--
2  - Copyright (C) 2004-2010 Internet Systems Consortium, Inc. ("ISC")
3  - Copyright (C) 2000-2003 Internet Software Consortium.
4  - 
5  - Permission to use, copy, modify, and/or 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$ -->
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.71.1">
23 </head>
24 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
25 <a name="man.nsupdate"></a><div class="titlepage"></div>
26 <div class="refnamediv">
27 <h2>Name</h2>
28 <p><span class="application">nsupdate</span> &#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">-D</code>] [[<code class="option">-g</code>] |  [<code class="option">-o</code>] |  [<code class="option">-l</code>] |  [<code class="option">-y <em class="replaceable"><code>[<span class="optional">hmac:</span>]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">-R <em class="replaceable"><code>randomdev</code></em></code>] [<code class="option">-v</code>] [filename]</p></div>
33 </div>
34 <div class="refsect1" lang="en">
35 <a name="id2543459"></a><h2>DESCRIPTION</h2>
36 <p><span><strong class="command">nsupdate</strong></span>
37       is used to submit Dynamic DNS Update requests as defined in RFC 2136
38       to a name server.
39       This allows resource records to be added or removed from a zone
40       without manually editing the zone file.
41       A single update request can contain requests to add or remove more than
42       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       The <code class="option">-D</code> option makes <span><strong class="command">nsupdate</strong></span>
70       report additional debugging information to <code class="option">-d</code>.
71     </p>
72 <p>
73       The <code class="option">-L</code> option with an integer argument of zero or
74       higher sets the logging debug level.  If zero, logging is disabled.
75     </p>
76 <p>
77       Transaction signatures can be used to authenticate the Dynamic
78       DNS updates.  These use the TSIG resource record type described
79       in RFC 2845 or the SIG(0) record described in RFC 2535 and
80       RFC 2931 or GSS-TSIG as described in RFC 3645.  TSIG relies on
81       a shared secret that should only be known to
82       <span><strong class="command">nsupdate</strong></span> and the name server.  Currently,
83       the only supported encryption algorithm for TSIG is HMAC-MD5,
84       which is defined in RFC 2104.  Once other algorithms are
85       defined for TSIG, applications will need to ensure they select
86       the appropriate algorithm as well as the key when authenticating
87       each other.  For instance, suitable <span class="type">key</span> and
88       <span class="type">server</span> statements would be added to
89       <code class="filename">/etc/named.conf</code> so that the name server
90       can associate the appropriate secret key and algorithm with
91       the IP address of the client application that will be using
92       TSIG authentication.  SIG(0) uses public key cryptography.
93       To use a SIG(0) key, the public key must be stored in a KEY
94       record in a zone served by the name server.
95       <span><strong class="command">nsupdate</strong></span> does not read
96       <code class="filename">/etc/named.conf</code>.
97     </p>
98 <p>
99       GSS-TSIG uses Kerberos credentials.  Standard GSS-TSIG mode
100       is switched on with the <code class="option">-g</code> flag.  A
101       non-standards-compliant variant of GSS-TSIG used by Windows
102       2000 can be switched on with the <code class="option">-o</code> flag.
103     </p>
104 <p><span><strong class="command">nsupdate</strong></span>
105       uses the <code class="option">-y</code> or <code class="option">-k</code> option
106       to provide the shared secret needed to generate a TSIG record
107       for authenticating Dynamic DNS update requests, default type
108       HMAC-MD5.  These options are mutually exclusive. 
109     </p>
110 <p>
111       When the <code class="option">-y</code> option is used, a signature is
112       generated from
113       [<span class="optional"><em class="parameter"><code>hmac:</code></em></span>]<em class="parameter"><code>keyname:secret.</code></em>
114       <em class="parameter"><code>keyname</code></em> is the name of the key, and
115       <em class="parameter"><code>secret</code></em> is the base64 encoded shared secret.
116       Use of the <code class="option">-y</code> option is discouraged because the
117       shared secret is supplied as a command line argument in clear text.
118       This may be visible in the output from
119       <span class="citerefentry"><span class="refentrytitle">ps</span>(1)</span>
120       or in a history file maintained by the user's shell.
121     </p>
122 <p>
123       With the
124       <code class="option">-k</code> option, <span><strong class="command">nsupdate</strong></span> reads
125       the shared secret from the file <em class="parameter"><code>keyfile</code></em>.
126       Keyfiles may be in two formats: a single file containing
127       a <code class="filename">named.conf</code>-format <span><strong class="command">key</strong></span>
128       statement, which may be generated automatically by
129       <span><strong class="command">ddns-confgen</strong></span>, or a pair of files whose names are
130       of the format <code class="filename">K{name}.+157.+{random}.key</code> and
131       <code class="filename">K{name}.+157.+{random}.private</code>, which can be
132       generated by <span><strong class="command">dnssec-keygen</strong></span>.
133       The <code class="option">-k</code> may also be used to specify a SIG(0) key used
134       to authenticate Dynamic DNS update requests.  In this case, the key
135       specified is not an HMAC-MD5 key.
136     </p>
137 <p>
138       <span><strong class="command">nsupdate</strong></span> can be run in a local-host only mode
139       using the <code class="option">-l</code> flag.  This sets the server address to
140       localhost (disabling the <span><strong class="command">server</strong></span> so that the server
141       address cannot be overridden).  Connections to the local server will
142       use a TSIG key found in <code class="filename">/var/run/named/session.key</code>,
143       which is automatically generated by <span><strong class="command">named</strong></span> if any
144       local master zone has set <span><strong class="command">update-policy</strong></span> to
145       <span><strong class="command">local</strong></span>.  The location of this key file can be
146       overridden with the <code class="option">-k</code> option.
147     </p>
148 <p>
149       By default, <span><strong class="command">nsupdate</strong></span>
150       uses UDP to send update requests to the name server unless they are too
151       large to fit in a UDP request in which case TCP will be used.
152       The
153       <code class="option">-v</code>
154       option makes
155       <span><strong class="command">nsupdate</strong></span>
156       use a TCP connection.
157       This may be preferable when a batch of update requests is made.
158     </p>
159 <p>
160       The <code class="option">-p</code> sets the default port number to use for
161       connections to a name server.  The default is 53.
162     </p>
163 <p>
164       The <code class="option">-t</code> option sets the maximum time an update request
165       can
166       take before it is aborted.  The default is 300 seconds.  Zero can be
167       used
168       to disable the timeout.
169     </p>
170 <p>
171       The <code class="option">-u</code> option sets the UDP retry interval.  The default
172       is
173       3 seconds.  If zero, the interval will be computed from the timeout
174       interval
175       and number of UDP retries.
176     </p>
177 <p>
178       The <code class="option">-r</code> option sets the number of UDP retries. The
179       default is
180       3.  If zero, only one update request will be made.
181     </p>
182 <p>
183       The <code class="option">-R <em class="replaceable"><code>randomdev</code></em></code> option
184       specifies a source of randomness.  If the operating system
185       does not provide a <code class="filename">/dev/random</code> or
186       equivalent device, the default source of randomness is keyboard
187       input.  <code class="filename">randomdev</code> specifies the name of
188       a character device or file containing random data to be used
189       instead of the default.  The special value
190       <code class="filename">keyboard</code> indicates that keyboard input
191       should be used.  This option may be specified multiple times.
192     </p>
193 </div>
194 <div class="refsect1" lang="en">
195 <a name="id2543790"></a><h2>INPUT FORMAT</h2>
196 <p><span><strong class="command">nsupdate</strong></span>
197       reads input from
198       <em class="parameter"><code>filename</code></em>
199       or standard input.
200       Each command is supplied on exactly one line of input.
201       Some commands are for administrative purposes.
202       The others are either update instructions or prerequisite checks on the
203       contents of the zone.
204       These checks set conditions that some name or set of
205       resource records (RRset) either exists or is absent from the zone.
206       These conditions must be met if the entire update request is to succeed.
207       Updates will be rejected if the tests for the prerequisite conditions
208       fail.
209     </p>
210 <p>
211       Every update request consists of zero or more prerequisites
212       and zero or more updates.
213       This allows a suitably authenticated update request to proceed if some
214       specified resource records are present or missing from the zone.
215       A blank input line (or the <span><strong class="command">send</strong></span> command)
216       causes the
217       accumulated commands to be sent as one Dynamic DNS update request to the
218       name server.
219     </p>
220 <p>
221       The command formats and their meaning are as follows:
222       </p>
223 <div class="variablelist"><dl>
224 <dt><span class="term">
225               <span><strong class="command">server</strong></span>
226                {servername}
227                [port]
228             </span></dt>
229 <dd><p>
230               Sends all dynamic update requests to the name server
231               <em class="parameter"><code>servername</code></em>.
232               When no server statement is provided,
233               <span><strong class="command">nsupdate</strong></span>
234               will send updates to the master server of the correct zone.
235               The MNAME field of that zone's SOA record will identify the
236               master
237               server for that zone.
238               <em class="parameter"><code>port</code></em>
239               is the port number on
240               <em class="parameter"><code>servername</code></em>
241               where the dynamic update requests get sent.
242               If no port number is specified, the default DNS port number of
243               53 is
244               used.
245             </p></dd>
246 <dt><span class="term">
247               <span><strong class="command">local</strong></span>
248                {address}
249                [port]
250             </span></dt>
251 <dd><p>
252               Sends all dynamic update requests using the local
253               <em class="parameter"><code>address</code></em>.
254
255               When no local statement is provided,
256               <span><strong class="command">nsupdate</strong></span>
257               will send updates using an address and port chosen by the
258               system.
259               <em class="parameter"><code>port</code></em>
260               can additionally be used to make requests come from a specific
261               port.
262               If no port number is specified, the system will assign one.
263             </p></dd>
264 <dt><span class="term">
265               <span><strong class="command">zone</strong></span>
266                {zonename}
267             </span></dt>
268 <dd><p>
269               Specifies that all updates are to be made to the zone
270               <em class="parameter"><code>zonename</code></em>.
271               If no
272               <em class="parameter"><code>zone</code></em>
273               statement is provided,
274               <span><strong class="command">nsupdate</strong></span>
275               will attempt determine the correct zone to update based on the
276               rest of the input.
277             </p></dd>
278 <dt><span class="term">
279               <span><strong class="command">class</strong></span>
280                {classname}
281             </span></dt>
282 <dd><p>
283               Specify the default class.
284               If no <em class="parameter"><code>class</code></em> is specified, the
285               default class is
286               <em class="parameter"><code>IN</code></em>.
287             </p></dd>
288 <dt><span class="term">
289               <span><strong class="command">ttl</strong></span>
290                {seconds}
291             </span></dt>
292 <dd><p>
293               Specify the default time to live for records to be added.
294               The value <em class="parameter"><code>none</code></em> will clear the default
295               ttl.
296             </p></dd>
297 <dt><span class="term">
298               <span><strong class="command">key</strong></span>
299                {name}
300                {secret}
301             </span></dt>
302 <dd><p>
303               Specifies that all updates are to be TSIG-signed using the
304               <em class="parameter"><code>keyname</code></em> <em class="parameter"><code>keysecret</code></em> pair.
305               The <span><strong class="command">key</strong></span> command
306               overrides any key specified on the command line via
307               <code class="option">-y</code> or <code class="option">-k</code>.
308             </p></dd>
309 <dt><span class="term">
310             <span><strong class="command">gsstsig</strong></span>
311           </span></dt>
312 <dd><p>
313               Use GSS-TSIG to sign the updated.  This is equivalent to
314               specifying <code class="option">-g</code> on the commandline.
315             </p></dd>
316 <dt><span class="term">
317             <span><strong class="command">oldgsstsig</strong></span>
318           </span></dt>
319 <dd><p>
320               Use the Windows 2000 version of GSS-TSIG to sign the updated.
321               This is equivalent to specifying <code class="option">-o</code> on the
322               commandline.
323             </p></dd>
324 <dt><span class="term">
325             <span><strong class="command">realm</strong></span>
326              {[<span class="optional">realm_name</span>]}
327           </span></dt>
328 <dd><p>
329               When using GSS-TSIG use <em class="parameter"><code>realm_name</code></em> rather
330               than the default realm in <code class="filename">krb5.conf</code>.  If no
331               realm is specified the saved realm is cleared.
332             </p></dd>
333 <dt><span class="term">
334               <span><strong class="command">prereq nxdomain</strong></span>
335                {domain-name}
336             </span></dt>
337 <dd><p>
338               Requires that no resource record of any type exists with name
339               <em class="parameter"><code>domain-name</code></em>.
340             </p></dd>
341 <dt><span class="term">
342               <span><strong class="command">prereq yxdomain</strong></span>
343                {domain-name}
344             </span></dt>
345 <dd><p>
346               Requires that
347               <em class="parameter"><code>domain-name</code></em>
348               exists (has as at least one resource record, of any type).
349             </p></dd>
350 <dt><span class="term">
351               <span><strong class="command">prereq nxrrset</strong></span>
352                {domain-name}
353                [class]
354                {type}
355             </span></dt>
356 <dd><p>
357               Requires that no resource record exists of the specified
358               <em class="parameter"><code>type</code></em>,
359               <em class="parameter"><code>class</code></em>
360               and
361               <em class="parameter"><code>domain-name</code></em>.
362               If
363               <em class="parameter"><code>class</code></em>
364               is omitted, IN (internet) is assumed.
365             </p></dd>
366 <dt><span class="term">
367               <span><strong class="command">prereq yxrrset</strong></span>
368                {domain-name}
369                [class]
370                {type}
371             </span></dt>
372 <dd><p>
373               This requires that a resource record of the specified
374               <em class="parameter"><code>type</code></em>,
375               <em class="parameter"><code>class</code></em>
376               and
377               <em class="parameter"><code>domain-name</code></em>
378               must exist.
379               If
380               <em class="parameter"><code>class</code></em>
381               is omitted, IN (internet) is assumed.
382             </p></dd>
383 <dt><span class="term">
384               <span><strong class="command">prereq yxrrset</strong></span>
385                {domain-name}
386                [class]
387                {type}
388                {data...}
389             </span></dt>
390 <dd><p>
391               The
392               <em class="parameter"><code>data</code></em>
393               from each set of prerequisites of this form
394               sharing a common
395               <em class="parameter"><code>type</code></em>,
396               <em class="parameter"><code>class</code></em>,
397               and
398               <em class="parameter"><code>domain-name</code></em>
399               are combined to form a set of RRs.  This set of RRs must
400               exactly match the set of RRs existing in the zone at the
401               given
402               <em class="parameter"><code>type</code></em>,
403               <em class="parameter"><code>class</code></em>,
404               and
405               <em class="parameter"><code>domain-name</code></em>.
406               The
407               <em class="parameter"><code>data</code></em>
408               are written in the standard text representation of the resource
409               record's
410               RDATA.
411             </p></dd>
412 <dt><span class="term">
413               <span><strong class="command">update delete</strong></span>
414                {domain-name}
415                [ttl]
416                [class]
417                [type [data...]]
418             </span></dt>
419 <dd><p>
420               Deletes any resource records named
421               <em class="parameter"><code>domain-name</code></em>.
422               If
423               <em class="parameter"><code>type</code></em>
424               and
425               <em class="parameter"><code>data</code></em>
426               is provided, only matching resource records will be removed.
427               The internet class is assumed if
428               <em class="parameter"><code>class</code></em>
429               is not supplied.  The
430               <em class="parameter"><code>ttl</code></em>
431               is ignored, and is only allowed for compatibility.
432             </p></dd>
433 <dt><span class="term">
434               <span><strong class="command">update add</strong></span>
435                {domain-name}
436                {ttl}
437                [class]
438                {type}
439                {data...}
440             </span></dt>
441 <dd><p>
442               Adds a new resource record with the specified
443               <em class="parameter"><code>ttl</code></em>,
444               <em class="parameter"><code>class</code></em>
445               and
446               <em class="parameter"><code>data</code></em>.
447             </p></dd>
448 <dt><span class="term">
449               <span><strong class="command">show</strong></span>
450             </span></dt>
451 <dd><p>
452               Displays the current message, containing all of the
453               prerequisites and
454               updates specified since the last send.
455             </p></dd>
456 <dt><span class="term">
457               <span><strong class="command">send</strong></span>
458             </span></dt>
459 <dd><p>
460               Sends the current message.  This is equivalent to entering a
461               blank line.
462             </p></dd>
463 <dt><span class="term">
464               <span><strong class="command">answer</strong></span>
465             </span></dt>
466 <dd><p>
467               Displays the answer.
468             </p></dd>
469 <dt><span class="term">
470               <span><strong class="command">debug</strong></span>
471             </span></dt>
472 <dd><p>
473               Turn on debugging.
474             </p></dd>
475 </dl></div>
476 <p>
477     </p>
478 <p>
479       Lines beginning with a semicolon are comments and are ignored.
480     </p>
481 </div>
482 <div class="refsect1" lang="en">
483 <a name="id2544702"></a><h2>EXAMPLES</h2>
484 <p>
485       The examples below show how
486       <span><strong class="command">nsupdate</strong></span>
487       could be used to insert and delete resource records from the
488       <span class="type">example.com</span>
489       zone.
490       Notice that the input in each example contains a trailing blank line so
491       that
492       a group of commands are sent as one dynamic update request to the
493       master name server for
494       <span class="type">example.com</span>.
495
496       </p>
497 <pre class="programlisting">
498 # nsupdate
499 &gt; update delete oldhost.example.com A
500 &gt; update add newhost.example.com 86400 A 172.16.1.1
501 &gt; send
502 </pre>
503 <p>
504     </p>
505 <p>
506       Any A records for
507       <span class="type">oldhost.example.com</span>
508       are deleted.
509       And an A record for
510       <span class="type">newhost.example.com</span>
511       with IP address 172.16.1.1 is added.
512       The newly-added record has a 1 day TTL (86400 seconds).
513       </p>
514 <pre class="programlisting">
515 # nsupdate
516 &gt; prereq nxdomain nickname.example.com
517 &gt; update add nickname.example.com 86400 CNAME somehost.example.com
518 &gt; send
519 </pre>
520 <p>
521     </p>
522 <p>
523       The prerequisite condition gets the name server to check that there
524       are no resource records of any type for
525       <span class="type">nickname.example.com</span>.
526
527       If there are, the update request fails.
528       If this name does not exist, a CNAME for it is added.
529       This ensures that when the CNAME is added, it cannot conflict with the
530       long-standing rule in RFC 1034 that a name must not exist as any other
531       record type if it exists as a CNAME.
532       (The rule has been updated for DNSSEC in RFC 2535 to allow CNAMEs to have
533       RRSIG, DNSKEY and NSEC records.)
534     </p>
535 </div>
536 <div class="refsect1" lang="en">
537 <a name="id2544746"></a><h2>FILES</h2>
538 <div class="variablelist"><dl>
539 <dt><span class="term"><code class="constant">/etc/resolv.conf</code></span></dt>
540 <dd><p>
541             used to identify default name server
542           </p></dd>
543 <dt><span class="term"><code class="constant">/var/run/named/session.key</code></span></dt>
544 <dd><p>
545             sets the default TSIG key for use in local-only mode
546           </p></dd>
547 <dt><span class="term"><code class="constant">K{name}.+157.+{random}.key</code></span></dt>
548 <dd><p>
549             base-64 encoding of HMAC-MD5 key created by
550             <span class="citerefentry"><span class="refentrytitle">dnssec-keygen</span>(8)</span>.
551           </p></dd>
552 <dt><span class="term"><code class="constant">K{name}.+157.+{random}.private</code></span></dt>
553 <dd><p>
554             base-64 encoding of HMAC-MD5 key created by
555             <span class="citerefentry"><span class="refentrytitle">dnssec-keygen</span>(8)</span>.
556           </p></dd>
557 </dl></div>
558 </div>
559 <div class="refsect1" lang="en">
560 <a name="id2544829"></a><h2>SEE ALSO</h2>
561 <p>
562       <em class="citetitle">RFC 2136</em>,
563       <em class="citetitle">RFC 3007</em>,
564       <em class="citetitle">RFC 2104</em>,
565       <em class="citetitle">RFC 2845</em>,
566       <em class="citetitle">RFC 1034</em>,
567       <em class="citetitle">RFC 2535</em>,
568       <em class="citetitle">RFC 2931</em>,
569       <span class="citerefentry"><span class="refentrytitle">named</span>(8)</span>,
570       <span class="citerefentry"><span class="refentrytitle">ddns-confgen</span>(8)</span>,
571       <span class="citerefentry"><span class="refentrytitle">dnssec-keygen</span>(8)</span>.
572     </p>
573 </div>
574 <div class="refsect1" lang="en">
575 <a name="id2542156"></a><h2>BUGS</h2>
576 <p>
577       The TSIG key is redundantly stored in two separate files.
578       This is a consequence of nsupdate using the DST library
579       for its cryptographic operations, and may change in future
580       releases.
581     </p>
582 </div>
583 </div></body>
584 </html>