nsupdate(1m)

1nsupdate(1M)            System Administration Commands            nsupdate(1M)
2
3
4

NAME

6       nsupdate - Dynamic DNS update utility
7

SYNOPSIS

9       nsupdate [-dv] [-y keyname:secret | -k keyfile] [-t timeout]
10            [-u udptimeout] [-r udpretries] [filename]
11
12

DESCRIPTION

14       The  nsupdate utility submits Dynamic DNS Update requests as defined in
15       RFC 2136 to a name server. This utility allows resource records  to  be
16       added  or removed from a zone without manually editing the zone file. A
17       single update request can contain requests to add or remove  more  than
18       one resource record.
19
20
21       Zones  that  are  under  dynamic control with 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
25
26       The  resource  records that are dynamically added or removed with nsup‐
27       date must be in the same zone. Requests are sent to the  zone's  master
28       servers identified by the MNAME field of the zone's SOA record.
29
30
31       Transaction  signatures  can  be  used  to authenticate the Dynamic DNS
32       updates using the TSIG resource record type described in RFC 2845.  The
33       signatures  rely  on a shared secret that should only be known to nsup‐
34       date and the name server.  Currently,  the  only  supported  encryption
35       algorithm  for  TSIG  is  HMAC-MD5,  which is defined in RFC 2104. Once
36       other algorithms are defined for TSIG, applications will need to ensure
37       that  they  select  the  appropriate  algorithm as well as the key when
38       authenticating each other. For instance, suitable key and server state‐
39       ments would be added to /etc/named.conf so that the name server can as‐
40       sociate the appropriate secret key and algorithm with the IP address of
41       the  client  application  that  will  be using TSIG authentication. The
42       nsupdate utility does not read /etc/named.conf.
43
44
45       The nsupdate utility uses the -y or -k option  to  provide  the  shared
46       secret  needed to generate a TSIG record for authenticating Dynamic DNS
47       update requests. These options are mutually exclusive. See OPTIONS.
48

OPTIONS

50       The following options are supported:
51
52       -d                   Operate  in  debug  mode.  This  provides  tracing
53                            information  about  the  update  requests that are
54                            made  and  the  replies  received  from  the  name
55                            server.
56
57
58       -k keyfile           Read  the  shared  secret  from  the file keyfile,
59                            whose name  is  of  the  form  K{name}.+157.+{ran‐
60                            dom}.private.  For  historical  reasons,  the file
61                            K{name}.+157.+{random}.key must also be present.
62
63
64       -r udpretries        Set the number of UDP retries. The  default  is  3
65                            retries.  If  udpretries  is set to zero, only one
66                            update request is made.
67
68
69       -t timeout           Set timeout interval in seconds before  update  is
70                            aborted.  The default is 300 seconds. A setting of
71                            zero disables the timeout.
72
73
74       -u udptimeout        Set interval in seconds between UDP  retires,  the
75                            default is 3 seconds. A setting of zero causes the
76                            interval to be calculated  based  on  the  timeout
77                            (-t) and the number of UDP retries (-r).
78
79
80       -v                   Use a TCP connection. Using a TCP connection could
81                            be preferable when a batch of update  requests  is
82                            made. By default, nsupdate uses UDP to send update
83                            requests to the name server.
84
85
86       -y keyname:secret    Generate   a    signature   from   keyname:secret,
87                            wherekeyname  is the name of the key and secret is
88                            the base64 encoded shared secret.
89
90                            Use of the -y option is  discouraged  because  the
91                            shared  secret is supplied as a command line argu‐
92                            ment in clear text and could  be  visible  in  the
93                            output  from ps(1) or in a history file maintained
94                            by the user's shell.
95
96

INPUT FORMAT

