nsupdate.docbook revision d4ef65050feac78554addf6e16a06c6e2e0bd331
1c57c3f79db0bf0358bbe6d7b5ad650c0c852f4bTinderbox User<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - Copyright (C) 2001 Internet Software Consortium.
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - Permission to use, copy, modify, and distribute this software for any
1c57c3f79db0bf0358bbe6d7b5ad650c0c852f4bTinderbox User - purpose with or without fee is hereby granted, provided that the above
1c57c3f79db0bf0358bbe6d7b5ad650c0c852f4bTinderbox User - copyright notice and this permission notice appear in all copies.
1c57c3f79db0bf0358bbe6d7b5ad650c0c852f4bTinderbox User - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
1c57c3f79db0bf0358bbe6d7b5ad650c0c852f4bTinderbox User - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
1c57c3f79db0bf0358bbe6d7b5ad650c0c852f4bTinderbox User - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
1c57c3f79db0bf0358bbe6d7b5ad650c0c852f4bTinderbox User - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
f9ce6280cec79deb16ff6d9807aa493ff23e10d9Tinderbox User - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
c2258eedf2d9d0207b45b90014f8fde5413b41a3Tinderbox User - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<!-- $Id: nsupdate.docbook,v 1.3 2001/04/10 21:50:48 bwelling Exp $ -->
46472a450e043434d78fa18edc73bca8c47f3981Tinderbox User<refentryinfo>
46472a450e043434d78fa18edc73bca8c47f3981Tinderbox User</refentryinfo>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<refpurpose>Dynamic DNS update utility</refpurpose>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<refsynopsisdiv>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<cmdsynopsis>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <arg><option>-y <replaceable class="parameter">keyname:secret</replaceable></option></arg>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <arg><option>-k <replaceable class="parameter">keyfile</replaceable></option></arg>
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User</cmdsynopsis>
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User</refsynopsisdiv>
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Useris used to submit Dynamic DNS Update requests as defined in RFC2136
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Userto a name server.
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserThis allows resource records to be added or removed from a zone
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Userwithout manually editing the zone file.
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox UserA single update request can contain requests to add or remove more than one
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Userresource record.
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserZones that are under dynamic control via
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox Useror a DHCP server should not be edited by hand.
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserManual edits could
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Userconflict with dynamic updates and cause data to be lost.
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserThe resource records that are dynamically added or removed with
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox Userhave to be in the same zone.
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox UserRequests are sent to the zone's master server.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThis is identified by the MNAME field of the zone's SOA record.
6b7cba2b10d6cb5363d94b434b0d22ecfb33a6f3Tinderbox Useroperate in debug mode.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserThis provides tracing information about the update requests that are
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Usermade and the replies received from the name server.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserTransaction signatures can be used to authenticate the Dynamic DNS
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox UserThese use the TSIG resource record type described in RFC2845.
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox UserThe signatures rely on a shared secret that should only be known to
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Userand the name server.
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox UserCurrently, the only supported encryption algorithm for TSIG is
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox UserHMAC-MD5, which is defined in RFC 2104.
1ffe3f29e3cd0d8355500e9fd34de918ad9b4a01Tinderbox UserOnce other algorithms are defined for TSIG, applications will need to
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Userensure they select the appropriate algorithm as well as the key when
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Userauthenticating each other.
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox UserFor instance suitable
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Userstatements would be added to
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Userso that the name server can associate the appropriate secret key
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Userand algorithm with the IP address of the
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Userclient application that will be using TSIG authentication.
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox Useroption to provide the shared secret needed to generate a TSIG record
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox Userfor authenticating Dynamic DNS update requests.
eb2a5f51bd5c100799d93d51c9e22666cbd64d90Tinderbox UserThese options are mutually exclusive.
3ba1f79ade054aa6a0dc5032502bcdcf357cd7bdTinderbox Userreads the shared secret from the file
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userwhose name is of the form
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<filename>K{name}.+157.+{random}.private</filename>.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntFor historical
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntreasons, the file
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntmust also be present. When the
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntoption is used, a signature is generated from
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntis the name of the key,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntis the base64 encoded shared secret.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntoption is discouraged because the shared secret is supplied as a command
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntline argument in clear text.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThis may be visible in the output from
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<citerefentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</citerefentry>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Useror in a history file maintained by the user's shell.
7e71f05d8643aca84914437c900cb716444507e4Tinderbox Useruses UDP to send update requests to the name server.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntuse a TCP connection.
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserThis may be preferable when a batch of update requests is made.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntreads input from
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntor standard input.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntEach command is supplied on exactly one line of input.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserSome commands are for administrative purposes.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserThe others are either update instructions or prerequisite checks on the
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntcontents of the zone.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThese checks set conditions that some name or set of
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntresource records (RRset) either exists or is absent from the zone.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThese conditions must be met if the entire update request is to succeed.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserUpdates will be rejected if the tests for the prerequisite conditions fail.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntEvery update request consists of zero or more prerequisites
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntand zero or more updates.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThis allows a suitably authenticated update request to proceed if some
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userspecified resource records are present or missing from the zone.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntA blank input line causes the accumulated commands to be sent as one Dynamic
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserDNS update request to the name server.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThe command formats and their meaning are as follows:
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<variablelist>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</cmdsynopsis>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntSends all dynamic update requests to the name server
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntWhen no server statement is provided,
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox Userwill send updates to the master server of the correct zone.
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox UserThe MNAME field of that zone's SOA record will identify the master
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox Userserver for that zone.
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox Useris the port number on
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox Userwhere the dynamic update requests get sent.
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox UserIf no port number is specified, the default DNS port number of 53 is
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User</cmdsynopsis>
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox UserSends all dynamic update requests using the local
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntWhen no local statement is provided,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntwill send updates using an address and port choosen by the system.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntcan additionally be used to make requests come from a specific port.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserIf no port number is specified, the system will assign one.
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox User</cmdsynopsis>
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox UserSpecifies that all updates are to be made to the zone
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox Userstatement is provided,
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox Userwill attempt determine the correct zone to update based on the rest of the input.
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User</cmdsynopsis>
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox UserRequires that no resource record of any type exists with name
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User</cmdsynopsis>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntexists (has as at least one resource record, of any type).
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<cmdsynopsis>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</cmdsynopsis>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntRequires that no resource record exists of the specified
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntis omitted, IN (internet) is assumed.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<cmdsynopsis>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</cmdsynopsis>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThis requires that a resource record of the specified
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntis omitted, IN (internet) is assumed.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User</cmdsynopsis>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntfrom each set of prerequisites of this form
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Usersharing a common
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userare combined to form a set of RRs. This set of RRs must
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntexactly match the set of RRs existing in the zone at the
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userare written in the standard text representation of the resource record's
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<cmdsynopsis>
0226754d9e537fd56b690d5890cfe215a6c59f89Tinderbox User<arg choice="opt">type <arg choice="opt" rep="repeat">data</arg></arg>
0226754d9e537fd56b690d5890cfe215a6c59f89Tinderbox User</cmdsynopsis>
eb2a5f51bd5c100799d93d51c9e22666cbd64d90Tinderbox UserDeletes any resource records named
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Useris provided, only matching resource records will be removed.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserThe internet class is assumed if
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntis not supplied. The
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Useris ignored, and is only allowed for compatibility.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</cmdsynopsis>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntAdds a new resource record with the specified
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</variablelist>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserLines beginning with a semicolon are comments, and are ignored.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThe examples below show how
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntcould be used to insert and delete resource records from the
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntNotice that the input in each example contains a trailing blank line so that
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunta group of commands are sent as one dynamic update request to the
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntmaster name server for
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<programlisting>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt> update delete oldhost.example.com A
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt> update add newhost.example.com 86400 A 172.16.1.1
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</programlisting>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserAny A records for
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userand an A record for
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntit IP address 172.16.1.1 is added.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThe newly-added record has a 1 day TTL (86400 seconds)
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<programlisting>
eb2a5f51bd5c100799d93d51c9e22666cbd64d90Tinderbox User> update add nickname.example.com CNAME somehost.example.com
eb2a5f51bd5c100799d93d51c9e22666cbd64d90Tinderbox User</programlisting>
eb2a5f51bd5c100799d93d51c9e22666cbd64d90Tinderbox UserThe prerequisite condition gets the name server to check that there
eb2a5f51bd5c100799d93d51c9e22666cbd64d90Tinderbox Userare no resource records of any type for
eb2a5f51bd5c100799d93d51c9e22666cbd64d90Tinderbox UserIf there are, the update request fails.
eb2a5f51bd5c100799d93d51c9e22666cbd64d90Tinderbox UserIf this name does not exist, a CNAME for it is added.
eb2a5f51bd5c100799d93d51c9e22666cbd64d90Tinderbox UserThis ensures that when the CNAME is added, it cannot conflict with the
eb2a5f51bd5c100799d93d51c9e22666cbd64d90Tinderbox Userlong-standing rule in RFC1034 that a name must not exist as any other
eb2a5f51bd5c100799d93d51c9e22666cbd64d90Tinderbox Userrecord type if it exists as a CNAME.
eb2a5f51bd5c100799d93d51c9e22666cbd64d90Tinderbox User(The rule has been updated for DNSSEC in RFC2535 to allow CNAMEs to have
eb2a5f51bd5c100799d93d51c9e22666cbd64d90Tinderbox UserSIG, KEY and NXT records.)
eb2a5f51bd5c100799d93d51c9e22666cbd64d90Tinderbox User<variablelist>
eb2a5f51bd5c100799d93d51c9e22666cbd64d90Tinderbox User<varlistentry><term><constant>/etc/resolv.conf</constant></term>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntused to identify default name server
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<varlistentry><term><constant>K{name}.+157.+{random}.key</constant></term>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntbase-64 encoding of HMAC-MD5 key created by
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<citerefentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</citerefentry>.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<varlistentry><term><constant>K{name}.+157.+{random}.private</constant></term>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntbase-64 encoding of HMAC-MD5 key created by
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<citerefentry>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</citerefentry>.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</variablelist>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<citerefentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</citerefentry>,
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<citerefentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</citerefentry>,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<citerefentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</citerefentry>,
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<citerefentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</citerefentry>,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<citerefentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</citerefentry>,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<citerefentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</citerefentry>,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<citerefentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User</citerefentry>,
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<citerefentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</citerefentry>.
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox UserThe TSIG key is redundantly stored in two separate files.
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox UserThis is a consequence of nsupdate using the DST library
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox Userfor its cryptographic operations, and may change in future