352N/A<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

352N/A

352N/A

1054N/A<refentry>

352N/A<refentryinfo>

352N/A<date>Jun 30, 2000</date>

352N/A</refentryinfo>

560N/A<refmeta>

921N/A<refentrytitle>nsupdate</refentrytitle>

352N/A<manvolnum>8</manvolnum>

560N/A<refmiscinfo>BIND9</refmiscinfo>

480N/A</refmeta>

480N/A<refnamediv>

352N/A<refname>nsupdate</refname>

352N/A<refpurpose>Dynamic DNS update utility</refpurpose>

352N/A</refnamediv>

352N/A<refsynopsisdiv>

352N/A<cmdsynopsis>

560N/A<command>nsupdate</command>

560N/A<arg><option>-d</option></arg>

480N/A<group>

352N/A <arg><option>-y <replaceable class="parameter">keyname:secret</replaceable></option></arg>

480N/A <arg><option>-k <replaceable class="parameter">keyfile</replaceable></option></arg>

592N/A</group>

665N/A<arg><option>-t <replaceable class="parameter">timeout</replaceable></option></arg>

665N/A<arg><option>-u <replaceable class="parameter">udptimeout</replaceable></option></arg>

876N/A<arg><option>-r <replaceable class="parameter">udpretries</replaceable></option></arg>

560N/A<arg><option>-v</option></arg>

377N/A<arg>filename</arg>

480N/A</cmdsynopsis>

352N/A</refsynopsisdiv>

352N/A

352N/A<refsect1>

352N/A<title>DESCRIPTION</title>

352N/A<para>

352N/A<command>nsupdate</command>

377N/Ais used to submit Dynamic DNS Update requests as defined in RFC2136

352N/Ato a name server.

352N/AThis allows resource records to be added or removed from a zone

352N/Awithout manually editing the zone file.

352N/AA single update request can contain requests to add or remove more than one

352N/Aresource record.

352N/A</para>

861N/A<para>

861N/AZones that are under dynamic control via

352N/A<command>nsupdate</command>

352N/Aor a DHCP server should not be edited by hand.

352N/AManual edits could

352N/Aconflict with dynamic updates and cause data to be lost.

352N/A</para>

352N/A<para>

352N/AThe resource records that are dynamically added or removed with

367N/A<command>nsupdate</command>

377N/Ahave to be in the same zone.

377N/ARequests are sent to the zone's master server.

352N/AThis is identified by the MNAME field of the zone's SOA record.

352N/A</para>

352N/A<para>

352N/AThe

377N/A<option>-d</option>

352N/Aoption makes

352N/A<command>nsupdate</command>

352N/Aoperate in debug mode.

352N/AThis provides tracing information about the update requests that are

352N/Amade and the replies received from the name server.

352N/A</para>

352N/A<para>

365N/ATransaction signatures can be used to authenticate the Dynamic DNS

352N/Aupdates.

352N/AThese use the TSIG resource record type described in RFC2845 or the

352N/ASIG(0) record described in RFC3535 and RFC2931.

489N/ATSIG relies on a shared secret that should only be known to

377N/A<command>nsupdate</command> and the name server.

352N/ACurrently, the only supported encryption algorithm for TSIG is

352N/AHMAC-MD5, which is defined in RFC 2104.

352N/AOnce other algorithms are defined for TSIG, applications will need to

352N/Aensure they select the appropriate algorithm as well as the key when

352N/Aauthenticating each other.

352N/AFor instance suitable

352N/A<type>key</type>

352N/Aand

365N/A<type>server</type>

365N/Astatements would be added to

365N/A<filename>/etc/named.conf</filename>

365N/Aso that the name server can associate the appropriate secret key

365N/Aand algorithm with the IP address of the

365N/Aclient application that will be using TSIG authentication.

365N/ASIG(0) uses public key cryptography. To use a SIG(0) key, the public

365N/Akey must be stored in a KEY record in a zone served by the name server.

365N/A<command>nsupdate</command>

1024N/Adoes not read

365N/A<filename>/etc/named.conf</filename>.

365N/A</para>

365N/A<para>

365N/A<command>nsupdate</command>

365N/Auses the

480N/A<option>-y</option>

480N/Aor

480N/A<option>-k</option>

480N/Aoption (with an HMAC-MD5 key) to provide the shared secret needed to generate

1054N/Aa TSIG record for authenticating Dynamic DNS update requests.

1054N/AThese options are mutually exclusive.

1054N/AWith the

1054N/A<option>-k</option>

1054N/Aoption,

480N/A<command>nsupdate</command>

480N/Areads the shared secret from the file

480N/A<parameter>keyfile</parameter>,

480N/Awhose name is of the form

1054N/A<filename>K{name}.+157.+{random}.private</filename>.

1054N/AFor historical

1054N/Areasons, the file

1054N/A<filename>K{name}.+157.+{random}.key</filename>

1054N/Amust also be present. When the

1054N/A<option>-y</option>

1054N/Aoption is used, a signature is generated from

1054N/A<parameter>keyname:secret.</parameter>

