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