630 lines
17 KiB
Plaintext
630 lines
17 KiB
Plaintext
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
|
<!--
|
|
- Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
|
|
- Copyright (C) 2001-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: nsupdate.docbook,v 1.8.2.3.2.8 2004/03/08 04:04:23 marka 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>-t <replaceable class="parameter">timeout</replaceable></option></arg>
|
|
<arg><option>-u <replaceable class="parameter">udptimeout</replaceable></option></arg>
|
|
<arg><option>-r <replaceable class="parameter">udpretries</replaceable></option></arg>
|
|
<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 or the
|
|
SIG(0) record described in RFC3535 and RFC2931.
|
|
TSIG relies 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.
|
|
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.
|
|
<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 (with an HMAC-MD5 key) 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>
|
|
The <option>-k</option> 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.
|
|
</para>
|
|
<para>
|
|
By default
|
|
<command>nsupdate</command>
|
|
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
|
|
<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>
|
|
<para>The <option>-t</option> option sets the maximum time a update request can
|
|
take before it is aborted. The default is 300 seconds. Zero can be used
|
|
to disable the timeout.
|
|
</para>
|
|
<para>The <option>-u</option> 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.
|
|
</para>
|
|
<para>The <option>-r</option> option sets the number of UDP retries. The default is
|
|
3. If zero only one update request will be 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 (or the <command>send</command> command) 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 chosen 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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term>
|
|
<cmdsynopsis>
|
|
<command>class</command>
|
|
<arg choice="req">classname</arg>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specify the default class.
|
|
If no <parameter>class</parameter> is specified the default class is
|
|
<parameter>IN</parameter>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term>
|
|
<cmdsynopsis>
|
|
<command>key</command>
|
|
<arg choice="req">name</arg>
|
|
<arg choice="req">secret</arg>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies that all updates are to be TSIG signed using the
|
|
<parameter>keyname</parameter> <parameter>keysecret</parameter> pair.
|
|
The <command>key</command> command
|
|
overrides any key specified on the command line via
|
|
<option>-y</option> or <option>-k</option>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term>
|
|
<cmdsynopsis>
|
|
<command>update delete</command>
|
|
<arg choice="req">domain-name</arg>
|
|
<arg choice="opt">ttl</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. The
|
|
<parameter>ttl</parameter>
|
|
is ignored, and is only allowed for compatibility.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<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>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term>
|
|
<cmdsynopsis>
|
|
<command>show</command>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Displays the current message, containing all of the prerequisites and
|
|
updates specified since the last send.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term>
|
|
<cmdsynopsis>
|
|
<command>send</command>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Sends the current message. This is equivalent to entering a blank line.
|
|
</para>
|
|
</listitem>
|
|
|
|
<varlistentry><term>
|
|
<cmdsynopsis>
|
|
<command>answer</command>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Displays the answer.
|
|
</para>
|
|
</listitem>
|
|
|
|
</variablelist>
|
|
|
|
<para>
|
|
Lines beginning with a semicolon are comments and are ignored.
|
|
</para>
|
|
|
|
</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
|
|
> send
|
|
</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 86400 CNAME somehost.example.com
|
|
> send
|
|
</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
|
|
RRSIG, DNSKEY and NSEC 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>RFC3007</refentrytitle>
|
|
</citerefentry>,
|
|
<citerefentry>
|
|
<refentrytitle>RFC2104</refentrytitle>
|
|
</citerefentry>,
|
|
<citerefentry>
|
|
<refentrytitle>RFC2845</refentrytitle>
|
|
</citerefentry>,
|
|
<citerefentry>
|
|
<refentrytitle>RFC1034</refentrytitle>
|
|
</citerefentry>,
|
|
<citerefentry>
|
|
<refentrytitle>RFC2535</refentrytitle>
|
|
</citerefentry>,
|
|
<citerefentry>
|
|
<refentrytitle>RFC2931</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>
|