contrib/bind9/bin/nsupdate/nsupdate.8

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