diff options
Diffstat (limited to 'contrib/bind9/bin/nsupdate/nsupdate.docbook')
| -rw-r--r-- | contrib/bind9/bin/nsupdate/nsupdate.docbook | 657 |
1 files changed, 0 insertions, 657 deletions
diff --git a/contrib/bind9/bin/nsupdate/nsupdate.docbook b/contrib/bind9/bin/nsupdate/nsupdate.docbook deleted file mode 100644 index 0ea4906..0000000 --- a/contrib/bind9/bin/nsupdate/nsupdate.docbook +++ /dev/null @@ -1,657 +0,0 @@ -<!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: ---> |
