553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt [<!ENTITY mdash "&#8212;">]>

eec29cfd40361662b25bad50e1b94f7738a8fea0Jeremy Reed

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt<refentry id="man.nsupdate">

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <refentryinfo>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <date>Jun 30, 2000</date>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </refentryinfo>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <refmeta>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <refentrytitle><application>nsupdate</application></refentrytitle>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <manvolnum>8</manvolnum>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <refmiscinfo>BIND9</refmiscinfo>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </refmeta>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <refnamediv>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <refname><application>nsupdate</application></refname>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <refpurpose>Dynamic DNS update utility</refpurpose>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </refnamediv>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <docinfo>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <copyright>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <year>2004</year>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <year>2005</year>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <year>2006</year>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <year>2007</year>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <holder>Internet Systems Consortium, Inc. ("ISC")</holder>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </copyright>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <copyright>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <year>2000</year>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <year>2001</year>

b843f577bbcd6660fbaa506d9e55b156c689a5a8Evan Hunt <year>2002</year>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <year>2003</year>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <holder>Internet Software Consortium.</holder>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </copyright>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </docinfo>

b843f577bbcd6660fbaa506d9e55b156c689a5a8Evan Hunt

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <refsynopsisdiv>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <cmdsynopsis>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <command>nsupdate</command>

8b78c993cb475cc94e88560941b28c37684789d9Francis Dupont <arg><option>-d</option></arg>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <group>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <arg><option>-y <replaceable class="parameter"><optional>hmac:</optional>keyname:secret</replaceable></option></arg>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <arg><option>-k <replaceable class="parameter">keyfile</replaceable></option></arg>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </group>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <arg><option>-t <replaceable class="parameter">timeout</replaceable></option></arg>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <arg><option>-u <replaceable class="parameter">udptimeout</replaceable></option></arg>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <arg><option>-r <replaceable class="parameter">udpretries</replaceable></option></arg>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <arg><option>-R <replaceable class="parameter">randomdev</replaceable></option></arg>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <arg><option>-v</option></arg>

b843f577bbcd6660fbaa506d9e55b156c689a5a8Evan Hunt <arg>filename</arg>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </cmdsynopsis>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </refsynopsisdiv>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <refsect1>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <title>DESCRIPTION</title>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <para><command>nsupdate</command>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt is used to submit Dynamic DNS Update requests as defined in RFC2136

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt to a name server.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt This allows resource records to be added or removed from a zone

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt without manually editing the zone file.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt A single update request can contain requests to add or remove more than

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt one

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt resource record.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt Zones that are under dynamic control via

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <command>nsupdate</command>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt or a DHCP server should not be edited by hand.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt Manual edits could

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt conflict with dynamic updates and cause data to be lost.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt The resource records that are dynamically added or removed with

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <command>nsupdate</command>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt have to be in the same zone.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt Requests are sent to the zone's master server.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt This is identified by the MNAME field of the zone's SOA record.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt The

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <option>-d</option>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt option makes

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <command>nsupdate</command>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt operate in debug mode.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt This provides tracing information about the update requests that are

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt made and the replies received from the name server.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt Transaction signatures can be used to authenticate the Dynamic DNS

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt updates.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt These use the TSIG resource record type described in RFC2845 or the

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt SIG(0) record described in RFC3535 and RFC2931.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt TSIG relies on a shared secret that should only be known to

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <command>nsupdate</command> and the name server.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt Currently, the only supported encryption algorithm for TSIG is

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt HMAC-MD5, which is defined in RFC 2104.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt Once other algorithms are defined for TSIG, applications will need to

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt ensure they select the appropriate algorithm as well as the key when

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt authenticating each other.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt For instance, suitable

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <type>key</type>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt and

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <type>server</type>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt statements would be added to

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <filename>/etc/named.conf</filename>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt so that the name server can associate the appropriate secret key

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt and algorithm with the IP address of the

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt client application that will be using TSIG authentication.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt SIG(0) uses public key cryptography. To use a SIG(0) key, the public

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt key must be stored in a KEY record in a zone served by the name server.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <command>nsupdate</command>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt does not read

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <filename>/etc/named.conf</filename>.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </para>