1054N/A<parameter>keyname</parameter>

480N/Ais the name of the key,

480N/Aand

480N/A<parameter>secret</parameter>

480N/Ais the base64 encoded shared secret.

678N/AUse of the

480N/A<option>-y</option>

480N/Aoption is discouraged because the shared secret is supplied as a command

489N/Aline argument in clear text.

480N/AThis may be visible in the output from

489N/A<citerefentry>

480N/A<refentrytitle>ps</refentrytitle><manvolnum>1

665N/A</manvolnum>

665N/A</citerefentry>

665N/Aor in a history file maintained by the user's shell.

807N/A</para>

665N/A<para>

665N/AThe <option>-k</option> may also be used to specify a SIG(0) key used

665N/Ato authenticate Dynamic DNS update requests. In this case, the key

665N/Aspecified is not an HMAC-MD5 key.

592N/A</para>

592N/A<para>

480N/ABy default

480N/A<command>nsupdate</command>

480N/Auses UDP to send update requests to the name server unless they are too

480N/Alarge to fit in a UDP request in which case TCP will be used.

480N/AThe

480N/A<option>-v</option>

480N/Aoption makes

480N/A<command>nsupdate</command>

480N/Ause a TCP connection.

480N/AThis may be preferable when a batch of update requests is made.

480N/A</para>

480N/A<para>The <option>-t</option> option sets the maximum time a update request can

480N/Atake before it is aborted. The default is 300 seconds. Zero can be used

480N/Ato disable the timeout.

480N/A</para>

807N/A<para>The <option>-u</option> option sets the UDP retry interval. The default is

480N/A3 seconds. If zero the interval will be computed from the timeout interval

807N/Aand number of UDP retries.

480N/A</para>

480N/A<para>The <option>-r</option> option sets the number of UDP retries. The default is

560N/A3. If zero only one update request will be made.

560N/A</para>

560N/A</refsect1>

560N/A

560N/A<refsect1>

560N/A<title>INPUT FORMAT</title>

560N/A<para>

560N/A<command>nsupdate</command>

560N/Areads input from

560N/A<parameter>filename</parameter>

921N/Aor standard input.

560N/AEach command is supplied on exactly one line of input.

560N/ASome commands are for administrative purposes.

560N/AThe others are either update instructions or prerequisite checks on the

560N/Acontents of the zone.

560N/AThese checks set conditions that some name or set of

560N/Aresource records (RRset) either exists or is absent from the zone.

560N/AThese conditions must be met if the entire update request is to succeed.

560N/AUpdates will be rejected if the tests for the prerequisite conditions fail.

560N/A</para>

560N/A<para>

593N/AEvery update request consists of zero or more prerequisites

678N/Aand zero or more updates.

593N/AThis allows a suitably authenticated update request to proceed if some

593N/Aspecified resource records are present or missing from the zone.

593N/AA blank input line (or the <command>send</command> command) causes the

593N/Aaccumulated commands to be sent as one Dynamic DNS update request to the

593N/Aname server.

593N/A</para>

593N/A<para>

593N/AThe command formats and their meaning are as follows:

593N/A<variablelist>

593N/A<varlistentry><term>

593N/A<cmdsynopsis>

593N/A<command>server</command>

593N/A<arg choice="req">servername</arg>

593N/A<arg choice="opt">port</arg>

593N/A</cmdsynopsis>

593N/A</term>

593N/A<listitem>

593N/A<para>

876N/ASends all dynamic update requests to the name server

876N/A<parameter>servername</parameter>.

876N/AWhen no server statement is provided,

876N/A<command>nsupdate</command>

876N/Awill send updates to the master server of the correct zone.

876N/AThe MNAME field of that zone's SOA record will identify the master

876N/Aserver for that zone.

876N/A<parameter>port</parameter>

876N/Ais the port number on

876N/A<parameter>servername</parameter>

876N/Awhere the dynamic update requests get sent.

876N/AIf no port number is specified, the default DNS port number of 53 is

876N/Aused.

876N/A</para>

876N/A

876N/A<varlistentry><term>

876N/A<cmdsynopsis>

876N/A<command>local</command>

1023N/A<arg choice="req">address</arg>

876N/A<arg choice="opt">port</arg>

876N/A</cmdsynopsis>

876N/A</term>

876N/A<listitem>

876N/A<para>

876N/ASends all dynamic update requests using the local

876N/A<parameter>address</parameter>.

876N/A

876N/AWhen no local statement is provided,

876N/A<command>nsupdate</command>

876N/Awill send updates using an address and port chosen by the system.

876N/A<parameter>port</parameter>

876N/Acan additionally be used to make requests come from a specific port.

876N/AIf no port number is specified, the system will assign one.

876N/A

876N/A<varlistentry><term>

876N/A<cmdsynopsis>

876N/A<command>zone</command>

876N/A<arg choice="req">zonename</arg>

876N/A</cmdsynopsis>

876N/A</term>

876N/A<listitem>

876N/A<para>

593N/ASpecifies 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>

</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

>

</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

>

</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>