diff options
Diffstat (limited to 'bin/nsupdate/nsupdate.docbook')
| -rw-r--r-- | bin/nsupdate/nsupdate.docbook | 657 |
1 files changed, 657 insertions, 0 deletions
diff --git a/bin/nsupdate/nsupdate.docbook b/bin/nsupdate/nsupdate.docbook new file mode 100644 index 0000000..0ea4906 --- /dev/null +++ b/bin/nsupdate/nsupdate.docbook @@ -0,0 +1,657 @@ +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" + [<!ENTITY mdash "—">]> +<!-- + - Copyright (C) 2004-2007 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2000-2003 Internet Software Consortium. + - + - Permission to use, copy, modify, and/or 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.18.18.10 2007/08/28 07:20:01 tbox 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> + + <docinfo> + <copyright> + <year>2004</year> + <year>2005</year> + <year>2006</year> + <year>2007</year> + <holder>Internet Systems Consortium, Inc. ("ISC")</holder> + </copyright> + <copyright> + <year>2000</year> + <year>2001</year> + <year>2002</year> + <year>2003</year> + <holder>Internet Software Consortium.</holder> + </copyright> + </docinfo> + + <refsynopsisdiv> + <cmdsynopsis> + <command>nsupdate</command> + <arg><option>-d</option></arg> + <group> + <arg><option>-y <replaceable class="parameter"><optional>hmac:</optional>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 + to provide the shared secret needed to generate a TSIG record + for authenticating Dynamic DNS update requests, default type + HMAC-MD5. 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 + <optional><parameter>hmac:</parameter></optional><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 an 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> + <command>server</command> + <arg choice="req">servername</arg> + <arg choice="opt">port</arg> + </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> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>local</command> + <arg choice="req">address</arg> + <arg choice="opt">port</arg> + </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. + </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 +> 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> + with 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> + + <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><!-- + - Local variables: + - mode: sgml + - End: +--> |
