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