/contrib/bind9/doc/arm/man.nsupdate.html
https://bitbucket.org/freebsd/freebsd-head/ · HTML · 622 lines · 602 code · 3 blank · 17 comment · 0 complexity · 583ab533cc0a89f6531132ade85d63c8 MD5 · raw file
- <!--
- - Copyright (C) 2004-2012 Internet Systems Consortium, Inc. ("ISC")
- - Copyright (C) 2000-2003 Internet Software Consortium.
- -
- - Permission to use, copy, modify, and/or 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$ -->
- <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-journalprint.html" title="named-journalprint">
- <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-journalprint.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">-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>
- </div>
- <div class="refsect1" lang="en">
- <a name="id2639154"></a><h2>DESCRIPTION</h2>
- <p><span><strong class="command">nsupdate</strong></span>
- is used to submit Dynamic DNS Update requests as defined in RFC 2136
- 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>
- The <code class="option">-L</code> option with an integer argument of zero or
- higher sets the logging debug level. If zero, logging is disabled.
- </p>
- <p>
- Transaction signatures can be used to authenticate the Dynamic
- DNS updates. These use the TSIG resource record type described
- in RFC 2845 or the SIG(0) record described in RFC 2535 and
- RFC 2931 or GSS-TSIG as described in RFC 3645. 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>
- GSS-TSIG uses Kerberos credentials. Standard GSS-TSIG mode
- is switched on with the <code class="option">-g</code> flag. A
- non-standards-compliant variant of GSS-TSIG used by Windows
- 2000 can be switched on with the <code class="option">-o</code> flag.
- </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.
- </p>
- <p>
- 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>
- 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>.
- Keyfiles may be in two formats: a single file containing
- a <code class="filename">named.conf</code>-format <span><strong class="command">key</strong></span>
- statement, which may be generated automatically by
- <span><strong class="command">ddns-confgen</strong></span>, or a pair of files whose names are
- of the format <code class="filename">K{name}.+157.+{random}.key</code> and
- <code class="filename">K{name}.+157.+{random}.private</code>, which can be
- generated by <span><strong class="command">dnssec-keygen</strong></span>.
- 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>
- <span><strong class="command">nsupdate</strong></span> can be run in a local-host only mode
- using the <code class="option">-l</code> flag. This sets the server address to
- localhost (disabling the <span><strong class="command">server</strong></span> so that the server
- address cannot be overridden). Connections to the local server will
- use a TSIG key found in <code class="filename">/var/run/named/session.key</code>,
- which is automatically generated by <span><strong class="command">named</strong></span> if any
- local master zone has set <span><strong class="command">update-policy</strong></span> to
- <span><strong class="command">local</strong></span>. The location of this key file can be
- overridden with the <code class="option">-k</code> option.
- </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">-p</code> sets the default port number to use for
- connections to a name server. The default is 53.
- </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="id2639897"></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">gsstsig</strong></span>
- </span></dt>
- <dd><p>
- Use GSS-TSIG to sign the updated. This is equivalent to
- specifying <code class="option">-g</code> on the commandline.
- </p></dd>
- <dt><span class="term">
- <span><strong class="command">oldgsstsig</strong></span>
- </span></dt>
- <dd><p>
- Use the Windows 2000 version of GSS-TSIG to sign the updated.
- This is equivalent to specifying <code class="option">-o</code> on the
- commandline.
- </p></dd>
- <dt><span class="term">
- <span><strong class="command">realm</strong></span>
- {[<span class="optional">realm_name</span>]}
- </span></dt>
- <dd><p>
- When using GSS-TSIG use <em class="parameter"><code>realm_name</code></em> rather
- than the default realm in <code class="filename">krb5.conf</code>. If no
- realm is specified the saved realm is cleared.
- </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="id2678629"></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 RFC 1034 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 RFC 2535 to allow CNAMEs to have
- RRSIG, DNSKEY and NSEC records.)
- </p>
- </div>
- <div class="refsect1" lang="en">
- <a name="id2678679"></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">/var/run/named/session.key</code></span></dt>
- <dd><p>
- sets the default TSIG key for use in local-only mode
- </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="id2678762"></a><h2>SEE ALSO</h2>
- <p>
- <em class="citetitle">RFC 2136</em>,
- <em class="citetitle">RFC 3007</em>,
- <em class="citetitle">RFC 2104</em>,
- <em class="citetitle">RFC 2845</em>,
- <em class="citetitle">RFC 1034</em>,
- <em class="citetitle">RFC 2535</em>,
- <em class="citetitle">RFC 2931</em>,
- <span class="citerefentry"><span class="refentrytitle">named</span>(8)</span>,
- <span class="citerefentry"><span class="refentrytitle">ddns-confgen</span>(8)</span>,
- <span class="citerefentry"><span class="refentrytitle">dnssec-keygen</span>(8)</span>.
- </p>
- </div>
- <div class="refsect1" lang="en">
- <a name="id2678820"></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-journalprint.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-journalprint</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>