nsupdate.html revision 351b62535d4c4f89883bfdba025999dd32490266
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - Copyright (C) 2004-2009 Internet Systems Consortium, Inc. ("ISC")
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - Copyright (C) 2000-2003 Internet Software Consortium.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews - Permission to use, copy, modify, and distribute this software for any
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - purpose with or without fee is hereby granted, provided that the above
ec5347e2c775f027573ce5648b910361aa926c01Automatic Updater - copyright notice and this permission notice appear in all copies.
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews<!-- $Id: nsupdate.html,v 1.43 2009/06/10 00:27:21 each Exp $ -->
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<meta name="generator" content="DocBook XSL Stylesheets V1.67.2">
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
c40265eba0c99708887d68e67901924065ba2514Brian Wellington<a name="man.nsupdate"></a><div class="titlepage"></div>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington<p><span class="application">nsupdate</span> — Dynamic DNS update utility</p>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington<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">-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>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<p><span><strong class="command">nsupdate</strong></span>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is used to submit Dynamic DNS Update requests as defined in RFC2136
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to a name server.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This allows resource records to be added or removed from a zone
c1a883f2e04d94e99c433b1f6cfd0c0338f4ed85Mark Andrews without manually editing the zone file.
fd4dcaddae08b0fb28b0ec4faf26a9d8b1f923caAutomatic Updater A single update request can contain requests to add or remove more than
6a6ceba6fe09c81558362f238dd727576af7108dTinderbox User resource record.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Zones that are under dynamic control via
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <span><strong class="command">nsupdate</strong></span>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein or a DHCP server should not be edited by hand.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Manual edits could
f5d30e2864e048a42c4dc1134993ae7efdb5d6c3Mark Andrews conflict with dynamic updates and cause data to be lost.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The resource records that are dynamically added or removed with
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <span><strong class="command">nsupdate</strong></span>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington have to be in the same zone.
c40265eba0c99708887d68e67901924065ba2514Brian Wellington Requests are sent to the zone's master server.
c40265eba0c99708887d68e67901924065ba2514Brian Wellington This is identified by the MNAME field of the zone's SOA record.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt option makes
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <span><strong class="command">nsupdate</strong></span>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt operate in debug mode.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt This provides tracing information about the update requests that are
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt made and the replies received from the name server.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt The <code class="option">-D</code> option makes <span><strong class="command">nsupdate</strong></span>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington report additional debugging information to <code class="option">-d</code>.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt The <code class="option">-L</code> option with an integer argument of zero or
30eec077db2bdcb6f2a0dc388a3cdde2ede75ec1Mark Andrews higher sets the logging debug level. If zero, logging is disabled.
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt Transaction signatures can be used to authenticate the Dynamic
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt DNS updates. These use the TSIG resource record type described
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt in RFC2845 or the SIG(0) record described in RFC3535 and
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt RFC2931 or GSS-TSIG as described in RFC3645. TSIG relies on
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt a shared secret that should only be known to
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt <span><strong class="command">nsupdate</strong></span> and the name server. Currently,
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt the only supported encryption algorithm for TSIG is HMAC-MD5,
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt which is defined in RFC 2104. Once other algorithms are
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt defined for TSIG, applications will need to ensure they select
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt the appropriate algorithm as well as the key when authenticating
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt each other. For instance, suitable <span class="type">key</span> and
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt <span class="type">server</span> statements would be added to
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt <code class="filename">/etc/named.conf</code> so that the name server
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt can associate the appropriate secret key and algorithm with
c40265eba0c99708887d68e67901924065ba2514Brian Wellington the IP address of the client application that will be using
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt TSIG authentication. SIG(0) uses public key cryptography.
c40265eba0c99708887d68e67901924065ba2514Brian Wellington To use a SIG(0) key, the public key must be stored in a KEY
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt record in a zone served by the name server.
30eec077db2bdcb6f2a0dc388a3cdde2ede75ec1Mark Andrews <span><strong class="command">nsupdate</strong></span> does not read
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <code class="filename">/etc/named.conf</code>.
c40265eba0c99708887d68e67901924065ba2514Brian Wellington GSS-TSIG uses Kerberos credentials.
0f8c9b5eed7e8714ceb7d6d3675555df9c5f6350Mark Andrews<p><span><strong class="command">nsupdate</strong></span>
0f8c9b5eed7e8714ceb7d6d3675555df9c5f6350Mark Andrews uses the <code class="option">-y</code> or <code class="option">-k</code> option
0f8c9b5eed7e8714ceb7d6d3675555df9c5f6350Mark Andrews to provide the shared secret needed to generate a TSIG record
0f8c9b5eed7e8714ceb7d6d3675555df9c5f6350Mark Andrews for authenticating Dynamic DNS update requests, default type
0f8c9b5eed7e8714ceb7d6d3675555df9c5f6350Mark Andrews HMAC-MD5. These options are mutually exclusive.
0f8c9b5eed7e8714ceb7d6d3675555df9c5f6350Mark Andrews When the <code class="option">-y</code> option is used, a signature is
0f8c9b5eed7e8714ceb7d6d3675555df9c5f6350Mark Andrews generated from
c40265eba0c99708887d68e67901924065ba2514Brian Wellington [<span class="optional"><em class="parameter"><code>hmac:</code></em></span>]<em class="parameter"><code>keyname:secret.</code></em>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <em class="parameter"><code>keyname</code></em> is the name of the key, and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <em class="parameter"><code>secret</code></em> is the base64 encoded shared secret.
3bc4221346e5045c5679dd0d84f4f7d888a9da79Mark Andrews Use of the <code class="option">-y</code> option is discouraged because the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein shared secret is supplied as a command line argument in clear text.
2637d30fbd235fe98145f4312b10cc41a13bf7dcJeremy C. Reed This may be visible in the output from
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <span class="citerefentry"><span class="refentrytitle">ps</span>(1)</span>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein or in a history file maintained by the user's shell.
a26ad011f382d12058478704cb5e90e6f4366d01Andreas Gustafsson <code class="option">-k</code> option, <span><strong class="command">nsupdate</strong></span> reads
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the shared secret from the file <em class="parameter"><code>keyfile</code></em>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Keyfiles may be in two formats: a single file containing
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein a <code class="filename">named.conf</code>-format <span><strong class="command">key</strong></span>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein statement, which may be generated automatically by
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <span><strong class="command">ddns-confgen</strong></span>, or a pair of files whose names are
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein of the format <code class="filename">K{name}.+157.+{random}.key</code> and
a26ad011f382d12058478704cb5e90e6f4366d01Andreas Gustafsson <code class="filename">K{name}.+157.+{random}.private</code>, which can be
a26ad011f382d12058478704cb5e90e6f4366d01Andreas Gustafsson generated by <span><strong class="command">dnssec-keygen</strong></span>.
3bc4221346e5045c5679dd0d84f4f7d888a9da79Mark Andrews The <code class="option">-k</code> may also be used to specify a SIG(0) key used
3bc4221346e5045c5679dd0d84f4f7d888a9da79Mark Andrews to authenticate Dynamic DNS update requests. In this case, the key
3bc4221346e5045c5679dd0d84f4f7d888a9da79Mark Andrews specified is not an HMAC-MD5 key.
3bc4221346e5045c5679dd0d84f4f7d888a9da79Mark Andrews <span><strong class="command">nsupdate</strong></span> can be run in a local-host only mode
3bc4221346e5045c5679dd0d84f4f7d888a9da79Mark Andrews using the <code class="option">-l</code> flag. This sets the server address to
3bc4221346e5045c5679dd0d84f4f7d888a9da79Mark Andrews localhost (disabling the <span><strong class="command">server</strong></span> so that the server
3bc4221346e5045c5679dd0d84f4f7d888a9da79Mark Andrews address cannot be overridden). Connections to the local server will
3bc4221346e5045c5679dd0d84f4f7d888a9da79Mark Andrews use a TSIG key found in <code class="filename">/var/run/named/ddns.key</code>,
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews which is automatically generated by <span><strong class="command">named</strong></span> if any
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews local master zone has the <span><strong class="command">dynamic</strong></span> zone option set
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews to yes. The location of this key file can be overridden with
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews By default, <span><strong class="command">nsupdate</strong></span>
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews uses UDP to send update requests to the name server unless they are too
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews large to fit in a UDP request in which case TCP will be used.
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews option makes
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews <span><strong class="command">nsupdate</strong></span>
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews use a TCP connection.
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews This may be preferable when a batch of update requests is made.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The <code class="option">-p</code> sets the default port number to use for
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein connections to a name server. The default is 53.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The <code class="option">-t</code> option sets the maximum time an update request
92551304a9abff9284de5b79a48e83d781989339Mark Andrews take before it is aborted. The default is 300 seconds. Zero can be
7791dd06ea69d0fb2494788ad4c24d568f40bcdfMark Andrews to disable the timeout.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The <code class="option">-u</code> option sets the UDP retry interval. The default
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein 3 seconds. If zero, the interval will be computed from the timeout
7791dd06ea69d0fb2494788ad4c24d568f40bcdfMark Andrews and number of UDP retries.
c40265eba0c99708887d68e67901924065ba2514Brian Wellington The <code class="option">-r</code> option sets the number of UDP retries. The
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein 3. If zero, only one update request will be made.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The <code class="option">-R <em class="replaceable"><code>randomdev</code></em></code> option
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein specifies a source of randomness. If the operating system
c40265eba0c99708887d68e67901924065ba2514Brian Wellington does not provide a <code class="filename">/dev/random</code> or
c40265eba0c99708887d68e67901924065ba2514Brian Wellington equivalent device, the default source of randomness is keyboard
c40265eba0c99708887d68e67901924065ba2514Brian Wellington input. <code class="filename">randomdev</code> specifies the name of
c40265eba0c99708887d68e67901924065ba2514Brian Wellington a character device or file containing random data to be used
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt instead of the default. The special value
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <code class="filename">keyboard</code> indicates that keyboard input
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt should be used. This option may be specified multiple times.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<p><span><strong class="command">nsupdate</strong></span>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt reads input from
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <em class="parameter"><code>filename</code></em>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt or standard input.
30eec077db2bdcb6f2a0dc388a3cdde2ede75ec1Mark Andrews Each command is supplied on exactly one line of input.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Some commands are for administrative purposes.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The others are either update instructions or prerequisite checks on the
c40265eba0c99708887d68e67901924065ba2514Brian Wellington contents of the zone.
6043e41fcf5dc91aa8a981c966512d73bdec31c1Mark Andrews These checks set conditions that some name or set of
6043e41fcf5dc91aa8a981c966512d73bdec31c1Mark Andrews resource records (RRset) either exists or is absent from the zone.
6043e41fcf5dc91aa8a981c966512d73bdec31c1Mark Andrews These conditions must be met if the entire update request is to succeed.
c40265eba0c99708887d68e67901924065ba2514Brian Wellington Updates will be rejected if the tests for the prerequisite conditions
<em class="parameter"><code>keyname</code></em> <em class="parameter"><code>keysecret</code></em> pair.
> update delete oldhost.example.com A
> update add newhost.example.com 86400 A 172.16.1.1
> prereq nxdomain nickname.example.com