8b78c993cb475cc94e88560941b28c37684789d9Francis Dupont <para><command>nsupdate</command>

8b78c993cb475cc94e88560941b28c37684789d9Francis Dupont uses the <option>-y</option> or <option>-k</option> option

8b78c993cb475cc94e88560941b28c37684789d9Francis Dupont to provide the shared secret needed to generate a TSIG record

8b78c993cb475cc94e88560941b28c37684789d9Francis Dupont for authenticating Dynamic DNS update requests, default type

8b78c993cb475cc94e88560941b28c37684789d9Francis Dupont HMAC-MD5. These options are mutually exclusive. With the

8b78c993cb475cc94e88560941b28c37684789d9Francis Dupont <option>-k</option> option, <command>nsupdate</command> reads

8b78c993cb475cc94e88560941b28c37684789d9Francis Dupont the shared secret from the file <parameter>keyfile</parameter>,

8b78c993cb475cc94e88560941b28c37684789d9Francis Dupont whose name is of the form

8b78c993cb475cc94e88560941b28c37684789d9Francis Dupont <filename>K{name}.+157.+{random}.private</filename>. For

8b78c993cb475cc94e88560941b28c37684789d9Francis Dupont historical reasons, the file

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <filename>K{name}.+157.+{random}.key</filename> must also be

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt present. When the <option>-y</option> option is used, a

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt signature is generated from

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <optional><parameter>hmac:</parameter></optional><parameter>keyname:secret.</parameter>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <parameter>keyname</parameter> is the name of the key, and

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <parameter>secret</parameter> is the base64 encoded shared

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt secret. Use of the <option>-y</option> option is discouraged

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt because the shared secret is supplied as a command line

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt argument in clear text. This may be visible in the output

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt from

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt <citerefentry>

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt <refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum>

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt </citerefentry> or in a history file maintained by the user's

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt shell.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt The <option>-k</option> may also be used to specify a SIG(0) key used

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt to authenticate Dynamic DNS update requests. In this case, the key

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt specified is not an HMAC-MD5 key.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt By default

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <command>nsupdate</command>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt uses UDP to send update requests to the name server unless they are too

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt large to fit in a UDP request in which case TCP will be used.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt The

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <option>-v</option>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt option makes

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <command>nsupdate</command>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt use a TCP connection.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt This may be preferable when a batch of update requests is made.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <para>

eec29cfd40361662b25bad50e1b94f7738a8fea0Jeremy Reed The <option>-t</option> option sets the maximum time an update request

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt can

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt take before it is aborted. The default is 300 seconds. Zero can be

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt used

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt to disable the timeout.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt The <option>-u</option> option sets the UDP retry interval. The default

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt is

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt 3 seconds. If zero, the interval will be computed from the timeout

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt interval

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt and number of UDP retries.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt The <option>-r</option> option sets the number of UDP retries. The

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt default is

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt 3. If zero, only one update request will be made.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </para>

b843f577bbcd6660fbaa506d9e55b156c689a5a8Evan Hunt <para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt The <option>-R <replaceable

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt class="parameter">randomdev</replaceable></option> option

b843f577bbcd6660fbaa506d9e55b156c689a5a8Evan Hunt specifies a source of randomness. If the operating system

b843f577bbcd6660fbaa506d9e55b156c689a5a8Evan Hunt does not provide a <filename>/dev/random</filename> or

b843f577bbcd6660fbaa506d9e55b156c689a5a8Evan Hunt equivalent device, the default source of randomness is keyboard

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt input. <filename>randomdev</filename> specifies the name of

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt a character device or file containing random data to be used

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt instead of the default. The special value

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <filename>keyboard</filename> indicates that keyboard input

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt should be used. This option may be specified multiple times.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </refsect1>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <refsect1>

