~ubuntu-branches/ubuntu/maverick/bind9/maverick

« back to all changes in this revision

Viewing changes to bin/nsupdate/nsupdate.docbook

  • Committer: Bazaar Package Importer
  • Author(s): LaMont Jones, LaMont Jones, Internet Software Consortium, Inc, localization folks
  • Date: 2008-08-02 14:20:20 UTC
  • mfrom: (1.2.1 upstream) (6.1.24 intrepid)
  • Revision ID: james.westby@ubuntu.com-20080802142020-l1hon9jy8lbbjxmg
[LaMont Jones]

* default to using resolvconf if it is installed
* fix sonames and dependencies.  Closes: #149259, #492418
* Do not build-depend libcap2-dev on non-linux.  Closes: #493392
* drop unused query-loc manpage.  Closes: #492564
* lwresd: Deliver /etc/bind directory.  Closes: #490027
* fix query-source comment in default install

[Internet Software Consortium, Inc]

* 9.5.0-P2.  Closes: #492949

[localization folks]

* l10n: Spanish debconf translation.  Closes: #492425 (Ignacio Mondino)
* l10n: Swedish debconf templates.  Closes: #491369 (Martin Ågren)
* l10n: Japanese debconf translations.  Closes: #492048 (Hideki Yamane
  (Debian-JP))
* l10n: Finnish translation.  Closes: #490630 (Esko Arajärvi)
* l10n: Italian debconf translations.  Closes: #492587 (Alessandro Vietta)

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
2
 
               "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
 
1
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 
2
               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3
3
               [<!ENTITY mdash "&#8212;">]>
4
4
<!--
5
 
 - Copyright (C) 2004, 2005  Internet Systems Consortium, Inc. ("ISC")
 
5
 - Copyright (C) 2004-2007  Internet Systems Consortium, Inc. ("ISC")
6
6
 - Copyright (C) 2000-2003  Internet Software Consortium.
7
7
 -
8
 
 - Permission to use, copy, modify, and distribute this software for any
 
8
 - Permission to use, copy, modify, and/or distribute this software for any
9
9
 - purpose with or without fee is hereby granted, provided that the above
10
10
 - copyright notice and this permission notice appear in all copies.
11
11
 -
18
18
 - PERFORMANCE OF THIS SOFTWARE.
19
19
-->
20
20
 
21
 
<!-- $Id: nsupdate.docbook,v 1.8.2.3.2.10 2005/05/12 21:36:03 sra Exp $ -->
22
 
 
 
21
<!-- $Id: nsupdate.docbook,v 1.29 2007/09/15 14:46:03 marka Exp $ -->
23
22
<refentry>
24
 
<refentryinfo>
25
 
<date>Jun 30, 2000</date>
26
 
</refentryinfo>
27
 
<refmeta>
28
 
<refentrytitle>nsupdate</refentrytitle>
29
 
<manvolnum>8</manvolnum>
30
 
<refmiscinfo>BIND9</refmiscinfo>
31
 
</refmeta>
 
23
  <refentryinfo>
 
24
    <date>Jun 30, 2000</date>
 
25
  </refentryinfo>
 
26
  <refmeta>
 
27
    <refentrytitle>nsupdate</refentrytitle>
 
28
    <manvolnum>8</manvolnum>
 
29
    <refmiscinfo>BIND9</refmiscinfo>
 
30
  </refmeta>
 
31
  <refnamediv>
 
32
    <refname>nsupdate</refname>
 
33
    <refpurpose>Dynamic DNS update utility</refpurpose>
 
34
  </refnamediv>
32
35
 
33
36
  <docinfo>
34
37
    <copyright>
35
38
      <year>2004</year>
36
39
      <year>2005</year>
 
40
      <year>2006</year>
 
41
      <year>2007</year>
37
42
      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
38
43
    </copyright>
39
44
    <copyright>
45
50
    </copyright>
46
51
  </docinfo>
47
52
 
48
 
<refnamediv>
49
 
<refname>nsupdate</refname>
50
 
<refpurpose>Dynamic DNS update utility</refpurpose>
51
 
</refnamediv>
52
 
<refsynopsisdiv>
53
 
<cmdsynopsis>
54
 
<command>nsupdate</command>
55
 
<arg><option>-d</option></arg>
56
 
<group>
57
 
  <arg><option>-y <replaceable class="parameter">keyname:secret</replaceable></option></arg>
58
 
  <arg><option>-k <replaceable class="parameter">keyfile</replaceable></option></arg>
59
 
</group>
60
 
<arg><option>-t <replaceable class="parameter">timeout</replaceable></option></arg>
61
 
<arg><option>-u <replaceable class="parameter">udptimeout</replaceable></option></arg>
62
 
<arg><option>-r <replaceable class="parameter">udpretries</replaceable></option></arg>
63
 
<arg><option>-v</option></arg>
64
 
<arg>filename</arg>
65
 
</cmdsynopsis>
66
 
</refsynopsisdiv>
67
 
 
68
 
<refsect1>
69
 
<title>DESCRIPTION</title>
70
 
<para>
71
 
<command>nsupdate</command>
72
 
is used to submit Dynamic DNS Update requests as defined in RFC2136
73
 
to a name server.
74
 
This allows resource records to be added or removed from a zone
75
 
without manually editing the zone file.
76
 
A single update request can contain requests to add or remove more than one
77
 
resource record.
78
 
</para>
79
 
<para>
80
 
Zones that are under dynamic control via
81
 
<command>nsupdate</command>
82
 
or a DHCP server should not be edited by hand.
83
 
Manual edits could
84
 
conflict with dynamic updates and cause data to be lost.
85
 
</para>
86
 
<para>
87
 
The resource records that are dynamically added or removed with
88
 
<command>nsupdate</command>
89
 
have to be in the same zone.
90
 
Requests are sent to the zone's master server.
91
 
This is identified by the MNAME field of the zone's SOA record.
92
 
</para>
93
 
<para>
94
 
The
95
 
<option>-d</option>
96
 
option makes
97
 
<command>nsupdate</command>
98
 
operate in debug mode.
99
 
This provides tracing information about the update requests that are
100
 
made and the replies received from the name server.
101
 
</para>
102
 
<para>
103
 
