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

1745N/A

1745N/A

2362N/A<refentry>

2362N/A<refentryinfo>

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

1745N/A</refentryinfo>

1745N/A<refmeta>

1745N/A<refentrytitle>nsupdate</refentrytitle>

1745N/A<manvolnum>8</manvolnum>

1745N/A<refmiscinfo>BIND9</refmiscinfo>

1745N/A</refmeta>

1745N/A<refnamediv>

1745N/A<refname>nsupdate</refname>

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

1745N/A</refnamediv>

1745N/A<refsynopsisdiv>

1745N/A<cmdsynopsis>

1799N/A<command>nsupdate</command>

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

1745N/A<group>

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

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

1745N/A</group>

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

1745N/A<arg>filename</arg>

1745N/A</cmdsynopsis>

1745N/A</refsynopsisdiv>

1745N/A

1745N/A<refsect1>

1745N/A<title>DESCRIPTION</title>

1745N/A<para>

1745N/A<command>nsupdate</command>

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

1745N/Ato a name server.

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

1745N/Awithout manually editing the zone file.

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

1745N/Aresource record.

1745N/A</para>

1745N/A<para>

1745N/AZones that are under dynamic control via

1799N/A<command>nsupdate</command>

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

1799N/AManual edits could

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

1799N/A</para>

1799N/A<para>

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

1799N/A<command>nsupdate</command>

1799N/Ahave to be in the same zone.

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

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

1799N/A</para>

1799N/A<para>

1799N/AThe

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

1799N/Aoption makes

1799N/A<command>nsupdate</command>

1799N/Aoperate in debug mode.

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

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

1799N/A</para>

1799N/A<para>

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

1799N/Aupdates.

1799N/AThese use the TSIG resource record type described in RFC2845.

1799N/AThe signatures rely on a shared secret that should only be known to

1745N/A<command>nsupdate</command>

1745N/Aand the name server.

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

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

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

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

1745N/Aauthenticating each other.

1745N/AFor instance suitable

1745N/A<type>key</type>

1745N/Aand

1745N/A<type>server</type>

1745N/Astatements would be added to

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

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

1799N/Aand algorithm with the IP address of the

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

1799N/A<command>nsupdate</command>

1799N/Adoes not read

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

1799N/A</para>

1799N/A<para>

1799N/A<command>nsupdate</command>

1799N/Auses the

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

1799N/Aor

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

1799N/Aoption to provide the shared secret needed to generate a TSIG record

1799N/Afor authenticating Dynamic DNS update requests.

1799N/AThese options are mutually exclusive.

1799N/AWith the

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

1799N/Aoption,

1799N/A<command>nsupdate</command>

1799N/Areads the shared secret from the file

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

1799N/Awhose name is of the form

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

1799N/AFor historical

1799N/Areasons, the file

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

1799N/Amust also be present. When the

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

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

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

1745N/A<parameter>keyname</parameter>

1745N/Ais the name of the key,

1745N/Aand

1745N/A<parameter>secret</parameter>

1745N/Ais the base64 encoded shared secret.

1745N/AUse of the

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

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

1745N/Aline argument in clear text.

1745N/AThis may be visible in the output from

1745N/A<citerefentry>

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

1745N/A</manvolnum>

1745N/A</citerefentry>

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

1799N/A</para>

1799N/A<para>

1799N/ABy default

1799N/A<command>nsupdate</command>

1799N/Auses UDP to send update requests to the name server.

1799N/AThe

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

1799N/Aoption makes

1799N/A<command>nsupdate</command>

1799N/Ause a TCP connection.

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

1799N/A</para>

1799N/A</refsect1>

1799N/A

1799N/A<refsect1>

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

1745N/A<para>

1745N/A<command>nsupdate</command>

1745N/Areads input from

1745N/A<parameter>filename</parameter>

1745N/Aor standard input.

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

1745N/ASome commands are for administrative purposes.

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

1745N/Acontents of the zone.

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

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

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

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

1745N/A</para>

1745N/A<para>

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

1745N/Aand zero or more updates.

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

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

1745N/AA blank input line causes the accumulated commands to be sent as one Dynamic

1745N/ADNS update request to the name server.

1745N/A</para>

1768N/A<para>

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

1768N/A<variablelist>

1768N/A<varlistentry><term>

1768N/A<cmdsynopsis>

1768N/A<command>server</command>

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

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

1768N/A</cmdsynopsis>

1768N/A</term>

1768N/A<listitem>

1768N/A<para>

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

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

1768N/AWhen no server statement is provided,

1768N/A<command>nsupdate</command>

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

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

1768N/Aserver for that zone.

1768N/A<parameter>port</parameter>

1768N/Ais the port number on

1768N/A<parameter>servername</parameter>

1768N/Awhere the dynamic update requests get sent.

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

1768N/Aused.

1768N/A</para>

1768N/A

1768N/A<varlistentry><term>

1768N/A<cmdsynopsis>

3479N/A<command>local</command>

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

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

1768N/A</cmdsynopsis>

1768N/A</term>

1768N/A<listitem>

1768N/A<para>

1768N/ASends all dynamic update requests using the local

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

1768N/A

1768N/AWhen no local statement is provided,

1768N/A<command>nsupdate</command>

3479N/Awill send updates using an address and port choosen by the system.

1768N/A<parameter>port</parameter>

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

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

1768N/A

1745N/A<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>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.

<command>Key</command> overrides any key specified on the command line via

<option>-y</option> or <option>-k</option>.

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

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

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