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