Transaction signatures can be used to authenticate the Dynamic DNS
104
 
updates.
105
 
These use the TSIG resource record type described in RFC2845 or the
106
 
SIG(0) record described in RFC3535 and RFC2931.
107
 
TSIG relies on a shared secret that should only be known to
108
 
<command>nsupdate</command> and the name server.
109
 
Currently, the only supported encryption algorithm for TSIG is
110
 
HMAC-MD5, which is defined in RFC 2104.
111
 
Once other algorithms are defined for TSIG, applications will need to
112
 
ensure they select the appropriate algorithm as well as the key when
113
 
authenticating each other.
114
 
For instance suitable
115
 
<type>key</type>
116
 
and
117
 
<type>server</type>
118
 
statements would be added to
119
 
<filename>/etc/named.conf</filename>
120
 
so that the name server can associate the appropriate secret key
121
 
and algorithm with the IP address of the
122
 
client application that will be using TSIG authentication.
123
 
SIG(0) uses public key cryptography.  To use a SIG(0) key, the public
124
 
key must be stored in a KEY record in a zone served by the name server.
125
 
<command>nsupdate</command>
126
 
does not read
127
 
<filename>/etc/named.conf</filename>.
128
 
</para>
129
 
<para>
130
 
<command>nsupdate</command>
131
 
uses the
132
 
<option>-y</option>
133
 
or
134
 
<option>-k</option>
135
 
option (with an HMAC-MD5 key) to provide the shared secret needed to generate
136
 
a TSIG record for authenticating Dynamic DNS update requests.
137
 
These options are mutually exclusive.
138
 
With the
139
 
<option>-k</option>
140
 
option,
141
 
<command>nsupdate</command>
142
 
reads the shared secret from the file
143
 
<parameter>keyfile</parameter>,
144
 
whose name is of the form 
145
 
<filename>K{name}.+157.+{random}.private</filename>.
146
 
For historical
147
 
reasons, the file 
148
 
<filename>K{name}.+157.+{random}.key</filename>
149
 
must also be present.  When the
150
 
<option>-y</option>
151
 
option is used, a signature is generated from
152
 
<parameter>keyname:secret.</parameter>
153
 
<parameter>keyname</parameter>
154
 
is the name of the key,
155
 
and
156
 
<parameter>secret</parameter>
157
 
is the base64 encoded shared secret.
158
 
Use of the
159
 
<option>-y</option>
160
 
option is discouraged because the shared secret is supplied as a command
161
 
line argument in clear text.
162
 
This may be visible in the output from
163
 
<citerefentry>
164
 
<refentrytitle>ps</refentrytitle><manvolnum>1
165
 
</manvolnum>
166
 
</citerefentry>
167
 
or in a history file maintained by the user's shell.
168
 
</para>
169
 
<para>
170
 
The <option>-k</option> may also be used to specify a SIG(0) key used
171
 
to authenticate Dynamic DNS update requests.  In this case, the key
172
 
specified is not an HMAC-MD5 key.
173
 
</para>
174
 
<para>
175
 
By default
176
 
<command>nsupdate</command>
177
 
uses UDP to send update requests to the name server unless they are too
178
 
large to fit in a UDP request in which case TCP will be used.
179
 
The
180
 
<option>-v</option>
181
 
option makes
182
 
<command>nsupdate</command>
183
 
use a TCP connection.
184
 
This may be preferable when a batch of update requests is made.
185
 
</para>
186
 
<para>The <option>-t</option> option sets the maximum time a update request can
187
 
take before it is aborted.  The default is 300 seconds.  Zero can be used
188
 
to disable the timeout.
189
 
</para>
190
 
<para>The <option>-u</option> option sets the UDP retry interval.  The default is
191
 
3 seconds.  If zero the interval will be computed from the timeout interval
192
 
and number of UDP retries.
193
 
</para>
194
 
<para>The <option>-r</option> option sets the number of UDP retries. The default is
195
 
3.  If zero only one update request will be made.
196
 
</para>
197
 
</refsect1>
198
 
 
199
 
<refsect1>
200
 
<title>INPUT FORMAT</title>
201
 
<para>
202
 
<command>nsupdate</command>
203
 
reads input from
204
 
<parameter>filename</parameter>
205
 
or standard input.
206
 
Each command is supplied on exactly one line of input.
207
 
Some commands are for administrative purposes.
208
 
The others are either update instructions or prerequisite checks on the
209
 
contents of the zone.
210
 
These checks set conditions that some name or set of
211
 
resource records (RRset) either exists or is absent from the zone.
212
 
These conditions must be met if the entire update request is to succeed.
213
 
Updates will be rejected if the tests for the prerequisite conditions fail.
214
 
</para>
215
 
<para>
216
 
Every update request consists of zero or more prerequisites
217
 
and zero or more updates.
218
 
This allows a suitably authenticated update request to proceed if some
219
 
specified resource records are present or missing from the zone.
220
 
A blank input line (or the <command>send</command> command) causes the
221
 
accumulated commands to be sent as one Dynamic DNS update request to the
222
 
name server.
223
 
</para>
224
 
<para>
225
 
The command formats and their meaning are as follows:
226
 
<variablelist>
227
 
<varlistentry><term>
228
 
<cmdsynopsis>
229
 
<command>server</command>
230
 
<arg choice="req">servername</arg>
231
 
<arg choice="opt">port</arg>
232
 
</cmdsynopsis>
233
 
</term>
234
 
<listitem>
235
 
<para>
236
 
Sends all dynamic update requests to the name server
237
 
<parameter>servername</parameter>.
238
 
When no server statement is provided,
239
 
<command>nsupdate</command>
240
 
will send updates to the master server of the correct zone.
241
 
The MNAME field of that zone's SOA record will identify the master
242
 
server for that zone.
243
 
<parameter>port</parameter>
244
 
is the port number on
245
 
<parameter>servername</parameter>
246
 
where the dynamic update requests get sent.
247
 
If no port number is specified, the default DNS port number of 53 is
248
 
used.
249
 
</para>
250
 
</listitem>
251
 
</varlistentry>
252
 
 
253
 
<varlistentry><term>
254
 
<cmdsynopsis>
255
 
<command>local</command>
256
 
<arg choice="req">address</arg>
257
 
