1858N/A - Copyright (C) 2000-2016 Internet Systems Consortium, Inc. ("ISC") 1858N/A - This Source Code Form is subject to the terms of the Mozilla Public 1858N/A - License, v. 2.0. If a copy of the MPL was not distributed with this 1858N/A<
meta http-
equiv="Content-Type" content="text/html; charset=ISO-8859-1">
1858N/A<
meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
1858N/A<
body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
1858N/A<
table width="100%" summary="Navigation header">
1858N/A<
tr><
th colspan="3" align="center"><
span class="application">nsupdate</
span></
th></
tr>
5090N/A<
td width="20%" align="left">
1858N/A<
th width="60%" align="center">Manual pages</
th>
2601N/A <
span class="application">nsupdate</
span>
5536N/A — Dynamic DNS update utility
2601N/A <
div class="refsynopsisdiv">
2601N/A <
div class="cmdsynopsis"><
p>
2601N/A <
code class="command">nsupdate</
code>
2601N/A [<
code class="option">-d</
code>]
2601N/A [<
code class="option">-D</
code>]
1858N/A [<
code class="option">-L <
em class="replaceable"><
code>level</
code></
em></
code>]
1858N/A [<
code class="option">-g</
code>]
1858N/A | [<
code class="option">-o</
code>]
1858N/A | [<
code class="option">-l</
code>]
1858N/A | [<
code class="option">-y <
em class="replaceable"><
code>[<
span class="optional">hmac:</
span>]keyname:secret</
code></
em></
code>]
1858N/A | [<
code class="option">-k <
em class="replaceable"><
code>keyfile</
code></
em></
code>]
2439N/A [<
code class="option">-t <
em class="replaceable"><
code>timeout</
code></
em></
code>]
2439N/A [<
code class="option">-u <
em class="replaceable"><
code>udptimeout</
code></
em></
code>]
1858N/A [<
code class="option">-r <
em class="replaceable"><
code>udpretries</
code></
em></
code>]
7238N/A [<
code class="option">-R <
em class="replaceable"><
code>randomdev</
code></
em></
code>]
2601N/A [<
code class="option">-v</
code>]
2601N/A [<
code class="option">-T</
code>]
7238N/A [<
code class="option">-P</
code>]
7238N/A [<
code class="option">-V</
code>]
6458N/A<
a name="id-1.14.26.7"></
a><
h2>DESCRIPTION</
h2>
7238N/A <
p><
span class="command"><
strong>nsupdate</
strong></
span>
6458N/A is used to submit Dynamic DNS Update requests as defined in RFC 2136
7238N/A This allows resource records to be added or removed from a zone
6458N/A without manually editing the zone file.
1858N/A A single update request can contain requests to add or remove more than
2601N/A Zones that are under dynamic control via
2601N/A <
span class="command"><
strong>nsupdate</
strong></
span>
6458N/A or a DHCP server should not be edited by hand.
2601N/A conflict with dynamic updates and cause data to be lost.
2601N/A The resource records that are dynamically added or removed with
2601N/A <
span class="command"><
strong>nsupdate</
strong></
span>
2601N/A have to be in the same zone.
1858N/A Requests are sent to the zone's master server.
1858N/A This is identified by the MNAME field of the zone's SOA record.
1858N/A Transaction signatures can be used to authenticate the Dynamic
1858N/A DNS updates. These use the TSIG resource record type described
1858N/A in RFC 2845 or the SIG(0) record described in RFC 2535 and
1858N/A RFC 2931 or GSS-TSIG as described in RFC 3645.
1858N/A a shared secret that should only be known to
2601N/A <
span class="command"><
strong>nsupdate</
strong></
span> and the name server.
2601N/A For instance, suitable <
span class="type">key</
span> and
1858N/A <
span class="type">server</
span> statements would be added to
1858N/A can associate the appropriate secret key and algorithm with
1858N/A the IP address of the client application that will be using
1858N/A TSIG authentication. You can use <
span class="command"><
strong>ddns-confgen</
strong></
span>
1858N/A to generate suitable configuration fragments.
1858N/A <
span class="command"><
strong>nsupdate</
strong></
span>
1858N/A uses the <
code class="option">-y</
code> or <
code class="option">-k</
code> options
4134N/A to provide the TSIG shared secret. These options are mutually exclusive.
1858N/A SIG(0) uses public key cryptography.
1858N/A To use a SIG(0) key, the public key must be stored in a KEY
1858N/A record in a zone served by the name server.
1858N/A GSS-TSIG uses Kerberos credentials. Standard GSS-TSIG mode
1858N/A is switched on with the <
code class="option">-g</
code> flag. A
1858N/A non-standards-compliant variant of GSS-TSIG used by Windows
1858N/A 2000 can be switched on with the <
code class="option">-o</
code> flag.
4134N/A<
a name="id-1.14.26.8"></
a><
h2>OPTIONS</
h2>
1858N/A <
div class="variablelist"><
dl class="variablelist">
1858N/A<
dt><
span class="term">-d</
span></
dt>
1858N/A Debug mode. This provides tracing information about the
1858N/A update requests that are made and the replies received
3902N/A<
dt><
span class="term">-D</
span></
dt>
3902N/A<
dt><
span class="term">-k <
em class="replaceable"><
code>keyfile</
code></
em></
span></
dt>
2601N/A The file containing the TSIG authentication key.
2601N/A Keyfiles may be in two formats: a single file containing
2601N/A a <
code class="filename">
named.conf</
code>-format <
span class="command"><
strong>key</
strong></
span>
3352N/A statement, which may be generated automatically by
2601N/A <
span class="command"><
strong>ddns-confgen</
strong></
span>, or a pair of files whose names are
6510N/A of the format <
code class="filename">K{name}.+157.+{random}.key</
code> and
6510N/A <
code class="filename">K{name}.+157.+{random}.private</
code>, which can be
6510N/A generated by <
span class="command"><
strong>dnssec-keygen</
strong></
span>.
6510N/A The <
code class="option">-k</
code> may also be used to specify a SIG(0) key used
2601N/A to authenticate Dynamic DNS update requests. In this case, the key
6510N/A specified is not an HMAC-MD5 key.
6510N/A<
dt><
span class="term">-l</
span></
dt>
6510N/A Local-host only mode. This sets the server address to
6510N/A localhost (disabling the <
span class="command"><
strong>server</
strong></
span> so that the server
6510N/A address cannot be overridden). Connections to the local server will
6510N/A which is automatically generated by <
span class="command"><
strong>named</
strong></
span> if any
6510N/A local master zone has set <
span class="command"><
strong>update-policy</
strong></
span> to
6510N/A <
span class="command"><
strong>local</
strong></
span>. The location of this key file can be
6510N/A overridden with the <
code class="option">-k</
code> option.
6510N/A<
dt><
span class="term">-L <
em class="replaceable"><
code>level</
code></
em></
span></
dt>
6510N/A Set the logging debug level. If zero, logging is disabled.
2601N/A<
dt><
span class="term">-p <
em class="replaceable"><
code>port</
code></
em></
span></
dt>
2601N/A Set the port to use for connections to a name server. The
3902N/A<
dt><
span class="term">-P</
span></
dt>
2601N/A Print the list of private BIND-specific resource record
3902N/A types whose format is understood
2601N/A by <
span class="command"><
strong>nsupdate</
strong></
span>. See also
3902N/A the <
code class="option">-T</
code> option.
2601N/A<
dt><
span class="term">-r <
em class="replaceable"><
code>udpretries</
code></
em></
span></
dt>
7238N/A The number of UDP retries. The default is 3. If zero, only
2601N/A one update request will be made.
2601N/A<
dt><
span class="term">-R <
em class="replaceable"><
code>randomdev</
code></
em></
span></
dt>
6458N/A Where to obtain randomness. If the operating system
6458N/A equivalent device, the default source of randomness is keyboard
6458N/A input. <
code class="filename">randomdev</
code> specifies the name of
6458N/A a character device or file containing random data to be used
6458N/A instead of the default. The special value
6458N/A <
code class="filename">keyboard</
code> indicates that keyboard input
1858N/A should be used. This option may be specified multiple times.
6458N/A<
dt><
span class="term">-t <
em class="replaceable"><
code>timeout</
code></
em></
span></
dt>
6458N/A The maximum time an update request can take before it is
6458N/A aborted. The default is 300 seconds. Zero can be used to
6458N/A<
dt><
span class="term">-T</
span></
dt>
6458N/A Print the list of IANA standard resource record types
6458N/A whose format is understood by <
span class="command"><
strong>nsupdate</
strong></
span>.
6458N/A <
span class="command"><
strong>nsupdate</
strong></
span> will exit after the lists are
6458N/A printed. The <
code class="option">-T</
code> option can be combined
6458N/A with the <
code class="option">-P</
code> option.
6458N/A Other types can be entered using "TYPEXXXXX" where "XXXXX" is the
6458N/A decimal value of the type with no leading zeros. The rdata,
6458N/A if present, will be parsed using the UNKNOWN rdata format,
6458N/A (<backslash> <hash> <space> <length>
6458N/A <space> <hexstring>).
6458N/A<
dt><
span class="term">-u <
em class="replaceable"><
code>udptimeout</
code></
em></
span></
dt>
6458N/A The UDP retry interval. The default is 3 seconds. If zero,
6458N/A the interval will be computed from the timeout interval and
6458N/A<
dt><
span class="term">-v</
span></
dt>
6458N/A Use TCP even for small update requests.
6458N/A By default, <
span class="command"><
strong>nsupdate</
strong></
span>
6458N/A uses UDP to send update requests to the name server unless they are too
7238N/A large to fit in a UDP request in which case TCP will be used.
6458N/A TCP may be preferable when a batch of update requests is made.
6458N/A<
dt><
span class="term">-V</
span></
dt>
6458N/A Print the version number and exit.
6458N/A<
dt><
span class="term">-y <
em class="replaceable"><
code>[<
span class="optional">hmac:</
span>]keyname:secret</
code></
em></
span></
dt>
6458N/A Literal TSIG authentication key.
6458N/A <
em class="parameter"><
code>keyname</
code></
em> is the name of the key, and
6458N/A <
em class="parameter"><
code>secret</
code></
em> is the base64 encoded shared secret.
6458N/A <
em class="parameter"><
code>hmac</
code></
em> is the name of the key algorithm;
6458N/A valid choices are <
code class="literal">hmac-md5</
code>,
6458N/A <
code class="literal">hmac-sha1</
code>, <
code class="literal">hmac-sha224</
code>,
6458N/A <
code class="literal">hmac-sha256</
code>, <
code class="literal">hmac-sha384</
code>, or
6458N/A <
code class="literal">hmac-sha512</
code>. If <
em class="parameter"><
code>hmac</
code></
em>
6458N/A is not specified, the default is <
code class="literal">hmac-md5</
code>
6458N/A or if MD5 was disabled <
code class="literal">hmac-sha256</
code>.
6458N/A NOTE: Use of the <
code class="option">-y</
code> option is discouraged because the
6458N/A shared secret is supplied as a command line argument in clear text.
6458N/A This may be visible in the output from
6458N/A <
span class="citerefentry">
6458N/A <
span class="refentrytitle">ps</
span>(1)
6458N/A or in a history file maintained by the user's shell.
6961N/A<
a name="id-1.14.26.9"></
a><
h2>INPUT FORMAT</
h2>
6510N/A <
p><
span class="command"><
strong>nsupdate</
strong></
span>
6510N/A <
em class="parameter"><
code>filename</
code></
em>
6510N/A Each command is supplied on exactly one line of input.
6510N/A Some commands are for administrative purposes.
6510N/A The others are either update instructions or prerequisite checks on the
6961N/A These checks set conditions that some name or set of
6961N/A resource records (RRset) either exists or is absent from the zone.
6510N/A These conditions must be met if the entire update request is to succeed.
6510N/A Updates will be rejected if the tests for the prerequisite conditions
6510N/A Every update request consists of zero or more prerequisites
6510N/A This allows a suitably authenticated update request to proceed if some
6510N/A specified resource records are present or missing from the zone.
6510N/A A blank input line (or the <
span class="command"><
strong>send</
strong></
span> command)
6510N/A accumulated commands to be sent as one Dynamic DNS update request to the
6510N/A The command formats and their meaning are as follows:
6458N/A<
div class="variablelist"><
dl class="variablelist">
6458N/A <
span class="command"><
strong>server</
strong></
span>
6458N/A Sends all dynamic update requests to the name server
6458N/A <
em class="parameter"><
code>servername</
code></
em>.
6465N/A When no server statement is provided,
6458N/A <
span class="command"><
strong>nsupdate</
strong></
span>
6458N/A will send updates to the master server of the correct zone.
6458N/A The MNAME field of that zone's SOA record will identify the
6458N/A <
em class="parameter"><
code>port</
code></
em>
6458N/A <
em class="parameter"><
code>servername</
code></
em>
6458N/A where the dynamic update requests get sent.
6458N/A If no port number is specified, the default DNS port number of
6458N/A <
span class="command"><
strong>local</
strong></
span>
6458N/A Sends all dynamic update requests using the local
6458N/A <
em class="parameter"><
code>address</
code></
em>.
6458N/A When no local statement is provided,
6458N/A <
span class="command"><
strong>nsupdate</
strong></
span>
6510N/A will send updates using an address and port chosen by the
6510N/A <
em class="parameter"><
code>port</
code></
em>
6510N/A can additionally be used to make requests come from a specific
6458N/A If no port number is specified, the system will assign one.
6458N/A <
span class="command"><
strong>zone</
strong></
span>
6458N/A Specifies that all updates are to be made to the zone
6458N/A <
em class="parameter"><
code>zonename</
code></
em>.
6458N/A <
em class="parameter"><
code>zone</
code></
em>
6458N/A <
span class="command"><
strong>nsupdate</
strong></
span>
6458N/A will attempt determine the correct zone to update based on the
6458N/A <
span class="command"><
strong>class</
strong></
span>
6458N/A If no <
em class="parameter"><
code>class</
code></
em> is specified, the
6458N/A <
em class="parameter"><
code>IN</
code></
em>.
6458N/A <
span class="command"><
strong>ttl</
strong></
span>
6458N/A Specify the default time to live for records to be added.
6458N/A The value <
em class="parameter"><
code>none</
code></
em> will clear the default
6458N/A <
span class="command"><
strong>key</
strong></
span>
6458N/A Specifies that all updates are to be TSIG-signed using the
6458N/A <
em class="parameter"><
code>keyname</
code></
em> <
em class="parameter"><
code>secret</
code></
em> pair.
6458N/A If <
em class="parameter"><
code>hmac</
code></
em> is specified, then it sets the
6458N/A signing algorithm in use; the default is
6458N/A <
code class="literal">hmac-md5</
code> or if MD5 was disabled
6458N/A <
code class="literal">hmac-sha256</
code>. The <
span class="command"><
strong>key</
strong></
span>
6458N/A command overrides any key specified on the command line via
6458N/A <
code class="option">-y</
code> or <
code class="option">-k</
code>.
6458N/A <
span class="command"><
strong>gsstsig</
strong></
span>
6458N/A Use GSS-TSIG to sign the updated. This is equivalent to
6458N/A specifying <
code class="option">-g</
code> on the command line.
6458N/A <
span class="command"><
strong>oldgsstsig</
strong></
span>
6458N/A Use the Windows 2000 version of GSS-TSIG to sign the updated.
6458N/A This is equivalent to specifying <
code class="option">-o</
code> on the
6458N/A <
span class="command"><
strong>realm</
strong></
span>
6458N/A {[<
span class="optional">realm_name</
span>]}
6458N/A When using GSS-TSIG use <
em class="parameter"><
code>realm_name</
code></
em> rather
6458N/A than the default realm in <
code class="filename">
krb5.conf</
code>. If no
6458N/A realm is specified the saved realm is cleared.
6458N/A <
span class="command"><
strong>check-names</
strong></
span>
6458N/A {[<
span class="optional">yes_or_no</
span>]}
6458N/A Turn on or off check-names processing on records to
6458N/A be added. Check-names has no effect on prerequisites
6458N/A or records to be deleted. By default check-names
6458N/A processing is on. If check-names processing fails
6458N/A the record will not be added to the UPDATE message.
6458N/A <
span class="command"><
strong>[<
span class="optional">prereq</
span>] nxdomain</
strong></
span>
6458N/A Requires that no resource record of any type exists with name
6458N/A <
em class="parameter"><
code>domain-name</
code></
em>.
6510N/A <
span class="command"><
strong>[<
span class="optional">prereq</
span>] yxdomain</
strong></
span>
6510N/A <
em class="parameter"><
code>domain-name</
code></
em>
6458N/A exists (has as at least one resource record, of any type).
6961N/A <
span class="command"><
strong>[<
span class="optional">prereq</
span>] nxrrset</
strong></
span>
6510N/A Requires that no resource record exists of the specified
6510N/A <
em class="parameter"><
code>type</
code></
em>,
6510N/A <
em class="parameter"><
code>class</
code></
em>
6510N/A <
em class="parameter"><
code>domain-name</
code></
em>.
6510N/A <
em class="parameter"><
code>class</
code></
em>
6510N/A is omitted, IN (internet) is assumed.
6464N/A <
span class="command"><
strong>[<
span class="optional">prereq</
span>] yxrrset</
strong></
span>
6465N/A This requires that a resource record of the specified
6464N/A <
em class="parameter"><
code>type</
code></
em>,
6464N/A <
em class="parameter"><
code>class</
code></
em>
6464N/A <
em class="parameter"><
code>domain-name</
code></
em>
6464N/A <
em class="parameter"><
code>class</
code></
em>
6464N/A is omitted, IN (internet) is assumed.
6464N/A <
span class="command"><
strong>[<
span class="optional">prereq</
span>] yxrrset</
strong></
span>
2601N/A <
em class="parameter"><
code>data</
code></
em>
6458N/A from each set of prerequisites of this form
6954N/A <
em class="parameter"><
code>type</
code></
em>,
6954N/A <
em class="parameter"><
code>class</
code></
em>,
7238N/A <
em class="parameter"><
code>domain-name</
code></
em>
2601N/A are combined to form a set of RRs. This set of RRs must
7238N/A exactly match the set of RRs existing in the zone at the
7238N/A <
em class="parameter"><
code>type</
code></
em>,
2601N/A <
em class="parameter"><
code>class</
code></
em>,
7238N/A <
em class="parameter"><
code>domain-name</
code></
em>.
4134N/A <
em class="parameter"><
code>data</
code></
em>
4134N/A are written in the standard text representation of the resource
4499N/A <
span class="command"><
strong>[<
span class="optional">update</
span>] del[<
span class="optional">ete</
span>]</
strong></
span>
6961N/A Deletes any resource records named
6510N/A <
em class="parameter"><
code>domain-name</
code></
em>.
6510N/A <
em class="parameter"><
code>type</
code></
em>
4499N/A <
em class="parameter"><
code>data</
code></
em>
4499N/A is provided, only matching resource records will be removed.
4499N/A The internet class is assumed if
4499N/A <
em class="parameter"><
code>class</
code></
em>
4499N/A <
em class="parameter"><
code>ttl</
code></
em>
4499N/A is ignored, and is only allowed for compatibility.
4499N/A <
span class="command"><
strong>[<
span class="optional">update</
span>] add</
strong></
span>
2601N/A Adds a new resource record with the specified
2601N/A <
em class="parameter"><
code>ttl</
code></
em>,
2601N/A <
em class="parameter"><
code>class</
code></
em>
2601N/A <
em class="parameter"><
code>data</
code></
em>.
2601N/A <
span class="command"><
strong>show</
strong></
span>
2601N/A Displays the current message, containing all of the
6961N/A updates specified since the last send.
2601N/A <
span class="command"><
strong>send</
strong></
span>
2601N/A Sends the current message. This is equivalent to entering a
7238N/A <
span class="command"><
strong>answer</
strong></
span>
2601N/A <
span class="command"><
strong>debug</
strong></
span>
5536N/A <
span class="command"><
strong>version</
strong></
span>
2601N/A <
span class="command"><
strong>help</
strong></
span>
2601N/A Lines beginning with a semicolon are comments and are ignored.
2601N/A<
a name="id-1.14.26.10"></
a><
h2>EXAMPLES</
h2>
4134N/A The examples below show how
4134N/A <
span class="command"><
strong>nsupdate</
strong></
span>
2601N/A could be used to insert and delete resource records from the
7238N/A Notice that the input in each example contains a trailing blank line so
7238N/A a group of commands are sent as one dynamic update request to the
7238N/A<
pre class="programlisting">
2601N/A with IP address 172.16.1.1 is added.
2601N/A The newly-added record has a 1 day TTL (86400 seconds).
2601N/A<
pre class="programlisting">
2601N/A The prerequisite condition gets the name server to check that there
2601N/A are no resource records of any type for
3853N/A If there are, the update request fails.
3853N/A If this name does not exist, a CNAME for it is added.
3853N/A This ensures that when the CNAME is added, it cannot conflict with the
3853N/A long-standing rule in RFC 1034 that a name must not exist as any other
2601N/A record type if it exists as a CNAME.
2601N/A (The rule has been updated for DNSSEC in RFC 2535 to allow CNAMEs to have
2601N/A RRSIG, DNSKEY and NSEC records.)
7238N/A<
a name="id-1.14.26.11"></
a><
h2>FILES</
h2>
2601N/A <
div class="variablelist"><
dl class="variablelist">
2601N/A used to identify default name server
2601N/A sets the default TSIG key for use in local-only mode
2601N/A<
dt><
span class="term"><
code class="constant">K{name}.+157.+{random}.key</
code></
span></
dt>
3853N/A base-64 encoding of HMAC-MD5 key created by
3853N/A <
span class="citerefentry">
3853N/A <
span class="refentrytitle">dnssec-keygen</
span>(8)
2601N/A<
dt><
span class="term"><
code class="constant">K{name}.+157.+{random}.private</
code></
span></
dt>
2601N/A base-64 encoding of HMAC-MD5 key created by
2601N/A <
span class="citerefentry">
2601N/A <
span class="refentrytitle">dnssec-keygen</
span>(8)
2601N/A<
a name="id-1.14.26.12"></
a><
h2>SEE ALSO</
h2>
2601N/A <
em class="citetitle">RFC 2136</
em>,
2601N/A <
em class="citetitle">RFC 3007</
em>,
2601N/A <
em class="citetitle">RFC 2104</
em>,
2601N/A <
em class="citetitle">RFC 2845</
em>,
2601N/A <
em class="citetitle">RFC 1034</
em>,
2601N/A <
em class="citetitle">RFC 2535</
em>,
2601N/A <
em class="citetitle">RFC 2931</
em>,
2601N/A <
span class="citerefentry">
2601N/A <
span class="refentrytitle">named</
span>(8)
2601N/A <
span class="citerefentry">
2601N/A <
span class="refentrytitle">ddns-confgen</
span>(8)
2601N/A <
span class="citerefentry">
2601N/A <
span class="refentrytitle">dnssec-keygen</
span>(8)
2601N/A<
a name="id-1.14.26.13"></
a><
h2>BUGS</
h2>
2601N/A The TSIG key is redundantly stored in two separate files.
2601N/A This is a consequence of nsupdate using the DST library
2601N/A for its cryptographic operations, and may change in future
2601N/A<
table width="100%" summary="Navigation footer">
2601N/A<
td width="40%" align="left">
2601N/A<
td width="40%" align="left" valign="top">
2601N/A<
span class="application">named-rrchecker</
span>�</
td>
5090N/A<
td width="40%" align="right" valign="top">�<
span class="application">rndc</
span>