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