man.nsupdate.html revision 824f38c0310fddef55f0f691580154022a7852f5
f0ab104f070bc7f569404826fea1828ed985638cvboxsync - Copyright (C) 2008 Internet Systems Consortium, Inc. ("ISC")
f0ab104f070bc7f569404826fea1828ed985638cvboxsync - Permission to use, copy, modify, and/or distribute this software for any
f0ab104f070bc7f569404826fea1828ed985638cvboxsync - purpose with or without fee is hereby granted, provided that the above
f0ab104f070bc7f569404826fea1828ed985638cvboxsync - copyright notice and this permission notice appear in all copies.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
f0ab104f070bc7f569404826fea1828ed985638cvboxsync - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
f0ab104f070bc7f569404826fea1828ed985638cvboxsync - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
f0ab104f070bc7f569404826fea1828ed985638cvboxsync - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
f0ab104f070bc7f569404826fea1828ed985638cvboxsync - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
f0ab104f070bc7f569404826fea1828ed985638cvboxsync - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
f0ab104f070bc7f569404826fea1828ed985638cvboxsync - PERFORMANCE OF THIS SOFTWARE.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync<!-- $Id: man.nsupdate.html,v 1.9 2008/09/24 01:12:39 tbox Exp $ -->
f0ab104f070bc7f569404826fea1828ed985638cvboxsync<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
f0ab104f070bc7f569404826fea1828ed985638cvboxsync<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
f0ab104f070bc7f569404826fea1828ed985638cvboxsync<link rel="start" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
f0ab104f070bc7f569404826fea1828ed985638cvboxsync<link rel="up" href="Bv9ARM.ch10.html" title="Manual pages">
f0ab104f070bc7f569404826fea1828ed985638cvboxsync<link rel="prev" href="man.named.html" title="named">
f0ab104f070bc7f569404826fea1828ed985638cvboxsync<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
f0ab104f070bc7f569404826fea1828ed985638cvboxsync<tr><th colspan="3" align="center"><span class="application">nsupdate</span></th></tr>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync<a accesskey="p" href="man.named.html">Prev</a>�</td>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync<td width="20%" align="right">�<a accesskey="n" href="man.rndc.html">Next</a>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync<a name="man.nsupdate"></a><div class="titlepage"></div>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync<p><span class="application">nsupdate</span> — Dynamic DNS update utility</p>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync<div class="cmdsynopsis"><p><code class="command">nsupdate</code> [<code class="option">-d</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>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync<p><span><strong class="command">nsupdate</strong></span>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync is used to submit Dynamic DNS Update requests as defined in RFC2136
f0ab104f070bc7f569404826fea1828ed985638cvboxsync to a name server.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync This allows resource records to be added or removed from a zone
f0ab104f070bc7f569404826fea1828ed985638cvboxsync without manually editing the zone file.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync A single update request can contain requests to add or remove more than
f0ab104f070bc7f569404826fea1828ed985638cvboxsync resource record.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync Zones that are under dynamic control via
f0ab104f070bc7f569404826fea1828ed985638cvboxsync <span><strong class="command">nsupdate</strong></span>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync or a DHCP server should not be edited by hand.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync Manual edits could
f0ab104f070bc7f569404826fea1828ed985638cvboxsync conflict with dynamic updates and cause data to be lost.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync The resource records that are dynamically added or removed with
f0ab104f070bc7f569404826fea1828ed985638cvboxsync <span><strong class="command">nsupdate</strong></span>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync have to be in the same zone.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync Requests are sent to the zone's master server.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync This is identified by the MNAME field of the zone's SOA record.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync option makes
f0ab104f070bc7f569404826fea1828ed985638cvboxsync <span><strong class="command">nsupdate</strong></span>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync operate in debug mode.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync This provides tracing information about the update requests that are
f0ab104f070bc7f569404826fea1828ed985638cvboxsync made and the replies received from the name server.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync Transaction signatures can be used to authenticate the Dynamic DNS
f0ab104f070bc7f569404826fea1828ed985638cvboxsync These use the TSIG resource record type described in RFC2845 or the
f0ab104f070bc7f569404826fea1828ed985638cvboxsync SIG(0) record described in RFC3535 and RFC2931.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync TSIG relies on a shared secret that should only be known to
f0ab104f070bc7f569404826fea1828ed985638cvboxsync <span><strong class="command">nsupdate</strong></span> and the name server.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync Currently, the only supported encryption algorithm for TSIG is
f0ab104f070bc7f569404826fea1828ed985638cvboxsync HMAC-MD5, which is defined in RFC 2104.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync Once other algorithms are defined for TSIG, applications will need to
f0ab104f070bc7f569404826fea1828ed985638cvboxsync ensure they select the appropriate algorithm as well as the key when
f0ab104f070bc7f569404826fea1828ed985638cvboxsync authenticating each other.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync For instance, suitable
f0ab104f070bc7f569404826fea1828ed985638cvboxsync statements would be added to
f0ab104f070bc7f569404826fea1828ed985638cvboxsync so that the name server can associate the appropriate secret key
f0ab104f070bc7f569404826fea1828ed985638cvboxsync and algorithm with the IP address of the
f0ab104f070bc7f569404826fea1828ed985638cvboxsync client application that will be using TSIG authentication.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync SIG(0) uses public key cryptography. To use a SIG(0) key, the public
f0ab104f070bc7f569404826fea1828ed985638cvboxsync key must be stored in a KEY record in a zone served by the name server.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync <span><strong class="command">nsupdate</strong></span>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync does not read
f0ab104f070bc7f569404826fea1828ed985638cvboxsync<p><span><strong class="command">nsupdate</strong></span>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync uses the <code class="option">-y</code> or <code class="option">-k</code> option
f0ab104f070bc7f569404826fea1828ed985638cvboxsync to provide the shared secret needed to generate a TSIG record
f0ab104f070bc7f569404826fea1828ed985638cvboxsync for authenticating Dynamic DNS update requests, default type
f0ab104f070bc7f569404826fea1828ed985638cvboxsync HMAC-MD5. These options are mutually exclusive. With the
f0ab104f070bc7f569404826fea1828ed985638cvboxsync <code class="option">-k</code> option, <span><strong class="command">nsupdate</strong></span> reads
f0ab104f070bc7f569404826fea1828ed985638cvboxsync the shared secret from the file <em class="parameter"><code>keyfile</code></em>,
f0ab104f070bc7f569404826fea1828ed985638cvboxsync whose name is of the form
f0ab104f070bc7f569404826fea1828ed985638cvboxsync <code class="filename">K{name}.+157.+{random}.private</code>. For
f0ab104f070bc7f569404826fea1828ed985638cvboxsync historical reasons, the file
f0ab104f070bc7f569404826fea1828ed985638cvboxsync <code class="filename">K{name}.+157.+{random}.key</code> must also be
f0ab104f070bc7f569404826fea1828ed985638cvboxsync present. When the <code class="option">-y</code> option is used, a
f0ab104f070bc7f569404826fea1828ed985638cvboxsync signature is generated from
f0ab104f070bc7f569404826fea1828ed985638cvboxsync [<span class="optional"><em class="parameter"><code>hmac:</code></em></span>]<em class="parameter"><code>keyname:secret.</code></em>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync <em class="parameter"><code>keyname</code></em> is the name of the key, and
f0ab104f070bc7f569404826fea1828ed985638cvboxsync <em class="parameter"><code>secret</code></em> is the base64 encoded shared
f0ab104f070bc7f569404826fea1828ed985638cvboxsync secret. Use of the <code class="option">-y</code> option is discouraged
f0ab104f070bc7f569404826fea1828ed985638cvboxsync because the shared secret is supplied as a command line
f0ab104f070bc7f569404826fea1828ed985638cvboxsync argument in clear text. This may be visible in the output
f0ab104f070bc7f569404826fea1828ed985638cvboxsync <span class="citerefentry"><span class="refentrytitle">ps</span>(1)</span> or in a history file maintained by the user's
f0ab104f070bc7f569404826fea1828ed985638cvboxsync The <code class="option">-k</code> may also be used to specify a SIG(0) key used
f0ab104f070bc7f569404826fea1828ed985638cvboxsync to authenticate Dynamic DNS update requests. In this case, the key
f0ab104f070bc7f569404826fea1828ed985638cvboxsync specified is not an HMAC-MD5 key.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync <span><strong class="command">nsupdate</strong></span>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync uses UDP to send update requests to the name server unless they are too
f0ab104f070bc7f569404826fea1828ed985638cvboxsync large to fit in a UDP request in which case TCP will be used.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync option makes
f0ab104f070bc7f569404826fea1828ed985638cvboxsync <span><strong class="command">nsupdate</strong></span>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync use a TCP connection.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync This may be preferable when a batch of update requests is made.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync The <code class="option">-t</code> option sets the maximum time an update request
f0ab104f070bc7f569404826fea1828ed985638cvboxsync take before it is aborted. The default is 300 seconds. Zero can be
f0ab104f070bc7f569404826fea1828ed985638cvboxsync to disable the timeout.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync The <code class="option">-u</code> option sets the UDP retry interval. The default
f0ab104f070bc7f569404826fea1828ed985638cvboxsync 3 seconds. If zero, the interval will be computed from the timeout
f0ab104f070bc7f569404826fea1828ed985638cvboxsync and number of UDP retries.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync The <code class="option">-r</code> option sets the number of UDP retries. The
f0ab104f070bc7f569404826fea1828ed985638cvboxsync 3. If zero, only one update request will be made.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync The <code class="option">-R <em class="replaceable"><code>randomdev</code></em></code> option
f0ab104f070bc7f569404826fea1828ed985638cvboxsync specifies a source of randomness. If the operating system
f0ab104f070bc7f569404826fea1828ed985638cvboxsync does not provide a <code class="filename">/dev/random</code> or
f0ab104f070bc7f569404826fea1828ed985638cvboxsync equivalent device, the default source of randomness is keyboard
f0ab104f070bc7f569404826fea1828ed985638cvboxsync input. <code class="filename">randomdev</code> specifies the name of
f0ab104f070bc7f569404826fea1828ed985638cvboxsync a character device or file containing random data to be used
f0ab104f070bc7f569404826fea1828ed985638cvboxsync instead of the default. The special value
f0ab104f070bc7f569404826fea1828ed985638cvboxsync <code class="filename">keyboard</code> indicates that keyboard input
f0ab104f070bc7f569404826fea1828ed985638cvboxsync should be used. This option may be specified multiple times.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync<p><span><strong class="command">nsupdate</strong></span>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync reads input from
f0ab104f070bc7f569404826fea1828ed985638cvboxsync or standard input.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync Each command is supplied on exactly one line of input.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync Some commands are for administrative purposes.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync The others are either update instructions or prerequisite checks on the
f0ab104f070bc7f569404826fea1828ed985638cvboxsync contents of the zone.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync These checks set conditions that some name or set of
f0ab104f070bc7f569404826fea1828ed985638cvboxsync resource records (RRset) either exists or is absent from the zone.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync These conditions must be met if the entire update request is to succeed.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync Updates will be rejected if the tests for the prerequisite conditions
f0ab104f070bc7f569404826fea1828ed985638cvboxsync Every update request consists of zero or more prerequisites
f0ab104f070bc7f569404826fea1828ed985638cvboxsync and zero or more updates.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync This allows a suitably authenticated update request to proceed if some
f0ab104f070bc7f569404826fea1828ed985638cvboxsync specified resource records are present or missing from the zone.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync A blank input line (or the <span><strong class="command">send</strong></span> command)
f0ab104f070bc7f569404826fea1828ed985638cvboxsync accumulated commands to be sent as one Dynamic DNS update request to the
f0ab104f070bc7f569404826fea1828ed985638cvboxsync name server.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync The command formats and their meaning are as follows:
f0ab104f070bc7f569404826fea1828ed985638cvboxsync <span><strong class="command">server</strong></span>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync {servername}
f0ab104f070bc7f569404826fea1828ed985638cvboxsync Sends all dynamic update requests to the name server
f0ab104f070bc7f569404826fea1828ed985638cvboxsync <em class="parameter"><code>servername</code></em>.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync When no server statement is provided,
f0ab104f070bc7f569404826fea1828ed985638cvboxsync <span><strong class="command">nsupdate</strong></span>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync will send updates to the master server of the correct zone.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync The MNAME field of that zone's SOA record will identify the
f0ab104f070bc7f569404826fea1828ed985638cvboxsync server for that zone.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync is the port number on
f0ab104f070bc7f569404826fea1828ed985638cvboxsync where the dynamic update requests get sent.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync If no port number is specified, the default DNS port number of
f0ab104f070bc7f569404826fea1828ed985638cvboxsync <span><strong class="command">local</strong></span>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync Sends all dynamic update requests using the local
f0ab104f070bc7f569404826fea1828ed985638cvboxsync When no local statement is provided,
f0ab104f070bc7f569404826fea1828ed985638cvboxsync <span><strong class="command">nsupdate</strong></span>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync will send updates using an address and port chosen by the
f0ab104f070bc7f569404826fea1828ed985638cvboxsync can additionally be used to make requests come from a specific
f0ab104f070bc7f569404826fea1828ed985638cvboxsync If no port number is specified, the system will assign one.
f0ab104f070bc7f569404826fea1828ed985638cvboxsync Specifies that all updates are to be made to the zone
f0ab104f070bc7f569404826fea1828ed985638cvboxsync statement is provided,
f0ab104f070bc7f569404826fea1828ed985638cvboxsync <span><strong class="command">nsupdate</strong></span>
f0ab104f070bc7f569404826fea1828ed985638cvboxsync will attempt determine the correct zone to update based on the
<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