diff options
Diffstat (limited to 'contrib/bind9/bin/nsupdate/nsupdate.docbook')
| -rw-r--r-- | contrib/bind9/bin/nsupdate/nsupdate.docbook | 658 |
1 files changed, 0 insertions, 658 deletions
diff --git a/contrib/bind9/bin/nsupdate/nsupdate.docbook b/contrib/bind9/bin/nsupdate/nsupdate.docbook deleted file mode 100644 index 7a2b4cfb7dd75..0000000000000 --- a/contrib/bind9/bin/nsupdate/nsupdate.docbook +++ /dev/null @@ -1,658 +0,0 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN" - "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" - [<!ENTITY mdash "—">]> -<!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") - - Copyright (C) 2000-2003 Internet Software Consortium. - - - - Permission to use, copy, modify, and 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.8.2.3.2.10 2005/05/12 21:36:03 sra Exp $ --> - -<refentry> -<refentryinfo> -<date>Jun 30, 2000</date> -</refentryinfo> -<refmeta> -<refentrytitle>nsupdate</refentrytitle> -<manvolnum>8</manvolnum> -<refmiscinfo>BIND9</refmiscinfo> -</refmeta> - - <docinfo> - <copyright> - <year>2004</year> - <year>2005</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> - -<refnamediv> -<refname>nsupdate</refname> -<refpurpose>Dynamic DNS update utility</refpurpose> -</refnamediv> -<refsynopsisdiv> -<cmdsynopsis> -<command>nsupdate</command> -<arg><option>-d</option></arg> -<group> - <arg><option>-y <replaceable class="parameter">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 (with an HMAC-MD5 key) to provide the shared secret needed to generate -a TSIG record for authenticating Dynamic DNS update requests. -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 -<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 a 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> -<cmdsynopsis> -<command>server</command> -<arg choice="req">servername</arg> -<arg choice="opt">port</arg> -</cmdsynopsis> -</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> -<cmdsynopsis> -<command>local</command> -<arg choice="req">address</arg> -<arg choice="opt">port</arg> -</cmdsynopsis> -</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> -<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> -</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> -</varlistentry> - -<varlistentry><term> -<cmdsynopsis> -<command>answer</command> -</cmdsynopsis> -</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> -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 -> 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> |