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 67is a program to query Internet domain name servers. 68.Nm 69has two modes: interactive and non-interactive. 70Interactive mode allows the user to query name servers for 71information about various hosts and domains or to print a list of hosts 72in a domain. 73Non-interactive mode is used to print just the name and requested information 74for a host or domain. 75.Sh ARGUMENTS 76Interactive mode is entered in the following cases: 77.Bl -enum 78.It 79when no arguments are given (the default name server will be used), 80.It 81when the first argument is a hyphen 82.Pq Sq \&- 83and the second argument 84is the host name or Internet address of a name server. 85.El 86.Pp 87Non-interactive mode is used when the name or Internet address 88of the host to be looked up 89is given as the first argument. 90The optional second argument specifies 91the host name or address of a name server. 92.Pp 93The options listed under the 94.Dq Li set 95command below can be specified in 96the 97.Pa .nslookuprc 98file in the user's home directory if they are listed 99one per line. 100Options can also be specified on the command line if they precede 101the arguments and are prefixed with a hyphen. 102For example, to change the default query type to host information, 103and the initial timeout to 10 seconds, type: 104.Bd -literal -offset indent 105 nslookup -query=hinfo -timeout=10 106.Ed 107.Sh INTERACTIVE COMMANDS 108Commands may be interrupted at any time by typing a control-C. 109To exit, type a control-D 110.Pq Dv EOF 111or type 112.Li exit . 113The command line length must be less than 256 characters. 114To treat a built-in command as a host name, 115precede 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 120Look up information for 121.Ar host 122using the current default server or using 123.Ar server , 124if specified. 125If 126.Ar host 127is an Internet address and the query type is 128.Dv A 129or 130.Dv PTR , 131the name of the host is returned. 132If 133.Ar host 134is a name and does not have a trailing period, the default 135domain name is appended to the name. 136(This behavior depends on the state of the 137.Ic set 138options 139.Ic domain , srchlist , defname , 140and 141.Ic search . ) 142.Pp 143To look up a host not in the current domain, append a period to 144the name. 145.It Ic server Ar domain 146.It Ic lserver Ar domain 147Change the default server to 148.Ar domain ; 149.Ic lserver 150uses the initial server to look up information about 151.Ar domain , 152while 153.Ic server 154uses the current default server. 155If an authoritative answer can't be found, the names of servers 156that might have the answer are returned. 157.It Ic root 158Changes the default server to the server for the root of the domain name space. 159Currently, the host 160.Li ns.internic.net 161is used. 162(This command is a synonym for 163.Dq Ic lserver ns.internic.net . ) 164The name of the root server can be changed with the 165.Dq Ic set root 166command. 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 169Connects with the finger server on the current host. 170The current host is defined when a previous lookup for a host 171was successful and returned address information (see the 172.Dq Ic set querytype Ns = Ns Dv A 173command). 174The 175.Ar name 176is optional. 177.Ic \*[Gt] 178and 179.Ic \*[Gt]\*[Gt] 180can 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 183List the information available for 184.Ar domain , 185optionally creating or appending to 186.Ar filename . 187The default output contains host names and their Internet addresses. 188.Ar Option 189can be one of the following: 190.Bl -tag -width "-a " 191.It Fl t Ar querytype 192lists all records of the specified type (see 193.Ar querytype 194below). 195.It Fl a 196lists aliases of hosts in the domain; 197synonym for 198.Dq Fl t Dv CNAME . 199.It Fl d 200lists all records for the domain; 201synonym for 202.Dq Fl t Dv ANY . 203.It Fl h 204lists CPU and operating system information for the domain; 205synonym for 206.Dq Fl t Dv HINFO . 207.It Fl s 208lists well-known services of hosts in the domain; 209synonym for 210.Dq Fl t Dv WKS . 211.El 212.Pp 213When output is directed to a file, hash marks are printed for every 21450 records received from the server. 215.It Ic view Ar filename 216Sorts and lists the output of previous 217.Ic ls 218command(s) with 219.Xr more 1 . 220.It Ic help 221.It Ic ?\& 222Prints a brief summary of commands. 223.It Ic exit 224Exits the program. 225.It Ic set Ar keyword Ns Op = Ns Ar value 226This command is used to change state information that affects the lookups. 227Valid keywords are: 228.Bl -tag -width "class=v" 229.It Ic all 230Prints the current values of the frequently-used options to 231.Ic set . 232Information about the current default server and host is also printed. 233.It Ic class Ns = Ns Ar value 234Change the query class to one of: 235.Bl -tag -width "HESIOD " 236.It Dv IN 237the Internet class 238.It Dv CHAOS 239the Chaos class 240.It Dv HESIOD 241the MIT Athena Hesiod class 242.It Dv ANY 243wildcard (any of the above) 244.El 245.Pp 246The class specifies the protocol group of the information. 247.Pp 248(Default = 249.Dv IN ; 250abbreviation = 251.Ic cl ) 252.It Oo Ic no Oc Ns Ic debug 253Turn debugging mode on. 254A lot more information is printed about the 255packet sent to the server and the resulting answer. 256.Pp 257(Default = 258.Ic nodebug ; 259abbreviation = 260.Oo Ic no Oc Ns Ic deb ) 261.It Oo Ic no Oc Ns Ic d2 262Turn exhaustive debugging mode on. 263Essentially all fields of every packet are printed. 264.Pp 265(Default = 266.Ic nod2 ) 267.It Ic domain Ns = Ns Ar name 268Change the default domain name to 269.Ar name . 270The default domain name is appended to a lookup request depending on the 271state of the 272.Ic defname 273and 274.Ic search 275options. 276The domain search list contains the parents of the default domain if it has 277at least two components in its name. 278For example, if the default domain 279is CC.Berkeley.EDU, the search list is CC.Berkeley.EDU and Berkeley.EDU. 280Use the 281.Dq Ic set srchlist 282command to specify a different list. 283Use the 284.Dq Ic set all 285command to display the list. 286.Pp 287(Default = value from 288.Xr hostname 1 , 289.Pa /etc/resolv.conf , 290or 291.Ev LOCALDOMAIN ; 292abbreviation = 293.Ic do ) 294.It Ic srchlist Ns No = Ns Ar name1 Ns No / Ns Ar name2 Ns No / Ns Ar ... 295Change the default domain name to 296.Ar name1 297and the domain search list 298to 299.Ar name1 , name2 , 300etc. 301A maximum of 6 names separated by slashes 302.Pq Sq / 303can be specified. 304For example, 305.Bd -literal -offset indent 306set srchlist=lcs.MIT.EDU/ai.MIT.EDU/MIT.EDU 307.Ed 308.Pp 309sets the domain to lcs.MIT.EDU and the search list to the three names. 310This command overrides the 311default domain name and search list of the 312.Dq Ic set domain 313command. 314Use the 315.Dq Ic set all 316command to display the list. 317.Pp 318(Default = value based on 319.Xr hostname 1 , 320.Pa /etc/resolv.conf , 321or 322.Ev LOCALDOMAIN ; 323abbreviation = 324.Ic srchl ) 325.It Oo Ic no Oc Ns Ic defname 326If 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 ; 331abbreviation = 332.Oo Ic no Oc Ns Ic defname ) 333.It Oo Ic no Oc Ns Ic search 334If the lookup request contains at least one period but 335.Em doesn't 336end with a trailing period, append the domain names in the domain search list 337to the request until an answer is received. 338.Pp 339(Default = 340.Ic search ; 341abbreviation = 342.Oo Ic no Oc Ns Ic sea ) 343.It Ic port Ns = Ns Ar value 344Change the default TCP/UDP name server port to 345.Ar value . 346.Pp 347(Default = 53; 348abbreviation = 349.Ic \&po ) 350.It Ic querytype Ns = Ns Ar value 351.It Ic type Ns = Ns Ar value 352Change the type of information query to one of: 353.Bl -tag -width "HINFO " 354.It Dv A 355the host's Internet address. 356.It Dv CNAME 357the canonical name for an alias. 358.It Dv HINFO 359the host CPU and operating system type. 360.It Dv MINFO 361the mailbox or mail list information. 362.It Dv MX 363the mail exchanger. 364.It Dv NS 365the name server for the named zone. 366.It Dv PTR 367the host name if the query is an Internet address; 368otherwise, the pointer to other information. 369.It Dv SOA 370the domain's 371.Dq start-of-authority 372information. 373.It Dv TXT 374the text information. 375.It Dv UINFO 376the user information. 377.It Dv WKS 378the supported well-known services. 379.El 380.Pp 381Other types 382.Dv ( ANY , AXFR , MB , 383.Dv MD , MF , NULL ) 384are described in the RFC-1035 document. 385.Pp 386(Default = 387.Dv A ; 388abbreviations = 389.Ic q , ty ) 390.It Oo Ic no Oc Ns Ic recurse 391Tell the name server to query other servers if it does not have the 392information. 393.Pp 394(Default = 395.Ic recurse ; 396abbreviation = 397.Oo Ic no Oc Ns Ic rec ) 398.It Ic retry Ns = Ns Ar number 399Set the number of retries to 400.Ar number . 401When a reply to a request is not received within a certain 402amount of time (changed with 403.Dq Ic set timeout ) , 404the timeout period is doubled and the request is resent. 405The 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 410Change the name of the root server to 411.Ar host . 412This affects the 413.Dq Ic root 414command. 415.Pp 416(Default = 417.Ic ns.internic.net. ; 418abbreviation = 419.Ic ro ) 420.It Ic timeout Ns = Ns Ar number 421Change the initial timeout interval for waiting for a reply to 422.Ar number 423seconds. 424Each retry doubles the timeout period. 425.Pp 426(Default = 5 seconds; abbreviation = 427.Ic ti ) 428.It Oo Ic no Oc Ns Ic vc 429Always use a virtual circuit when sending requests to the server. 430.Pp 431(Default = 432.Ic novc ; 433abbreviation = 434.Oo Ic no Oc Ns Ic v ) 435.It Oo Ic no Oc Ns Ic ignoretc 436Ignore packet truncation errors. 437.Pp 438(Default = 439.Ic noignoretc ; 440abbreviation = 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 447file containing host aliases 448.It Ev LOCALDOMAIN 449overrides default domain 450.El 451.Sh FILES 452.Bl -tag -width "/usr/share/misc/nslookup.helpXXX" -compact 453.It Pa /etc/resolv.conf 454initial domain name and name server addresses 455.It Pa $HOME/.nslookuprc 456user's initial options 457.It Pa /usr/share/misc/nslookup.help 458summary of commands 459.El 460.Sh DIAGNOSTICS 461If the lookup request was not successful, an error message is printed. 462Possible errors are: 463.Bl -tag -width "Timed" 464.It Li Timed out 465The server did not respond to a request after a certain amount of 466time (changed with 467.Dq Ic set timeout Ns = Ns Ar value ) 468and 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 473No name server is running on the server machine. 474.It Li \&No records 475The server does not have resource records of the current query type for the 476host, although the host name is valid. 477The query type is specified with the 478.Dq Ic set querytype 479command. 480.It Li Non-existent domain 481The host or domain name does not exist. 482.It Li Connection refused 483.It Li Network is unreachable 484The connection to the name or finger server could not be made 485at the current time. 486This error commonly occurs with 487.Ic ls 488and 489.Ic finger 490requests. 491.It Li Server failure 492The name server found an internal inconsistency in its database 493and could not return a valid answer. 494.It Li Refused 495The name server refused to service the request. 496.It Li Format error 497The name server found that the request packet was not in the proper format. 498It 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 518Andrew Cherenson 519