10139N/A<!
DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 18593N/A - Copyright (C) 2004-2012, 2014, 2015 Internet Systems Consortium, Inc. ("ISC") 18632N/A - Copyright (C) 2000-2003 Internet Software Consortium. 13600N/A - Permission to use, copy, modify, and/or distribute this software for any 10139N/A - purpose with or without fee is hereby granted, provided that the above 10139N/A - copyright notice and this permission notice appear in all copies. 10139N/A - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10139N/A - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 10139N/A - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 10139N/A - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 19825N/A - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 19825N/A - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 10139N/A - PERFORMANCE OF THIS SOFTWARE. 10139N/A <
refentrytitle><
application>nsupdate</
application></
refentrytitle>
17811N/A <
refmiscinfo>BIND9</
refmiscinfo>
15761N/A <
refname><
application>nsupdate</
application></
refname>
16554N/A <
refpurpose>Dynamic DNS update utility</
refpurpose>
10139N/A <
holder>Internet Systems Consortium, Inc. ("ISC")</
holder>
12830N/A <
holder>Internet Software Consortium.</
holder>
16597N/A <
arg><
option>-L <
replaceable class="parameter">level</
replaceable></
option></
arg>
19825N/A <
arg><
option>-y <
replaceable class="parameter"><
optional>hmac:</
optional>keyname:secret</
replaceable></
option></
arg>
17811N/A <
arg><
option>-k <
replaceable class="parameter">keyfile</
replaceable></
option></
arg>
16554N/A <
arg><
option>-t <
replaceable class="parameter">timeout</
replaceable></
option></
arg>
16554N/A <
arg><
option>-u <
replaceable class="parameter">udptimeout</
replaceable></
option></
arg>
17811N/A <
arg><
option>-r <
replaceable class="parameter">udpretries</
replaceable></
option></
arg>
16554N/A <
arg><
option>-R <
replaceable class="parameter">randomdev</
replaceable></
option></
arg>
17811N/A <
para><
command>nsupdate</
command>
17338N/A is used to submit Dynamic DNS Update requests as defined in RFC 2136
17811N/A This allows resource records to be added or removed from a zone
15529N/A without manually editing the zone file.
17811N/A A single update request can contain requests to add or remove more than
17811N/A Zones that are under dynamic control via
16020N/A or a DHCP server should not be edited by hand.
17811N/A conflict with dynamic updates and cause data to be lost.
17811N/A The resource records that are dynamically added or removed with
19825N/A Requests are sent to the zone's master server.
17811N/A This is identified by the MNAME field of the zone's SOA record.
19825N/A Transaction signatures can be used to authenticate the Dynamic
17811N/A DNS updates. These use the TSIG resource record type described
17811N/A in RFC 2845 or the SIG(0) record described in RFC 2535 and
17964N/A RFC 2931 or GSS-TSIG as described in RFC 3645.
18036N/A a shared secret that should only be known to
18036N/A <
command>nsupdate</
command> and the name server.
18036N/A For instance, suitable <
type>key</
type> and
18190N/A <
type>server</
type> statements would be added to
18190N/A can associate the appropriate secret key and algorithm with
18251N/A the IP address of the client application that will be using
18251N/A TSIG authentication. You can use <
command>ddns-confgen</
command>
18251N/A to generate suitable configuration fragments.
18384N/A uses the <
option>-y</
option> or <
option>-k</
option> options
18384N/A to provide the TSIG shared secret. These options are mutually exclusive.
18384N/A SIG(0) uses public key cryptography.
18384N/A To use a SIG(0) key, the public key must be stored in a KEY
18384N/A record in a zone served by the name server.
18384N/A GSS-TSIG uses Kerberos credentials. Standard GSS-TSIG mode
18384N/A is switched on with the <
option>-g</
option> flag. A
18384N/A non-standards-compliant variant of GSS-TSIG used by Windows
18384N/A 2000 can be switched on with the <
option>-o</
option> flag.
15536N/A Debug mode. This provides tracing information about the
10139N/A update requests that are made and the replies received
13898N/A <
term>-k <
replaceable class="parameter">keyfile</
replaceable></
term>
10139N/A The file containing the TSIG authentication key.
10139N/A Keyfiles may be in two formats: a single file containing
10139N/A statement, which may be generated automatically by
10139N/A <
command>ddns-confgen</
command>, or a pair of files whose names are
10139N/A of the format <
filename>K{name}.+157.+{random}.key</
filename> and
10139N/A <
filename>K{name}.+157.+{random}.private</
filename>, which can be
10139N/A generated by <
command>dnssec-keygen</
command>.
10139N/A The <
option>-k</
option> may also be used to specify a SIG(0) key used
10139N/A to authenticate Dynamic DNS update requests. In this case, the key
10139N/A specified is not an HMAC-MD5 key.
10139N/A Local-host only mode. This sets the server address to
15536N/A localhost (disabling the <
command>server</
command> so that the server
15536N/A address cannot be overridden). Connections to the local server will
15536N/A which is automatically generated by <
command>named</
command> if any
17811N/A local master zone has set <
command>update-policy</
command> to
17811N/A <
command>local</
command>. The location of this key file can be
10139N/A overridden with the <
option>-k</
option> option.
18036N/A <
term>-L <
replaceable class="parameter">level</
replaceable></
term>
18384N/A Set the logging debug level. If zero, logging is disabled.
16050N/A <
term>-p <
replaceable class="parameter">port</
replaceable></
term>
16020N/A Set the port to use for connections to a name server. The
10139N/A Print the list of private BIND-specific resource record
17811N/A types whose format is understood
10139N/A by <
command>nsupdate</
command>. See also
10139N/A the <
option>-T</
option> option.
10139N/A <
term>-r <
replaceable class="parameter">udpretries</
replaceable></
term>
10139N/A The number of UDP retries. The default is 3. If zero, only
10139N/A one update request will be made.
19111N/A <
term>-R <
replaceable class="parameter">randomdev</
replaceable></
term>
19111N/A Where to obtain randomness. If the operating system
10139N/A equivalent device, the default source of randomness is keyboard
13898N/A input. <
filename>randomdev</
filename> specifies the name of
18918N/A a character device or file containing random data to be used
13898N/A instead of the default. The special value
13898N/A <
filename>keyboard</
filename> indicates that keyboard input
17965N/A should be used. This option may be specified multiple times.
16554N/A <
term>-t <
replaceable class="parameter">timeout</
replaceable></
term>
17964N/A The maximum time an update request can take before it is
10139N/A aborted. The default is 300 seconds. Zero can be used to
13898N/A Print the list of IANA standard resource record types
13898N/A whose format is understood by <
command>nsupdate</
command>.
13898N/A <
command>nsupdate</
command> will exit after the lists are
10139N/A printed. The <
option>-T</
option> option can be combined
16554N/A with the <
option>-P</
option> option.
16554N/A Other types can be entered using "TYPEXXXXX" where "XXXXX" is the
16554N/A decimal value of the type with no leading zeros. The rdata,
16554N/A if present, will be parsed using the UNKNOWN rdata format,
16554N/A (<backslash> <hash> <space> <length>
18384N/A <space> <hexstring>).
18384N/A <
term>-u <
replaceable class="parameter">udptimeout</
replaceable></
term>
14124N/A The UDP retry interval. The default is 3 seconds. If zero,
13898N/A the interval will be computed from the timeout interval and
13898N/A Use TCP even for small update requests.
13898N/A By default, <
command>nsupdate</
command>
13898N/A uses UDP to send update requests to the name server unless they are too
13898N/A large to fit in a UDP request in which case TCP will be used.
13898N/A TCP may be preferable when a batch of update requests is made.
13898N/A Print the version number and exit.
13898N/A <
term>-y <
replaceable class="parameter"><
optional>hmac:</
optional>keyname:secret</
replaceable></
term>
13898N/A Literal TSIG authentication key.
13898N/A <
parameter>keyname</
parameter> is the name of the key, and
10139N/A <
parameter>secret</
parameter> is the base64 encoded shared secret.
10139N/A <
parameter>hmac</
parameter> is the name of the key algorithm;
10139N/A valid choices are <
literal>hmac-md5</
literal>,
10139N/A <
literal>hmac-sha1</
literal>, <
literal>hmac-sha224</
literal>,
10139N/A <
literal>hmac-sha256</
literal>, <
literal>hmac-sha384</
literal>, or
10139N/A <
literal>hmac-sha512</
literal>. If <
parameter>hmac</
parameter>
10139N/A is not specified, the default is <
literal>hmac-md5</
literal>.
15536N/A NOTE: Use of the <
option>-y</
option> option is discouraged because the
13898N/A shared secret is supplied as a command line argument in clear text.
10139N/A This may be visible in the output from
13898N/A <
refentrytitle>ps</
refentrytitle><
manvolnum>1</
manvolnum>
13898N/A or in a history file maintained by the user's shell.
16617N/A <
para><
command>nsupdate</
command>
16617N/A <
parameter>filename</
parameter>
16617N/A Each command is supplied on exactly one line of input.
16617N/A Some commands are for administrative purposes.
16617N/A The others are either update instructions or prerequisite checks on the
17811N/A These checks set conditions that some name or set of
14376N/A resource records (RRset) either exists or is absent from the zone.
13898N/A These conditions must be met if the entire update request is to succeed.
13898N/A Updates will be rejected if the tests for the prerequisite conditions
15536N/A Every update request consists of zero or more prerequisites
17811N/A This allows a suitably authenticated update request to proceed if some
14376N/A specified resource records are present or missing from the zone.
13898N/A A blank input line (or the <
command>send</
command> command)
13898N/A accumulated commands to be sent as one Dynamic DNS update request to the
15536N/A The command formats and their meaning are as follows:
16617N/A <
arg choice="req">servername</
arg>
16617N/A Sends all dynamic update requests to the name server
17811N/A <
parameter>servername</
parameter>.
14376N/A When no server statement is provided,
13898N/A will send updates to the master server of the correct zone.
16958N/A The MNAME field of that zone's SOA record will identify the
10550N/A <
parameter>servername</
parameter>
15536N/A where the dynamic update requests get sent.
10550N/A If no port number is specified, the default DNS port number of
19825N/A <
arg choice="req">address</
arg>
19041N/A Sends all dynamic update requests using the local
19041N/A <
parameter>address</
parameter>.
18955N/A When no local statement is provided,
18936N/A will send updates using an address and port chosen by the
18384N/A can additionally be used to make requests come from a specific
18270N/A If no port number is specified, the system will assign one.
18149N/A <
arg choice="req">zonename</
arg>
18036N/A Specifies that all updates are to be made to the zone
17964N/A <
parameter>zonename</
parameter>.
17964N/A will attempt determine the correct zone to update based on the
17450N/A <
arg choice="req">classname</
arg>
17338N/A If no <
parameter>class</
parameter> is specified, the
16952N/A <
arg choice="req">seconds</
arg>
16801N/A Specify the default time to live for records to be added.
16801N/A The value <
parameter>none</
parameter> will clear the default
16758N/A <
arg choice="opt">hmac:</
arg><
arg choice="req">keyname</
arg>
16702N/A Specifies that all updates are to be TSIG-signed using the
16702N/A <
parameter>keyname</
parameter> <
parameter>secret</
parameter> pair.
16689N/A If <
parameter>hmac</
parameter> is specified, then it sets the
16689N/A signing algorithm in use; the default is
16680N/A <
literal>hmac-md5</
literal>. The <
command>key</
command>
16680N/A command overrides any key specified on the command line via
16656N/A <
option>-y</
option> or <
option>-k</
option>.
16608N/A Use GSS-TSIG to sign the updated. This is equivalent to
16601N/A specifying <
option>-g</
option> on the command line.
16437N/A Use the Windows 2000 version of GSS-TSIG to sign the updated.
16437N/A This is equivalent to specifying <
option>-o</
option> on the
16207N/A <
arg choice="req"><
optional>realm_name</
optional></
arg>
16050N/A When using GSS-TSIG use <
parameter>realm_name</
parameter> rather
16020N/A realm is specified the saved realm is cleared.
15747N/A <
arg choice="req"><
optional>yes_or_no</
optional></
arg>
15548N/A Turn on or off check-names processing on records to
15548N/A be added. Check-names has no effect on prerequisites
15548N/A or records to be deleted. By default check-names
15536N/A processing is on. If check-names processing fails
15536N/A the record will not be added to the UPDATE message.
15529N/A <
command><
optional>prereq</
optional> nxdomain</
command>
15525N/A <
arg choice="req">domain-name</
arg>
15529N/A Requires that no resource record of any type exists with name
15529N/A <
parameter>domain-name</
parameter>.
15516N/A <
command><
optional>prereq</
optional> yxdomain</
command>
15516N/A <
arg choice="req">domain-name</
arg>
15516N/A <
parameter>domain-name</
parameter>
15516N/A exists (has as at least one resource record, of any type).
15453N/A <
command><
optional>prereq</
optional> nxrrset</
command>
15453N/A <
arg choice="req">domain-name</
arg>
15216N/A Requires that no resource record exists of the specified
15191N/A <
parameter>domain-name</
parameter>.
15190N/A is omitted, IN (internet) is assumed.
14425N/A <
command><
optional>prereq</
optional> yxrrset</
command>
14425N/A <
arg choice="req">domain-name</
arg>
14376N/A This requires that a resource record of the specified
14124N/A <
parameter>domain-name</
parameter>
14033N/A is omitted, IN (internet) is assumed.
13914N/A <
command><
optional>prereq</
optional> yxrrset</
command>
13914N/A <
arg choice="req">domain-name</
arg>
13898N/A <
arg choice="req" rep="repeat">data</
arg>
13898N/A from each set of prerequisites of this form
13898N/A <
parameter>domain-name</
parameter>
13898N/A are combined to form a set of RRs. This set of RRs must
13898N/A exactly match the set of RRs existing in the zone at the
13898N/A <
parameter>domain-name</
parameter>.
13898N/A are written in the standard text representation of the resource
13898N/A <
command><
optional>update</
optional> del<
optional>ete</
optional></
command>
13898N/A <
arg choice="req">domain-name</
arg>
13268N/A <
arg choice="opt">type <
arg choice="opt" rep="repeat">data</
arg></
arg>
13898N/A Deletes any resource records named
13898N/A <
parameter>domain-name</
parameter>.
12830N/A is provided, only matching resource records will be removed.
13898N/A The internet class is assumed if
13898N/A is ignored, and is only allowed for compatibility.
12169N/A <
command><
optional>update</
optional> add</
command>
13898N/A <
arg choice="req">domain-name</
arg>
12102N/A <
arg choice="req" rep="repeat">data</
arg>
12018N/A Adds a new resource record with the specified
11425N/A Displays the current message, containing all of the
11314N/A updates specified since the last send.
10711N/A Sends the current message. This is equivalent to entering a
10139N/A Lines beginning with a semicolon are comments and are ignored.
10139N/A could be used to insert and delete resource records from the
10139N/A Notice that the input in each example contains a trailing blank line so
10139N/A a group of commands are sent as one dynamic update request to the
10139N/A with IP address 172.16.1.1 is added.
10139N/A The newly-added record has a 1 day TTL (86400 seconds).
10139N/A The prerequisite condition gets the name server to check that there
10139N/A are no resource records of any type for
10139N/A If there are, the update request fails.
10139N/A If this name does not exist, a CNAME for it is added.
10139N/A This ensures that when the CNAME is added, it cannot conflict with the
10139N/A long-standing rule in RFC 1034 that a name must not exist as any other
10139N/A record type if it exists as a CNAME.
10139N/A (The rule has been updated for DNSSEC in RFC 2535 to allow CNAMEs to have
10139N/A RRSIG, DNSKEY and NSEC records.)
10139N/A used to identify default name server
10139N/A sets the default TSIG key for use in local-only mode
10139N/A <
term><
constant>K{name}.+157.+{random}.key</
constant></
term>
10139N/A base-64 encoding of HMAC-MD5 key created by
10139N/A <
refentrytitle>dnssec-keygen</
refentrytitle><
manvolnum>8</
manvolnum>
10139N/A <
term><
constant>K{name}.+157.+{random}.private</
constant></
term>
10139N/A base-64 encoding of HMAC-MD5 key created by
10139N/A <
refentrytitle>dnssec-keygen</
refentrytitle><
manvolnum>8</
manvolnum>
10139N/A <
citetitle>RFC 2136</
citetitle>,
10139N/A <
citetitle>RFC 3007</
citetitle>,
10139N/A <
citetitle>RFC 2104</
citetitle>,
10139N/A <
citetitle>RFC 2845</
citetitle>,
<
citetitle>RFC 1034</
citetitle>,
<
citetitle>RFC 2535</
citetitle>,
<
citetitle>RFC 2931</
citetitle>,
<
refentrytitle>named</
refentrytitle><
manvolnum>8</
manvolnum>
<
refentrytitle>ddns-confgen</
refentrytitle><
manvolnum>8</
manvolnum>
<
refentrytitle>dnssec-keygen</
refentrytitle><
manvolnum>8</
manvolnum>
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