nslookup.8

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