<arg choice="opt">port</arg>
258
 
</cmdsynopsis>
259
 
</term>
260
 
<listitem>
261
 
<para>
262
 
Sends all dynamic update requests using the local
263
 
<parameter>address</parameter>.
264
 
 
265
 
When no local statement is provided,
266
 
<command>nsupdate</command>
267
 
will send updates using an address and port chosen by the system.
268
 
<parameter>port</parameter>
269
 
can additionally be used to make requests come from a specific port.
270
 
If no port number is specified, the system will assign one.
271
 
</para>
272
 
</listitem>
273
 
</varlistentry>
274
 
 
275
 
<varlistentry><term>
276
 
<cmdsynopsis>
277
 
<command>zone</command>
278
 
<arg choice="req">zonename</arg>
279
 
</cmdsynopsis>
280
 
</term>
281
 
<listitem>
282
 
<para>
283
 
Specifies that all updates are to be made to the zone
284
 
<parameter>zonename</parameter>.
285
 
If no
286
 
<parameter>zone</parameter>
287
 
statement is provided,
288
 
<command>nsupdate</command>
289
 
will attempt determine the correct zone to update based on the rest of the input.
290
 
</para>
291
 
</listitem>
292
 
</varlistentry>
293
 
 
294
 
<varlistentry><term>
295
 
<cmdsynopsis>
296
 
<command>class</command>
297
 
<arg choice="req">classname</arg>
298
 
</cmdsynopsis>
299
 
</term>
300
 
<listitem>
301
 
<para>
302
 
Specify the default class.
303
 
If no <parameter>class</parameter> is specified the default class is
304
 
<parameter>IN</parameter>.
305
 
</para>
306
 
</listitem>
307
 
</varlistentry>
308
 
 
309
 
<varlistentry><term>
310
 
<cmdsynopsis>
311
 
<command>key</command>
312
 
<arg choice="req">name</arg>
313
 
<arg choice="req">secret</arg>
314
 
</cmdsynopsis>
315
 
</term>
316
 
<listitem>
317
 
<para>
318
 
Specifies that all updates are to be TSIG signed using the
319
 
<parameter>keyname</parameter> <parameter>keysecret</parameter> pair.
320
 
The <command>key</command> command
321
 
overrides any key specified on the command line via
322
 
<option>-y</option> or <option>-k</option>.
323
 
</para>
324
 
</listitem>
325
 
</varlistentry>
326
 
 
327
 
<varlistentry><term>
328
 
<cmdsynopsis>
329
 
<command>prereq nxdomain</command>
330
 
<arg choice="req">domain-name</arg>
331
 
</cmdsynopsis>
332
 
</term>
333
 
<listitem>
334
 
<para>
335
 
Requires that no resource record of any type exists with name
336
 
<parameter>domain-name</parameter>.
337
 
</para>
338
 
</listitem>
339
 
</varlistentry>
340
 
 
341
 
 
342
 
<varlistentry><term>
343
 
<cmdsynopsis>
344
 
<command>prereq yxdomain</command>
345
 
<arg choice="req">domain-name</arg>
346
 
</cmdsynopsis>
347
 
</term>
348
 
<listitem>
349
 
<para>
350
 
Requires that
351
 
<parameter>domain-name</parameter>
352
 
exists (has as at least one resource record, of any type).
353
 
</para>
354
 
</listitem>
355
 
</varlistentry>
356
 
 
357
 
<varlistentry><term>
358
 
<cmdsynopsis>
359
 
<command>prereq nxrrset</command>
360
 
<arg choice="req">domain-name</arg>
361
 
<arg choice="opt">class</arg>
362
 
<arg choice="req">type</arg>
363
 
</cmdsynopsis>
364
 
</term>
365
 
<listitem>
366
 
<para>
367
 
Requires that no resource record exists of the specified
368
 
<parameter>type</parameter>,
369
 
<parameter>class</parameter>
370
 
and
371
 
<parameter>domain-name</parameter>.
372
 
If
373
 
<parameter>class</parameter>
374
 
is omitted, IN (internet) is assumed.
375
 
</para>
376
 
</listitem>
377
 
</varlistentry>
378
 
 
379
 
 
380
 
<varlistentry><term>
381
 
<cmdsynopsis>
382
 
<command>prereq yxrrset</command>
383
 
<arg choice="req">domain-name</arg>
384
 
<arg choice="opt">class</arg>
385
 
<arg choice="req">type</arg>
386
 
</cmdsynopsis>
387
 
</term>
388
 
<listitem>
389
 
<para>
390
 
This requires that a resource record of the specified
391
 
<parameter>type</parameter>,
392
 
<parameter>class</parameter>
393
 
and
394
 
<parameter>domain-name</parameter>
395
 
must exist.
396
 
If
397
 
<parameter>class</parameter>
398
 
is omitted, IN (internet) is assumed.
399
 
</para>
400
 
</listitem>
401
 
</varlistentry>
402
 
 
403
 
<varlistentry><term>
404
 
<cmdsynopsis>
405
 
<command>prereq yxrrset</command>
406
 
<arg choice="req">domain-name</arg>
407
 
<arg choice="opt">class</arg>
408
 
<arg choice="req">type</arg>
409
 
<arg choice="req" rep="repeat">data</arg>
410
 
</cmdsynopsis>
411
 
</term>
412
 
<listitem>
413
 
<para>
414
 
The
415
 
<parameter>data</parameter>
416
 
from each set of prerequisites of this form
417
 
sharing a common
418
 
<parameter>type</parameter>,
419
 
<parameter>class</parameter>,
420
 
and 
421
 
<parameter>domain-name</parameter>
422
 
are combined to form a set of RRs.  This set of RRs must
423
 
exactly match the set of RRs existing in the zone at the
424
 
given 
425
 
<parameter>type</parameter>,
426
 
<parameter>class</parameter>,
427
 
and 
428
 
<parameter>domain-name</parameter>.
429
 
The
430
 
<parameter>data</parameter>
431
 
are written in the standard text representation of the resource record's
432
 
RDATA.
433
 
</para>
434
 
</listitem>
435
 
</varlistentry>
436
 
 
437
 
<varlistentry><term>
438
 
<cmdsynopsis>
439
 
<command>update delete</command>
440
 
