| blob | 9f0d7e827667e5929991f443e75d7e0fcb4949cf |
1 .\" $NetBSD: nslookup.8,v 1.2 2009/10/14 19:08:55 joerg Exp $
2 .\"
3 .\"
4 .\" ++Copyright++ 1985, 1989
5 .\" -
6 .\" Copyright (c) 1985, 1989
7 .\" The Regents of the University of California. All rights reserved.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\" 3. Neither the name of the University nor the names of its contributors
18 .\" may be used to endorse or promote products derived from this software
19 .\" without specific prior written permission.
20 .\"
21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .\" SUCH DAMAGE.
32 .\" -
33 .\" Portions Copyright (c) 1993 by Digital Equipment Corporation.
34 .\"
35 .\" Permission to use, copy, modify, and distribute this software for any
36 .\" purpose with or without fee is hereby granted, provided that the above
37 .\" copyright notice and this permission notice appear in all copies, and that
38 .\" the name of Digital Equipment Corporation not be used in advertising or
39 .\" publicity pertaining to distribution of the document or software without
40 .\" specific, written prior permission.
41 .\"
42 .\" THE SOFTWARE IS PROVIDED "AS IS" AND DIGITAL EQUIPMENT CORP. DISCLAIMS ALL
43 .\" WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES
44 .\" OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL DIGITAL EQUIPMENT
45 .\" CORPORATION BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
46 .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
47 .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
48 .\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
49 .\" SOFTWARE.
50 .\" -
51 .\" --Copyright--
52 .\"
53 .\" @(#)nslookup.8 5.3 (Berkeley) 6/24/90
54 .\"
55 .Dd June 24, 1990
56 .Dt NSLOOKUP 8
57 .Os
58 .Sh NAME
59 .Nm nslookup
60 .Nd query Internet name servers interactively
61 .Sh SYNOPSIS
62 .Nm nslookup
63 .Op Fl option Ar ...
64 .Op Ar host-to-find | Fl Op Ar server
65 .Sh DESCRIPTION
66 .Nm
67 is a program to query Internet domain name servers.
68 .Nm
69 has two modes: interactive and non-interactive.
70 Interactive mode allows the user to query name servers for
71 information about various hosts and domains or to print a list of hosts
72 in a domain.
73 Non-interactive mode is used to print just the name and requested information
74 for a host or domain.
75 .Sh ARGUMENTS
76 Interactive mode is entered in the following cases:
77 .Bl -enum
78 .It
79 when no arguments are given (the default name server will be used),
80 .It
81 when the first argument is a hyphen
82 .Pq Sq \&-
83 and the second argument
84 is the host name or Internet address of a name server.
85 .El
86 .Pp
87 Non-interactive mode is used when the name or Internet address
88 of the host to be looked up
89 is given as the first argument.
90 The optional second argument specifies
91 the host name or address of a name server.
92 .Pp
93 The options listed under the
94 .Dq Li set
95 command below can be specified in
96 the
97 .Pa .nslookuprc
98 file in the user's home directory if they are listed
99 one per line.
100 Options can also be specified on the command line if they precede
101 the arguments and are prefixed with a hyphen.
102 For example, to change the default query type to host information,
103 and the initial timeout to 10 seconds, type:
104 .Bd -literal -offset indent
105 nslookup -query=hinfo -timeout=10
106 .Ed
107 .Sh INTERACTIVE COMMANDS
108 Commands may be interrupted at any time by typing a control-C.
109 To exit, type a control-D
110 .Pq Dv EOF
111 or type
112 .Li exit .
113 The command line length must be less than 256 characters.
114 To treat a built-in command as a host name,
115 precede it with an escape character
116 .Pq Sq \e .
117 .Em N.B.: An unrecognized command will be interpreted as a host name.
118 .Bl -tag -width "lserver"
119 .It Ar host Op Ar server
120 Look up information for
121 .Ar host
122 using the current default server or using
123 .Ar server ,
124 if specified.
125 If
126 .Ar host
127 is an Internet address and the query type is
128 .Dv A
129 or
130 .Dv PTR ,
131 the name of the host is returned.
132 If
133 .Ar host
134 is a name and does not have a trailing period, the default
135 domain name is appended to the name.
136 (This behavior depends on the state of the
137 .Ic set
138 options
139 .Ic domain , srchlist , defname ,
140 and
141 .Ic search . )
142 .Pp
143 To look up a host not in the current domain, append a period to
144 the name.
145 .It Ic server Ar domain
146 .It Ic lserver Ar domain
147 Change the default server to
148 .Ar domain ;
149 .Ic lserver
150 uses the initial server to look up information about
151 .Ar domain ,
152 while
153 .Ic server
154 uses the current default server.
155 If an authoritative answer can't be found, the names of servers
156 that might have the answer are returned.
157 .It Ic root
158 Changes the default server to the server for the root of the domain name space.
159 Currently, the host
160 .Li ns.internic.net
161 is used.
162 (This command is a synonym for
163 .Dq Ic lserver ns.internic.net . )
164 The name of the root server can be changed with the
165 .Dq Ic set root
166 command.
167 .It Ic finger Oo Ar name Oc Op Ic \*[Gt] Ar filename
168 .It Ic finger Oo Ar name Oc Op Ic \*[Gt]\*[Gt] Ar filename
169 Connects with the finger server on the current host.
170 The current host is defined when a previous lookup for a host
171 was successful and returned address information (see the
172 .Dq Ic set querytype Ns = Ns Dv A
173 command).
174 The
175 .Ar name
176 is optional.
177 .Ic \*[Gt]
178 and
179 .Ic \*[Gt]\*[Gt]
180 can be used to redirect output in the usual manner.
181 .It Ic ls Oo Ar option Oc Ar domain Op Ic \*[Gt] Ar filename
182 .It Ic ls Oo Ar option Oc Ar domain Op Ic \*[Gt]\*[Gt] Ar filename
183 List the information available for
184 .Ar domain ,
185 optionally creating or appending to
186 .Ar filename .
187 The default output contains host names and their Internet addresses.
188 .Ar Option
189 can be one of the following:
190 .Bl -tag -width "-a "
191 .It Fl t Ar querytype
192 lists all records of the specified type (see
193 .Ar querytype
194 below).
195 .It Fl a
196 lists aliases of hosts in the domain;
197 synonym for
198 .Dq Fl t Dv CNAME .
199 .It Fl d
200 lists all records for the domain;
201 synonym for
202 .Dq Fl t Dv ANY .
203 .It Fl h
204 lists CPU and operating system information for the domain;
205 synonym for
206 .Dq Fl t Dv HINFO .
207 .It Fl s
208 lists well-known services of hosts in the domain;
209 synonym for
210 .Dq Fl t Dv WKS .
211 .El
212 .Pp
213 When output is directed to a file, hash marks are printed for every
214 50 records received from the server.
215 .It Ic view Ar filename
216 Sorts and lists the output of previous
217 .Ic ls
218 command(s) with
219 .Xr more 1 .
220 .It Ic help
221 .It Ic ?\&
222 Prints a brief summary of commands.
223 .It Ic exit
224 Exits the program.
225 .It Ic set Ar keyword Ns Op = Ns Ar value
226 This command is used to change state information that affects the lookups.
227 Valid keywords are:
228 .Bl -tag -width "class=v"
229 .It Ic all
230 Prints the current values of the frequently-used options to
231 .Ic set .
232 Information about the current default server and host is also printed.
233 .It Ic class Ns = Ns Ar value
234 Change the query class to one of:
235 .Bl -tag -width "HESIOD "
236 .It Dv IN
237 the Internet class
238 .It Dv CHAOS
239 the Chaos class
240 .It Dv HESIOD
241 the MIT Athena Hesiod class
242 .It Dv ANY
243 wildcard (any of the above)
244 .El
245 .Pp
246 The class specifies the protocol group of the information.
247 .Pp
248 (Default =
249 .Dv IN ;
250 abbreviation =
251 .Ic cl )
252 .It Oo Ic no Oc Ns Ic debug
253 Turn debugging mode on.
254 A lot more information is printed about the
255 packet sent to the server and the resulting answer.
256 .Pp
257 (Default =
258 .Ic nodebug ;
259 abbreviation =
260 .Oo Ic no Oc Ns Ic deb )
261 .It Oo Ic no Oc Ns Ic d2
262 Turn exhaustive debugging mode on.
263 Essentially all fields of every packet are printed.
264 .Pp
265 (Default =
266 .Ic nod2 )
267 .It Ic domain Ns = Ns Ar name
268 Change the default domain name to
269 .Ar name .
270 The default domain name is appended to a lookup request depending on the
271 state of the
272 .Ic defname
273 and
274 .Ic search
275 options.
276 The domain search list contains the parents of the default domain if it has
277 at least two components in its name.
278 For example, if the default domain
279 is CC.Berkeley.EDU, the search list is CC.Berkeley.EDU and Berkeley.EDU.
280 Use the
281 .Dq Ic set srchlist
282 command to specify a different list.
283 Use the
284 .Dq Ic set all
285 command to display the list.
286 .Pp
287 (Default = value from
288 .Xr hostname 1 ,
289 .Pa /etc/resolv.conf ,
290 or
291 .Ev LOCALDOMAIN ;
292 abbreviation =
293 .Ic do )
294 .It Ic srchlist Ns No = Ns Ar name1 Ns No / Ns Ar name2 Ns No / Ns Ar ...
295 Change the default domain name to
296 .Ar name1
297 and the domain search list
298 to
299 .Ar name1 , name2 ,
300 etc.
301 A maximum of 6 names separated by slashes
302 .Pq Sq /
303 can be specified.
304 For example,
305 .Bd -literal -offset indent
306 set srchlist=lcs.MIT.EDU/ai.MIT.EDU/MIT.EDU
307 .Ed
308 .Pp
309 sets the domain to lcs.MIT.EDU and the search list to the three names.
310 This command overrides the
311 default domain name and search list of the
312 .Dq Ic set domain
313 command.
314 Use the
315 .Dq Ic set all
316 command to display the list.
317 .Pp
318 (Default = value based on
319 .Xr hostname 1 ,
320 .Pa /etc/resolv.conf ,
321 or
322 .Ev LOCALDOMAIN ;
323 abbreviation =
324 .Ic srchl )
325 .It Oo Ic no Oc Ns Ic defname
326 If set, append the default domain name to a single-component lookup request
327 (i.e., one that does not contain a period).
328 .Pp
329 (Default =
330 .Ic defname ;
331 abbreviation =
332 .Oo Ic no Oc Ns Ic defname )
333 .It Oo Ic no Oc Ns Ic search
334 If the lookup request contains at least one period but
335 .Em doesn't
336 end with a trailing period, append the domain names in the domain search list
337 to the request until an answer is received.
338 .Pp
339 (Default =
340 .Ic search ;
341 abbreviation =
342 .Oo Ic no Oc Ns Ic sea )
343 .It Ic port Ns = Ns Ar value
344 Change the default TCP/UDP name server port to
345 .Ar value .
346 .Pp
347 (Default = 53;
348 abbreviation =
349 .Ic \&po )
350 .It Ic querytype Ns = Ns Ar value
351 .It Ic type Ns = Ns Ar value
352 Change the type of information query to one of:
353 .Bl -tag -width "HINFO "
354 .It Dv A
355 the host's Internet address.
356 .It Dv CNAME
357 the canonical name for an alias.
358 .It Dv HINFO
359 the host CPU and operating system type.
360 .It Dv MINFO
361 the mailbox or mail list information.
362 .It Dv MX
363 the mail exchanger.
364 .It Dv NS
365 the name server for the named zone.
366 .It Dv PTR
367 the host name if the query is an Internet address;
368 otherwise, the pointer to other information.
369 .It Dv SOA
370 the domain's
371 .Dq start-of-authority
372 information.
373 .It Dv TXT
374 the text information.
375 .It Dv UINFO
376 the user information.
377 .It Dv WKS
378 the supported well-known services.
379 .El
380 .Pp
381 Other types
382 .Dv ( ANY , AXFR , MB ,
383 .Dv MD , MF , NULL )
384 are described in the RFC-1035 document.
385 .Pp
386 (Default =
387 .Dv A ;
388 abbreviations =
389 .Ic q , ty )
390 .It Oo Ic no Oc Ns Ic recurse
391 Tell the name server to query other servers if it does not have the
392 information.
393 .Pp
394 (Default =
395 .Ic recurse ;
396 abbreviation =
397 .Oo Ic no Oc Ns Ic rec )
398 .It Ic retry Ns = Ns Ar number
399 Set the number of retries to
400 .Ar number .
401 When a reply to a request is not received within a certain
402 amount of time (changed with
403 .Dq Ic set timeout ) ,
404 the timeout period is doubled and the request is resent.
405 The retry value controls how many times a request is resent before giving up.
406 .Pp
407 (Default = 4, abbreviation =
408 .Ic ret )
409 .It Ic root Ns = Ns Ar host
410 Change the name of the root server to
411 .Ar host .
412 This affects the
413 .Dq Ic root
414 command.
415 .Pp
416 (Default =
417 .Ic ns.internic.net. ;
418 abbreviation =
419 .Ic ro )
420 .It Ic timeout Ns = Ns Ar number
421 Change the initial timeout interval for waiting for a reply to
422 .Ar number
423 seconds.
424 Each retry doubles the timeout period.
425 .Pp
426 (Default = 5 seconds; abbreviation =
427 .Ic ti )
428 .It Oo Ic no Oc Ns Ic vc
429 Always use a virtual circuit when sending requests to the server.
430 .Pp
431 (Default =
432 .Ic novc ;
433 abbreviation =
434 .Oo Ic no Oc Ns Ic v )
435 .It Oo Ic no Oc Ns Ic ignoretc
436 Ignore packet truncation errors.
437 .Pp
438 (Default =
439 .Ic noignoretc ;
440 abbreviation =
441 .Oo Ic no Oc Ns Ic ig )
442 .El
443 .El
444 .Sh ENVIRONMENT
445 .Bl -tag -width "HOSTALIASESXXXX" -compact
446 .It Ev HOSTALIASES
447 file containing host aliases
448 .It Ev LOCALDOMAIN
449 overrides default domain
450 .El
451 .Sh FILES
452 .Bl -tag -width "/usr/share/misc/nslookup.helpXXX" -compact
453 .It Pa /etc/resolv.conf
454 initial domain name and name server addresses
455 .It Pa $HOME/.nslookuprc
456 user's initial options
457 .It Pa /usr/share/misc/nslookup.help
458 summary of commands
459 .El
460 .Sh DIAGNOSTICS
461 If the lookup request was not successful, an error message is printed.
462 Possible errors are:
463 .Bl -tag -width "Timed"
464 .It Li Timed out
465 The server did not respond to a request after a certain amount of
466 time (changed with
467 .Dq Ic set timeout Ns = Ns Ar value )
468 and a certain number of retries (changed with
469 .Do
470 .Ic set retry Ns = Ns Ar value
471 .Dc ) .
472 .It Li \&No response from server
473 No name server is running on the server machine.
474 .It Li \&No records
475 The server does not have resource records of the current query type for the
476 host, although the host name is valid.
477 The query type is specified with the
478 .Dq Ic set querytype
479 command.
480 .It Li Non-existent domain
481 The host or domain name does not exist.
482 .It Li Connection refused
483 .It Li Network is unreachable
484 The connection to the name or finger server could not be made
485 at the current time.
486 This error commonly occurs with
487 .Ic ls
488 and
489 .Ic finger
490 requests.
491 .It Li Server failure
492 The name server found an internal inconsistency in its database
493 and could not return a valid answer.
494 .It Li Refused
495 The name server refused to service the request.
496 .It Li Format error
497 The name server found that the request packet was not in the proper format.
498 It may indicate an error in
499 .Nm nslookup .
500 .El
501 .Sh SEE ALSO
502 .Xr resolver 3 ,
503 .Xr resolv.conf 5 ,
504 .Xr named 8
505 .Rs
506 .%A P.V. Mockapetris
507 .%T Domain Names - Concepts and Facilities
508 .%R RFC 1034
509 .%D Nov 1, 1987
510 .Re
511 .Rs
512 .%A P.V. Mockapetris
513 .%T Domain Names - Implementation and Specification
514 .%R RFC 1035
515 .%D Nov 1, 1987
516 .Re
517 .Sh AUTHORS
518 Andrew Cherenson