contrib/bind9/bin/nsupdate/nsupdate.docbook

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