nsupdate.docbook revision ea2a4bbc5db66edbba7966f7f0b535259ee1a6a9
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - Copyright (C) 2001 Internet Software Consortium.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson - Permission to use, copy, modify, and distribute this software for any
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson - copyright notice and this permission notice appear in all copies.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
ea2a4bbc5db66edbba7966f7f0b535259ee1a6a9Mark Andrews<!-- $Id: nsupdate.docbook,v 1.5 2001/07/02 06:09:28 marka Exp $ -->
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson</refentryinfo>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson<refpurpose>Dynamic DNS update utility</refpurpose>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson<refsynopsisdiv>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson <arg><option>-y <replaceable class="parameter">keyname:secret</replaceable></option></arg>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson <arg><option>-k <replaceable class="parameter">keyfile</replaceable></option></arg>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson</refsynopsisdiv>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonis used to submit Dynamic DNS Update requests as defined in RFC2136
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonto a name server.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThis allows resource records to be added or removed from a zone
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonwithout manually editing the zone file.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonA single update request can contain requests to add or remove more than one
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonresource record.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonZones that are under dynamic control via
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonor a DHCP server should not be edited by hand.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonManual edits could
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonconflict with dynamic updates and cause data to be lost.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThe resource records that are dynamically added or removed with
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonhave to be in the same zone.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonRequests are sent to the zone's master server.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThis is identified by the MNAME field of the zone's SOA record.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonoperate in debug mode.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThis provides tracing information about the update requests that are
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonmade and the replies received from the name server.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonTransaction signatures can be used to authenticate the Dynamic DNS
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThese use the TSIG resource record type described in RFC2845.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThe signatures rely on a shared secret that should only be known to
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonand the name server.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonCurrently, the only supported encryption algorithm for TSIG is
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonHMAC-MD5, which is defined in RFC 2104.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonOnce other algorithms are defined for TSIG, applications will need to
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonensure they select the appropriate algorithm as well as the key when
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonauthenticating each other.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonFor instance suitable
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonstatements would be added to
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonso that the name server can associate the appropriate secret key
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonand algorithm with the IP address of the
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonclient application that will be using TSIG authentication.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonoption to provide the shared secret needed to generate a TSIG record
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonfor authenticating Dynamic DNS update requests.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThese options are mutually exclusive.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonreads the shared secret from the file
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonwhose name is of the form
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson<filename>K{name}.+157.+{random}.private</filename>.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonreasons, the file
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson<filename>K{name}.+157.+{random}.key</filename>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonmust also be present. When the
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonoption is used, a signature is generated from
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonis the name of the key,
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonis the base64 encoded shared secret.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonoption is discouraged because the shared secret is supplied as a command
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonline argument in clear text.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThis may be visible in the output from
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson<refentrytitle>ps</refentrytitle><manvolnum>1
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson</citerefentry>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonor in a history file maintained by the user's shell.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonuses UDP to send update requests to the name server.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonuse a TCP connection.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThis may be preferable when a batch of update requests is made.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonreads input from
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonor standard input.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonEach command is supplied on exactly one line of input.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonSome commands are for administrative purposes.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThe others are either update instructions or prerequisite checks on the
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssoncontents of the zone.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThese checks set conditions that some name or set of
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonresource records (RRset) either exists or is absent from the zone.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThese conditions must be met if the entire update request is to succeed.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonUpdates will be rejected if the tests for the prerequisite conditions fail.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonEvery update request consists of zero or more prerequisites
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonand zero or more updates.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThis allows a suitably authenticated update request to proceed if some
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonspecified resource records are present or missing from the zone.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonA blank input line causes the accumulated commands to be sent as one Dynamic
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonDNS update request to the name server.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThe command formats and their meaning are as follows:
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonSends all dynamic update requests to the name server
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonWhen no server statement is provided,
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonwill send updates to the master server of the correct zone.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThe MNAME field of that zone's SOA record will identify the master
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonserver for that zone.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonis the port number on
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonwhere the dynamic update requests get sent.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonIf no port number is specified, the default DNS port number of 53 is
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonSends all dynamic update requests using the local
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonWhen no local statement is provided,
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonwill send updates using an address and port choosen by the system.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssoncan additionally be used to make requests come from a specific port.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonIf no port number is specified, the system will assign one.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonSpecifies that all updates are to be made to the zone
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonstatement is provided,
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonwill attempt determine the correct zone to update based on the rest of the input.
ea2a4bbc5db66edbba7966f7f0b535259ee1a6a9Mark Andrews<cmdsynopsis>
ea2a4bbc5db66edbba7966f7f0b535259ee1a6a9Mark Andrews</cmdsynopsis>
ea2a4bbc5db66edbba7966f7f0b535259ee1a6a9Mark AndrewsSpecifies that all updates are to be TSIG signed using the
ea2a4bbc5db66edbba7966f7f0b535259ee1a6a9Mark Andrews<parameter>keyname</parameter> <parameter>keysecret</parameter> pair.
ea2a4bbc5db66edbba7966f7f0b535259ee1a6a9Mark Andrews<command>Key</command> overrides any key specified on the command line via
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonRequires that no resource record of any type exists with name
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonexists (has as at least one resource record, of any type).
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonRequires that no resource record exists of the specified
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonis omitted, IN (internet) is assumed.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThis requires that a resource record of the specified
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonis omitted, IN (internet) is assumed.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonfrom each set of prerequisites of this form
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonsharing a common
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonare combined to form a set of RRs. This set of RRs must
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonexactly match the set of RRs existing in the zone at the
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonare written in the standard text representation of the resource record's
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson<arg choice="opt">type <arg choice="opt" rep="repeat">data</arg></arg>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonDeletes any resource records named
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonis provided, only matching resource records will be removed.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThe internet class is assumed if
edac761923fac89405f7d1e4244a11d88a89f413Brian Wellingtonis not supplied. The
edac761923fac89405f7d1e4244a11d88a89f413Brian Wellingtonis ignored, and is only allowed for compatibility.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonAdds a new resource record with the specified
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson</variablelist>
edac761923fac89405f7d1e4244a11d88a89f413Brian WellingtonLines beginning with a semicolon are comments, and are ignored.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThe examples below show how
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssoncould be used to insert and delete resource records from the
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonNotice that the input in each example contains a trailing blank line so that
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssona group of commands are sent as one dynamic update request to the
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonmaster name server for
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson<programlisting>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson> update add newhost.example.com 86400 A 172.16.1.1
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson</programlisting>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonAny A records for
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonand an A record for
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonit IP address 172.16.1.1 is added.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThe newly-added record has a 1 day TTL (86400 seconds)
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson<programlisting>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson> update add nickname.example.com CNAME somehost.example.com
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson</programlisting>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThe prerequisite condition gets the name server to check that there
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonare no resource records of any type for
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonIf there are, the update request fails.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonIf this name does not exist, a CNAME for it is added.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThis ensures that when the CNAME is added, it cannot conflict with the
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonlong-standing rule in RFC1034 that a name must not exist as any other
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonrecord type if it exists as a CNAME.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson(The rule has been updated for DNSSEC in RFC2535 to allow CNAMEs to have
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonSIG, KEY and NXT records.)
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson<varlistentry><term><constant>/etc/resolv.conf</constant></term>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonused to identify default name server
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson<varlistentry><term><constant>K{name}.+157.+{random}.key</constant></term>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonbase-64 encoding of HMAC-MD5 key created by
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson<refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson</citerefentry>.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson<varlistentry><term><constant>K{name}.+157.+{random}.private</constant></term>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonbase-64 encoding of HMAC-MD5 key created by
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson<refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson</citerefentry>.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson</variablelist>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson</citerefentry>,
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson</citerefentry>,
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson</citerefentry>,
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson</citerefentry>,
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson</citerefentry>,
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson</citerefentry>,
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson<refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson</citerefentry>,
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson<refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson</citerefentry>.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThe TSIG key is redundantly stored in two separate files.
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas GustafssonThis is a consequence of nsupdate using the DST library
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafssonfor its cryptographic operations, and may change in future