1NSUPDATE(8) BIND9 NSUPDATE(8)
2
6 nsupdate - Dynamic DNS update utility
7
9 nsupdate [-d] [[-y [hmac:]keyname:secret] | [-k keyfile]] [-t timeout]
10 [-u udptimeout] [-r udpretries] [-v] [filename]
11
13 nsupdate is used to submit Dynamic DNS Update requests as defined in
14 RFC2136 to a name server. This allows resource records to be added or
15 removed from a zone without manually editing the zone file. A single
16 update request can contain requests to add or remove more than one
17 resource record.
18 Zones that are under dynamic control via nsupdate or a DHCP server
20 should not be edited by hand. Manual edits could conflict with dynamic
21 updates and cause data to be lost.
22 The resource records that are dynamically added or removed with
24 nsupdate have to be in the same zone. Requests are sent to the zone's
25 master server. This is identified by the MNAME field of the zone's SOA
26 record.
27 The -d option makes nsupdate operate in debug mode. This provides
29 tracing information about the update requests that are made and the
30 replies received from the name server.
31 Transaction signatures can be used to authenticate the Dynamic DNS
33 updates. These use the TSIG resource record type described in RFC2845
34 or the SIG(0) record described in RFC3535 and RFC2931. TSIG relies on a
35 shared secret that should only be known to nsupdate and the name
36 server. Currently, the only supported encryption algorithm for TSIG is
37 HMAC-MD5, which is defined in RFC 2104. Once other algorithms are
38 defined for TSIG, applications will need to ensure they select the
39 appropriate algorithm as well as the key when authenticating each
40 other. For instance, suitable key and server statements would be added
41 to /etc/named.conf so that the name server can associate the
42 appropriate secret key and algorithm with the IP address of the client
43 application that will be using TSIG authentication. SIG(0) uses public
44 key cryptography. To use a SIG(0) key, the public key must be stored in
45 a KEY record in a zone served by the name server. nsupdate does not
46 read /etc/named.conf.
47 nsupdate uses the -y or -k option to provide the shared secret needed
49 to generate a TSIG record for authenticating Dynamic DNS update
50 requests, default type HMAC-MD5. These options are mutually exclusive.
51 With the -k option, nsupdate reads the shared secret from the file
52 keyfile, whose name is of the form K{name}.+157.+{random}.private. For
53 historical reasons, the file K{name}.+157.+{random}.key must also be
54 present. When the -y option is used, a signature is generated from
55 [hmac:]keyname:secret. keyname is the name of the key, and secret is
56 the base64 encoded shared secret. Use of the -y option is discouraged
57 because the shared secret is supplied as a command line argument in
58 clear text. This may be visible in the output from ps(1) or in a
59 history file maintained by the user's shell.
60 The -k may also be used to specify a SIG(0) key used to authenticate
62 Dynamic DNS update requests. In this case, the key specified is not an
63 HMAC-MD5 key.
64 By default nsupdate uses UDP to send update requests to the name server
66 unless they are too large to fit in a UDP request in which case TCP
67 will be used. The -v option makes nsupdate use a TCP connection. This
68 may be preferable when a batch of update requests is made.
69 The -t option sets the maximum time an update request can take before
71 it is aborted. The default is 300 seconds. Zero can be used to disable
72 the timeout.
73 The -u option sets the UDP retry interval. The default is 3 seconds. If
75 zero, the interval will be computed from the timeout interval and
76 number of UDP retries.
77 The -r option sets the number of UDP retries. The default is 3. If
79 zero, only one update request will be made.
80
82 nsupdate reads input from filename or standard input. Each command is
83 supplied on exactly one line of input. Some commands are for
84 administrative purposes. The others are either update instructions or
85 prerequisite checks on the contents of the zone. These checks set
86 conditions that some name or set of resource records (RRset) either
87 exists or is absent from the zone. These conditions must be met if the
88 entire update request is to succeed. Updates will be rejected if the
89 tests for the prerequisite conditions fail.
90 Every update request consists of zero or more prerequisites and zero or
92 more updates. This allows a suitably authenticated update request to
93 proceed if some specified resource records are present or missing from
94 the zone. A blank input line (or the send command) causes the
95 accumulated commands to be sent as one Dynamic DNS update request to
96 the name server.
97 The command formats and their meaning are as follows:
99 server {servername} [port]
101 Sends all dynamic update requests to the name server servername.
102 When no server statement is provided, nsupdate will send updates to
103 the master server of the correct zone. The MNAME field of that
104 zone's SOA record will identify the master server for that zone.
105 port is the port number on servername where the dynamic update
106 requests get sent. If no port number is specified, the default DNS
107 port number of 53 is used.
108 local {address} [port]
110 Sends all dynamic update requests using the local address. When no
111 local statement is provided, nsupdate will send updates using an
112 address and port chosen by the system. port can additionally be
113 used to make requests come from a specific port. If no port number
114 is specified, the system will assign one.
115 zone {zonename}
117 Specifies that all updates are to be made to the zone zonename. If
118 no zone statement is provided, nsupdate will attempt determine the
119 correct zone to update based on the rest of the input.
120 class {classname}
122 Specify the default class. If no class is specified, the default
123 class is IN.
124 key {name} {secret}
126 Specifies that all updates are to be TSIG-signed using the keyname
127 keysecret pair. The key command overrides any key specified on the
128 command line via -y or -k.
129 prereq nxdomain {domain-name}
131 Requires that no resource record of any type exists with name
132 domain-name.
133 prereq yxdomain {domain-name}
135 Requires that domain-name exists (has as at least one resource
136 record, of any type).
137 prereq nxrrset {domain-name} [class] {type}
139 Requires that no resource record exists of the specified type,
140 class and domain-name. If class is omitted, IN (internet) is
141 assumed.
142 prereq yxrrset {domain-name} [class] {type}
144 This requires that a resource record of the specified type, class
145 and domain-name must exist. If class is omitted, IN (internet) is
146 assumed.
147 prereq yxrrset {domain-name} [class] {type} {data...}
149 The data from each set of prerequisites of this form sharing a
150 common type, class, and domain-name are combined to form a set of
151 RRs. This set of RRs must exactly match the set of RRs existing in
152 the zone at the given type, class, and domain-name. The data are
153 written in the standard text representation of the resource
154 record's RDATA.
155 update delete {domain-name} [ttl] [class] [type [data...]]
157 Deletes any resource records named domain-name. If type and data is
158 provided, only matching resource records will be removed. The
159 internet class is assumed if class is not supplied. The ttl is
160 ignored, and is only allowed for compatibility.
161 update add {domain-name} {ttl} [class] {type} {data...}
163 Adds a new resource record with the specified ttl, class and data.
164 show
166 Displays the current message, containing all of the prerequisites
167 and updates specified since the last send.
168 send
170 Sends the current message. This is equivalent to entering a blank
171 line.
172 answer
174 Displays the answer.
175 Lines beginning with a semicolon are comments and are ignored.
177
179 The examples below show how nsupdate could be used to insert and delete
180 resource records from the example.com zone. Notice that the input in
181 each example contains a trailing blank line so that a group of commands
182 are sent as one dynamic update request to the master name server for
183 example.com.
184 # nsupdate
186 > update delete oldhost.example.com A
187 > update add newhost.example.com 86400 A 172.16.1.1
188 > send
189 Any A records for oldhost.example.com are deleted. And an A record for
192 newhost.example.com with IP address 172.16.1.1 is added. The
193 newly-added record has a 1 day TTL (86400 seconds).
194 # nsupdate
196 > prereq nxdomain nickname.example.com
197 > update add nickname.example.com 86400 CNAME somehost.example.com
198 > send
199 The prerequisite condition gets the name server to check that there are
202 no resource records of any type for nickname.example.com. If there are,
203 the update request fails. If this name does not exist, a CNAME for it
204 is added. This ensures that when the CNAME is added, it cannot conflict
205 with the long-standing rule in RFC1034 that a name must not exist as
206 any other record type if it exists as a CNAME. (The rule has been
207 updated for DNSSEC in RFC2535 to allow CNAMEs to have RRSIG, DNSKEY and
208 NSEC records.)
209
211 /etc/resolv.conf
212 used to identify default name server
213 K{name}.+157.+{random}.key
215 base-64 encoding of HMAC-MD5 key created by dnssec-keygen(8).
216 K{name}.+157.+{random}.private
218 base-64 encoding of HMAC-MD5 key created by dnssec-keygen(8).
219
221 RFC2136(), RFC3007(), RFC2104(), RFC2845(), RFC1034(), RFC2535(),
222 RFC2931(), named(8), dnssec-keygen(8).
223
225 The TSIG key is redundantly stored in two separate files. This is a
226 consequence of nsupdate using the DST library for its cryptographic
227 operations, and may change in future releases.
228
230 Copyright © 2004-2007 Internet Systems Consortium, Inc. ("ISC")
231 Copyright © 2000-2003 Internet Software Consortium.
232BIND9 Jun 30, 2000 NSUPDATE(8)