nsupdate.8 9.77 KB
Newer Older
Andreas Gustafsson's avatar
Andreas Gustafsson committed
1
.\"
Brian Wellington's avatar
Brian Wellington committed
2
.\" Copyright (C) 2000, 2001  Internet Software Consortium.
3
.\"
4 5 6
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
7
.\"
8
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
9 10 11 12 13 14 15
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
Andreas Gustafsson's avatar
Andreas Gustafsson committed
16
.\"
17 18 19 20 21 22 23 24 25
.TH "NSUPDATE" "8" "Jun 30, 2000" "BIND9" ""
.SH NAME
nsupdate \- Dynamic DNS update utility
.SH SYNOPSIS
.sp
\fBnsupdate\fR [ \fB-d\fR ]  [ \fB [ -y \fIkeyname:secret\fB ]  [ -k \fIkeyfile\fB ] \fR ]  [ \fB-v\fR ]  [ \fBfilename\fR ] 
.SH "DESCRIPTION"
.PP
\fBnsupdate\fR
26 27 28 29
is used to submit Dynamic DNS Update requests as defined in RFC2136
to a name server.
This allows resource records to be added or removed from a zone
without manually editing the zone file.
Andreas Gustafsson's avatar
Andreas Gustafsson committed
30
A single update request can contain requests to add or remove more than one
31
resource record.
32
.PP
33
Zones that are under dynamic control via
34
\fBnsupdate\fR
35 36
or a DHCP server should not be edited by hand.
Manual edits could
Andreas Gustafsson's avatar
Andreas Gustafsson committed
37
conflict with dynamic updates and cause data to be lost.
38
.PP
Andreas Gustafsson's avatar
Andreas Gustafsson committed
39
The resource records that are dynamically added or removed with
40
\fBnsupdate\fR
41 42 43
have to be in the same zone.
Requests are sent to the zone's master server.
This is identified by the MNAME field of the zone's SOA record.
44
.PP
45
The
46
\fB-d\fR
47
option makes
48
\fBnsupdate\fR
49 50 51
operate in debug mode.
This provides tracing information about the update requests that are
made and the replies received from the name server.
52
.PP
53 54 55 56
Transaction signatures can be used to authenticate the Dynamic DNS
updates.
These use the TSIG resource record type described in RFC2845.
The signatures rely on a shared secret that should only be known to
57
\fBnsupdate\fR
58
and the name server.
59
Currently, the only supported encryption algorithm for TSIG is
60 61 62 63
HMAC-MD5, which is defined in RFC 2104.
Once other algorithms are defined for TSIG, applications will need to
ensure they select the appropriate algorithm as well as the key when
authenticating each other.
64
For instance suitable
65
\fBkey\fR
66
and
67
\fBserver\fR
68
statements would be added to
69
\fI/etc/named.conf\fR
70 71
so that the name server can associate the appropriate secret key
and algorithm with the IP address of the
72
client application that will be using TSIG authentication.
73
\fBnsupdate\fR
74
does not read
75 76 77
\fI/etc/named.conf\fR.
.PP
\fBnsupdate\fR
78
uses the
79
\fB-y\fR
Andreas Gustafsson's avatar
Andreas Gustafsson committed
80
or
81
\fB-k\fR
Andreas Gustafsson's avatar
Andreas Gustafsson committed
82
option to provide the shared secret needed to generate a TSIG record
83 84
for authenticating Dynamic DNS update requests.
These options are mutually exclusive.
Andreas Gustafsson's avatar
Andreas Gustafsson committed
85
With the
86
\fB-k\fR
Andreas Gustafsson's avatar
Andreas Gustafsson committed
87
option,
88
\fBnsupdate\fR
Andreas Gustafsson's avatar
Andreas Gustafsson committed
89
reads the shared secret from the file
90
\fIkeyfile\fR,
Andreas Gustafsson's avatar
Andreas Gustafsson committed
91
whose name is of the form 
92
\fIK{name}.+157.+{random}.private\fR.
Andreas Gustafsson's avatar
Andreas Gustafsson committed
93 94
For historical
reasons, the file 
95 96 97
\fIK{name}.+157.+{random}.key\fR
must also be present. When the
\fB-y\fR
Andreas Gustafsson's avatar
Andreas Gustafsson committed
98
option is used, a signature is generated from
99 100
\fIkeyname:secret.\fR
\fIkeyname\fR
101 102
is the name of the key,
and
103
\fIsecret\fR
Andreas Gustafsson's avatar
Andreas Gustafsson committed
104
is the base64 encoded shared secret.
105
Use of the
106
\fB-y\fR
107 108 109
option is discouraged because the shared secret is supplied as a command
line argument in clear text.
This may be visible in the output from
110
\fBps\fR(1)
111
or in a history file maintained by the user's shell.
112
.PP
113
By default
114
\fBnsupdate\fR
115 116
uses UDP to send update requests to the name server.
The
117
\fB-v\fR
118
option makes
119
\fBnsupdate\fR
120
use a TCP connection.
Andreas Gustafsson's avatar
Andreas Gustafsson committed
121
This may be preferable when a batch of update requests is made.
122 123 124
.SH "INPUT FORMAT"
.PP
\fBnsupdate\fR
125
reads input from
126
\fIfilename\fR
127
or standard input.
128
Each command is supplied on exactly one line of input.
129 130
Some commands are for administrative purposes.
The others are either update instructions or prerequisite checks on the
131 132 133 134 135
contents of the zone.
These checks set conditions that some name or set of
resource records (RRset) either exists or is absent from the zone.
These conditions must be met if the entire update request is to succeed.
Updates will be rejected if the tests for the prerequisite conditions fail.
136
.PP
137
Every update request consists of zero or more prerequisites
Andreas Gustafsson's avatar
Andreas Gustafsson committed
138
and zero or more updates.
139
This allows a suitably authenticated update request to proceed if some
140
specified resource records are present or missing from the zone.
Brian Wellington's avatar
regen  
Brian Wellington committed
141
A blank input line (or the \fBsend\fR command) causes the
Brian Wellington's avatar
Brian Wellington committed
142 143
accumulated commands to be sent as one Dynamic DNS update request to the
name server.
144
.PP
145
The command formats and their meaning are as follows:
146
.TP
147
\fBserver servername [ port ]\fR
148
Sends all dynamic update requests to the name server
149
\fIservername\fR.
150
When no server statement is provided,
151
\fBnsupdate\fR
152 153 154
will send updates to the master server of the correct zone.
The MNAME field of that zone's SOA record will identify the master
server for that zone.
155
\fIport\fR
156
is the port number on
157
\fIservername\fR
158 159 160
where the dynamic update requests get sent.
If no port number is specified, the default DNS port number of 53 is
used.
161
.TP
162
\fBlocal address [ port ]\fR
Mark Andrews's avatar
Mark Andrews committed
163
Sends all dynamic update requests using the local
164
\fIaddress\fR.
Mark Andrews's avatar
Mark Andrews committed
165
When no local statement is provided,
166
\fBnsupdate\fR
Mark Andrews's avatar
Mark Andrews committed
167
will send updates using an address and port choosen by the system.
168
\fIport\fR
Mark Andrews's avatar
Mark Andrews committed
169 170
can additionally be used to make requests come from a specific port.
If no port number is specified, the system will assign one.
171
.TP
172
\fBzone zonename\fR
173
Specifies that all updates are to be made to the zone
174
\fIzonename\fR.
Andreas Gustafsson's avatar
Andreas Gustafsson committed
175
If no
176
\fIzone\fR
Andreas Gustafsson's avatar
Andreas Gustafsson committed
177
statement is provided,
178
\fBnsupdate\fR
Andreas Gustafsson's avatar
Andreas Gustafsson committed
179
will attempt determine the correct zone to update based on the rest of the input.
180
.TP
181 182 183 184 185 186 187
\fBkey name secret\fR
Specifies that all updates are to be TSIG signed using the
\fIkeyname\fR \fIkeysecret\fR pair.
The \fBkey\fR command
overrides any key specified on the command line via
\fB-y\fR or \fB-k\fR.
.TP
188
\fBprereq nxdomain domain-name\fR
189
Requires that no resource record of any type exists with name
190 191
\fIdomain-name\fR.
.TP
192
\fBprereq yxdomain domain-name\fR
193
Requires that
194
\fIdomain-name\fR
Andreas Gustafsson's avatar
Andreas Gustafsson committed
195
exists (has as at least one resource record, of any type).
196
.TP
197
\fBprereq nxrrset domain-name [ class ]  type\fR
198
Requires that no resource record exists of the specified
199 200
\fItype\fR,
\fIclass\fR
201
and
202
\fIdomain-name\fR.
203
If
204
\fIclass\fR
205
is omitted, IN (internet) is assumed.
206
.TP
207
\fBprereq yxrrset domain-name [ class ]  type\fR
Andreas Gustafsson's avatar
Andreas Gustafsson committed
208
This requires that a resource record of the specified
209 210
\fItype\fR,
\fIclass\fR
Andreas Gustafsson's avatar
Andreas Gustafsson committed
211
and
212
\fIdomain-name\fR
213 214
must exist.
If
215
\fIclass\fR
216
is omitted, IN (internet) is assumed.
217
.TP
218
\fBprereq yxrrset domain-name [ class ]  type data\fI...\fB\fR
Andreas Gustafsson's avatar
Andreas Gustafsson committed
219
The
220
\fIdata\fR
Andreas Gustafsson's avatar
Andreas Gustafsson committed
221 222
from each set of prerequisites of this form
sharing a common
223 224
\fItype\fR,
\fIclass\fR,
Andreas Gustafsson's avatar
Andreas Gustafsson committed
225
and 
226 227
\fIdomain-name\fR
are combined to form a set of RRs. This set of RRs must
Andreas Gustafsson's avatar
Andreas Gustafsson committed
228 229
exactly match the set of RRs existing in the zone at the
given 
230 231
\fItype\fR,
\fIclass\fR,
Andreas Gustafsson's avatar
Andreas Gustafsson committed
232
and 
233
\fIdomain-name\fR.
Andreas Gustafsson's avatar
Andreas Gustafsson committed
234
The
235
\fIdata\fR
Andreas Gustafsson's avatar
Andreas Gustafsson committed
236
are written in the standard text representation of the resource record's
237
RDATA.
238
.TP
239
\fBupdate delete domain-name [ ttl ]  [ class ]  [ type  [ data\fI...\fB ]  ]\fR
240
Deletes any resource records named
241
\fIdomain-name\fR.
242
If
243
\fItype\fR
244
and
245
\fIdata\fR
246 247
is provided, only matching resource records will be removed.
The internet class is assumed if
248
\fIclass\fR
Brian Wellington's avatar
updates  
Brian Wellington committed
249 250 251
is not supplied. The
\fIttl\fR
is ignored, and is only allowed for compatibility.
252
.TP
253
\fBupdate add domain-name ttl [ class ]  type data\fI...\fB\fR
254
Adds a new resource record with the specified
255 256
\fIttl\fR,
\fIclass\fR
257
and
258
\fIdata\fR.
Brian Wellington's avatar
Brian Wellington committed
259 260 261 262 263 264 265
.TP
\fBshow\fR
Displays the current message, containing all of the prerequisites and
updates specified since the last send.
.TP
\fBsend\fR
Sends the current message. This is equivalent to entering a blank line.
Brian Wellington's avatar
updates  
Brian Wellington committed
266 267
.PP
Lines beginning with a semicolon are comments, and are ignored.
268 269
.SH "EXAMPLES"
.PP
270
The examples below show how
271
\fBnsupdate\fR
272
could be used to insert and delete resource records from the
273
\fBexample.com\fR
274 275 276
zone.
Notice that the input in each example contains a trailing blank line so that
a group of commands are sent as one dynamic update request to the
277
master name server for
278 279 280
\fBexample.com\fR.
.sp
.nf
281 282 283 284
# nsupdate
> update delete oldhost.example.com A
> update add newhost.example.com 86400 A 172.16.1.1
>
285 286 287
.sp
.fi
.PP
288
Any A records for
289
\fBoldhost.example.com\fR
290 291
are deleted.
and an A record for
292
\fBnewhost.example.com\fR
293 294
it IP address 172.16.1.1 is added.
The newly-added record has a 1 day TTL (86400 seconds)
295 296
.sp
.nf
297 298 299 300
# nsupdate
> prereq nxdomain nickname.example.com
> update add nickname.example.com CNAME somehost.example.com
>
301 302 303
.sp
.fi
.PP
304 305
The prerequisite condition gets the name server to check that there
are no resource records of any type for
306
\fBnickname.example.com\fR.
307 308 309 310 311 312 313
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.)
314 315 316
.SH "FILES"
.TP
\fB/etc/resolv.conf\fR
Andreas Gustafsson's avatar
Andreas Gustafsson committed
317
used to identify default name server
318 319
.TP
\fBK{name}.+157.+{random}.key\fR
320
base-64 encoding of HMAC-MD5 key created by
321 322 323
\fBdnssec-keygen\fR(8).
.TP
\fBK{name}.+157.+{random}.private\fR
324
base-64 encoding of HMAC-MD5 key created by
325 326 327 328
\fBdnssec-keygen\fR(8).
.SH "SEE ALSO"
.PP
\fBRFC2136\fR,
329
\fBRFC3007\fR,
330 331 332 333 334 335 336 337
\fBRFC2104\fR,
\fBRFC2845\fR,
\fBRFC1034\fR,
\fBRFC2535\fR,
\fBnamed\fR(8),
\fBdnssec-keygen\fR(8).
.SH "BUGS"
.PP
Andreas Gustafsson's avatar
Andreas Gustafsson committed
338 339 340 341
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
releases.