1NSUPDATE(1) BIND9 NSUPDATE(1)
2
6 nsupdate - Dynamic DNS update utility
7
9 nsupdate [-d] [-D] [-i] [-L level] [[-g] | [-o] | [-l] |
10 [-y [hmac:]keyname:secret] | [-k keyfile]] [-t timeout]
11 [-u udptimeout] [-r udpretries] [-R randomdev] [-v] [-T] [-P]
12 [-V] [filename]
13
15 nsupdate is used to submit Dynamic DNS Update requests as defined in
16 RFC 2136 to a name server. This allows resource records to be added or
17 removed from a zone without manually editing the zone file. A single
18 update request can contain requests to add or remove more than one
19 resource record.
20 Zones that are under dynamic control via nsupdate or a DHCP server
22 should not be edited by hand. Manual edits could conflict with dynamic
23 updates and cause data to be lost.
24 The resource records that are dynamically added or removed with
26 nsupdate have to be in the same zone. Requests are sent to the zone's
27 master server. This is identified by the MNAME field of the zone's SOA
28 record.
29 Transaction signatures can be used to authenticate the Dynamic DNS
31 updates. These use the TSIG resource record type described in RFC 2845
32 or the SIG(0) record described in RFC 2535 and RFC 2931 or GSS-TSIG as
33 described in RFC 3645.
34 TSIG relies on a shared secret that should only be known to nsupdate
36 and the name server. For instance, suitable key and server statements
37 would be added to /etc/named.conf so that the name server can associate
38 the appropriate secret key and algorithm with the IP address of the
39 client application that will be using TSIG authentication. You can use
40 ddns-confgen to generate suitable configuration fragments. nsupdate
41 uses the -y or -k options to provide the TSIG shared secret. These
42 options are mutually exclusive.
43 SIG(0) uses public key cryptography. To use a SIG(0) key, the public
45 key must be stored in a KEY record in a zone served by the name server.
46 GSS-TSIG uses Kerberos credentials. Standard GSS-TSIG mode is switched
48 on with the -g flag. A non-standards-compliant variant of GSS-TSIG used
49 by Windows 2000 can be switched on with the -o flag.
50
52 -d
53 Debug mode. This provides tracing information about the update
54 requests that are made and the replies received from the name
55 server.
56 -D
58 Extra debug mode.
59 -i
61 Force interactive mode, even when standard input is not a terminal.
62 -k keyfile
64 The file containing the TSIG authentication key. Keyfiles may be in
65 two formats: a single file containing a named.conf-format key
66 statement, which may be generated automatically by ddns-confgen, or
67 a pair of files whose names are of the format
68 K{name}.+157.+{random}.key and K{name}.+157.+{random}.private,
69 which can be generated by dnssec-keygen. The -k may also be used to
70 specify a SIG(0) key used to authenticate Dynamic DNS update
71 requests. In this case, the key specified is not an HMAC-MD5 key.
72 -l
74 Local-host only mode. This sets the server address to localhost
75 (disabling the server so that the server address cannot be
76 overridden). Connections to the local server will use a TSIG key
77 found in /var/run/named/session.key, which is automatically
78 generated by named if any local master zone has set update-policy
79 to local. The location of this key file can be overridden with the
80 -k option.
81 -L level
83 Set the logging debug level. If zero, logging is disabled.
84 -p port
86 Set the port to use for connections to a name server. The default
87 is 53.
88 -P
90 Print the list of private BIND-specific resource record types whose
91 format is understood by nsupdate. See also the -T option.
92 -r udpretries
94 The number of UDP retries. The default is 3. If zero, only one
95 update request will be made.
96 -R randomdev
98 Where to obtain randomness. If the operating system does not
99 provide a /dev/random or equivalent device, the default source of
100 randomness is keyboard input. randomdev specifies the name of a
101 character device or file containing random data to be used instead
102 of the default. The special value keyboard indicates that keyboard
103 input should be used. This option may be specified multiple times.
104 -t timeout
106 The maximum time an update request can take before it is aborted.
107 The default is 300 seconds. Zero can be used to disable the
108 timeout.
109 -T
111 Print the list of IANA standard resource record types whose format
112 is understood by nsupdate. nsupdate will exit after the lists are
113 printed. The -T option can be combined with the -P option.
114 Other types can be entered using "TYPEXXXXX" where "XXXXX" is the
116 decimal value of the type with no leading zeros. The rdata, if
117 present, will be parsed using the UNKNOWN rdata format,
118 (<backslash> <hash> <space> <length> <space> <hexstring>).
119 -u udptimeout
121 The UDP retry interval. The default is 3 seconds. If zero, the
122 interval will be computed from the timeout interval and number of
123 UDP retries.
124 -v
126 Use TCP even for small update requests. By default, nsupdate uses
127 UDP to send update requests to the name server unless they are too
128 large to fit in a UDP request in which case TCP will be used. TCP
129 may be preferable when a batch of update requests is made.
130 -V
132 Print the version number and exit.
133 -y [hmac:]keyname:secret
135 Literal TSIG authentication key. keyname is the name of the key,
136 and secret is the base64 encoded shared secret. hmac is the name
137 of the key algorithm; valid choices are hmac-md5, hmac-sha1,
138 hmac-sha224, hmac-sha256, hmac-sha384, or hmac-sha512. If hmac is
139 not specified, the default is hmac-md5 or if MD5 was disabled
140 hmac-sha256.
141 NOTE: Use of the -y option is discouraged because the shared secret
143 is supplied as a command line argument in clear text. This may be
144 visible in the output from ps(1) or in a history file maintained by
145 the user's shell.
146
148 nsupdate reads input from filename or standard input. Each command is
149 supplied on exactly one line of input. Some commands are for
150 administrative purposes. The others are either update instructions or
151 prerequisite checks on the contents of the zone. These checks set
152 conditions that some name or set of resource records (RRset) either
153 exists or is absent from the zone. These conditions must be met if the
154 entire update request is to succeed. Updates will be rejected if the
155 tests for the prerequisite conditions fail.
156 Every update request consists of zero or more prerequisites and zero or
158 more updates. This allows a suitably authenticated update request to
159 proceed if some specified resource records are present or missing from
160 the zone. A blank input line (or the send command) causes the
161 accumulated commands to be sent as one Dynamic DNS update request to
162 the name server.
163 The command formats and their meaning are as follows:
165 server {servername} [port]
167 Sends all dynamic update requests to the name server servername.
168 When no server statement is provided, nsupdate will send updates to
169 the master server of the correct zone. The MNAME field of that
170 zone's SOA record will identify the master server for that zone.
171 port is the port number on servername where the dynamic update
172 requests get sent. If no port number is specified, the default DNS
173 port number of 53 is used.
174 local {address} [port]
176 Sends all dynamic update requests using the local address. When no
177 local statement is provided, nsupdate will send updates using an
178 address and port chosen by the system. port can additionally be
179 used to make requests come from a specific port. If no port number
180 is specified, the system will assign one.
181 zone {zonename}
183 Specifies that all updates are to be made to the zone zonename. If
184 no zone statement is provided, nsupdate will attempt determine the
185 correct zone to update based on the rest of the input.
186 class {classname}
188 Specify the default class. If no class is specified, the default
189 class is IN.
190 ttl {seconds}
192 Specify the default time to live for records to be added. The value
193 none will clear the default ttl.
194 key [hmac:] {keyname} {secret}
196 Specifies that all updates are to be TSIG-signed using the keyname
197 secret pair. If hmac is specified, then it sets the signing
198 algorithm in use; the default is hmac-md5 or if MD5 was disabled
199 hmac-sha256. The key command overrides any key specified on the
200 command line via -y or -k.
201 gsstsig
203 Use GSS-TSIG to sign the updated. This is equivalent to specifying
204 -g on the command line.
205 oldgsstsig
207 Use the Windows 2000 version of GSS-TSIG to sign the updated. This
208 is equivalent to specifying -o on the command line.
209 realm {[realm_name]}
211 When using GSS-TSIG use realm_name rather than the default realm in
212 krb5.conf. If no realm is specified the saved realm is cleared.
213 check-names {[yes_or_no]}
215 Turn on or off check-names processing on records to be added.
216 Check-names has no effect on prerequisites or records to be
217 deleted. By default check-names processing is on. If check-names
218 processing fails the record will not be added to the UPDATE
219 message.
220 [prereq] nxdomain {domain-name}
222 Requires that no resource record of any type exists with name
223 domain-name.
224 [prereq] yxdomain {domain-name}
226 Requires that domain-name exists (has as at least one resource
227 record, of any type).
228 [prereq] nxrrset {domain-name} [class] {type}
230 Requires that no resource record exists of the specified type,
231 class and domain-name. If class is omitted, IN (internet) is
232 assumed.
233 [prereq] yxrrset {domain-name} [class] {type}
235 This requires that a resource record of the specified type, class
236 and domain-name must exist. If class is omitted, IN (internet) is
237 assumed.
238 [prereq] yxrrset {domain-name} [class] {type} {data...}
240 The data from each set of prerequisites of this form sharing a
241 common type, class, and domain-name are combined to form a set of
242 RRs. This set of RRs must exactly match the set of RRs existing in
243 the zone at the given type, class, and domain-name. The data are
244 written in the standard text representation of the resource
245 record's RDATA.
246 [update] del[ete] {domain-name} [ttl] [class] [type [data...]]
248 Deletes any resource records named domain-name. If type and data is
249 provided, only matching resource records will be removed. The
250 internet class is assumed if class is not supplied. The ttl is
251 ignored, and is only allowed for compatibility.
252 [update] add {domain-name} {ttl} [class] {type} {data...}
254 Adds a new resource record with the specified ttl, class and data.
255 show
257 Displays the current message, containing all of the prerequisites
258 and updates specified since the last send.
259 send
261 Sends the current message. This is equivalent to entering a blank
262 line.
263 answer
265 Displays the answer.
266 debug
268 Turn on debugging.
269 version
271 Print version number.
272 help
274 Print a list of commands.
275 Lines beginning with a semicolon are comments and are ignored.
277
279 The examples below show how nsupdate could be used to insert and delete
280 resource records from the example.com zone. Notice that the input in
281 each example contains a trailing blank line so that a group of commands
282 are sent as one dynamic update request to the master name server for
283 example.com.
284 # nsupdate
286 > update delete oldhost.example.com A
287 > update add newhost.example.com 86400 A 172.16.1.1
288 > send
289 Any A records for oldhost.example.com are deleted. And an A record for
291 newhost.example.com with IP address 172.16.1.1 is added. The
292 newly-added record has a 1 day TTL (86400 seconds).
293 # nsupdate
295 > prereq nxdomain nickname.example.com
296 > update add nickname.example.com 86400 CNAME somehost.example.com
297 > send
298 The prerequisite condition gets the name server to check that there are
300 no resource records of any type for nickname.example.com. If there are,
301 the update request fails. If this name does not exist, a CNAME for it
302 is added. This ensures that when the CNAME is added, it cannot conflict
303 with the long-standing rule in RFC 1034 that a name must not exist as
304 any other record type if it exists as a CNAME. (The rule has been
305 updated for DNSSEC in RFC 2535 to allow CNAMEs to have RRSIG, DNSKEY
306 and NSEC records.)
307
309 /etc/resolv.conf
310 used to identify default name server
311 /var/run/named/session.key
313 sets the default TSIG key for use in local-only mode
314 K{name}.+157.+{random}.key
316 base-64 encoding of HMAC-MD5 key created by dnssec-keygen(8).
317 K{name}.+157.+{random}.private
319 base-64 encoding of HMAC-MD5 key created by dnssec-keygen(8).
320
322 RFC 2136, RFC 3007, RFC 2104, RFC 2845, RFC 1034, RFC 2535, RFC 2931,
323 named(8), ddns-confgen(8), dnssec-keygen(8).
324
326 The TSIG key is redundantly stored in two separate files. This is a
327 consequence of nsupdate using the DST library for its cryptographic
328 operations, and may change in future releases.
329
331 Internet Systems Consortium, Inc.
332
334 Copyright © 2000-2012, 2014-2021 Internet Systems Consortium, Inc.
335 ("ISC")
336ISC 2014-04-18 NSUPDATE(1)