diff options
Diffstat (limited to 'usr.sbin/bind/bin/nsupdate/nsupdate.html')
| -rw-r--r-- | usr.sbin/bind/bin/nsupdate/nsupdate.html | 500 |
1 files changed, 0 insertions, 500 deletions
diff --git a/usr.sbin/bind/bin/nsupdate/nsupdate.html b/usr.sbin/bind/bin/nsupdate/nsupdate.html deleted file mode 100644 index f8e323963a8..00000000000 --- a/usr.sbin/bind/bin/nsupdate/nsupdate.html +++ /dev/null @@ -1,500 +0,0 @@ -<!-- - - Copyright (C) 2004-2007 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. ---> -<!-- $ISC: nsupdate.html,v 1.14.18.22 2007/05/09 03:33:13 marka 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"> -</head> -<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> -<a name="id2476275"></a><div class="titlepage"></div> -<div class="refnamediv"> -<h2>Name</h2> -<p>nsupdate — 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">-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">-v</code>] [filename]</p></div> -</div> -<div class="refsect1" lang="en"> -<a name="id2543417"></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> - 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> -</div> -<div class="refsect1" lang="en"> -<a name="id2543645"></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">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> -</dl></div> -<p> - </p> -<p> - Lines beginning with a semicolon are comments and are ignored. - </p> -</div> -<div class="refsect1" lang="en"> -<a name="id2544648"></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="id2544692"></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="id2544829"></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="id2544900"></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></body> -</html> |