1N/A<!
DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 1N/A [<!ENTITY mdash "—">]>
1N/A - Copyright (C) 2004-2009 Internet Systems Consortium, Inc. ("ISC") 1N/A - Copyright (C) 2000-2003 Internet Software Consortium. 1N/A - Permission to use, copy, modify, and/or distribute this software for any 1N/A - purpose with or without fee is hereby granted, provided that the above 1N/A - copyright notice and this permission notice appear in all copies. 1N/A - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 1N/A - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 1N/A - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 1N/A - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 1N/A - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 1N/A - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 1N/A - PERFORMANCE OF THIS SOFTWARE. 2N/A <
date>Jun 30, 2000</
date>
1N/A <
refentrytitle><
application>nsupdate</
application></
refentrytitle>
1N/A <
manvolnum>1</
manvolnum>
1N/A <
refmiscinfo>BIND9</
refmiscinfo>
1N/A <
refname><
application>nsupdate</
application></
refname>
1N/A <
refpurpose>Dynamic DNS update utility</
refpurpose>
1N/A <
holder>Internet Systems Consortium, Inc. ("ISC")</
holder>
1N/A <
holder>Internet Software Consortium.</
holder>
1N/A <
command>nsupdate</
command>
1N/A <
arg><
option>-d</
option></
arg>
1N/A <
arg><
option>-D</
option></
arg>
1N/A <
arg><
option>-g</
option></
arg>
1N/A <
arg><
option>-o</
option></
arg>
1N/A <
arg><
option>-y <
replaceable class="parameter"><
optional>hmac:</
optional>keyname:secret</
replaceable></
option></
arg>
1N/A <
arg><
option>-k <
replaceable class="parameter">keyfile</
replaceable></
option></
arg>
1N/A <
arg><
option>-t <
replaceable class="parameter">timeout</
replaceable></
option></
arg>
1N/A <
arg><
option>-u <
replaceable class="parameter">udptimeout</
replaceable></
option></
arg>
1N/A <
arg><
option>-r <
replaceable class="parameter">udpretries</
replaceable></
option></
arg>
1N/A <
arg><
option>-R <
replaceable class="parameter">randomdev</
replaceable></
option></
arg>
1N/A <
arg><
option>-v</
option></
arg>
1N/A <
title>DESCRIPTION</
title>
1N/A <
para><
command>nsupdate</
command>
1N/A is used to submit Dynamic DNS Update requests as defined in RFC2136
1N/A This allows resource records to be added or removed from a zone
1N/A without manually editing the zone file.
1N/A A single update request can contain requests to add or remove more than
1N/A Zones that are under dynamic control via
1N/A <
command>nsupdate</
command>
1N/A or a DHCP server should not be edited by hand.
1N/A conflict with dynamic updates and cause data to be lost.
1N/A The resource records that are dynamically added or removed with
1N/A <
command>nsupdate</
command>
1N/A have to be in the same zone.
1N/A Requests are sent to the zone's master server.
1N/A This is identified by the MNAME field of the zone's SOA record.
1N/A <
command>nsupdate</
command>
1N/A operate in debug mode.
1N/A This provides tracing information about the update requests that are
1N/A made and the replies received from the name server.
1N/A The <
option>-D</
option> option makes <
command>nsupdate</
command>
1N/A report additional debugging information to <
option>-d</
option>.
1N/A The <
option>-L</
option> option with an integer argument of zero or
1N/A higher sets the logging debug level. If zero, logging is disabled.
1N/A Transaction signatures can be used to authenticate the Dynamic
1N/A DNS updates. These use the TSIG resource record type described
1N/A in RFC2845 or the SIG(0) record described in RFC3535 and
1N/A RFC2931 or GSS-TSIG as described in RFC3645. TSIG relies on
1N/A a shared secret that should only be known to
1N/A <
command>nsupdate</
command> and the name server. Currently,
1N/A the only supported encryption algorithm for TSIG is HMAC-MD5,
1N/A which is defined in RFC 2104. Once other algorithms are
1N/A defined for TSIG, applications will need to ensure they select
1N/A the appropriate algorithm as well as the key when authenticating
1N/A each other. For instance, suitable <
type>key</
type> and
2N/A <
type>server</
type> statements would be added to
1N/A can associate the appropriate secret key and algorithm with
1N/A the IP address of the client application that will be using
1N/A TSIG authentication. SIG(0) uses public key cryptography.
1N/A To use a SIG(0) key, the public key must be stored in a KEY
1N/A record in a zone served by the name server.
1N/A <
command>nsupdate</
command> does not read
1N/A GSS-TSIG uses Kerberos credentials.
1N/A <
para><
command>nsupdate</
command>
1N/A uses the <
option>-y</
option> or <
option>-k</
option> option
1N/A to provide the shared secret needed to generate a TSIG record
1N/A for authenticating Dynamic DNS update requests, default type
1N/A HMAC-MD5. These options are mutually exclusive.
1N/A When the <
option>-y</
option> option is used, a signature is
1N/A <
optional><
parameter>hmac:</
parameter></
optional><
parameter>keyname:secret.</
parameter>
1N/A <
parameter>keyname</
parameter> is the name of the key, and
1N/A <
parameter>secret</
parameter> is the base64 encoded shared secret.
1N/A Use of the <
option>-y</
option> option is discouraged because the
1N/A shared secret is supplied as a command line argument in clear text.
1N/A This may be visible in the output from
1N/A <
refentrytitle>ps</
refentrytitle><
manvolnum>1</
manvolnum>
1N/A or in a history file maintained by the user's shell.
1N/A <
option>-k</
option> option, <
command>nsupdate</
command> reads
1N/A the shared secret from the file <
parameter>keyfile</
parameter>.
1N/A Keyfiles may be in two formats: a single file containing
1N/A statement, which may be generated automatically by
1N/A <
command>ddns-confgen</
command>, or a pair of files whose names are
1N/A of the format <
filename>K{name}.+157.+{random}.key</
filename> and
1N/A <
filename>K{name}.+157.+{random}.private</
filename>, which can be
1N/A generated by <
command>dnssec-keygen</
command>.
1N/A The <
option>-k</
option> may also be used to specify a SIG(0) key used
1N/A to authenticate Dynamic DNS update requests. In this case, the key
1N/A specified is not an HMAC-MD5 key.
1N/A <
command>nsupdate</
command> can be run in a local-host only mode
1N/A using the <
option>-l</
option> flag. This sets the server address to
1N/A localhost (disabling the <
command>server</
command> so that the server
1N/A address cannot be overridden). Connections to the local server will
1N/A which is automatically generated by <
command>named</
command> if any
1N/A local master zone has set <
command>update-policy</
command> to
1N/A <
command>local</
command>. The location of this key file can be
1N/A overridden with the <
option>-k</
option> option.
1N/A By default, <
command>nsupdate</
command>
1N/A uses UDP to send update requests to the name server unless they are too
1N/A large to fit in a UDP request in which case TCP will be used.
1N/A <
command>nsupdate</
command>
1N/A use a TCP connection.
1N/A This may be preferable when a batch of update requests is made.
1N/A The <
option>-p</
option> sets the default port number to use for
1N/A connections to a name server. The default is 53.
1N/A The <
option>-t</
option> option sets the maximum time an update request
1N/A take before it is aborted. The default is 300 seconds. Zero can be
1N/A to disable the timeout.
1N/A The <
option>-u</
option> option sets the UDP retry interval. The default
1N/A 3 seconds. If zero, the interval will be computed from the timeout
1N/A and number of UDP retries.
1N/A The <
option>-r</
option> option sets the number of UDP retries. The
1N/A 3. If zero, only one update request will be made.
1N/A The <
option>-R <
replaceable 1N/A class="parameter">randomdev</
replaceable></
option> option
1N/A specifies a source of randomness. If the operating system
1N/A equivalent device, the default source of randomness is keyboard
1N/A input. <
filename>randomdev</
filename> specifies the name of
1N/A a character device or file containing random data to be used
1N/A instead of the default. The special value
1N/A <
filename>keyboard</
filename> indicates that keyboard input
1N/A should be used. This option may be specified multiple times.
1N/A <
title>INPUT FORMAT</
title>
1N/A <
para><
command>nsupdate</
command>
1N/A <
parameter>filename</
parameter>
1N/A Each command is supplied on exactly one line of input.
1N/A Some commands are for administrative purposes.
1N/A The others are either update instructions or prerequisite checks on the
1N/A contents of the zone.
1N/A These checks set conditions that some name or set of
1N/A resource records (RRset) either exists or is absent from the zone.
1N/A These conditions must be met if the entire update request is to succeed.
1N/A Updates will be rejected if the tests for the prerequisite conditions
1N/A Every update request consists of zero or more prerequisites
1N/A and zero or more updates.
1N/A This allows a suitably authenticated update request to proceed if some
1N/A specified resource records are present or missing from the zone.
1N/A A blank input line (or the <
command>send</
command> command)
1N/A accumulated commands to be sent as one Dynamic DNS update request to the
1N/A The command formats and their meaning are as follows:
1N/A <
command>server</
command>
1N/A <
arg choice="req">servername</
arg>
1N/A <
arg choice="opt">port</
arg>
1N/A Sends all dynamic update requests to the name server
1N/A <
parameter>servername</
parameter>.
1N/A When no server statement is provided,
1N/A <
command>nsupdate</
command>
1N/A will send updates to the master server of the correct zone.
1N/A The MNAME field of that zone's SOA record will identify the
1N/A server for that zone.
1N/A <
parameter>port</
parameter>
1N/A is the port number on
1N/A <
parameter>servername</
parameter>
1N/A where the dynamic update requests get sent.
1N/A If no port number is specified, the default DNS port number of
1N/A <
command>local</
command>
1N/A <
arg choice="req">address</
arg>
1N/A <
arg choice="opt">port</
arg>
1N/A Sends all dynamic update requests using the local
1N/A <
parameter>address</
parameter>.
1N/A When no local statement is provided,
1N/A <
command>nsupdate</
command>
1N/A will send updates using an address and port chosen by the
1N/A <
parameter>port</
parameter>
1N/A can additionally be used to make requests come from a specific
1N/A If no port number is specified, the system will assign one.
1N/A <
command>zone</
command>
1N/A <
arg choice="req">zonename</
arg>
1N/A Specifies that all updates are to be made to the zone
1N/A <
parameter>zonename</
parameter>.
1N/A <
parameter>zone</
parameter>
1N/A statement is provided,
1N/A <
command>nsupdate</
command>
1N/A will attempt determine the correct zone to update based on the
1N/A <
command>class</
command>
1N/A <
arg choice="req">classname</
arg>
1N/A Specify the default class.
1N/A If no <
parameter>class</
parameter> is specified, the
1N/A <
parameter>IN</
parameter>.
1N/A <
command>ttl</
command>
1N/A <
arg choice="req">seconds</
arg>
1N/A Specify the default time to live for records to be added.
1N/A The value <
parameter>none</
parameter> will clear the default
1N/A <
command>key</
command>
1N/A <
arg choice="req">name</
arg>
1N/A <
arg choice="req">secret</
arg>
1N/A Specifies that all updates are to be TSIG-signed using the
1N/A <
parameter>keyname</
parameter> <
parameter>keysecret</
parameter> pair.
1N/A The <
command>key</
command> command
1N/A overrides any key specified on the command line via
1N/A <
option>-y</
option> or <
option>-k</
option>.
1N/A <
command>prereq nxdomain</
command>
1N/A <
arg choice="req">domain-name</
arg>
1N/A Requires that no resource record of any type exists with name
1N/A <
parameter>domain-name</
parameter>.
1N/A <
command>prereq yxdomain</
command>
1N/A <
arg choice="req">domain-name</
arg>
1N/A <
parameter>domain-name</
parameter>
1N/A exists (has as at least one resource record, of any type).
1N/A <
command>prereq nxrrset</
command>
1N/A <
arg choice="req">domain-name</
arg>
1N/A <
arg choice="opt">class</
arg>
1N/A <
arg choice="req">type</
arg>
1N/A Requires that no resource record exists of the specified
1N/A <
parameter>type</
parameter>,
1N/A <
parameter>class</
parameter>
1N/A <
parameter>domain-name</
parameter>.
1N/A <
parameter>class</
parameter>
1N/A is omitted, IN (internet) is assumed.
1N/A <
command>prereq yxrrset</
command>
1N/A <
arg choice="req">domain-name</
arg>
1N/A <
arg choice="opt">class</
arg>
1N/A <
arg choice="req">type</
arg>
1N/A This requires that a resource record of the specified
1N/A <
parameter>type</
parameter>,
1N/A <
parameter>class</
parameter>
1N/A <
parameter>domain-name</
parameter>
1N/A <
parameter>class</
parameter>
1N/A is omitted, IN (internet) is assumed.
1N/A <
command>prereq yxrrset</
command>
1N/A <
arg choice="req">domain-name</
arg>
1N/A <
arg choice="opt">class</
arg>
1N/A <
arg choice="req">type</
arg>
1N/A <
arg choice="req" rep="repeat">data</
arg>
1N/A <
parameter>data</
parameter>
1N/A from each set of prerequisites of this form
1N/A <
parameter>type</
parameter>,
1N/A <
parameter>class</
parameter>,
1N/A <
parameter>domain-name</
parameter>
1N/A are combined to form a set of RRs. This set of RRs must
1N/A exactly match the set of RRs existing in the zone at the
1N/A <
parameter>type</
parameter>,
1N/A <
parameter>class</
parameter>,
1N/A <
parameter>domain-name</
parameter>.
1N/A <
parameter>data</
parameter>
1N/A are written in the standard text representation of the resource
1N/A <
command>update delete</
command>
1N/A <
arg choice="req">domain-name</
arg>
1N/A <
arg choice="opt">ttl</
arg>
1N/A <
arg choice="opt">class</
arg>
1N/A <
arg choice="opt">type <
arg choice="opt" rep="repeat">data</
arg></
arg>
1N/A Deletes any resource records named
1N/A <
parameter>domain-name</
parameter>.
1N/A <
parameter>type</
parameter>
1N/A <
parameter>data</
parameter>
1N/A is provided, only matching resource records will be removed.
1N/A The internet class is assumed if
1N/A <
parameter>class</
parameter>
1N/A is not supplied. The
1N/A <
parameter>ttl</
parameter>
1N/A is ignored, and is only allowed for compatibility.
1N/A <
command>update add</
command>
1N/A <
arg choice="req">domain-name</
arg>
1N/A <
arg choice="req">ttl</
arg>
1N/A <
arg choice="opt">class</
arg>
1N/A <
arg choice="req">type</
arg>
1N/A <
arg choice="req" rep="repeat">data</
arg>
1N/A Adds a new resource record with the specified
1N/A <
parameter>ttl</
parameter>,
1N/A <
parameter>class</
parameter>
1N/A <
parameter>data</
parameter>.
1N/A <
command>show</
command>
1N/A Displays the current message, containing all of the
1N/A updates specified since the last send.
1N/A <
command>send</
command>
1N/A Sends the current message. This is equivalent to entering a
1N/A <
command>answer</
command>
1N/A Displays the answer.
1N/A <
command>debug</
command>
1N/A Lines beginning with a semicolon are comments and are ignored.
1N/A <
title>EXAMPLES</
title>
1N/A The examples below show how
1N/A <
command>nsupdate</
command>
1N/A could be used to insert and delete resource records from the
1N/A Notice that the input in each example contains a trailing blank line so
1N/A a group of commands are sent as one dynamic update request to the
1N/A master name server for
1N/A with IP address 172.16.1.1 is added.
1N/A The newly-added record has a 1 day TTL (86400 seconds).
1N/A The prerequisite condition gets the name server to check that there
1N/A are no resource records of any type for
1N/A If there are, the update request fails.
1N/A If this name does not exist, a CNAME for it is added.
1N/A This ensures that when the CNAME is added, it cannot conflict with the
1N/A long-standing rule in RFC1034 that a name must not exist as any other
1N/A record type if it exists as a CNAME.
1N/A (The rule has been updated for DNSSEC in RFC2535 to allow CNAMEs to have
1N/A RRSIG, DNSKEY and NSEC records.)
1N/A <
title>FILES</
title>
1N/A used to identify default name server
1N/A sets the default TSIG key for use in local-only mode
1N/A <
term><
constant>K{name}.+157.+{random}.key</
constant></
term>
1N/A base-64 encoding of HMAC-MD5 key created by
1N/A <
refentrytitle>dnssec-keygen</
refentrytitle><
manvolnum>8</
manvolnum>
1N/A <
term><
constant>K{name}.+157.+{random}.private</
constant></
term>
1N/A base-64 encoding of HMAC-MD5 key created by
1N/A <
refentrytitle>dnssec-keygen</
refentrytitle><
manvolnum>8</
manvolnum>
1N/A <
title>SEE ALSO</
title>
1N/A <
para><
citerefentry>
1N/A <
refentrytitle>RFC2136</
refentrytitle>
1N/A <
refentrytitle>RFC3007</
refentrytitle>
1N/A <
refentrytitle>RFC2104</
refentrytitle>
1N/A <
refentrytitle>RFC2845</
refentrytitle>
1N/A <
refentrytitle>RFC1034</
refentrytitle>
1N/A <
refentrytitle>RFC2535</
refentrytitle>
1N/A <
refentrytitle>RFC2931</
refentrytitle>
1N/A <
refentrytitle>named</
refentrytitle><
manvolnum>8</
manvolnum>
1N/A <
refentrytitle>ddns-confgen</
refentrytitle><
manvolnum>8</
manvolnum>
1N/A <
refentrytitle>dnssec-keygen</
refentrytitle><
manvolnum>8</
manvolnum>
1N/A The TSIG key is redundantly stored in two separate files.
1N/A This is a consequence of nsupdate using the DST library
1N/A for its cryptographic operations, and may change in future