<arg choice="req">domain-name</arg>
441
 
<arg choice="opt">ttl</arg>
442
 
<arg choice="opt">class</arg>
443
 
<arg choice="opt">type <arg choice="opt" rep="repeat">data</arg></arg>
444
 
</cmdsynopsis>
445
 
</term>
446
 
<listitem>
447
 
<para>
448
 
Deletes any resource records named
449
 
<parameter>domain-name</parameter>.
450
 
If
451
 
<parameter>type</parameter>
452
 
and
453
 
<parameter>data</parameter>
454
 
is provided, only matching resource records will be removed.
455
 
The internet class is assumed if
456
 
<parameter>class</parameter>
457
 
is not supplied.  The
458
 
<parameter>ttl</parameter>
459
 
is ignored, and is only allowed for compatibility.
460
 
</para>
461
 
</listitem>
462
 
</varlistentry>
463
 
 
464
 
<varlistentry><term>
465
 
<cmdsynopsis>
466
 
<command>update add</command>
467
 
<arg choice="req">domain-name</arg>
468
 
<arg choice="req">ttl</arg>
469
 
<arg choice="opt">class</arg>
470
 
<arg choice="req">type</arg>
471
 
<arg choice="req" rep="repeat">data</arg>
472
 
</cmdsynopsis>
473
 
</term>
474
 
<listitem>
475
 
<para>
476
 
Adds a new resource record with the specified
477
 
<parameter>ttl</parameter>,
478
 
<parameter>class</parameter>
479
 
and
480
 
<parameter>data</parameter>.
481
 
</para>
482
 
</listitem>
483
 
</varlistentry>
484
 
 
485
 
<varlistentry><term>
486
 
<cmdsynopsis>
487
 
<command>show</command>
488
 
</cmdsynopsis>
489
 
</term>
490
 
<listitem>
491
 
<para>
492
 
Displays the current message, containing all of the prerequisites and
493
 
updates specified since the last send.
494
 
</para>
495
 
</listitem>
496
 
</varlistentry>
497
 
 
498
 
<varlistentry><term>
499
 
<cmdsynopsis>
500
 
<command>send</command>
501
 
</cmdsynopsis>
502
 
</term>
503
 
<listitem>
504
 
<para>
505
 
Sends the current message.  This is equivalent to entering a blank line.
506
 
</para>
507
 
</listitem>
508
 
</varlistentry>
509
 
 
510
 
<varlistentry><term>
511
 
<cmdsynopsis>
512
 
<command>answer</command>
513
 
</cmdsynopsis>
514
 
</term>
515
 
<listitem>
516
 
<para>
517
 
Displays the answer.
518
 
</para>
519
 
</listitem>
520
 
</varlistentry>
521
 
 
522
 
</variablelist>
523
 
</para>
524
 
 
525
 
<para>
526
 
Lines beginning with a semicolon are comments and are ignored.
527
 
</para>
528
 
 
529
 
</refsect1>
530
 
 
531
 
<refsect1>
532
 
<title>EXAMPLES</title>
533
 
<para>
534
 
The examples below show how
535
 
<command>nsupdate</command>
536
 
could be used to insert and delete resource records from the
537
 
<type>example.com</type>
538
 
zone.
539
 
Notice that the input in each example contains a trailing blank line so that
540
 
a group of commands are sent as one dynamic update request to the
541
 
master name server for
542
 
<type>example.com</type>.
543
 
 
544
 
<programlisting>
545
 
# nsupdate
546
 
> update delete oldhost.example.com A
547
 
> update add newhost.example.com 86400 A 172.16.1.1
548
 
> send
549
 
</programlisting>
550
 
</para>
551
 
<para>
552
 
Any A records for
553
 
<type>oldhost.example.com</type>
554
 
are deleted.
555
 
and an A record for
556
 
<type>newhost.example.com</type>
557
 
it IP address 172.16.1.1 is added.
558
 
The newly-added record has a 1 day TTL (86400 seconds)
559
 
<programlisting>
560
 
# nsupdate
561
 
> prereq nxdomain nickname.example.com
562
 
> update add nickname.example.com 86400 CNAME somehost.example.com
563
 
> send
564
 
</programlisting>
565
 
</para>
566
 
<para>
567
 
The prerequisite condition gets the name server to check that there
568
 
are no resource records of any type for
569
 
<type>nickname.example.com</type>.
570
 
 
571
 
If there are, the update request fails.
572
 
If this name does not exist, a CNAME for it is added.
573
 
This ensures that when the CNAME is added, it cannot conflict with the
574
 
long-standing rule in RFC1034 that a name must not exist as any other
575
 
record type if it exists as a CNAME.
576
 
(The rule has been updated for DNSSEC in RFC2535 to allow CNAMEs to have
577
 
RRSIG, DNSKEY and NSEC records.)
578
 
</para>
579
 
</refsect1>
580
 
 
581
 
<refsect1>
582
 
<title>FILES</title>
583
 
 
584
 
<variablelist>
585
 
<varlistentry><term><constant>/etc/resolv.conf</constant></term>
586
 
<listitem>
587
 
<para>
588
 
used to identify default name server
589
 
</para>
590
 
</listitem>
591
 
</varlistentry>
592
 
 
593
 
<varlistentry><term><constant>K{name}.+157.+{random}.key</constant></term>
594
 
<listitem>
595
 
<para>
596
 
base-64 encoding of HMAC-MD5 key created by
597
 
<citerefentry>
598
 
<refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
599
 
</citerefentry>.
600
 
</para>
601
 
</listitem>
602
 
</varlistentry>
603
 
 
604
 
<varlistentry><term><constant>K{name}.+157.+{random}.private</constant></term>
605
 
<listitem>
606
 
<para>
607
 
base-64 encoding of HMAC-MD5 key created by
608
 
<citerefentry>
609
 
<refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
610
 
</citerefentry>.
611
 
</para>
612
 
</listitem>
613
 
</varlistentry>
614
 
</variablelist>
615
 
</refsect1>
616
 
 
617
 
<refsect1>
618
 
<title>SEE ALSO</title>
619
 
<para>
620
 
<citerefentry>
621
 
<refentrytitle>RFC2136</refentrytitle>
622
 
</citerefentry>,
623
 
