Penguin
Recent Changes
Annotated edit history of nsupdate(8) version 4, including all changes. View license author blame.
Rev Author # Line
1 perry 1 NSUPDATE
2 !!!NSUPDATE
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 INPUT FORMAT
7 EXAMPLES
8 FILES
9 SEE ALSO
10 BUGS
11 ----
12 !!NAME
13
14
15 nsupdate - Dynamic DNS update utility
16 !!SYNOPSIS
17
18
19 __nsupdate__ [[ __-d__ ] [[ __[[ -y__
20 ''keyname:secret'' __] [[ -k__ ''keyfile'' __]__
21 ] [[ __-v__ ] [[ __filename__ ]
22 !!DESCRIPTION
23
24
25 __nsupdate__ is used to submit Dynamic DNS Update
26 requests as defined in RFC2136 to a name server. This allows
27 resource records to be added or removed from a zone without
28 manually editing the zone file. A single update request can
29 contain requests to add or remove more than one resource
30 record.
31
32
33 Zones that are under dynamic control via __nsupdate__ or
34 a DHCP server should not be edited by hand. Manual edits
35 could conflict with dynamic updates and cause data to be
36 lost.
37
38
39 The resource records that are dynamically added or removed
40 with __nsupdate__ have to be in the same zone. Requests
41 are sent to the zone's master server. This is identified by
42 the MNAME field of the zone's SOA record.
43
44
45 The __-d__ option makes __nsupdate__ operate in debug
46 mode. This provides tracing information about the update
47 requests that are made and the replies received from the
48 name server.
49
50
51 Transaction signatures can be used to authenticate the
52 Dynamic DNS updates. These use the TSIG resource record type
53 described in RFC2845. The signatures rely on a shared secret
54 that should only be known to __nsupdate__ and the name
55 server. Currently, the only supported encryption algorithm
56 for TSIG is HMAC-MD5, which is defined in RFC 2104. Once
57 other algorithms are defined for TSIG, applications will
58 need to ensure they select the appropriate algorithm as well
59 as the key when authenticating each other. For instance
60 suitable __key__ and __server__ statements would be
61 added to ''/etc/named.conf'' so that the name server can
62 associate the appropriate secret key and algorithm with the
63 IP address of the client application that will be using TSIG
64 authentication. __nsupdate__ does not read
65 ''/etc/named.conf''.
66
67
68 __nsupdate__ uses the __-y__ or __-k__ option to
69 provide the shared secret needed to generate a TSIG record
70 for authenticating Dynamic DNS update requests. These
71 options are mutually exclusive. With the __-k__ option,
72 __nsupdate__ reads the shared secret from the file
73 ''keyfile'', whose name is of the form
74 ''K{name}.+157.+{random}.private''. For historical
75 reasons, the file ''K{name}.+157.+{random}.key'' must
76 also be present. When the __-y__ option is used, a
77 signature is generated from ''keyname:secret. keyname''
78 is the name of the key, and ''secret'' is the base64
79 encoded shared secret. Use of the __-y__ option is
80 discouraged because the shared secret is supplied as a
81 command line argument in clear text. This may be visible in
82 the output from ps(1) or in a history file maintained
83 by the user's shell.
84
85
86 By default __nsupdate__ uses UDP to send update requests
87 to the name server. The __-v__ option makes
88 __nsupdate__ use a TCP connection. This may be preferable
89 when a batch of update requests is made.
90 !!INPUT FORMAT
91
92
93 __nsupdate__ reads input from ''filename'' or standard
94 input. Each command is supplied on exactly one line of
95 input. Some commands are for administrative purposes. The
96 others are either update instructions or prerequisite checks
97 on the contents of the zone. These checks set conditions
98 that some name or set of resource records (RRset) either
99 exists or is absent from the zone. These conditions must be
100 met if the entire update request is to succeed. Updates will
101 be rejected if the tests for the prerequisite conditions
102 fail.
103
104
105 Every update request consists of zero or more prerequisites
106 and zero or more updates. This allows a suitably
107 authenticated update request to proceed if some specified
108 resource records are present or missing from the zone. A
109 blank input line (or the __send__ command) causes the
110 accumulated commands to be sent as one Dynamic DNS update
111 request to the name server.
112
113
114 The command formats and their meaning are as
115 follows:
116
117
118 __server servername [[ port ]__
119
120
121 Sends all dynamic update requests to the name server
122 ''servername''. When no server statement is provided,
123 __nsupdate__ will send updates to the master server of
124 the correct zone. The MNAME field of that zone's SOA record
125 will identify the master server for that zone. ''port''
126 is the port number on ''servername'' where the dynamic
127 update requests get sent. If no port number is specified,
128 the default DNS port number of 53 is used.
129
130
131 __local address [[ port ]__
132
133
134 Sends all dynamic update requests using the local
135 ''address''. When no local statement is provided,
136 __nsupdate__ will send updates using an address and port
137 choosen by the system. ''port'' can additionally be used
138 to make requests come from a specific port. If no port
139 number is specified, the system will assign
140 one.
141
142
143 __zone zonename__
144
145
146 Specifies that all updates are to be made to the zone
147 ''zonename''. If no ''zone'' statement is provided,
148 __nsupdate__ will attempt determine the correct zone to
149 update based on the rest of the input.
150
151
152 __key name secret__
153
154
155 Specifies that all updates are to be TSIG signed using the
156 ''keyname keysecret'' pair. The __key__ command
157 overrides any key specified on the command line via
158 __-y__ or __-k__.
159
160
161 __prereq nxdomain domain-name__
162
163
164 Requires that no resource record of any type exists with
165 name ''domain-name''.
166
167
168 __prereq yxdomain domain-name__
169
170
171 Requires that ''domain-name'' exists (has as at least one
172 resource record, of any type).
173
174
175 __prereq nxrrset domain-name [[ class ]
176 type__
177
178
179 Requires that no resource record exists of the specified
180 ''type'', ''class'' and ''domain-name''. If
181 ''class'' is omitted, IN (internet) is
182 assumed.
183
184
185 __prereq yxrrset domain-name [[ class ]
186 type__
187
188
189 This requires that a resource record of the specified
190 ''type'', ''class'' and ''domain-name'' must exist.
191 If ''class'' is omitted, IN (internet) is
192 assumed.
193
194
195 __prereq yxrrset domain-name [[ class ] type
196 data__''...''
197
198
199 The ''data'' from each set of prerequisites of this form
200 sharing a common ''type'', ''class'', and
201 ''domain-name'' are combined to form a set of RRs. This
202 set of RRs must exactly match the set of RRs existing in the
203 zone at the given ''type'', ''class'', and
204 ''domain-name''. The ''data'' are written in the
205 standard text representation of the resource record's
206 RDATA.
207
208
209 __update delete domain-name [[ ttl ] [[ class ] [[ type [[
210 data__''...'' __] ]__
211
212
213 Deletes any resource records named ''domain-name''. If
214 ''type'' and ''data'' is provided, only matching
215 resource records will be removed. The internet class is
216 assumed if ''class'' is not supplied. The ''ttl'' is
217 ignored, and is only allowed for compatibility.
218
219
220 __update add domain-name ttl [[ class ] type
221 data__''...''
222
223
224 Adds a new resource record with the specified ''ttl'',
225 ''class'' and ''data''.
226
227
228 __show__
229
230
231 Displays the current message, containing all of the
232 prerequisites and updates specified since the last
233 send.
234
235
236 __send__
237
238
239 Sends the current message. This is equivalent to entering a
240 blank line.
241
242
243 Lines beginning with a semicolon are comments, and are
244 ignored.
245 !!EXAMPLES
246
247
248 The examples below show how __nsupdate__ could be used to
249 insert and delete resource records from the
250 __example.com__ zone. Notice that the input in each
251 example contains a trailing blank line so that a group of
252 commands are sent as one dynamic update request to the
253 master name server for __example.com__.
254
255
256 # nsupdate
257 Any A records for __oldhost.example.com__ are deleted. and an A record for __newhost.example.com__ it IP address 172.16.1.1 is added. The newly-added record has a 1 day TTL (86400 seconds)
258
259
260 # nsupdate
261 The prerequisite condition gets the name server to check that there are no resource records of any type for __nickname.example.com__. If there are, the update request fails. If this name does not exist, a CNAME for it is added. This ensures that when the CNAME is added, it cannot conflict with the long-standing rule in RFC1034 that a name must not exist as any other record type if it exists as a CNAME. (The rule has been updated for DNSSEC in RFC2535 to allow CNAMEs to have SIG, KEY and NXT records.)
262 !!FILES
263
264
265 __/etc/resolv.conf__
266
267
268 used to identify default name server
269
270
271 __K{name}.+157.+{random}.key__
272
273
274 base-64 encoding of HMAC-MD5 key created by
4 perry 275 dnssec-keygen(8).
1 perry 276
277
278 __K{name}.+157.+{random}.private__
279
280
281 base-64 encoding of HMAC-MD5 key created by
4 perry 282 dnssec-keygen(8).
1 perry 283 !!SEE ALSO
284
285
286 __RFC2136__, __RFC3007__, __RFC2104__,
287 __RFC2845__, __RFC1034__, __RFC2535__,
4 perry 288 named(8), dnssec-keygen(8).
1 perry 289 !!BUGS
290
291
292 The TSIG key is redundantly stored in two separate files.
293 This is a consequence of nsupdate using the DST library for
294 its cryptographic operations, and may change in future
295 releases.
296 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.