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