<citerefentry>
624
 
<refentrytitle>RFC3007</refentrytitle>
625
 
</citerefentry>,
626
 
<citerefentry>
627
 
<refentrytitle>RFC2104</refentrytitle>
628
 
</citerefentry>,
629
 
<citerefentry>
630
 
<refentrytitle>RFC2845</refentrytitle>
631
 
</citerefentry>,
632
 
<citerefentry>
633
 
<refentrytitle>RFC1034</refentrytitle>
634
 
</citerefentry>,
635
 
<citerefentry>
636
 
<refentrytitle>RFC2535</refentrytitle>
637
 
</citerefentry>,
638
 
<citerefentry>
639
 
<refentrytitle>RFC2931</refentrytitle>
640
 
</citerefentry>,
641
 
<citerefentry>
642
 
<refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
643
 
</citerefentry>,
644
 
<citerefentry>
645
 
<refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
646
 
</citerefentry>.
647
 
</para>
648
 
</refsect1>
649
 
<refsect1>
650
 
<title>BUGS</title>
651
 
<para>
652
 
The TSIG key is redundantly stored in two separate files.
653
 
This is a consequence of nsupdate using the DST library
654
 
for its cryptographic operations, and may change in future
655
 
releases.
656
 
</para>
657
 
</refsect1>
658
 
</refentry>
 
53
  <refsynopsisdiv>
 
54
    <cmdsynopsis>
 
55
      <command>nsupdate</command>
 
56
      <arg><option>-d</option></arg>
 
57
      <group>
 
58
        <arg><option>-y <replaceable class="parameter"><optional>hmac:</optional>keyname:secret</replaceable></option></arg>
 
59
        <arg><option>-k <replaceable class="parameter">keyfile</replaceable></option></arg>
 
60
      </group>
 
61
      <arg><option>-t <replaceable class="parameter">timeout</replaceable></option></arg>
 
62
      <arg><option>-u <replaceable class="parameter">udptimeout</replaceable></option></arg>
 
63
      <arg><option>-r <replaceable class="parameter">udpretries</replaceable></option></arg>
 
64
      <arg><option>-R <replaceable class="parameter">randomdev</replaceable></option></arg>
 
65
      <arg><option>-v</option></arg>
 
66
      <arg>filename</arg>
 
67
    </cmdsynopsis>
 
68
  </refsynopsisdiv>
 
69
 
 
70
  <refsect1>
 
71
    <title>DESCRIPTION</title>
 
72
    <para><command>nsupdate</command>
 
73
      is used to submit Dynamic DNS Update requests as defined in RFC2136
 
74
      to a name server.
 
75
      This allows resource records to be added or removed from a zone
 
76
      without manually editing the zone file.
 
77
      A single update request can contain requests to add or remove more than
 
78
      one
 
79
      resource record.
 
80
    </para>
 
81
    <para>
 
82
      Zones that are under dynamic control via
 
83
      <command>nsupdate</command>
 
84
      or a DHCP server should not be edited by hand.
 
85
      Manual edits could
 
86
      conflict with dynamic updates and cause data to be lost.
 
87
    </para>
 
88
    <para>
 
89
      The resource records that are dynamically added or removed with
 
90
      <command>nsupdate</command>
 
91
      have to be in the same zone.
 
92
      Requests are sent to the zone's master server.
 
93
      This is identified by the MNAME field of the zone's SOA record.
 
94
    </para>
 
95
    <para>
 
96
      The
 
97
      <option>-d</option>
 
98
      option makes
 
99
      <command>nsupdate</command>
 
100
      operate in debug mode.
 
101
      This provides tracing information about the update requests that are
 
102
      made and the replies received from the name server.
 
103
    </para>
 
104
    <para>
 
105
      Transaction signatures can be used to authenticate the Dynamic DNS
 
106
      updates.
 
107
      These use the TSIG resource record type described in RFC2845 or the
 
108
      SIG(0) record described in RFC3535 and RFC2931.
 
109
      TSIG relies on a shared secret that should only be known to
 
110
      <command>nsupdate</command> and the name server.
 
111
      Currently, the only supported encryption algorithm for TSIG is
 
112
      HMAC-MD5, which is defined in RFC 2104.
 
113
      Once other algorithms are defined for TSIG, applications will need to
 
114
      ensure they select the appropriate algorithm as well as the key when
 
115
      authenticating each other.
 
116
      For instance, suitable
 
117
      <type>key</type>
 
118
      and
 
119
      <type>server</type>
 
120
      statements would be added to
 
121
      <filename>/etc/named.conf</filename>
 
122
      so that the name server can associate the appropriate secret key
 
123
      and algorithm with the IP address of the
 
124
      client application that will be using TSIG authentication.
 
125
      SIG(0) uses public key cryptography.  To use a SIG(0) key, the public
 
126
      key must be stored in a KEY record in a zone served by the name server.
 
127
      <command>nsupdate</command>
 
128
      does not read
 
129
      <filename>/etc/named.conf</filename>.
 
130
    </para>
 
131
    <para><command>nsupdate</command>
 
132
      uses the <option>-y</option> or <option>-k</option> option
 
133
      to provide the shared secret needed to generate a TSIG record
 
134
      for authenticating Dynamic DNS update requests, default type
 
135
      HMAC-MD5.  These options are mutually exclusive.  With the
 
136
      <option>-k</option> option, <command>nsupdate</command> reads
 
137
      the shared secret from the file <parameter>keyfile</parameter>,
 
138
      whose name is of the form
 
139
      <filename>K{name}.+157.+{random}.private</filename>.  For
 
140
      historical reasons, the file
 
141
      <filename>K{name}.+157.+{random}.key</filename> must also be
 
142
      present.  When the <option>-y</option> option is used, a
 
143
      signature is generated from
 
144
      <optional><parameter>hmac:</parameter></optional><parameter>keyname:secret.</parameter>
 
145
      <parameter>keyname</parameter> is the name of the key, and
 
146
      <parameter>secret</parameter> is the base64 encoded shared
 
147
      secret.  Use of the <option>-y</option> option is discouraged
 
148
      because the shared secret is supplied as a command line
 
149
      argument in clear text.  This may be visible in the output
 
150
      from
 
151
      <citerefentry>
 