98       The nsupdate utility reads input from filename or the  standard  input.
99       Each  command  is  supplied on exactly one line of input. Some commands
100       are for administrative purposes. The others are either update  instruc‐
101       tions  or prerequisite checks on the contents of the zone. These checks
102       set conditions that some name or set of resource records (RRset) either
103       exists  or is absent from the zone. These conditions must be met if the
104       entire update request is to succeed. Updates will be  rejected  if  the
105       tests for the prerequisite conditions fail.
106
107
108       Every update request consists of zero or more prerequisites and zero or
109       more updates. This condition allows  a  suitably  authenticated  update
110       request  to  proceed  if some specified resource records are present or
111       missing from the zone. A blank input line (or the send command)  causes
112       the  accumulated  commands to be sent as one Dynamic DNS update request
113       to the name server.
114
115
116       The command formats and their meaning are as follows:
117
118       server servername [ port ]
119
120           Send all dynamic update requests to  the  name  server  servername.
121           When no server statement is provided, nsupdate sends updates to the
122           master server of the correct zone. The MNAME field of  that  zone's
123           SOA  record  identifies  the  master server for that zone. The port
124           argument is the port number on servername where the dynamic  update
125           requests  get sent. If no port number is specified, the default DNS
126           port number of 53 is used.
127
128
129       local address [ port ]
130
131           Send all dynamic update requests using the local address.  When  no
132           local  statement  is  provided,  nsupdate  sends  updates  using an
133           address and port chosen by the system. The port argument  can  also
134           be used to make requests come from a specific port. If no port num‐
135           ber is specified, the system assigns one.
136
137
138       zone zonename
139
140           Specify that all updates are to be made to the zone zonename. If no
141           zone statement is provided, nsupdate attempts to determine the cor‐
142           rect zone to update based on the rest of the input.
143
144
145       class classname
146
147           Specify the default class. If no class  is  specified  the  default
148           class is IN.
149
150
151       key name secret
152
153           Specify  that  all  updates  are  to  be TSIG signed using the name
154           secret pair. The key command overrides any  key  specified  on  the
155           command line with -y or -k.
156
157
158       prereq nxdomain domain-name
159
160           Require  that  no  resource  record of any type exists withthe name
161           domain-name.
162
163
164       prereq yxdomain domain-name
165
166           Require that domain-name exists  (has  as  at  least  one  resource
167           record, of any type).
168
169
170       prereq nxrrset domain-name [ class ]  type
171
172           Require that no resource record exists of the specified type, class
173           and domain-name. If class is omitted, IN (internet) is assumed.
174
175
176       prereq yxrrset domain-name [ class ]  type
177
178           Require that a resource record of the  specified  type,  class  and
179           domain-name  must  exist.  If  class  is  omitted, IN (internet) is
180           assumed.
181
182
183       prereq yxrrset domain-name [ class ]  type data...
184
185           The data from each set of prerequisites of this form sharing a com‐
186           mon type, class, and domain-name are combined to form a set of RRs.
187           This set of RRs must exactly match the set of RRs existing  in  the
188           zone  at the given type, class, and domain-name. The data are writ‐
189           ten in the standard text representation of  the  resource  record's
190           RDATA.
191
192
193       update delete domain-name [ ttl ]  [ class ]  [ type  [ data... ] ]
194
195           Delete any resource records named domain-name. If type and data are
196           provided, only matching resource records are removed. The  internet
197           class  is assumed if class is not supplied. The ttl is ignored, and
198           is only provided for compatibility.
199
200
201       update add domain-name ttl [ class ]  type data...
202
203           Add a new resource record with the specified ttl, class and data.
204
205
206       show
207
208           Display the current message, containing all  of  the  prerequisites
209           and updates specified since the last send.
210
211
212       send
213
214           Sends  the  current message. This is equivalent to entering a blank
215           line.
216
217
218       answer
219
220           Displays the answer.
221
222
223
224       Lines beginning with a semicolon are comments and are ignored.
225

EXAMPLES

227       Example 1 Inserting and Deleting Resource Records from the Zone
228
229
230       The examples below show how nsupdate could be used to insert and delete
231       resource  records  from  the example.com zone. Notice that the input in
232       each example contains a trailing blank line so that a group of commands
233       are  sent  as  one dynamic update request to the master name server for
234       example.com.
235
236
237         # nsupdate
238         > update delete oldhost.example.com A
239         > update add newhost.example.com 86400 A 172.16.1.1
240         > send
241
242
243
244
245       Any A records for oldhost.example.com are  deleted.  An  A  record  for
246       newhost.example.com  with  IP  address  172.16.1.1 is added. The newly-
247       added record has a 1 day TTL (86400 seconds).
248
249
250       Example 2 Adding CNAME Only If No Records Exist
251
252
253       The following command adds a CNAME only if no records already exist for
254       it.
255
256
257         # nsupdate
258         > prereq nxdomain nickname.example.com
259         > update add nickname.example.com 86400 CNAME somehost.example.com
260         > send
261
262
263
264
265       The prerequisite condition gets the name server to check that there are
266       no resource records of any type for nickname.example.com. If there are,
267       the  update  request fails. If this name does not exist, a CNAME for it
268       is added. This action ensures that when the CNAME is added,  it  cannot
269       conflict  with  the long-standing rule in RFC 1034 that a name must not
270       exist as any other record type if it exists as a CNAME. (The  rule  has
271       been  updated  for  DNSSEC  in  RFC  4035 to allow CNAMEs to have RSIG,
272       DNSKEY, and NSEC records.)
273
274

FILES

276       /etc/resolv.conf
277
278           used to identify default name server
279
280
281       K{name}.+157.+{random}.key
282
283           base-64 encoding of HMAC-MD5 key created by dnssec-keygen(1M).
284
285
286       K{name}.+157.+{random}.private
287
288           base-64 encoding of HMAC-MD5 key created by dnssec-keygen(1M)
289
290

BUGS

292       The TSIG key is redundantly stored in two separate  files.  This  is  a
293       consequence  of  nsupdate  using  the DST library for its cryptographic
294       operations and could change in future releases.
295

ATTRIBUTES

297       See attributes(5) for descriptions of the following attributes:
298
299
300
301
302       ┌─────────────────────────────┬─────────────────────────────┐
303       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
304       ├─────────────────────────────┼─────────────────────────────┤
305       │Availability                 │SUNWbind                     │
306       ├─────────────────────────────┼─────────────────────────────┤
307       │Interface Stability          │External                     │
308       └─────────────────────────────┴─────────────────────────────┘
309