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