152
        <refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum>
 
153
      </citerefentry> or in a history file maintained by the user's
 
154
      shell.
 
155
    </para>
 
156
    <para>
 
157
      The <option>-k</option> may also be used to specify a SIG(0) key used
 
158
      to authenticate Dynamic DNS update requests.  In this case, the key
 
159
      specified is not an HMAC-MD5 key.
 
160
    </para>
 
161
    <para>
 
162
      By default
 
163
      <command>nsupdate</command>
 
164
      uses UDP to send update requests to the name server unless they are too
 
165
      large to fit in a UDP request in which case TCP will be used.
 
166
      The
 
167
      <option>-v</option>
 
168
      option makes
 
169
      <command>nsupdate</command>
 
170
      use a TCP connection.
 
171
      This may be preferable when a batch of update requests is made.
 
172
    </para>
 
173
    <para>
 
174
      The <option>-t</option> option sets the maximum time an update request
 
175
      can
 
176
      take before it is aborted.  The default is 300 seconds.  Zero can be
 
177
      used
 
178
      to disable the timeout.
 
179
    </para>
 
180
    <para>
 
181
      The <option>-u</option> option sets the UDP retry interval.  The default
 
182
      is
 
183
      3 seconds.  If zero, the interval will be computed from the timeout
 
184
      interval
 
185
      and number of UDP retries.
 
186
    </para>
 
187
    <para>
 
188
      The <option>-r</option> option sets the number of UDP retries. The
 
189
      default is
 
190
      3.  If zero, only one update request will be made.
 
191
    </para>
 
192
    <para>
 
193
      The <option>-R <replaceable
 
194
      class="parameter">randomdev</replaceable></option> option
 
195
      specifies a source of randomness.  If the operating system
 
196
      does not provide a <filename>/dev/random</filename> or
 
197
      equivalent device, the default source of randomness is keyboard
 
198
      input.  <filename>randomdev</filename> specifies the name of
 
199
      a character device or file containing random data to be used
 
200
      instead of the default.  The special value
 
201
      <filename>keyboard</filename> indicates that keyboard input
 
202
      should be used.  This option may be specified multiple times.
 
203
    </para>
 
204
  </refsect1>
 
205
 
 
206
  <refsect1>
 
207
    <title>INPUT FORMAT</title>
 
208
    <para><command>nsupdate</command>
 
209
      reads input from
 
210
      <parameter>filename</parameter>
 
211
      or standard input.
 
212
      Each command is supplied on exactly one line of input.
 
213
      Some commands are for administrative purposes.
 
214
      The others are either update instructions or prerequisite checks on the
 
215
      contents of the zone.
 
216
      These checks set conditions that some name or set of
 
217
      resource records (RRset) either exists or is absent from the zone.
 
218
      These conditions must be met if the entire update request is to succeed.
 
219
      Updates will be rejected if the tests for the prerequisite conditions
 
220
      fail.
 
221
    </para>
 
222
    <para>
 
223
      Every update request consists of zero or more prerequisites
 
224
      and zero or more updates.
 
225
      This allows a suitably authenticated update request to proceed if some
 
226
      specified resource records are present or missing from the zone.
 
227
      A blank input line (or the <command>send</command> command)
 
228
      causes the
 
229
      accumulated commands to be sent as one Dynamic DNS update request to the
 
230
      name server.
 
231
    </para>
 
232
    <para>
 
233
      The command formats and their meaning are as follows:
 
234
      <variablelist>
 
235
 
 
236
        <varlistentry>
 
237
          <term>
 
238
              <command>server</command>
 
239
              <arg choice="req">servername</arg>
 
240
              <arg choice="opt">port</arg>
 
241
            </term>
 
242
          <listitem>
 
243
            <para>
 
244
              Sends all dynamic update requests to the name server
 
245
              <parameter>servername</parameter>.
 
246
              When no server statement is provided,
 
247
              <command>nsupdate</command>
 
248
              will send updates to the master server of the correct zone.
 
249
              The MNAME field of that zone's SOA record will identify the
 
250
              master
 
251
              server for that zone.
 
252
              <parameter>port</parameter>
 
253
              is the port number on
 
254
              <parameter>servername</parameter>
 
255
              where the dynamic update requests get sent.
 
256
              If no port number is specified, the default DNS port number of
 
257
              53 is
 
258
              used.
 
259
            </para>
 
260
          </listitem>
 
261
        </varlistentry>
 
262
 
 
263
        <varlistentry>
 
264
          <term>
 
265
              <command>local</command>
 
266
              <arg choice="req">address</arg>
 
267
              <arg choice="opt">port</arg>
 
268
            </term>
 
269
          <listitem>
 
270
            <para>
 
271
              Sends all dynamic update requests using the local
 
272
              <parameter>address</parameter>.
 
273
 
 
274
              When no local statement is provided,
 
275
              <command>nsupdate</command>
 
276
              will send updates using an address and port chosen by the
 
277
              system.
 
278
              <parameter>port</parameter>
 
279
              can additionally be used to make requests come from a specific
 
280
              port.
 
281
              If no port number is specified, the system will assign one.
 
282
            </para>
 
283
          </listitem>
 
284
        </varlistentry>
 
285
 
 
286
        <varlistentry>
 
287
          <term>
 
288
              <command>zone</command>
 
289
              <arg choice="req">zonename</arg>
 
290
            </term>
 
291
          <listitem>
 
292
            <para>
 
293
              Specifies that all updates are to be made to the zone
 
294
              <parameter>zonename</parameter>.
 
295
              If no
 
296
              <parameter>zone</parameter>
 
297
              statement is provided,
 
298
              <command>nsupdate</command>
 
299
              will attempt determine the correct zone to update based on the
 
300
              rest of the input.
 
301
            </para>
 
302
          </listitem>
 
303
        </varlistentry>
 
304
 
 
305
        <varlistentry>
 
306
          <term>
 
307
              <command>class</command>
 
308
              <arg choice="req">classname</arg>
 
309
            </term>
 
310
          <listitem>
 
311
            <para>
 
312
              Specify the default class.
 
313
              If no <parameter>class</parameter> is specified, the
 
314
              default class is
 
315
              <parameter>IN</parameter>.
 
316
            </para>
 
317
          </listitem>
 
