1170222Sdougb<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 2170222Sdougb "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" 3153816Sdougb [<!ENTITY mdash "—">]> 4135446Strhodes<!-- 5254897Serwin - Copyright (C) 2004-2012 Internet Systems Consortium, Inc. ("ISC") 6153816Sdougb - Copyright (C) 2000-2003 Internet Software Consortium. 7135446Strhodes - 8174187Sdougb - Permission to use, copy, modify, and/or distribute this software for any 9135446Strhodes - purpose with or without fee is hereby granted, provided that the above 10135446Strhodes - copyright notice and this permission notice appear in all copies. 11135446Strhodes - 12135446Strhodes - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 13135446Strhodes - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 14135446Strhodes - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 15135446Strhodes - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 16135446Strhodes - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 17135446Strhodes - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 18135446Strhodes - PERFORMANCE OF THIS SOFTWARE. 19135446Strhodes--> 20135446Strhodes 21254897Serwin<!-- $Id$ --> 22193149Sdougb<refentry id="man.nsupdate"> 23170222Sdougb <refentryinfo> 24224092Sdougb <date>Aug 25, 2009</date> 25170222Sdougb </refentryinfo> 26170222Sdougb <refmeta> 27193149Sdougb <refentrytitle><application>nsupdate</application></refentrytitle> 28186462Sdougb <manvolnum>1</manvolnum> 29170222Sdougb <refmiscinfo>BIND9</refmiscinfo> 30170222Sdougb </refmeta> 31170222Sdougb <refnamediv> 32193149Sdougb <refname><application>nsupdate</application></refname> 33170222Sdougb <refpurpose>Dynamic DNS update utility</refpurpose> 34170222Sdougb </refnamediv> 35153816Sdougb 36153816Sdougb <docinfo> 37153816Sdougb <copyright> 38153816Sdougb <year>2004</year> 39153816Sdougb <year>2005</year> 40170222Sdougb <year>2006</year> 41170222Sdougb <year>2007</year> 42186462Sdougb <year>2008</year> 43193149Sdougb <year>2009</year> 44218384Sdougb <year>2010</year> 45254897Serwin <year>2011</year> 46254897Serwin <year>2012</year> 47153816Sdougb <holder>Internet Systems Consortium, Inc. ("ISC")</holder> 48153816Sdougb </copyright> 49153816Sdougb <copyright> 50153816Sdougb <year>2000</year> 51153816Sdougb <year>2001</year> 52153816Sdougb <year>2002</year> 53153816Sdougb <year>2003</year> 54153816Sdougb <holder>Internet Software Consortium.</holder> 55153816Sdougb </copyright> 56153816Sdougb </docinfo> 57153816Sdougb 58170222Sdougb <refsynopsisdiv> 59170222Sdougb <cmdsynopsis> 60170222Sdougb <command>nsupdate</command> 61170222Sdougb <arg><option>-d</option></arg> 62193149Sdougb <arg><option>-D</option></arg> 63170222Sdougb <group> 64193149Sdougb <arg><option>-g</option></arg> 65193149Sdougb <arg><option>-o</option></arg> 66224092Sdougb <arg><option>-l</option></arg> 67170222Sdougb <arg><option>-y <replaceable class="parameter"><optional>hmac:</optional>keyname:secret</replaceable></option></arg> 68170222Sdougb <arg><option>-k <replaceable class="parameter">keyfile</replaceable></option></arg> 69170222Sdougb </group> 70170222Sdougb <arg><option>-t <replaceable class="parameter">timeout</replaceable></option></arg> 71170222Sdougb <arg><option>-u <replaceable class="parameter">udptimeout</replaceable></option></arg> 72170222Sdougb <arg><option>-r <replaceable class="parameter">udpretries</replaceable></option></arg> 73193149Sdougb <arg><option>-R <replaceable class="parameter">randomdev</replaceable></option></arg> 74170222Sdougb <arg><option>-v</option></arg> 75170222Sdougb <arg>filename</arg> 76170222Sdougb </cmdsynopsis> 77170222Sdougb </refsynopsisdiv> 78135446Strhodes 79170222Sdougb <refsect1> 80170222Sdougb <title>DESCRIPTION</title> 81170222Sdougb <para><command>nsupdate</command> 82224092Sdougb is used to submit Dynamic DNS Update requests as defined in RFC 2136 83170222Sdougb to a name server. 84170222Sdougb This allows resource records to be added or removed from a zone 85170222Sdougb without manually editing the zone file. 86170222Sdougb A single update request can contain requests to add or remove more than 87170222Sdougb one 88170222Sdougb resource record. 89170222Sdougb </para> 90170222Sdougb <para> 91170222Sdougb Zones that are under dynamic control via 92170222Sdougb <command>nsupdate</command> 93170222Sdougb or a DHCP server should not be edited by hand. 94170222Sdougb Manual edits could 95170222Sdougb conflict with dynamic updates and cause data to be lost. 96170222Sdougb </para> 97170222Sdougb <para> 98170222Sdougb The resource records that are dynamically added or removed with 99170222Sdougb <command>nsupdate</command> 100170222Sdougb have to be in the same zone. 101170222Sdougb Requests are sent to the zone's master server. 102170222Sdougb This is identified by the MNAME field of the zone's SOA record. 103170222Sdougb </para> 104170222Sdougb <para> 105170222Sdougb The 106170222Sdougb <option>-d</option> 107170222Sdougb option makes 108170222Sdougb <command>nsupdate</command> 109170222Sdougb operate in debug mode. 110170222Sdougb This provides tracing information about the update requests that are 111170222Sdougb made and the replies received from the name server. 112170222Sdougb </para> 113170222Sdougb <para> 114193149Sdougb The <option>-D</option> option makes <command>nsupdate</command> 115193149Sdougb report additional debugging information to <option>-d</option>. 116193149Sdougb </para> 117193149Sdougb <para> 118224092Sdougb The <option>-L</option> option with an integer argument of zero or 119224092Sdougb higher sets the logging debug level. If zero, logging is disabled. 120224092Sdougb </para> 121224092Sdougb <para> 122193149Sdougb Transaction signatures can be used to authenticate the Dynamic 123193149Sdougb DNS updates. These use the TSIG resource record type described 124224092Sdougb in RFC 2845 or the SIG(0) record described in RFC 2535 and 125224092Sdougb RFC 2931 or GSS-TSIG as described in RFC 3645. TSIG relies on 126193149Sdougb a shared secret that should only be known to 127193149Sdougb <command>nsupdate</command> and the name server. Currently, 128193149Sdougb the only supported encryption algorithm for TSIG is HMAC-MD5, 129193149Sdougb which is defined in RFC 2104. Once other algorithms are 130193149Sdougb defined for TSIG, applications will need to ensure they select 131193149Sdougb the appropriate algorithm as well as the key when authenticating 132193149Sdougb each other. For instance, suitable <type>key</type> and 133193149Sdougb <type>server</type> statements would be added to 134193149Sdougb <filename>/etc/named.conf</filename> so that the name server 135193149Sdougb can associate the appropriate secret key and algorithm with 136193149Sdougb the IP address of the client application that will be using 137193149Sdougb TSIG authentication. SIG(0) uses public key cryptography. 138193149Sdougb To use a SIG(0) key, the public key must be stored in a KEY 139193149Sdougb record in a zone served by the name server. 140193149Sdougb <command>nsupdate</command> does not read 141170222Sdougb <filename>/etc/named.conf</filename>. 142170222Sdougb </para> 143224092Sdougb <para> 144224092Sdougb GSS-TSIG uses Kerberos credentials. Standard GSS-TSIG mode 145224092Sdougb is switched on with the <option>-g</option> flag. A 146224092Sdougb non-standards-compliant variant of GSS-TSIG used by Windows 147224092Sdougb 2000 can be switched on with the <option>-o</option> flag. 148224092Sdougb </para> 149170222Sdougb <para><command>nsupdate</command> 150170222Sdougb uses the <option>-y</option> or <option>-k</option> option 151170222Sdougb to provide the shared secret needed to generate a TSIG record 152170222Sdougb for authenticating Dynamic DNS update requests, default type 153224092Sdougb HMAC-MD5. These options are mutually exclusive. 154224092Sdougb </para> 155224092Sdougb <para> 156224092Sdougb When the <option>-y</option> option is used, a signature is 157224092Sdougb generated from 158170222Sdougb <optional><parameter>hmac:</parameter></optional><parameter>keyname:secret.</parameter> 159170222Sdougb <parameter>keyname</parameter> is the name of the key, and 160224092Sdougb <parameter>secret</parameter> is the base64 encoded shared secret. 161224092Sdougb Use of the <option>-y</option> option is discouraged because the 162224092Sdougb shared secret is supplied as a command line argument in clear text. 163224092Sdougb This may be visible in the output from 164170222Sdougb <citerefentry> 165224092Sdougb <refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum> 166224092Sdougb </citerefentry> 167224092Sdougb or in a history file maintained by the user's shell. 168170222Sdougb </para> 169170222Sdougb <para> 170224092Sdougb With the 171224092Sdougb <option>-k</option> option, <command>nsupdate</command> reads 172224092Sdougb the shared secret from the file <parameter>keyfile</parameter>. 173224092Sdougb Keyfiles may be in two formats: a single file containing 174224092Sdougb a <filename>named.conf</filename>-format <command>key</command> 175224092Sdougb statement, which may be generated automatically by 176224092Sdougb <command>ddns-confgen</command>, or a pair of files whose names are 177224092Sdougb of the format <filename>K{name}.+157.+{random}.key</filename> and 178224092Sdougb <filename>K{name}.+157.+{random}.private</filename>, which can be 179224092Sdougb generated by <command>dnssec-keygen</command>. 180170222Sdougb The <option>-k</option> may also be used to specify a SIG(0) key used 181170222Sdougb to authenticate Dynamic DNS update requests. In this case, the key 182170222Sdougb specified is not an HMAC-MD5 key. 183170222Sdougb </para> 184170222Sdougb <para> 185224092Sdougb <command>nsupdate</command> can be run in a local-host only mode 186224092Sdougb using the <option>-l</option> flag. This sets the server address to 187224092Sdougb localhost (disabling the <command>server</command> so that the server 188224092Sdougb address cannot be overridden). Connections to the local server will 189224092Sdougb use a TSIG key found in <filename>/var/run/named/session.key</filename>, 190224092Sdougb which is automatically generated by <command>named</command> if any 191224092Sdougb local master zone has set <command>update-policy</command> to 192224092Sdougb <command>local</command>. The location of this key file can be 193224092Sdougb overridden with the <option>-k</option> option. 194193149Sdougb </para> 195193149Sdougb <para> 196224092Sdougb By default, <command>nsupdate</command> 197170222Sdougb uses UDP to send update requests to the name server unless they are too 198170222Sdougb large to fit in a UDP request in which case TCP will be used. 199170222Sdougb The 200170222Sdougb <option>-v</option> 201170222Sdougb option makes 202170222Sdougb <command>nsupdate</command> 203170222Sdougb use a TCP connection. 204170222Sdougb This may be preferable when a batch of update requests is made. 205170222Sdougb </para> 206170222Sdougb <para> 207224092Sdougb The <option>-p</option> sets the default port number to use for 208224092Sdougb connections to a name server. The default is 53. 209224092Sdougb </para> 210224092Sdougb <para> 211174187Sdougb The <option>-t</option> option sets the maximum time an update request 212170222Sdougb can 213170222Sdougb take before it is aborted. The default is 300 seconds. Zero can be 214170222Sdougb used 215170222Sdougb to disable the timeout. 216170222Sdougb </para> 217170222Sdougb <para> 218170222Sdougb The <option>-u</option> option sets the UDP retry interval. The default 219170222Sdougb is 220174187Sdougb 3 seconds. If zero, the interval will be computed from the timeout 221170222Sdougb interval 222170222Sdougb and number of UDP retries. 223170222Sdougb </para> 224170222Sdougb <para> 225170222Sdougb The <option>-r</option> option sets the number of UDP retries. The 226170222Sdougb default is 227174187Sdougb 3. If zero, only one update request will be made. 228170222Sdougb </para> 229193149Sdougb <para> 230193149Sdougb The <option>-R <replaceable 231193149Sdougb class="parameter">randomdev</replaceable></option> option 232193149Sdougb specifies a source of randomness. If the operating system 233193149Sdougb does not provide a <filename>/dev/random</filename> or 234193149Sdougb equivalent device, the default source of randomness is keyboard 235193149Sdougb input. <filename>randomdev</filename> specifies the name of 236193149Sdougb a character device or file containing random data to be used 237193149Sdougb instead of the default. The special value 238193149Sdougb <filename>keyboard</filename> indicates that keyboard input 239193149Sdougb should be used. This option may be specified multiple times. 240193149Sdougb </para> 241170222Sdougb </refsect1> 242135446Strhodes 243170222Sdougb <refsect1> 244170222Sdougb <title>INPUT FORMAT</title> 245170222Sdougb <para><command>nsupdate</command> 246170222Sdougb reads input from 247170222Sdougb <parameter>filename</parameter> 248170222Sdougb or standard input. 249170222Sdougb Each command is supplied on exactly one line of input. 250170222Sdougb Some commands are for administrative purposes. 251170222Sdougb The others are either update instructions or prerequisite checks on the 252170222Sdougb contents of the zone. 253170222Sdougb These checks set conditions that some name or set of 254170222Sdougb resource records (RRset) either exists or is absent from the zone. 255170222Sdougb These conditions must be met if the entire update request is to succeed. 256170222Sdougb Updates will be rejected if the tests for the prerequisite conditions 257170222Sdougb fail. 258170222Sdougb </para> 259170222Sdougb <para> 260170222Sdougb Every update request consists of zero or more prerequisites 261170222Sdougb and zero or more updates. 262170222Sdougb This allows a suitably authenticated update request to proceed if some 263170222Sdougb specified resource records are present or missing from the zone. 264170222Sdougb A blank input line (or the <command>send</command> command) 265170222Sdougb causes the 266170222Sdougb accumulated commands to be sent as one Dynamic DNS update request to the 267170222Sdougb name server. 268170222Sdougb </para> 269170222Sdougb <para> 270170222Sdougb The command formats and their meaning are as follows: 271170222Sdougb <variablelist> 272135446Strhodes 273170222Sdougb <varlistentry> 274170222Sdougb <term> 275170222Sdougb <command>server</command> 276170222Sdougb <arg choice="req">servername</arg> 277170222Sdougb <arg choice="opt">port</arg> 278170222Sdougb </term> 279170222Sdougb <listitem> 280170222Sdougb <para> 281170222Sdougb Sends all dynamic update requests to the name server 282170222Sdougb <parameter>servername</parameter>. 283170222Sdougb When no server statement is provided, 284170222Sdougb <command>nsupdate</command> 285170222Sdougb will send updates to the master server of the correct zone. 286170222Sdougb The MNAME field of that zone's SOA record will identify the 287170222Sdougb master 288170222Sdougb server for that zone. 289170222Sdougb <parameter>port</parameter> 290170222Sdougb is the port number on 291170222Sdougb <parameter>servername</parameter> 292170222Sdougb where the dynamic update requests get sent. 293170222Sdougb If no port number is specified, the default DNS port number of 294170222Sdougb 53 is 295170222Sdougb used. 296170222Sdougb </para> 297170222Sdougb </listitem> 298170222Sdougb </varlistentry> 299135446Strhodes 300170222Sdougb <varlistentry> 301170222Sdougb <term> 302170222Sdougb <command>local</command> 303170222Sdougb <arg choice="req">address</arg> 304170222Sdougb <arg choice="opt">port</arg> 305170222Sdougb </term> 306170222Sdougb <listitem> 307170222Sdougb <para> 308170222Sdougb Sends all dynamic update requests using the local 309170222Sdougb <parameter>address</parameter>. 310135446Strhodes 311170222Sdougb When no local statement is provided, 312170222Sdougb <command>nsupdate</command> 313170222Sdougb will send updates using an address and port chosen by the 314170222Sdougb system. 315170222Sdougb <parameter>port</parameter> 316170222Sdougb can additionally be used to make requests come from a specific 317170222Sdougb port. 318170222Sdougb If no port number is specified, the system will assign one. 319170222Sdougb </para> 320170222Sdougb </listitem> 321170222Sdougb </varlistentry> 322135446Strhodes 323170222Sdougb <varlistentry> 324170222Sdougb <term> 325170222Sdougb <command>zone</command> 326170222Sdougb <arg choice="req">zonename</arg> 327170222Sdougb </term> 328170222Sdougb <listitem> 329170222Sdougb <para> 330170222Sdougb Specifies that all updates are to be made to the zone 331170222Sdougb <parameter>zonename</parameter>. 332170222Sdougb If no 333170222Sdougb <parameter>zone</parameter> 334170222Sdougb statement is provided, 335170222Sdougb <command>nsupdate</command> 336170222Sdougb will attempt determine the correct zone to update based on the 337170222Sdougb rest of the input. 338170222Sdougb </para> 339170222Sdougb </listitem> 340170222Sdougb </varlistentry> 341135446Strhodes 342170222Sdougb <varlistentry> 343170222Sdougb <term> 344170222Sdougb <command>class</command> 345170222Sdougb <arg choice="req">classname</arg> 346170222Sdougb </term> 347170222Sdougb <listitem> 348170222Sdougb <para> 349170222Sdougb Specify the default class. 350174187Sdougb If no <parameter>class</parameter> is specified, the 351170222Sdougb default class is 352170222Sdougb <parameter>IN</parameter>. 353170222Sdougb </para> 354170222Sdougb </listitem> 355170222Sdougb </varlistentry> 356135446Strhodes 357170222Sdougb <varlistentry> 358170222Sdougb <term> 359193149Sdougb <command>ttl</command> 360193149Sdougb <arg choice="req">seconds</arg> 361193149Sdougb </term> 362193149Sdougb <listitem> 363193149Sdougb <para> 364193149Sdougb Specify the default time to live for records to be added. 365193149Sdougb The value <parameter>none</parameter> will clear the default 366193149Sdougb ttl. 367193149Sdougb </para> 368193149Sdougb </listitem> 369193149Sdougb </varlistentry> 370193149Sdougb 371193149Sdougb <varlistentry> 372193149Sdougb <term> 373170222Sdougb <command>key</command> 374170222Sdougb <arg choice="req">name</arg> 375170222Sdougb <arg choice="req">secret</arg> 376170222Sdougb </term> 377170222Sdougb <listitem> 378170222Sdougb <para> 379174187Sdougb Specifies that all updates are to be TSIG-signed using the 380170222Sdougb <parameter>keyname</parameter> <parameter>keysecret</parameter> pair. 381170222Sdougb The <command>key</command> command 382170222Sdougb overrides any key specified on the command line via 383170222Sdougb <option>-y</option> or <option>-k</option>. 384170222Sdougb </para> 385170222Sdougb </listitem> 386170222Sdougb </varlistentry> 387135446Strhodes 388170222Sdougb <varlistentry> 389170222Sdougb <term> 390218384Sdougb <command>gsstsig</command> 391218384Sdougb </term> 392218384Sdougb <listitem> 393218384Sdougb <para> 394218384Sdougb Use GSS-TSIG to sign the updated. This is equivalent to 395218384Sdougb specifying <option>-g</option> on the commandline. 396218384Sdougb </para> 397218384Sdougb </listitem> 398218384Sdougb </varlistentry> 399218384Sdougb 400218384Sdougb <varlistentry> 401218384Sdougb <term> 402218384Sdougb <command>oldgsstsig</command> 403218384Sdougb </term> 404218384Sdougb <listitem> 405218384Sdougb <para> 406218384Sdougb Use the Windows 2000 version of GSS-TSIG to sign the updated. 407218384Sdougb This is equivalent to specifying <option>-o</option> on the 408218384Sdougb commandline. 409218384Sdougb </para> 410218384Sdougb </listitem> 411218384Sdougb </varlistentry> 412218384Sdougb 413218384Sdougb <varlistentry> 414218384Sdougb <term> 415218384Sdougb <command>realm</command> 416218384Sdougb <arg choice="req"><optional>realm_name</optional></arg> 417218384Sdougb </term> 418218384Sdougb <listitem> 419218384Sdougb <para> 420218384Sdougb When using GSS-TSIG use <parameter>realm_name</parameter> rather 421218384Sdougb than the default realm in <filename>krb5.conf</filename>. If no 422218384Sdougb realm is specified the saved realm is cleared. 423218384Sdougb </para> 424218384Sdougb </listitem> 425218384Sdougb </varlistentry> 426218384Sdougb 427218384Sdougb <varlistentry> 428218384Sdougb <term> 429254897Serwin <command><optional>prereq</optional> nxdomain</command> 430170222Sdougb <arg choice="req">domain-name</arg> 431170222Sdougb </term> 432170222Sdougb <listitem> 433170222Sdougb <para> 434170222Sdougb Requires that no resource record of any type exists with name 435170222Sdougb <parameter>domain-name</parameter>. 436170222Sdougb </para> 437170222Sdougb </listitem> 438170222Sdougb </varlistentry> 439135446Strhodes 440135446Strhodes 441170222Sdougb <varlistentry> 442170222Sdougb <term> 443254897Serwin <command><optional>prereq</optional> yxdomain</command> 444170222Sdougb <arg choice="req">domain-name</arg> 445170222Sdougb </term> 446170222Sdougb <listitem> 447170222Sdougb <para> 448170222Sdougb Requires that 449170222Sdougb <parameter>domain-name</parameter> 450170222Sdougb exists (has as at least one resource record, of any type). 451170222Sdougb </para> 452170222Sdougb </listitem> 453170222Sdougb </varlistentry> 454135446Strhodes 455170222Sdougb <varlistentry> 456170222Sdougb <term> 457254897Serwin <command><optional>prereq</optional> nxrrset</command> 458170222Sdougb <arg choice="req">domain-name</arg> 459170222Sdougb <arg choice="opt">class</arg> 460170222Sdougb <arg choice="req">type</arg> 461170222Sdougb </term> 462170222Sdougb <listitem> 463170222Sdougb <para> 464170222Sdougb Requires that no resource record exists of the specified 465170222Sdougb <parameter>type</parameter>, 466170222Sdougb <parameter>class</parameter> 467170222Sdougb and 468170222Sdougb <parameter>domain-name</parameter>. 469170222Sdougb If 470170222Sdougb <parameter>class</parameter> 471170222Sdougb is omitted, IN (internet) is assumed. 472170222Sdougb </para> 473170222Sdougb </listitem> 474170222Sdougb </varlistentry> 475135446Strhodes 476135446Strhodes 477170222Sdougb <varlistentry> 478170222Sdougb <term> 479254897Serwin <command><optional>prereq</optional> yxrrset</command> 480170222Sdougb <arg choice="req">domain-name</arg> 481170222Sdougb <arg choice="opt">class</arg> 482170222Sdougb <arg choice="req">type</arg> 483170222Sdougb </term> 484170222Sdougb <listitem> 485170222Sdougb <para> 486170222Sdougb This requires that a resource record of the specified 487170222Sdougb <parameter>type</parameter>, 488170222Sdougb <parameter>class</parameter> 489170222Sdougb and 490170222Sdougb <parameter>domain-name</parameter> 491170222Sdougb must exist. 492170222Sdougb If 493170222Sdougb <parameter>class</parameter> 494170222Sdougb is omitted, IN (internet) is assumed. 495170222Sdougb </para> 496170222Sdougb </listitem> 497170222Sdougb </varlistentry> 498135446Strhodes 499170222Sdougb <varlistentry> 500170222Sdougb <term> 501254897Serwin <command><optional>prereq</optional> yxrrset</command> 502170222Sdougb <arg choice="req">domain-name</arg> 503170222Sdougb <arg choice="opt">class</arg> 504170222Sdougb <arg choice="req">type</arg> 505170222Sdougb <arg choice="req" rep="repeat">data</arg> 506170222Sdougb </term> 507170222Sdougb <listitem> 508170222Sdougb <para> 509170222Sdougb The 510170222Sdougb <parameter>data</parameter> 511170222Sdougb from each set of prerequisites of this form 512170222Sdougb sharing a common 513170222Sdougb <parameter>type</parameter>, 514170222Sdougb <parameter>class</parameter>, 515170222Sdougb and 516170222Sdougb <parameter>domain-name</parameter> 517170222Sdougb are combined to form a set of RRs. This set of RRs must 518170222Sdougb exactly match the set of RRs existing in the zone at the 519170222Sdougb given 520170222Sdougb <parameter>type</parameter>, 521170222Sdougb <parameter>class</parameter>, 522170222Sdougb and 523170222Sdougb <parameter>domain-name</parameter>. 524170222Sdougb The 525170222Sdougb <parameter>data</parameter> 526170222Sdougb are written in the standard text representation of the resource 527170222Sdougb record's 528170222Sdougb RDATA. 529170222Sdougb </para> 530170222Sdougb </listitem> 531170222Sdougb </varlistentry> 532135446Strhodes 533170222Sdougb <varlistentry> 534170222Sdougb <term> 535254897Serwin <command><optional>update</optional> del<optional>ete</optional></command> 536170222Sdougb <arg choice="req">domain-name</arg> 537170222Sdougb <arg choice="opt">ttl</arg> 538170222Sdougb <arg choice="opt">class</arg> 539170222Sdougb <arg choice="opt">type <arg choice="opt" rep="repeat">data</arg></arg> 540170222Sdougb </term> 541170222Sdougb <listitem> 542170222Sdougb <para> 543170222Sdougb Deletes any resource records named 544170222Sdougb <parameter>domain-name</parameter>. 545170222Sdougb If 546170222Sdougb <parameter>type</parameter> 547170222Sdougb and 548170222Sdougb <parameter>data</parameter> 549170222Sdougb is provided, only matching resource records will be removed. 550170222Sdougb The internet class is assumed if 551170222Sdougb <parameter>class</parameter> 552170222Sdougb is not supplied. The 553170222Sdougb <parameter>ttl</parameter> 554170222Sdougb is ignored, and is only allowed for compatibility. 555170222Sdougb </para> 556170222Sdougb </listitem> 557170222Sdougb </varlistentry> 558135446Strhodes 559170222Sdougb <varlistentry> 560170222Sdougb <term> 561254897Serwin <command><optional>update</optional> add</command> 562170222Sdougb <arg choice="req">domain-name</arg> 563170222Sdougb <arg choice="req">ttl</arg> 564170222Sdougb <arg choice="opt">class</arg> 565170222Sdougb <arg choice="req">type</arg> 566170222Sdougb <arg choice="req" rep="repeat">data</arg> 567170222Sdougb </term> 568170222Sdougb <listitem> 569170222Sdougb <para> 570170222Sdougb Adds a new resource record with the specified 571170222Sdougb <parameter>ttl</parameter>, 572170222Sdougb <parameter>class</parameter> 573170222Sdougb and 574170222Sdougb <parameter>data</parameter>. 575170222Sdougb </para> 576170222Sdougb </listitem> 577170222Sdougb </varlistentry> 578135446Strhodes 579170222Sdougb <varlistentry> 580170222Sdougb <term> 581170222Sdougb <command>show</command> 582170222Sdougb </term> 583170222Sdougb <listitem> 584170222Sdougb <para> 585170222Sdougb Displays the current message, containing all of the 586170222Sdougb prerequisites and 587170222Sdougb updates specified since the last send. 588170222Sdougb </para> 589170222Sdougb </listitem> 590170222Sdougb </varlistentry> 591135446Strhodes 592170222Sdougb <varlistentry> 593170222Sdougb <term> 594170222Sdougb <command>send</command> 595170222Sdougb </term> 596170222Sdougb <listitem> 597170222Sdougb <para> 598170222Sdougb Sends the current message. This is equivalent to entering a 599170222Sdougb blank line. 600170222Sdougb </para> 601170222Sdougb </listitem> 602170222Sdougb </varlistentry> 603135446Strhodes 604170222Sdougb <varlistentry> 605170222Sdougb <term> 606170222Sdougb <command>answer</command> 607170222Sdougb </term> 608170222Sdougb <listitem> 609170222Sdougb <para> 610170222Sdougb Displays the answer. 611170222Sdougb </para> 612170222Sdougb </listitem> 613170222Sdougb </varlistentry> 614135446Strhodes 615193149Sdougb <varlistentry> 616193149Sdougb <term> 617193149Sdougb <command>debug</command> 618193149Sdougb </term> 619193149Sdougb <listitem> 620193149Sdougb <para> 621193149Sdougb Turn on debugging. 622193149Sdougb </para> 623193149Sdougb </listitem> 624193149Sdougb </varlistentry> 625193149Sdougb 626170222Sdougb </variablelist> 627170222Sdougb </para> 628135446Strhodes 629170222Sdougb <para> 630170222Sdougb Lines beginning with a semicolon are comments and are ignored. 631170222Sdougb </para> 632135446Strhodes 633170222Sdougb </refsect1> 634135446Strhodes 635170222Sdougb <refsect1> 636170222Sdougb <title>EXAMPLES</title> 637170222Sdougb <para> 638170222Sdougb The examples below show how 639170222Sdougb <command>nsupdate</command> 640170222Sdougb could be used to insert and delete resource records from the 641170222Sdougb <type>example.com</type> 642170222Sdougb zone. 643170222Sdougb Notice that the input in each example contains a trailing blank line so 644170222Sdougb that 645170222Sdougb a group of commands are sent as one dynamic update request to the 646170222Sdougb master name server for 647170222Sdougb <type>example.com</type>. 648170222Sdougb 649170222Sdougb <programlisting> 650135446Strhodes# nsupdate 651170222Sdougb> update delete oldhost.example.com A 652170222Sdougb> update add newhost.example.com 86400 A 172.16.1.1 653170222Sdougb> send 654135446Strhodes</programlisting> 655170222Sdougb </para> 656170222Sdougb <para> 657170222Sdougb Any A records for 658170222Sdougb <type>oldhost.example.com</type> 659170222Sdougb are deleted. 660174187Sdougb And an A record for 661170222Sdougb <type>newhost.example.com</type> 662174187Sdougb with IP address 172.16.1.1 is added. 663174187Sdougb The newly-added record has a 1 day TTL (86400 seconds). 664170222Sdougb <programlisting> 665135446Strhodes# nsupdate 666170222Sdougb> prereq nxdomain nickname.example.com 667170222Sdougb> update add nickname.example.com 86400 CNAME somehost.example.com 668170222Sdougb> send 669135446Strhodes</programlisting> 670170222Sdougb </para> 671170222Sdougb <para> 672170222Sdougb The prerequisite condition gets the name server to check that there 673170222Sdougb are no resource records of any type for 674170222Sdougb <type>nickname.example.com</type>. 675135446Strhodes 676170222Sdougb If there are, the update request fails. 677170222Sdougb If this name does not exist, a CNAME for it is added. 678170222Sdougb This ensures that when the CNAME is added, it cannot conflict with the 679224092Sdougb long-standing rule in RFC 1034 that a name must not exist as any other 680170222Sdougb record type if it exists as a CNAME. 681224092Sdougb (The rule has been updated for DNSSEC in RFC 2535 to allow CNAMEs to have 682170222Sdougb RRSIG, DNSKEY and NSEC records.) 683170222Sdougb </para> 684170222Sdougb </refsect1> 685135446Strhodes 686170222Sdougb <refsect1> 687170222Sdougb <title>FILES</title> 688135446Strhodes 689170222Sdougb <variablelist> 690170222Sdougb <varlistentry> 691170222Sdougb <term><constant>/etc/resolv.conf</constant></term> 692170222Sdougb <listitem> 693170222Sdougb <para> 694170222Sdougb used to identify default name server 695170222Sdougb </para> 696170222Sdougb </listitem> 697170222Sdougb </varlistentry> 698135446Strhodes 699170222Sdougb <varlistentry> 700224092Sdougb <term><constant>/var/run/named/session.key</constant></term> 701224092Sdougb <listitem> 702224092Sdougb <para> 703224092Sdougb sets the default TSIG key for use in local-only mode 704224092Sdougb </para> 705224092Sdougb </listitem> 706224092Sdougb </varlistentry> 707224092Sdougb 708224092Sdougb <varlistentry> 709170222Sdougb <term><constant>K{name}.+157.+{random}.key</constant></term> 710170222Sdougb <listitem> 711170222Sdougb <para> 712170222Sdougb base-64 encoding of HMAC-MD5 key created by 713170222Sdougb <citerefentry> 714170222Sdougb <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum> 715170222Sdougb </citerefentry>. 716170222Sdougb </para> 717170222Sdougb </listitem> 718170222Sdougb </varlistentry> 719135446Strhodes 720170222Sdougb <varlistentry> 721170222Sdougb <term><constant>K{name}.+157.+{random}.private</constant></term> 722170222Sdougb <listitem> 723170222Sdougb <para> 724170222Sdougb base-64 encoding of HMAC-MD5 key created by 725170222Sdougb <citerefentry> 726170222Sdougb <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum> 727170222Sdougb </citerefentry>. 728170222Sdougb </para> 729170222Sdougb </listitem> 730170222Sdougb </varlistentry> 731135446Strhodes 732170222Sdougb </variablelist> 733170222Sdougb </refsect1> 734170222Sdougb 735170222Sdougb <refsect1> 736170222Sdougb <title>SEE ALSO</title> 737224092Sdougb <para> 738224092Sdougb <citetitle>RFC 2136</citetitle>, 739224092Sdougb <citetitle>RFC 3007</citetitle>, 740224092Sdougb <citetitle>RFC 2104</citetitle>, 741224092Sdougb <citetitle>RFC 2845</citetitle>, 742224092Sdougb <citetitle>RFC 1034</citetitle>, 743224092Sdougb <citetitle>RFC 2535</citetitle>, 744224092Sdougb <citetitle>RFC 2931</citetitle>, 745170222Sdougb <citerefentry> 746224092Sdougb <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum> 747170222Sdougb </citerefentry>, 748170222Sdougb <citerefentry> 749224092Sdougb <refentrytitle>ddns-confgen</refentrytitle><manvolnum>8</manvolnum> 750170222Sdougb </citerefentry>, 751170222Sdougb <citerefentry> 752170222Sdougb <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum> 753170222Sdougb </citerefentry>. 754170222Sdougb </para> 755224092Sdougb </refsect1> 756170222Sdougb 757170222Sdougb <refsect1> 758170222Sdougb <title>BUGS</title> 759170222Sdougb <para> 760170222Sdougb The TSIG key is redundantly stored in two separate files. 761170222Sdougb This is a consequence of nsupdate using the DST library 762170222Sdougb for its cryptographic operations, and may change in future 763170222Sdougb releases. 764170222Sdougb </para> 765170222Sdougb </refsect1> 766170222Sdougb</refentry><!-- 767170222Sdougb - Local variables: 768170222Sdougb - mode: sgml 769170222Sdougb - End: 770170222Sdougb--> 771