diff options
Diffstat (limited to 'usr.sbin/bind/bin/nsupdate/nsupdate.html')
| -rw-r--r-- | usr.sbin/bind/bin/nsupdate/nsupdate.html | 959 |
1 files changed, 959 insertions, 0 deletions
diff --git a/usr.sbin/bind/bin/nsupdate/nsupdate.html b/usr.sbin/bind/bin/nsupdate/nsupdate.html new file mode 100644 index 00000000000..b8e63dcaea9 --- /dev/null +++ b/usr.sbin/bind/bin/nsupdate/nsupdate.html @@ -0,0 +1,959 @@ +<!-- + - Copyright (C) 2000, 2001 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 INTERNET SOFTWARE CONSORTIUM + - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL + - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL + - INTERNET SOFTWARE CONSORTIUM 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. +--> +<HTML +><HEAD +><TITLE +>nsupdate</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.61 +"></HEAD +><BODY +CLASS="REFENTRY" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><H1 +><A +NAME="AEN1" +>nsupdate</A +></H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN8" +></A +><H2 +>Name</H2 +>nsupdate -- Dynamic DNS update utility</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN11" +></A +><H2 +>Synopsis</H2 +><P +><B +CLASS="COMMAND" +>nsupdate</B +> [<TT +CLASS="OPTION" +>-d</TT +>] [<TT +CLASS="OPTION" +>-y <TT +CLASS="REPLACEABLE" +><I +>keyname:secret</I +></TT +></TT +> | <TT +CLASS="OPTION" +>-k <TT +CLASS="REPLACEABLE" +><I +>keyfile</I +></TT +></TT +>] [<TT +CLASS="OPTION" +>-v</TT +>] [filename]</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN26" +></A +><H2 +>DESCRIPTION</H2 +><P +><B +CLASS="COMMAND" +>nsupdate</B +> +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.</P +><P +>Zones that are under dynamic control via +<B +CLASS="COMMAND" +>nsupdate</B +> +or a DHCP server should not be edited by hand. +Manual edits could +conflict with dynamic updates and cause data to be lost.</P +><P +>The resource records that are dynamically added or removed with +<B +CLASS="COMMAND" +>nsupdate</B +> +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.</P +><P +>The +<TT +CLASS="OPTION" +>-d</TT +> +option makes +<B +CLASS="COMMAND" +>nsupdate</B +> +operate in debug mode. +This provides tracing information about the update requests that are +made and the replies received from the name server.</P +><P +>Transaction signatures can be used to authenticate the Dynamic DNS +updates. +These use the TSIG resource record type described in RFC2845. +The signatures rely on a shared secret that should only be known to +<B +CLASS="COMMAND" +>nsupdate</B +> +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 +<SPAN +CLASS="TYPE" +>key</SPAN +> +and +<SPAN +CLASS="TYPE" +>server</SPAN +> +statements would be added to +<TT +CLASS="FILENAME" +>/etc/named.conf</TT +> +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. +<B +CLASS="COMMAND" +>nsupdate</B +> +does not read +<TT +CLASS="FILENAME" +>/etc/named.conf</TT +>.</P +><P +><B +CLASS="COMMAND" +>nsupdate</B +> +uses the +<TT +CLASS="OPTION" +>-y</TT +> +or +<TT +CLASS="OPTION" +>-k</TT +> +option to provide the shared secret needed to generate a TSIG record +for authenticating Dynamic DNS update requests. +These options are mutually exclusive. +With the +<TT +CLASS="OPTION" +>-k</TT +> +option, +<B +CLASS="COMMAND" +>nsupdate</B +> +reads the shared secret from the file +<TT +CLASS="PARAMETER" +><I +>keyfile</I +></TT +>, +whose name is of the form +<TT +CLASS="FILENAME" +>K{name}.+157.+{random}.private</TT +>. +For historical +reasons, the file +<TT +CLASS="FILENAME" +>K{name}.+157.+{random}.key</TT +> +must also be present. When the +<TT +CLASS="OPTION" +>-y</TT +> +option is used, a signature is generated from +<TT +CLASS="PARAMETER" +><I +>keyname:secret.</I +></TT +> +<TT +CLASS="PARAMETER" +><I +>keyname</I +></TT +> +is the name of the key, +and +<TT +CLASS="PARAMETER" +><I +>secret</I +></TT +> +is the base64 encoded shared secret. +Use of the +<TT +CLASS="OPTION" +>-y</TT +> +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 +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>ps</SPAN +>(1)</SPAN +> +or in a history file maintained by the user's shell.</P +><P +>By default +<B +CLASS="COMMAND" +>nsupdate</B +> +uses UDP to send update requests to the name server. +The +<TT +CLASS="OPTION" +>-v</TT +> +option makes +<B +CLASS="COMMAND" +>nsupdate</B +> +use a TCP connection. +This may be preferable when a batch of update requests is made.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN65" +></A +><H2 +>INPUT FORMAT</H2 +><P +><B +CLASS="COMMAND" +>nsupdate</B +> +reads input from +<TT +CLASS="PARAMETER" +><I +>filename</I +></TT +> +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.</P +><P +>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 <B +CLASS="COMMAND" +>send</B +> command) causes the +accumulated commands to be sent as one Dynamic DNS update request to the +name server.</P +><P +>The command formats and their meaning are as follows: +<P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><P +><B +CLASS="COMMAND" +>server</B +> {servername} [port]</P +></DT +><DD +><P +>Sends all dynamic update requests to the name server +<TT +CLASS="PARAMETER" +><I +>servername</I +></TT +>. +When no server statement is provided, +<B +CLASS="COMMAND" +>nsupdate</B +> +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. +<TT +CLASS="PARAMETER" +><I +>port</I +></TT +> +is the port number on +<TT +CLASS="PARAMETER" +><I +>servername</I +></TT +> +where the dynamic update requests get sent. +If no port number is specified, the default DNS port number of 53 is +used.</P +></DD +><DT +><P +><B +CLASS="COMMAND" +>local</B +> {address} [port]</P +></DT +><DD +><P +>Sends all dynamic update requests using the local +<TT +CLASS="PARAMETER" +><I +>address</I +></TT +>. + +When no local statement is provided, +<B +CLASS="COMMAND" +>nsupdate</B +> +will send updates using an address and port choosen by the system. +<TT +CLASS="PARAMETER" +><I +>port</I +></TT +> +can additionally be used to make requests come from a specific port. +If no port number is specified, the system will assign one. </P +></DD +><DT +><P +><B +CLASS="COMMAND" +>zone</B +> {zonename}</P +></DT +><DD +><P +>Specifies that all updates are to be made to the zone +<TT +CLASS="PARAMETER" +><I +>zonename</I +></TT +>. +If no +<TT +CLASS="PARAMETER" +><I +>zone</I +></TT +> +statement is provided, +<B +CLASS="COMMAND" +>nsupdate</B +> +will attempt determine the correct zone to update based on the rest of the input.</P +></DD +><DT +><P +><B +CLASS="COMMAND" +>key</B +> {name} {secret}</P +></DT +><DD +><P +>Specifies that all updates are to be TSIG signed using the +<TT +CLASS="PARAMETER" +><I +>keyname</I +></TT +> <TT +CLASS="PARAMETER" +><I +>keysecret</I +></TT +> pair. +The <B +CLASS="COMMAND" +>key</B +> command +overrides any key specified on the command line via +<TT +CLASS="OPTION" +>-y</TT +> or <TT +CLASS="OPTION" +>-k</TT +>.</P +></DD +><DT +><P +><B +CLASS="COMMAND" +>prereq nxdomain</B +> {domain-name}</P +></DT +><DD +><P +>Requires that no resource record of any type exists with name +<TT +CLASS="PARAMETER" +><I +>domain-name</I +></TT +>.</P +></DD +><DT +><P +><B +CLASS="COMMAND" +>prereq yxdomain</B +> {domain-name}</P +></DT +><DD +><P +>Requires that +<TT +CLASS="PARAMETER" +><I +>domain-name</I +></TT +> +exists (has as at least one resource record, of any type).</P +></DD +><DT +><P +><B +CLASS="COMMAND" +>prereq nxrrset</B +> {domain-name} [class] {type}</P +></DT +><DD +><P +>Requires that no resource record exists of the specified +<TT +CLASS="PARAMETER" +><I +>type</I +></TT +>, +<TT +CLASS="PARAMETER" +><I +>class</I +></TT +> +and +<TT +CLASS="PARAMETER" +><I +>domain-name</I +></TT +>. +If +<TT +CLASS="PARAMETER" +><I +>class</I +></TT +> +is omitted, IN (internet) is assumed. + </P +></DD +><DT +><P +><B +CLASS="COMMAND" +>prereq yxrrset</B +> {domain-name} [class] {type}</P +></DT +><DD +><P +>This requires that a resource record of the specified +<TT +CLASS="PARAMETER" +><I +>type</I +></TT +>, +<TT +CLASS="PARAMETER" +><I +>class</I +></TT +> +and +<TT +CLASS="PARAMETER" +><I +>domain-name</I +></TT +> +must exist. +If +<TT +CLASS="PARAMETER" +><I +>class</I +></TT +> +is omitted, IN (internet) is assumed.</P +></DD +><DT +><P +><B +CLASS="COMMAND" +>prereq yxrrset</B +> {domain-name} [class] {type} {data...}</P +></DT +><DD +><P +>The +<TT +CLASS="PARAMETER" +><I +>data</I +></TT +> +from each set of prerequisites of this form +sharing a common +<TT +CLASS="PARAMETER" +><I +>type</I +></TT +>, +<TT +CLASS="PARAMETER" +><I +>class</I +></TT +>, +and +<TT +CLASS="PARAMETER" +><I +>domain-name</I +></TT +> +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 +<TT +CLASS="PARAMETER" +><I +>type</I +></TT +>, +<TT +CLASS="PARAMETER" +><I +>class</I +></TT +>, +and +<TT +CLASS="PARAMETER" +><I +>domain-name</I +></TT +>. +The +<TT +CLASS="PARAMETER" +><I +>data</I +></TT +> +are written in the standard text representation of the resource record's +RDATA.</P +></DD +><DT +><P +><B +CLASS="COMMAND" +>update delete</B +> {domain-name} [ttl] [class] [type [data...]]</P +></DT +><DD +><P +>Deletes any resource records named +<TT +CLASS="PARAMETER" +><I +>domain-name</I +></TT +>. +If +<TT +CLASS="PARAMETER" +><I +>type</I +></TT +> +and +<TT +CLASS="PARAMETER" +><I +>data</I +></TT +> +is provided, only matching resource records will be removed. +The internet class is assumed if +<TT +CLASS="PARAMETER" +><I +>class</I +></TT +> +is not supplied. The +<TT +CLASS="PARAMETER" +><I +>ttl</I +></TT +> +is ignored, and is only allowed for compatibility.</P +></DD +><DT +><P +><B +CLASS="COMMAND" +>update add</B +> {domain-name} {ttl} [class] {type} {data...}</P +></DT +><DD +><P +>Adds a new resource record with the specified +<TT +CLASS="PARAMETER" +><I +>ttl</I +></TT +>, +<TT +CLASS="PARAMETER" +><I +>class</I +></TT +> +and +<TT +CLASS="PARAMETER" +><I +>data</I +></TT +>.</P +></DD +><DT +><P +><B +CLASS="COMMAND" +>show</B +> </P +></DT +><DD +><P +>Displays the current message, containing all of the prerequisites and +updates specified since the last send.</P +></DD +><DT +><P +><B +CLASS="COMMAND" +>send</B +> </P +></DT +><DD +><P +>Sends the current message. This is equivalent to entering a blank line.</P +></DD +></DL +></DIV +> </P +><P +>Lines beginning with a semicolon are comments, and are ignored.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN223" +></A +><H2 +>EXAMPLES</H2 +><P +>The examples below show how +<B +CLASS="COMMAND" +>nsupdate</B +> +could be used to insert and delete resource records from the +<SPAN +CLASS="TYPE" +>example.com</SPAN +> +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 +<SPAN +CLASS="TYPE" +>example.com</SPAN +>. + +<PRE +CLASS="PROGRAMLISTING" +># nsupdate +> update delete oldhost.example.com A +> update add newhost.example.com 86400 A 172.16.1.1 +></PRE +></P +><P +>Any A records for +<SPAN +CLASS="TYPE" +>oldhost.example.com</SPAN +> +are deleted. +and an A record for +<SPAN +CLASS="TYPE" +>newhost.example.com</SPAN +> +it IP address 172.16.1.1 is added. +The newly-added record has a 1 day TTL (86400 seconds) +<PRE +CLASS="PROGRAMLISTING" +># nsupdate +> prereq nxdomain nickname.example.com +> update add nickname.example.com 86400 CNAME somehost.example.com +></PRE +></P +><P +>The prerequisite condition gets the name server to check that there +are no resource records of any type for +<SPAN +CLASS="TYPE" +>nickname.example.com</SPAN +>. + +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.)</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN236" +></A +><H2 +>FILES</H2 +><P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><TT +CLASS="CONSTANT" +>/etc/resolv.conf</TT +></DT +><DD +><P +>used to identify default name server</P +></DD +><DT +><TT +CLASS="CONSTANT" +>K{name}.+157.+{random}.key</TT +></DT +><DD +><P +>base-64 encoding of HMAC-MD5 key created by +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>dnssec-keygen</SPAN +>(8)</SPAN +>.</P +></DD +><DT +><TT +CLASS="CONSTANT" +>K{name}.+157.+{random}.private</TT +></DT +><DD +><P +>base-64 encoding of HMAC-MD5 key created by +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>dnssec-keygen</SPAN +>(8)</SPAN +>.</P +></DD +></DL +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN260" +></A +><H2 +>SEE ALSO</H2 +><P +><SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>RFC2136</SPAN +></SPAN +>, +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>RFC3007</SPAN +></SPAN +>, +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>RFC2104</SPAN +></SPAN +>, +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>RFC2845</SPAN +></SPAN +>, +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>RFC1034</SPAN +></SPAN +>, +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>RFC2535</SPAN +></SPAN +>, +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>named</SPAN +>(8)</SPAN +>, +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>dnssec-keygen</SPAN +>(8)</SPAN +>. </P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN281" +></A +><H2 +>BUGS</H2 +><P +>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.</P +></DIV +></BODY +></HTML +>
\ No newline at end of file |