318
        </varlistentry>
 
319
 
 
320
        <varlistentry>
 
321
          <term>
 
322
              <command>key</command>
 
323
              <arg choice="req">name</arg>
 
324
              <arg choice="req">secret</arg>
 
325
            </term>
 
326
          <listitem>
 
327
            <para>
 
328
              Specifies that all updates are to be TSIG-signed using the
 
329
              <parameter>keyname</parameter> <parameter>keysecret</parameter> pair.
 
330
              The <command>key</command> command
 
331
              overrides any key specified on the command line via
 
332
              <option>-y</option> or <option>-k</option>.
 
333
            </para>
 
334
          </listitem>
 
335
        </varlistentry>
 
336
 
 
337
        <varlistentry>
 
338
          <term>
 
339
              <command>prereq nxdomain</command>
 
340
              <arg choice="req">domain-name</arg>
 
341
            </term>
 
342
          <listitem>
 
343
            <para>
 
344
              Requires that no resource record of any type exists with name
 
345
              <parameter>domain-name</parameter>.
 
346
            </para>
 
347
          </listitem>
 
348
        </varlistentry>
 
349
 
 
350
 
 
351
        <varlistentry>
 
352
          <term>
 
353
              <command>prereq yxdomain</command>
 
354
              <arg choice="req">domain-name</arg>
 
355
            </term>
 
356
          <listitem>
 
357
            <para>
 
358
              Requires that
 
359
              <parameter>domain-name</parameter>
 
360
              exists (has as at least one resource record, of any type).
 
361
            </para>
 
362
          </listitem>
 
363
        </varlistentry>
 
364
 
 
365
        <varlistentry>
 
366
          <term>
 
367
              <command>prereq nxrrset</command>
 
368
              <arg choice="req">domain-name</arg>
 
369
              <arg choice="opt">class</arg>
 
370
              <arg choice="req">type</arg>
 
371
            </term>
 
372
          <listitem>
 
373
            <para>
 
374
              Requires that no resource record exists of the specified
 
375
              <parameter>type</parameter>,
 
376
              <parameter>class</parameter>
 
377
              and
 
378
              <parameter>domain-name</parameter>.
 
379
              If
 
380
              <parameter>class</parameter>
 
381
              is omitted, IN (internet) is assumed.
 
382
            </para>
 
383
          </listitem>
 
384
        </varlistentry>
 
385
 
 
386
 
 
387
        <varlistentry>
 
388
          <term>
 
389
              <command>prereq yxrrset</command>
 
390
              <arg choice="req">domain-name</arg>
 
391
              <arg choice="opt">class</arg>
 
392
              <arg choice="req">type</arg>
 
393
            </term>
 
394
          <listitem>
 
395
            <para>
 
396
              This requires that a resource record of the specified
 
397
              <parameter>type</parameter>,
 
398
              <parameter>class</parameter>
 
399
              and
 
400
              <parameter>domain-name</parameter>
 
401
              must exist.
 
402
              If
 
403
              <parameter>class</parameter>
 
404
              is omitted, IN (internet) is assumed.
 
405
            </para>
 
406
          </listitem>
 
407
        </varlistentry>
 
408
 
 
409
        <varlistentry>
 
410
          <term>
 
411
              <command>prereq yxrrset</command>
 
412
              <arg choice="req">domain-name</arg>
 
413
              <arg choice="opt">class</arg>
 
414
              <arg choice="req">type</arg>
 
415
              <arg choice="req" rep="repeat">data</arg>
 
416
            </term>
 
417
          <listitem>
 
418
            <para>
 
419
              The
 
420
              <parameter>data</parameter>
 
421
              from each set of prerequisites of this form
 
422
              sharing a common
 
423
              <parameter>type</parameter>,
 
424
              <parameter>class</parameter>,
 
425
              and
 
426
              <parameter>domain-name</parameter>
 
427
              are combined to form a set of RRs.  This set of RRs must
 
428
              exactly match the set of RRs existing in the zone at the
 
429
              given
 
430
              <parameter>type</parameter>,
 
431
              <parameter>class</parameter>,
 
432
              and
 
433
              <parameter>domain-name</parameter>.
 
434
              The
 
435
              <parameter>data</parameter>
 
436
              are written in the standard text representation of the resource
 
437
              record's
 
438
              RDATA.
 
439
            </para>
 
440
          </listitem>
 
441
        </varlistentry>
 
442
 
 
443
        <varlistentry>
 
444
          <term>
 
445
              <command>update delete</command>
 
446
              <arg choice="req">domain-name</arg>
 
447
              <arg choice="opt">ttl</arg>
 
448
              <arg choice="opt">class</arg>
 
449
              <arg choice="opt">type <arg choice="opt" rep="repeat">data</arg></arg>
 
450
            </term>
 
451
          <listitem>
 
452
            <para>
 
453
              Deletes any resource records named
 
454
              <parameter>domain-name</parameter>.
 
455
              If
 
456
              <parameter>type</parameter>
 
457
              and
 
458
              <parameter>data</parameter>
 
459
              is provided, only matching resource records will be removed.
 
460
              The internet class is assumed if
 
461
              <parameter>class</parameter>
 
462
              is not supplied.  The
 
463
              <parameter>ttl</parameter>
 
464
              is ignored, and is only allowed for compatibility.
 
465
            </para>
 
466
          </listitem>
 
467
        </varlistentry>
 
468
 
 
469
        <varlistentry>
 
470
          <term>
 
471
              <command>update add</command>
 
472
              <arg choice="req">domain-name</arg>
 
473
              <arg choice="req">ttl</arg>
 
474
              <arg choice="opt">class</arg>
 
475
              <arg choice="req">type</arg>
 
476
              <arg choice="req" rep="repeat">data</arg>
 
477
            </term>
 
478
          <listitem>
 
479
            <para>
 
480
              Adds a new resource record with the specified
 
481
              <parameter>ttl</parameter>,
 
482
              <parameter>class</parameter>
 
483
              and
 
484
              <parameter>data</parameter>.
 
485
            </para>
 
486
          </listitem>
 
487
        </varlistentry>
 
488
 
 
489
        <varlistentry>
 
490
          <term>
 
491
              <command>show</command>
 
492
            </term>
 
