diff options
Diffstat (limited to 'doc/arm/man.nsupdate.html')
| -rw-r--r-- | doc/arm/man.nsupdate.html | 568 |
1 files changed, 568 insertions, 0 deletions
diff --git a/doc/arm/man.nsupdate.html b/doc/arm/man.nsupdate.html new file mode 100644 index 0000000..40ab5a0 --- /dev/null +++ b/doc/arm/man.nsupdate.html @@ -0,0 +1,568 @@ +<!-- + - Copyright (C) 2004-2008 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2000-2003 Internet Software Consortium. + - + - Permission to use, copy, modify, and distribute this software for any + - purpose with or without fee is hereby granted, provided that the above + - copyright notice and this permission notice appear in all copies. + - + - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH + - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, + - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE + - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + - PERFORMANCE OF THIS SOFTWARE. +--> +<!-- $Id: man.nsupdate.html,v 1.22 2008/11/09 01:11:56 tbox Exp $ --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>nsupdate</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> +<link rel="start" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.ch10.html" title="Manual pages"> +<link rel="prev" href="man.named.html" title="named"> +<link rel="next" href="man.rndc.html" title="rndc"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center"><span class="application">nsupdate</span></th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="man.named.html">Prev</a> </td> +<th width="60%" align="center">Manual pages</th> +<td width="20%" align="right"> <a accesskey="n" href="man.rndc.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="refentry" lang="en"> +<a name="man.nsupdate"></a><div class="titlepage"></div> +<div class="refnamediv"> +<h2>Name</h2> +<p><span class="application">nsupdate</span> — Dynamic DNS update utility</p> +</div> +<div class="refsynopsisdiv"> +<h2>Synopsis</h2> +<div class="cmdsynopsis"><p><code class="command">nsupdate</code> [<code class="option">-d</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> +</div> +<div class="refsect1" lang="en"> +<a name="id2609806"></a><h2>DESCRIPTION</h2> +<p><span><strong class="command">nsupdate</strong></span> + is used to submit Dynamic DNS Update requests as defined in RFC2136 + to a name server. + This allows resource records to be added or removed from a zone + without manually editing the zone file. + A single update request can contain requests to add or remove more than + one + resource record. + </p> +<p> + Zones that are under dynamic control via + <span><strong class="command">nsupdate</strong></span> + or a DHCP server should not be edited by hand. + Manual edits could + conflict with dynamic updates and cause data to be lost. + </p> +<p> + The resource records that are dynamically added or removed with + <span><strong class="command">nsupdate</strong></span> + have to be in the same zone. + Requests are sent to the zone's master server. + This is identified by the MNAME field of the zone's SOA record. + </p> +<p> + The + <code class="option">-d</code> + option makes + <span><strong class="command">nsupdate</strong></span> + operate in debug mode. + This provides tracing information about the update requests that are + made and the replies received from the name server. + </p> +<p> + The <code class="option">-D</code> option makes <span><strong class="command">nsupdate</strong></span> + report additional debugging information to <code class="option">-d</code>. + </p> +<p> + Transaction signatures can be used to authenticate the Dynamic DNS + updates. + These use the TSIG resource record type described in RFC2845 or the + SIG(0) record described in RFC3535 and RFC2931. + TSIG relies on a shared secret that should only be known to + <span><strong class="command">nsupdate</strong></span> and the name server. + Currently, the only supported encryption algorithm for TSIG is + HMAC-MD5, which is defined in RFC 2104. + Once other algorithms are defined for TSIG, applications will need to + ensure they select the appropriate algorithm as well as the key when + authenticating each other. + For instance, suitable + <span class="type">key</span> + and + <span class="type">server</span> + statements would be added to + <code class="filename">/etc/named.conf</code> + so that the name server can associate the appropriate secret key + and algorithm with the IP address of the + client application that will be using TSIG authentication. + SIG(0) uses public key cryptography. To use a SIG(0) key, the public + key must be stored in a KEY record in a zone served by the name server. + <span><strong class="command">nsupdate</strong></span> + does not read + <code class="filename">/etc/named.conf</code>. + </p> +<p><span><strong class="command">nsupdate</strong></span> + uses the <code class="option">-y</code> or <code class="option">-k</code> option + to provide the shared secret needed to generate a TSIG record + for authenticating Dynamic DNS update requests, default type + HMAC-MD5. These options are mutually exclusive. With the + <code class="option">-k</code> option, <span><strong class="command">nsupdate</strong></span> reads + the shared secret from the file <em class="parameter"><code>keyfile</code></em>, + whose name is of the form + <code class="filename">K{name}.+157.+{random}.private</code>. For + historical reasons, the file + <code class="filename">K{name}.+157.+{random}.key</code> must also be + present. When the <code class="option">-y</code> option is used, a + signature is generated from + [<span class="optional"><em class="parameter"><code>hmac:</code></em></span>]<em class="parameter"><code>keyname:secret.</code></em> + <em class="parameter"><code>keyname</code></em> is the name of the key, and + <em class="parameter"><code>secret</code></em> is the base64 encoded shared + secret. Use of the <code class="option">-y</code> option is discouraged + because the shared secret is supplied as a command line + argument in clear text. This may be visible in the output + from + <span class="citerefentry"><span class="refentrytitle">ps</span>(1)</span> or in a history file maintained by the user's + shell. + </p> +<p> + The <code class="option">-k</code> may also be used to specify a SIG(0) key used + to authenticate Dynamic DNS update requests. In this case, the key + specified is not an HMAC-MD5 key. + </p> +<p> + By default + <span><strong class="command">nsupdate</strong></span> + uses UDP to send update requests to the name server unless they are too + large to fit in a UDP request in which case TCP will be used. + The + <code class="option">-v</code> + option makes + <span><strong class="command">nsupdate</strong></span> + use a TCP connection. + This may be preferable when a batch of update requests is made. + </p> +<p> + The <code class="option">-t</code> option sets the maximum time an update request + can + take before it is aborted. The default is 300 seconds. Zero can be + used + to disable the timeout. + </p> +<p> + The <code class="option">-u</code> option sets the UDP retry interval. The default + is + 3 seconds. If zero, the interval will be computed from the timeout + interval + and number of UDP retries. + </p> +<p> + The <code class="option">-r</code> option sets the number of UDP retries. The + default is + 3. If zero, only one update request will be made. + </p> +<p> + The <code class="option">-R <em class="replaceable"><code>randomdev</code></em></code> option + specifies a source of randomness. If the operating system + does not provide a <code class="filename">/dev/random</code> or + equivalent device, the default source of randomness is keyboard + input. <code class="filename">randomdev</code> specifies the name of + a character device or file containing random data to be used + instead of the default. The special value + <code class="filename">keyboard</code> indicates that keyboard input + should be used. This option may be specified multiple times. + </p> +</div> +<div class="refsect1" lang="en"> +<a name="id2610186"></a><h2>INPUT FORMAT</h2> +<p><span><strong class="command">nsupdate</strong></span> + reads input from + <em class="parameter"><code>filename</code></em> + or standard input. + Each command is supplied on exactly one line of input. + Some commands are for administrative purposes. + The others are either update instructions or prerequisite checks on the + contents of the zone. + These checks set conditions that some name or set of + resource records (RRset) either exists or is absent from the zone. + These conditions must be met if the entire update request is to succeed. + Updates will be rejected if the tests for the prerequisite conditions + fail. + </p> +<p> + Every update request consists of zero or more prerequisites + and zero or more updates. + This allows a suitably authenticated update request to proceed if some + specified resource records are present or missing from the zone. + A blank input line (or the <span><strong class="command">send</strong></span> command) + causes the + accumulated commands to be sent as one Dynamic DNS update request to the + name server. + </p> +<p> + The command formats and their meaning are as follows: + </p> +<div class="variablelist"><dl> +<dt><span class="term"> + <span><strong class="command">server</strong></span> + {servername} + [port] + </span></dt> +<dd><p> + Sends all dynamic update requests to the name server + <em class="parameter"><code>servername</code></em>. + When no server statement is provided, + <span><strong class="command">nsupdate</strong></span> + will send updates to the master server of the correct zone. + The MNAME field of that zone's SOA record will identify the + master + server for that zone. + <em class="parameter"><code>port</code></em> + is the port number on + <em class="parameter"><code>servername</code></em> + where the dynamic update requests get sent. + If no port number is specified, the default DNS port number of + 53 is + used. + </p></dd> +<dt><span class="term"> + <span><strong class="command">local</strong></span> + {address} + [port] + </span></dt> +<dd><p> + Sends all dynamic update requests using the local + <em class="parameter"><code>address</code></em>. + + When no local statement is provided, + <span><strong class="command">nsupdate</strong></span> + will send updates using an address and port chosen by the + system. + <em class="parameter"><code>port</code></em> + can additionally be used to make requests come from a specific + port. + If no port number is specified, the system will assign one. + </p></dd> +<dt><span class="term"> + <span><strong class="command">zone</strong></span> + {zonename} + </span></dt> +<dd><p> + Specifies that all updates are to be made to the zone + <em class="parameter"><code>zonename</code></em>. + If no + <em class="parameter"><code>zone</code></em> + statement is provided, + <span><strong class="command">nsupdate</strong></span> + will attempt determine the correct zone to update based on the + rest of the input. + </p></dd> +<dt><span class="term"> + <span><strong class="command">class</strong></span> + {classname} + </span></dt> +<dd><p> + Specify the default class. + If no <em class="parameter"><code>class</code></em> is specified, the + default class is + <em class="parameter"><code>IN</code></em>. + </p></dd> +<dt><span class="term"> + <span><strong class="command">ttl</strong></span> + {seconds} + </span></dt> +<dd><p> + Specify the default time to live for records to be added. + The value <em class="parameter"><code>none</code></em> will clear the default + ttl. + </p></dd> +<dt><span class="term"> + <span><strong class="command">key</strong></span> + {name} + {secret} + </span></dt> +<dd><p> + Specifies that all updates are to be TSIG-signed using the + <em class="parameter"><code>keyname</code></em> <em class="parameter"><code>keysecret</code></em> pair. + The <span><strong class="command">key</strong></span> command + overrides any key specified on the command line via + <code class="option">-y</code> or <code class="option">-k</code>. + </p></dd> +<dt><span class="term"> + <span><strong class="command">prereq nxdomain</strong></span> + {domain-name} + </span></dt> +<dd><p> + Requires that no resource record of any type exists with name + <em class="parameter"><code>domain-name</code></em>. + </p></dd> +<dt><span class="term"> + <span><strong class="command">prereq yxdomain</strong></span> + {domain-name} + </span></dt> +<dd><p> + Requires that + <em class="parameter"><code>domain-name</code></em> + exists (has as at least one resource record, of any type). + </p></dd> +<dt><span class="term"> + <span><strong class="command">prereq nxrrset</strong></span> + {domain-name} + [class] + {type} + </span></dt> +<dd><p> + Requires that no resource record exists of the specified + <em class="parameter"><code>type</code></em>, + <em class="parameter"><code>class</code></em> + and + <em class="parameter"><code>domain-name</code></em>. + If + <em class="parameter"><code>class</code></em> + is omitted, IN (internet) is assumed. + </p></dd> +<dt><span class="term"> + <span><strong class="command">prereq yxrrset</strong></span> + {domain-name} + [class] + {type} + </span></dt> +<dd><p> + This requires that a resource record of the specified + <em class="parameter"><code>type</code></em>, + <em class="parameter"><code>class</code></em> + and + <em class="parameter"><code>domain-name</code></em> + must exist. + If + <em class="parameter"><code>class</code></em> + is omitted, IN (internet) is assumed. + </p></dd> +<dt><span class="term"> + <span><strong class="command">prereq yxrrset</strong></span> + {domain-name} + [class] + {type} + {data...} + </span></dt> +<dd><p> + The + <em class="parameter"><code>data</code></em> + from each set of prerequisites of this form + sharing a common + <em class="parameter"><code>type</code></em>, + <em class="parameter"><code>class</code></em>, + and + <em class="parameter"><code>domain-name</code></em> + are combined to form a set of RRs. This set of RRs must + exactly match the set of RRs existing in the zone at the + given + <em class="parameter"><code>type</code></em>, + <em class="parameter"><code>class</code></em>, + and + <em class="parameter"><code>domain-name</code></em>. + The + <em class="parameter"><code>data</code></em> + are written in the standard text representation of the resource + record's + RDATA. + </p></dd> +<dt><span class="term"> + <span><strong class="command">update delete</strong></span> + {domain-name} + [ttl] + [class] + [type [data...]] + </span></dt> +<dd><p> + Deletes any resource records named + <em class="parameter"><code>domain-name</code></em>. + If + <em class="parameter"><code>type</code></em> + and + <em class="parameter"><code>data</code></em> + is provided, only matching resource records will be removed. + The internet class is assumed if + <em class="parameter"><code>class</code></em> + is not supplied. The + <em class="parameter"><code>ttl</code></em> + is ignored, and is only allowed for compatibility. + </p></dd> +<dt><span class="term"> + <span><strong class="command">update add</strong></span> + {domain-name} + {ttl} + [class] + {type} + {data...} + </span></dt> +<dd><p> + Adds a new resource record with the specified + <em class="parameter"><code>ttl</code></em>, + <em class="parameter"><code>class</code></em> + and + <em class="parameter"><code>data</code></em>. + </p></dd> +<dt><span class="term"> + <span><strong class="command">show</strong></span> + </span></dt> +<dd><p> + Displays the current message, containing all of the + prerequisites and + updates specified since the last send. + </p></dd> +<dt><span class="term"> + <span><strong class="command">send</strong></span> + </span></dt> +<dd><p> + Sends the current message. This is equivalent to entering a + blank line. + </p></dd> +<dt><span class="term"> + <span><strong class="command">answer</strong></span> + </span></dt> +<dd><p> + Displays the answer. + </p></dd> +<dt><span class="term"> + <span><strong class="command">debug</strong></span> + </span></dt> +<dd><p> + Turn on debugging. + </p></dd> +</dl></div> +<p> + </p> +<p> + Lines beginning with a semicolon are comments and are ignored. + </p> +</div> +<div class="refsect1" lang="en"> +<a name="id2659005"></a><h2>EXAMPLES</h2> +<p> + The examples below show how + <span><strong class="command">nsupdate</strong></span> + could be used to insert and delete resource records from the + <span class="type">example.com</span> + zone. + Notice that the input in each example contains a trailing blank line so + that + a group of commands are sent as one dynamic update request to the + master name server for + <span class="type">example.com</span>. + + </p> +<pre class="programlisting"> +# nsupdate +> update delete oldhost.example.com A +> update add newhost.example.com 86400 A 172.16.1.1 +> send +</pre> +<p> + </p> +<p> + Any A records for + <span class="type">oldhost.example.com</span> + are deleted. + And an A record for + <span class="type">newhost.example.com</span> + with IP address 172.16.1.1 is added. + The newly-added record has a 1 day TTL (86400 seconds). + </p> +<pre class="programlisting"> +# nsupdate +> prereq nxdomain nickname.example.com +> update add nickname.example.com 86400 CNAME somehost.example.com +> send +</pre> +<p> + </p> +<p> + The prerequisite condition gets the name server to check that there + are no resource records of any type for + <span class="type">nickname.example.com</span>. + + If there are, the update request fails. + If this name does not exist, a CNAME for it is added. + This ensures that when the CNAME is added, it cannot conflict with the + long-standing rule in RFC1034 that a name must not exist as any other + record type if it exists as a CNAME. + (The rule has been updated for DNSSEC in RFC2535 to allow CNAMEs to have + RRSIG, DNSKEY and NSEC records.) + </p> +</div> +<div class="refsect1" lang="en"> +<a name="id2659056"></a><h2>FILES</h2> +<div class="variablelist"><dl> +<dt><span class="term"><code class="constant">/etc/resolv.conf</code></span></dt> +<dd><p> + used to identify default name server + </p></dd> +<dt><span class="term"><code class="constant">K{name}.+157.+{random}.key</code></span></dt> +<dd><p> + base-64 encoding of HMAC-MD5 key created by + <span class="citerefentry"><span class="refentrytitle">dnssec-keygen</span>(8)</span>. + </p></dd> +<dt><span class="term"><code class="constant">K{name}.+157.+{random}.private</code></span></dt> +<dd><p> + base-64 encoding of HMAC-MD5 key created by + <span class="citerefentry"><span class="refentrytitle">dnssec-keygen</span>(8)</span>. + </p></dd> +</dl></div> +</div> +<div class="refsect1" lang="en"> +<a name="id2659125"></a><h2>SEE ALSO</h2> +<p><span class="citerefentry"><span class="refentrytitle">RFC2136</span></span>, + <span class="citerefentry"><span class="refentrytitle">RFC3007</span></span>, + <span class="citerefentry"><span class="refentrytitle">RFC2104</span></span>, + <span class="citerefentry"><span class="refentrytitle">RFC2845</span></span>, + <span class="citerefentry"><span class="refentrytitle">RFC1034</span></span>, + <span class="citerefentry"><span class="refentrytitle">RFC2535</span></span>, + <span class="citerefentry"><span class="refentrytitle">RFC2931</span></span>, + <span class="citerefentry"><span class="refentrytitle">named</span>(8)</span>, + <span class="citerefentry"><span class="refentrytitle">dnssec-keygen</span>(8)</span>. + </p> +</div> +<div class="refsect1" lang="en"> +<a name="id2659264"></a><h2>BUGS</h2> +<p> + The TSIG key is redundantly stored in two separate files. + This is a consequence of nsupdate using the DST library + for its cryptographic operations, and may change in future + releases. + </p> +</div> +</div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="man.named.html">Prev</a> </td> +<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch10.html">Up</a></td> +<td width="40%" align="right"> <a accesskey="n" href="man.rndc.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top"> +<span class="application">named</span> </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> <span class="application">rndc</span> +</td> +</tr> +</table> +</div> +</body> +</html> |