--- /dev/null
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+<!--
+ - Copyright (C) 2000, 2001 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 INTERNET SOFTWARE CONSORTIUM
+ - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
+ - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
+ - INTERNET SOFTWARE CONSORTIUM 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: nsupdate.docbook,v 1.1 2001/03/31 02:31:16 gson Exp $ -->
+
+<refentry>
+<refentryinfo>
+<date>Jun 30, 2000</date>
+</refentryinfo>
+<refmeta>
+<refentrytitle>nsupdate</refentrytitle>
+<manvolnum>8</manvolnum>
+<refmiscinfo>BIND9</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>nsupdate</refname>
+<refpurpose>Dynamic DNS update utility</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<cmdsynopsis>
+<command>nsupdate</command>
+<arg><option>-d</option></arg>
+<group>
+ <arg><option>-y <replaceable class="parameter">keyname:secret</replaceable></option></arg>
+ <arg><option>-k <replaceable class="parameter">keyfile</replaceable></option></arg>
+</group>
+<arg><option>-v</option></arg>
+<arg>filename</arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>DESCRIPTION</title>
+<para>
+<command>nsupdate</command>
+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.
+</para>
+<para>
+Zones that are under dynamic control via
+<command>nsupdate</command>
+or a DHCP server should not be edited by hand.
+Manual edits could
+conflict with dynamic updates and cause data to be lost.
+</para>
+<para>
+The resource records that are dynamically added or removed with
+<command>nsupdate</command>
+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.
+</para>
+<para>
+The
+<option>-d</option>
+option makes
+<command>nsupdate</command>
+operate in debug mode.
+This provides tracing information about the update requests that are
+made and the replies received from the name server.
+</para>
+<para>
+Transaction signatures can be used to authenticate the Dynamic DNS
+updates.
+These use the TSIG resource record type described in RFC2845.
+The signatures rely on a shared secret that should only be known to
+<command>nsupdate</command>
+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
+<type>key</type>
+and
+<type>server</type>
+statements would be added to
+<filename>/etc/named.conf</filename>
+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.
+<command>nsupdate</command>
+does not read
+<filename>/etc/named.conf</filename>.
+</para>
+<para>
+<command>nsupdate</command>
+uses the
+<option>-y</option>
+or
+<option>-k</option>
+option to provide the shared secret needed to generate a TSIG record
+for authenticating Dynamic DNS update requests.
+These options are mutually exclusive.
+With the
+<option>-k</option>
+option,
+<command>nsupdate</command>
+reads the shared secret from the file
+<parameter>keyfile</parameter>,
+whose name is of the form
+<filename>K{name}.+157.+{random}.private</filename>.
+For historical
+reasons, the file
+<filename>K{name}.+157.+{random}.key</filename>
+must also be present. When the
+<option>-y</option>
+option is used, a signature is generated from
+<parameter>keyname:secret.</parameter>
+<parameter>keyname</parameter>
+is the name of the key,
+and
+<parameter>secret</parameter>
+is the base64 encoded shared secret.
+Use of the
+<option>-y</option>
+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
+<citerefentry>
+<refentrytitle>ps</refentrytitle><manvolnum>1
+</manvolnum>
+</citerefentry>
+or in a history file maintained by the user's shell.
+</para>
+<para>
+By default
+<command>nsupdate</command>
+uses UDP to send update requests to the name server.
+The
+<option>-v</option>
+option makes
+<command>nsupdate</command>
+use a TCP connection.
+This may be preferable when a batch of update requests is made.
+</para>
+</refsect1>
+
+<refsect1>
+<title>INPUT FORMAT</title>
+<para>
+<command>nsupdate</command>
+reads input from
+<parameter>filename</parameter>
+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.
+</para>
+<para>
+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 causes the accumulated commands to be sent as one Dynamic
+DNS update request to the name server.
+</para>
+<para>
+The command formats and their meaning are as follows:
+<variablelist>
+<varlistentry><term>
+<cmdsynopsis>
+<command>server</command>
+<arg choice="req">servername</arg>
+<arg choice="opt">port</arg>
+</cmdsynopsis>
+</term>
+<listitem>
+<para>
+Sends all dynamic update requests to the name server
+<parameter>servername</parameter>.
+When no server statement is provided,
+<command>nsupdate</command>
+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.
+<parameter>port</parameter>
+is the port number on
+<parameter>servername</parameter>
+where the dynamic update requests get sent.
+If no port number is specified, the default DNS port number of 53 is
+used.
+</para>
+
+<varlistentry><term>
+<cmdsynopsis>
+<command>local</command>
+<arg choice="req">address</arg>
+<arg choice="opt">port</arg>
+</cmdsynopsis>
+</term>
+<listitem>
+<para>
+Sends all dynamic update requests using the local
+<parameter>address</parameter>.
+
+When no local statement is provided,
+<command>nsupdate</command>
+will send updates using an address and port choosen by the system.
+<parameter>port</parameter>
+can additionally be used to make requests come from a specific port.
+If no port number is specified, the system will assign one.
+
+<varlistentry><term>
+<cmdsynopsis>
+<command>zone</command>
+<arg choice="req">zonename</arg>
+</cmdsynopsis>
+</term>
+<listitem>
+<para>
+Specifies that all updates are to be made to the zone
+<parameter>zonename</parameter>.
+If no
+<parameter>zone</parameter>
+statement is provided,
+<command>nsupdate</command>
+will attempt determine the correct zone to update based on the rest of the input.
+</para>
+
+<varlistentry><term>
+<cmdsynopsis>
+<command>prereq nxdomain</command>
+<arg choice="req">domain-name</arg>
+</cmdsynopsis>
+</term>
+<listitem>
+<para>
+Requires that no resource record of any type exists with name
+<parameter>domain-name</parameter>.
+</para>
+
+
+<varlistentry><term>
+<cmdsynopsis>
+<command>prereq yxdomain</command>
+<arg choice="req">domain-name</arg>
+</cmdsynopsis>
+</term>
+<listitem>
+<para>
+Requires that
+<parameter>domain-name</parameter>
+exists (has as at least one resource record, of any type).
+</para>
+
+<varlistentry><term>
+<cmdsynopsis>
+<command>prereq nxrrset</command>
+<arg choice="req">domain-name</arg>
+<arg choice="opt">class</arg>
+<arg choice="req">type</arg>
+</cmdsynopsis>
+</term>
+<listitem>
+<para>
+Requires that no resource record exists of the specified
+<parameter>type</parameter>,
+<parameter>class</parameter>
+and
+<parameter>domain-name</parameter>.
+If
+<parameter>class</parameter>
+is omitted, IN (internet) is assumed.
+
+
+<varlistentry><term>
+<cmdsynopsis>
+<command>prereq yxrrset</command>
+<arg choice="req">domain-name</arg>
+<arg choice="opt">class</arg>
+<arg choice="req">type</arg>
+</cmdsynopsis>
+</term>
+<listitem>
+<para>
+This requires that a resource record of the specified
+<parameter>type</parameter>,
+<parameter>class</parameter>
+and
+<parameter>domain-name</parameter>
+must exist.
+If
+<parameter>class</parameter>
+is omitted, IN (internet) is assumed.
+</para>
+
+<varlistentry><term>
+<cmdsynopsis>
+<command>prereq yxrrset</command>
+<arg choice="req">domain-name</arg>
+<arg choice="opt">class</arg>
+<arg choice="req">type</arg>
+<arg choice="req" rep="repeat">data</arg>
+</cmdsynopsis>
+</term>
+<listitem>
+<para>
+The
+<parameter>data</parameter>
+from each set of prerequisites of this form
+sharing a common
+<parameter>type</parameter>,
+<parameter>class</parameter>,
+and
+<parameter>domain-name</parameter>
+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
+<parameter>type</parameter>,
+<parameter>class</parameter>,
+and
+<parameter>domain-name</parameter>.
+The
+<parameter>data</parameter>
+are written in the standard text representation of the resource record's
+RDATA.
+</para>
+
+<varlistentry><term>
+<cmdsynopsis>
+<command>update delete</command>
+<arg choice="req">domain-name</arg>
+<arg choice="opt">class</arg>
+<arg choice="opt">type <arg choice="opt" rep="repeat">data</arg></arg>
+</cmdsynopsis>
+</term>
+<listitem>
+<para>
+Deletes any resource records named
+<parameter>domain-name</parameter>.
+If
+<parameter>type</parameter>
+and
+<parameter>data</parameter>
+is provided, only matching resource records will be removed.
+The internet class is assumed if
+<parameter>class</parameter>
+is not supplied.
+</para>
+
+<varlistentry><term>
+<cmdsynopsis>
+<command>update add</command>
+<arg choice="req">domain-name</arg>
+<arg choice="req">ttl</arg>
+<arg choice="opt">class</arg>
+<arg choice="req">type</arg>
+<arg choice="req" rep="repeat">data</arg>
+</cmdsynopsis>
+</term>
+<listitem>
+<para>
+Adds a new resource record with the specified
+<parameter>ttl</parameter>,
+<parameter>class</parameter>
+and
+<parameter>data</parameter>.
+</para>
+</listitem>
+</variablelist>
+</refsect1>
+
+<refsect1>
+<title>EXAMPLES</title>
+<para>
+The examples below show how
+<command>nsupdate</command>
+could be used to insert and delete resource records from the
+<type>example.com</type>
+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
+<type>example.com</type>.
+
+<programlisting>
+# nsupdate
+> update delete oldhost.example.com A
+> update add newhost.example.com 86400 A 172.16.1.1
+>
+</programlisting>
+</para>
+<para>
+Any A records for
+<type>oldhost.example.com</type>
+are deleted.
+and an A record for
+<type>newhost.example.com</type>
+it IP address 172.16.1.1 is added.
+The newly-added record has a 1 day TTL (86400 seconds)
+<programlisting>
+# nsupdate
+> prereq nxdomain nickname.example.com
+> update add nickname.example.com CNAME somehost.example.com
+>
+</programlisting>
+</para>
+<para>
+The prerequisite condition gets the name server to check that there
+are no resource records of any type for
+<type>nickname.example.com</type>.
+
+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
+SIG, KEY and NXT records.)
+</para>
+</refsect1>
+
+<refsect1>
+<title>FILES</title>
+
+<variablelist>
+<varlistentry><term><constant>/etc/resolv.conf</constant></term>
+<listitem>
+<para>
+used to identify default name server
+</para>
+</listitem>
+
+<varlistentry><term><constant>K{name}.+157.+{random}.key</constant></term>
+<listitem>
+<para>
+base-64 encoding of HMAC-MD5 key created by
+<citerefentry>
+<refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
+</citerefentry>.
+</para>
+</listitem>
+
+<varlistentry><term><constant>K{name}.+157.+{random}.private</constant></term>
+<listitem>
+<para>
+base-64 encoding of HMAC-MD5 key created by
+<citerefentry>
+<refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
+</citerefentry>.
+</para>
+</listitem>
+</variablelist>
+</refsect1>
+
+<refsect1>
+<title>SEE ALSO</title>
+<para>
+<citerefentry>
+<refentrytitle>RFC2136</refentrytitle>
+</citerefentry>,
+<citerefentry>
+<refentrytitle>RFC2137</refentrytitle>
+</citerefentry>,
+<citerefentry>
+<refentrytitle>RFC2104</refentrytitle>
+</citerefentry>,
+<citerefentry>
+<refentrytitle>RFC2845</refentrytitle>
+</citerefentry>,
+<citerefentry>
+<refentrytitle>RFC1034</refentrytitle>
+</citerefentry>,
+<citerefentry>
+<refentrytitle>RFC2535</refentrytitle>
+</citerefentry>,
+<citerefentry>
+<refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
+</citerefentry>,
+<citerefentry>
+<refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
+</citerefentry>.
+
+</refsect1>
+<refsect1>
+<title>BUGS</title>
+<para>
+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.
+</para>
+</refsect1>
+</refentry>
projects / thirdparty / bind9.git / commitdiff