493
          <listitem>
 
494
            <para>
 
495
              Displays the current message, containing all of the
 
496
              prerequisites and
 
497
              updates specified since the last send.
 
498
            </para>
 
499
          </listitem>
 
500
        </varlistentry>
 
501
 
 
502
        <varlistentry>
 
503
          <term>
 
504
              <command>send</command>
 
505
            </term>
 
506
          <listitem>
 
507
            <para>
 
508
              Sends the current message.  This is equivalent to entering a
 
509
              blank line.
 
510
            </para>
 
511
          </listitem>
 
512
        </varlistentry>
 
513
 
 
514
        <varlistentry>
 
515
          <term>
 
516
              <command>answer</command>
 
517
            </term>
 
518
          <listitem>
 
519
            <para>
 
520
              Displays the answer.
 
521
            </para>
 
522
          </listitem>
 
523
        </varlistentry>
 
524
 
 
525
      </variablelist>
 
526
    </para>
 
527
 
 
528
    <para>
 
529
      Lines beginning with a semicolon are comments and are ignored.
 
530
    </para>
 
531
 
 
532
  </refsect1>
 
533
 
 
534
  <refsect1>
 
535
    <title>EXAMPLES</title>
 
536
    <para>
 
537
      The examples below show how
 
538
      <command>nsupdate</command>
 
539
      could be used to insert and delete resource records from the
 
540
      <type>example.com</type>
 
541
      zone.
 
542
      Notice that the input in each example contains a trailing blank line so
 
543
      that
 
544
      a group of commands are sent as one dynamic update request to the
 
545
      master name server for
 
546
      <type>example.com</type>.
 
547
 
 
548
      <programlisting>
 
549
# nsupdate
 
550
&gt; update delete oldhost.example.com A
 
551
&gt; update add newhost.example.com 86400 A 172.16.1.1
 
552
&gt; send
 
553
</programlisting>
 
554
    </para>
 
555
    <para>
 
556
      Any A records for
 
557
      <type>oldhost.example.com</type>
 
558
      are deleted.
 
559
      And an A record for
 
560
      <type>newhost.example.com</type>
 
561
      with IP address 172.16.1.1 is added.
 
562
      The newly-added record has a 1 day TTL (86400 seconds).
 
563
      <programlisting>
 
564
# nsupdate
 
565
&gt; prereq nxdomain nickname.example.com
 
566
&gt; update add nickname.example.com 86400 CNAME somehost.example.com
 
567
&gt; send
 
568
</programlisting>
 
569
    </para>
 
570
    <para>
 
571
      The prerequisite condition gets the name server to check that there
 
572
      are no resource records of any type for
 
573
      <type>nickname.example.com</type>.
 
574
 
 
575
      If there are, the update request fails.
 
576
      If this name does not exist, a CNAME for it is added.
 
577
      This ensures that when the CNAME is added, it cannot conflict with the
 
578
      long-standing rule in RFC1034 that a name must not exist as any other
 
579
      record type if it exists as a CNAME.
 
580
      (The rule has been updated for DNSSEC in RFC2535 to allow CNAMEs to have
 
581
      RRSIG, DNSKEY and NSEC records.)
 
582
    </para>
 
583
  </refsect1>
 
584
 
 
585
  <refsect1>
 
586
    <title>FILES</title>
 
587
 
 
588
    <variablelist>
 
589
      <varlistentry>
 
590
        <term><constant>/etc/resolv.conf</constant></term>
 
591
        <listitem>
 
592
          <para>
 
593
            used to identify default name server
 
594
          </para>
 
595
        </listitem>
 
596
      </varlistentry>
 
597
 
 
598
      <varlistentry>
 
599
        <term><constant>K{name}.+157.+{random}.key</constant></term>
 
600
        <listitem>
 
601
          <para>
 
602
            base-64 encoding of HMAC-MD5 key created by
 
603
            <citerefentry>
 
604
              <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
 
605
            </citerefentry>.
 
606
          </para>
 
607
        </listitem>
 
608
      </varlistentry>
 
609
 
 
610
      <varlistentry>
 
611
        <term><constant>K{name}.+157.+{random}.private</constant></term>
 
612
        <listitem>
 
613
          <para>
 
614
            base-64 encoding of HMAC-MD5 key created by
 
615
            <citerefentry>
 
616
              <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
 
617
            </citerefentry>.
 
618
          </para>
 
619
        </listitem>
 
620
      </varlistentry>
 
621
 
 
622
    </variablelist>
 
623
  </refsect1>
 
624
 
 
625
  <refsect1>
 
626
    <title>SEE ALSO</title>
 
627
    <para><citerefentry>
 
628
        <refentrytitle>RFC2136</refentrytitle>
 
629
      </citerefentry>,
 
630
      <citerefentry>
 
631
        <refentrytitle>RFC3007</refentrytitle>
 
632
      </citerefentry>,
 
633
      <citerefentry>
 
634
        <refentrytitle>RFC2104</refentrytitle>
 
635
      </citerefentry>,
 
636
      <citerefentry>
 
637
        <refentrytitle>RFC2845</refentrytitle>
 
638
      </citerefentry>,
 
639
      <citerefentry>
 
640
        <refentrytitle>RFC1034</refentrytitle>
 
641
      </citerefentry>,
 
642
      <citerefentry>
 
643
        <refentrytitle>RFC2535</refentrytitle>
 
644
      </citerefentry>,
 
645
      <citerefentry>
 
646
        <refentrytitle>RFC2931</refentrytitle>
 
647
      </citerefentry>,
 
648
      <citerefentry>
 
649
        <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
 
650
      </citerefentry>,
 
651
      <citerefentry>
 
652
        <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
 
653
      </citerefentry>.
 
654
    </para>
 
655
 
 
656
  </refsect1>
 
657
  <refsect1>
 
658
    <title>BUGS</title>
 
659
    <para>
 
660
      The TSIG key is redundantly stored in two separate files.
 
661
      This is a consequence of nsupdate using the DST library
 
662
      for its cryptographic operations, and may change in future
 
663
      releases.
 
664
    </para>
 
665
  </refsect1>
 
666
</refentry><!--
 
667
 - Local variables:
 
668
 - mode: sgml
 
669
 - End:
 
670
-->