contrib/bind/doc/man/nsupdate.8

   1 .\" $Id: nsupdate.8,v 8.4 1999/10/17 06:26:18 cyarnell Exp $
   2 .\"
   3 .\"Copyright (c) 1999 by Internet Software Consortium
   4 .\"
   5 .\"Permission to use, copy, modify, and distribute this software for any
   6 .\"purpose with or without fee is hereby granted, provided that the above
   7 .\"copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\"THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS
  10 .\"ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
  11 .\"OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE
  12 .\"CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
  13 .\"DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
  14 .\"PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
  15 .\"ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
  16 .\"SOFTWARE.
  17 .Dd March 5, 1999
  18 .Dt NSUPDATE @SYS_OPS_EXT_U@
  19 .Os BSD 4
  20 .Sh NAME
  21 .Nm nsupdate
  22 .Nd update Internet name servers interactively
  23 .Sh SYNOPSIS
  24 .Nm nsupdate
  25 .Op Fl Ar k  keydir:keyname
  26 .Op Fl Ar d
  27 .Op Fl Ar v
  28 .Op Ar filename
  29 .Sh DESCRIPTION
  30 .Ic Nsupdate
  31 is a program to update Internet domain name servers
  32 supporting dynamic update.
  33 .Ic Nsupdate
  34 uses the DNS resolver library to pass messages
  35 to a DNS server requesting the additional or deletion of
  36 DNS resource records (RRs).
  37 .Ic Nsupdate
  38 reads input from
  39 .Ar filename
  40 or standard input.
  41 .Sh ARGUMENTS
  42 .Bl -tag -width Fl
  43 .It Fl k
  44 Sign updates with TSIG.
  45 .It Fl d
  46 Debug mode.
  47 .It Fl v
  48 Virtual circuit - use TCP to communication with server.
  49 Default is UDP.
  50 .Sh INPUT FORMAT
  51 .Ic Nsupdate
  52 reads input records, one per line,
  53 each line contributing a resource record to an
  54 update request.
  55 All domain names used in a single update request
  56 must belong to the same DNS zone.
  57 A blank line causes the accumulated
  58 records to be formated into a single update request
  59 and transmitted to the zone's authoritative name servers.
  60 Additional records may follow,
  61 which are formed into additional,
  62 completely independent update requests.
  63 For the last request to be transmitted, a blank line
  64 must end the input.
  65 .Pp
  66 Records take one of two general forms.
  67 .Em Prerequisite
  68 records specify conditions that must be satisfied before
  69 the request will be processed.
  70 .Em Update
  71 records specify changes to be made to the DNS database.
  72 A update request consists of zero or more prerequisites
  73 and one or more updates.
  74 Each update request is processed atomically -
  75 all prerequisites must be satisfied, then all updates
  76 will be performed.
  77 .Pp
  78 .Ic Nsupdate
  79 understands the following input record formats:
  80 .Pp
  81
  82 .Bl -ohang
  83
  84 .It Ic prereq nxdomain Va domain-name
  85 Requires that no RR of any type exists with name
  86 .Va domain-name .
  87
  88 .It Ic prereq yxdomain Va domain-name
  89 Requires that at least one RR named
  90 .Va domain-name
  91 must exist.
  92
  93 .It Xo
  94 .Ic prereq nxrrset Va domain-name Op class
  95 .Va type
  96 .Xc
  97 Requires that no RR exists of the specified
  98 .Va type
  99 and
 100 .Va domain-name .
 101
 102 .It Xo
 103 .Ic prereq yxrrset
 104 .Va domain-name Op class
 105 .Va type Op data...
 106 .Xc
 107 Requires that a RR exists of the specified
 108 .Va type
 109 and
 110 .Va domain-name .
 111 If
 112 .Va data
 113 is specified, it must match exactly.
 114
 115 .It Xo
 116 .Ic update delete
 117 .Va domain-name Op class
 118 .Va Op type Op data...
 119 .Xc
 120 Deletes RRs named
 121 .Va domain-name .
 122 If
 123 .Va type
 124 (and possibly
 125 .Va data )
 126 is specified,
 127 only matching records will be deleted.
 128
 129 .It Xo
 130 .Ic update add
 131 .Va domain-name ttl Op class
 132 .Va type data...
 133 .Xc
 134 Adds a new RR with specified
 135 .Va ttl , type ,
 136 and
 137 .Va data .
 138
 139 .El
 140
 141 .Sh EXAMPLES
 142 The following example illustrates the interactive use of
 143 .Ic nsupdate
 144 to change an IP address by deleting any existing A records
 145 for a domain name and then inserting a new one.
 146 Since no prerequisites are specified,
 147 the new record will be added even if
 148 there were no existing records to delete.
 149 Note the
 150 trailing blank line, required to process the request.
 151 .Bd -literal -offset indent
 152 $ nsupdate
 153 > update delete test.example.com A
 154 > update add test.example.com 3600 A 10.1.1.1
 155 >
 156
 157 .Ed
 158 .Pp
 159 In this example, a CNAME alias is added to the database
 160 only if there are no existing A or CNAME records for
 161 the domain name.
 162 .Bd -literal -offset indent
 163 $ nsupdate
 164 > prereq nxrrset www.example.com A
 165 > prereq nxrrset www.example.com CNAME
 166 > update add www.example.com 3600 CNAME test.example.com
 167 >
 168
 169 .Ed
 170 .Pp
 171 In this example, the nsupdate will be signed with the key "mykey", which
 172 is in the directory "/var/named/keys".
 173 .Bd -literal -offset indent
 174 $ nsupdate -k /var/named/keys:mykey
 175 > update add ftp.example.com 60 A 192.168.5.1
 176 >
 177
 178 .Ed
 179
 180 .Sh DIAGNOSTICS
 181 .Bl -ohang
 182
 183 .It Qq send error
 184 Typically indicates that the authoritative nameservers could not be reached
 185
 186 .It Qq failed update packet
 187 Typically indicates that the nameserver has rejected the update,
 188 either because the nameserver doesn't support dynamic update,
 189 or due to an authentication failure
 190
 191 .It Qq res_mkupdate: packet size = Va size
 192 (and no other messages)
 193 The update was successfully received and authenticated by the nameserver.
 194 The prerequisites, however, may have prevented the update from actually
 195 being performed.  The only way to determine if the update was performed
 196 is to use debug mode
 197 .Fl ( d )
 198 and examine the status field in the nameserver's reply.
 199
 200 .Sh FILES
 201 .It Pa /etc/resolv.conf
 202 initial domain name and name server addresses
 203 .Sh SEE ALSO
 204 .Xr @INDOT@named @SYS_OPS_EXT@ ,
 205 .Xr resolver @LIB_NETWORK_EXT@ ,
 206 .Xr resolver @FORMAT_EXT@ ;
 207 RFC-1034,
 208 .Dq Domain Names - Concepts and Facilities ;
 209 RFC-1035,
 210 .Dq Domain Names - Implementation and Specification ;
 211 RFC-2136,
 212 Dynamic Updates in the Domain Name System.
 213 .Sh AUTHOR
 214 Brent Baccala