b843f577bbcd6660fbaa506d9e55b156c689a5a8Evan Hunt <title>INPUT FORMAT</title>

b843f577bbcd6660fbaa506d9e55b156c689a5a8Evan Hunt <para><command>nsupdate</command>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt reads input from

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <parameter>filename</parameter>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt or standard input.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt Each command is supplied on exactly one line of input.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt Some commands are for administrative purposes.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt The others are either update instructions or prerequisite checks on the

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt contents of the zone.

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt These checks set conditions that some name or set of

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt resource records (RRset) either exists or is absent from the zone.

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt These conditions must be met if the entire update request is to succeed.

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt Updates will be rejected if the tests for the prerequisite conditions

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt fail.

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt </para>

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt <para>

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt Every update request consists of zero or more prerequisites

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt and zero or more updates.

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt This allows a suitably authenticated update request to proceed if some

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt specified resource records are present or missing from the zone.

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt A blank input line (or the <command>send</command> command)

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt causes the

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt accumulated commands to be sent as one Dynamic DNS update request to the

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt name server.

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt </para>

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt <para>

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt The command formats and their meaning are as follows:

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt <variablelist>

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt <varlistentry>

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt <term>

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt <command>server</command>

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt <arg choice="req">servername</arg>

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt <arg choice="opt">port</arg>

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt </term>

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt <listitem>

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt <para>

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt Sends all dynamic update requests to the name server

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt <parameter>servername</parameter>.

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt When no server statement is provided,

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt <command>nsupdate</command>

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt will send updates to the master server of the correct zone.

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt The MNAME field of that zone's SOA record will identify the

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt master

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt server for that zone.

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt <parameter>port</parameter>

eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt is the port number on

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <parameter>servername</parameter>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt where the dynamic update requests get sent.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt If no port number is specified, the default DNS port number of

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt 53 is

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt used.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </listitem>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </varlistentry>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <varlistentry>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <term>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <command>local</command>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <arg choice="req">address</arg>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <arg choice="opt">port</arg>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt </term>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <listitem>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <para>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt Sends all dynamic update requests using the local

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <parameter>address</parameter>.

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt When no local statement is provided,

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt <command>nsupdate</command>

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt will send updates using an address and port chosen by the

553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt 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.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<command>zone</command>

<arg choice="req">zonename</arg>

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

<command>class</command>

<arg choice="req">classname</arg>

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

<command>key</command>

<arg choice="req">name</arg>

<arg choice="req">secret</arg>

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

<command>prereq nxdomain</command>

<arg choice="req">domain-name</arg>

</term>

<listitem>

<para>

Requires that no resource record of any type exists with name

<parameter>domain-name</parameter>.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<command>prereq yxdomain</command>

<arg choice="req">domain-name</arg>

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

<command>prereq nxrrset</command>

<arg choice="req">domain-name</arg>

<arg choice="opt">class</arg>

<arg choice="req">type</arg>

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

<command>prereq yxrrset</command>

<arg choice="req">domain-name</arg>

<arg choice="opt">class</arg>

<arg choice="req">type</arg>

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

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

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

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

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

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

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

<command>show</command>

</term>

<listitem>

<para>

Displays the current message, containing all of the

prerequisites and

updates specified since the last send.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<command>send</command>

</term>

<listitem>

<para>

Sends the current message. This is equivalent to entering a

blank line.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<command>answer</command>

</term>

<listitem>

<para>

Displays the answer.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

<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

&gt; update delete oldhost.example.com A

&gt; update add newhost.example.com 86400 A 172.16.1.1

&gt; 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>

with IP address 172.16.1.1 is added.

The newly-added record has a 1 day TTL (86400 seconds).

<programlisting>

# nsupdate

&gt; prereq nxdomain nickname.example.com

&gt; update add nickname.example.com 86400 CNAME somehost.example.com

&gt; 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>

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

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

</varlistentry>

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

</para>

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