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