contrib/bind/doc/man/host.1

   1 .\" ++Copyright++ 1993
   2 .\" -
   3 .\" Copyright (c) 1993
   4 .\"    The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\" -
  34 .\" Portions Copyright (c) 1993 by Digital Equipment Corporation.
  35 .\"
  36 .\" Permission to use, copy, modify, and distribute this software for any
  37 .\" purpose with or without fee is hereby granted, provided that the above
  38 .\" copyright notice and this permission notice appear in all copies, and that
  39 .\" the name of Digital Equipment Corporation not be used in advertising or
  40 .\" publicity pertaining to distribution of the document or software without
  41 .\" specific, written prior permission.
  42 .\"
  43 .\" THE SOFTWARE IS PROVIDED "AS IS" AND DIGITAL EQUIPMENT CORP. DISCLAIMS ALL
  44 .\" WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES
  45 .\" OF MERCHANTABILITY AND FITNESS.   IN NO EVENT SHALL DIGITAL EQUIPMENT
  46 .\" CORPORATION BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
  47 .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
  48 .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
  49 .\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
  50 .\" SOFTWARE.
  51 .\" -
  52 .\" --Copyright--
  53 .\" $Id: host.1,v 8.2 1997/03/14 02:29:44 vixie Exp $
  54 .\" $FreeBSD$
  55 .\"
  56 .Dd December 15, 1994
  57 .Dt HOST @CMD_EXT_U@
  58 .Os BSD 4
  59 .Sh NAME
  60 .Nm host
  61 .Nd look up host names using domain server
  62 .Sh SYNOPSIS
  63 .Nm host
  64 .Op Fl adlrwv
  65 .Op Fl c Ar class
  66 .Op Fl t Ar querytype
  67 .Ar host
  68 .Op Ar server
  69 .Sh DESCRIPTION
  70 .Ic Host
  71 looks for information about Internet hosts.  It gets this information
  72 from a set of interconnected servers that are spread across the
  73 country.  By default, it simply converts between host names and
  74 Internet addresses.  However, with the
  75 .Dq Fl t
  76 or
  77 .Dq Fl a
  78 options, it can be used
  79 to find all of the information about this host that is maintained
  80 by the domain server.
  81 .Pp
  82 The arguments can be either host names or host numbers.  The program
  83 first attempts to interpret them as host numbers.  If this fails,
  84 it will treat them as host names.  A host number consists of
  85 four decimal numbers separated by dots, e.g. 128.6.4.194
  86 A host name consists of names separated by dots, e.g. topaz.rutgers.edu.
  87 Unless the name ends in a dot, the local domain
  88 is automatically tacked on the end.  Thus, a Rutgers user can say
  89 .Pp
  90 .D1 Ic host topaz
  91 .Pp
  92 and it will actually look up "topaz.rutgers.edu".
  93 If this fails, the name is tried unchanged (in this case, "topaz").
  94 This same convention is used for mail and other network utilities.
  95 The actual suffix to tack on the end is obtained
  96 by looking at the results of a
  97 .Xr hostname @CMD_EXT@
  98 call, and using everything
  99 starting at the first dot.  (See below for a description of
 100 .Sx CUSTOMIZING HOST NAME LOOKUP . )
 101 .Pp
 102 The first argument is the host name you want to look up.
 103 If this is a number, an
 104 .Dq inverse query
 105 is done, i.e. the domain
 106 system looks in a separate set of databases used to convert numbers
 107 to names.
 108 .Pp
 109 The second argument is optional.  It
 110 allows you to specify a particular server to query.  If you don't
 111 specify this argument, the default server (normally the local machine)
 112 is used.
 113 .Pp
 114 If a name is specified, you may see output of three different kinds.
 115 Here is an example that shows all of them:
 116 .Pp
 117 .D1 Ic % host sun4
 118 .Dl sun4.rutgers.edu is a nickname for ATHOS.RUTGERS.EDU
 119 .Dl ATHOS.RUTGERS.EDU has address 128.6.5.46
 120 .Dl ATHOS.RUTGERS.EDU has address 128.6.4.4
 121 .Dl ATHOS.RUTGERS.EDU mail is handled by ARAMIS.RUTGERS.EDU
 122 .Pp
 123 The user has typed the command
 124 .Dq Ic host sun4 .
 125 The first line indicates that the name
 126 .Dq Li sun4.rutgers.edu
 127 is actually a nickname.  The official host name is
 128 .Dq Li ATHOS.RUTGERS.EDU .
 129 The next two lines show the
 130 address.  If a system has more than one network interface, there
 131 will be a separate address for each.  The last line indicates
 132 that
 133 .Li ATHOS.RUTGERS.EDU
 134 does not receive its own mail.  Mail for
 135 it is taken by
 136 .Li ARAMIS.RUTGERS.EDU .
 137 There may be more than one
 138 such line, since some systems have more than one other system
 139 that will handle mail for them.  Technically, every system that
 140 can receive mail is supposed to have an entry of this kind.  If
 141 the system receives its own mail, there should be an entry
 142 the mentions the system itself; for example,
 143 .Pp
 144 .D1 Li XXX mail is handled by XXX
 145 .Pp
 146 However, many systems that receive
 147 their own mail do not bother to mention that fact.  If a system
 148 has a
 149 .Dq Li mail is handled by
 150 entry, but no address, this indicates
 151 that it is not really part of the Internet, but a system that is
 152 on the network will forward mail to it.  Systems on Usenet, Bitnet,
 153 and a number of other networks have entries of this kind.
 154 .Sh OPTIONS
 155 There are a number of options that can be used before the
 156 host name.  Most of these options are meaningful only to the
 157 staff who have to maintain the domain database.
 158 .Bl -tag -width Fl
 159 .It Fl a
 160 .Dq all ;
 161 this is equivalent to
 162 .Dq Fl v Fl t Cm any .
 163 .It Fl c Ar class
 164 The
 165 .Ar class
 166 to look for non-Internet data.
 167 .It Fl d
 168 Turn on debugging.  Network transactions are shown in detail.
 169 .It Fl l
 170 List a complete domain; e.g.:
 171 .Pp
 172 .D1 Ic host -l rutgers.edu
 173 .Pp
 174 will give a listing of all hosts in the rutgers.edu domain.  The
 175 .Dq Fl t
 176 option is used to filter what information is presented, as you
 177 would expect.  The default is address information, which also
 178 include PTR and NS records.  The command
 179 .Pp
 180 .D1 Ic host -l -v -t any rutgers.edu
 181 .Pp
 182 will give a complete download of the zone data for rutgers.edu,
 183 in the official master file format.  (However the SOA record is
 184 listed twice, for arcane reasons.)
 185 .Pp
 186 .Sy NOTE:
 187 .Dq Fl l
 188 is implemented by
 189 doing a complete zone transfer and then filtering out the information
 190 that you have asked for.  This command should be used only if it
 191 is absolutely necessary.
 192 .It Fl r
 193 Turn off recursion in the request.
 194 This means that the name server will return only data it has in
 195 its own database.  It will not ask other servers for more
 196 information.
 197 .It Fl t Ar querytype
 198 Allows you to specify a particular
 199 .Ar querytype
 200 of information
 201 to be looked up.  The arguments are defined in the man page for
 202 .Xr @INDOT@named @SYS_OPS_EXT@ .
 203 Currently-supported types include:
 204 .Dq Cm a ,
 205 .Dq Cm ns ,
 206 .Dq Cm md ,
 207 .Dq Cm mf ,
 208 .Dq Cm cname ,
 209 .Dq Cm soa ,
 210 .Dq Cm mb ,
 211 .Dq Cm mg ,
 212 .Dq Cm mr ,
 213 .Dq Cm null ,
 214 .Dq Cm wks ,
 215 .Dq Cm ptr ,
 216 .Dq Cm hinfo ,
 217 .Dq Cm minfo ,
 218 .Dq Cm mx ,
 219 .Dq Cm uinfo ,
 220 .Dq Cm uid ,
 221 .Dq Cm gid ,
 222 .Dq Cm unspec .
 223 Additionally, the wildcard, which may be written
 224 as either
 225 .Dq Cm any
 226 or
 227 .Dq Cm * ,
 228 can be used to specify any (all) of the above types.
 229 Types must be given in lower case.
 230 Note that the default is to look first for
 231 .Dq Cm a ,
 232 and then
 233 .Dq Cm mx ,
 234 except that if the verbose option is turned on, the default is only
 235 .Dq Cm a .
 236 The
 237 .Dq Fl t
 238 option is particularly useful for filtering information returned by
 239 .Ic host ;
 240 see the explanation of the
 241 .Dq Fl l
 242 option for more information.
 243 .It Fl v
 244 Use "verbose" format for printout.  This
 245 is the official domain master file format, which is documented
 246 in the man page for
 247 .Xr @INDOT@named @SYS_OPS_EXT@ .
 248 Without this option, output still follows
 249 this format in general terms, but some attempt is made to make it
 250 more intelligible to normal users.  Without
 251 .Dq Fl v ,
 252 any "a", "mx", and "cname" records
 253 are written out as "has address", "mail is handled by", and
 254 "is a nickname for" (respectively), and TTL and class fields are not shown.
 255 .It Fl w
 256 This causes
 257 .Ic host
 258 to wait forever for a response.  Normally
 259 it will time out after approximate one minute.
 260 .Sh CUSTOMIZING HOST NAME LOOKUP
 261 In general, if the name supplied by the user does not
 262 have any dots in it, a default domain is appended to the end.
 263 This domain can be defined in
 264 .Pa /etc/resolv.conf ,
 265 but is normally derived
 266 by taking the local hostname after its first dot.  The user can override
 267 this, and specify a different default domain, using the environment
 268 variable
 269 .Ev LOCALDOMAIN .
 270 In addition, the user can supply his own abbreviations for host names.
 271 They should be in a file consisting of one line per abbreviation.
 272 Each line contains an abbreviation, a space, and then the full
 273 host name.  The name file must be contained in the
 274 .Ev HOSTALIASES
 275 environment variable.
 276 .Sh ENVIRONMENT
 277 .Bl -tag -width "/etc/resolv.conf  " -compress
 278 .It Ev HOSTALIASES
 279 Name of file containing
 280 .Pq Ar host alias , full hostname
 281 pairs.
 282 .El
 283 .Sh FILES
 284 .Bl -tag -width "/etc/resolv.conf  " -compress
 285 .It Pa /etc/resolv.conf
 286 See
 287 .Xr resolver @FORMAT_EXT@ .
 288 .It Ev HOSTALIASES
 289 Name of file containing
 290 .Pq Ar host alias , full hostname
 291 pairs.
 292 .El
 293 .Sh SEE ALSO
 294 .Xr @INDOT@named  @SYS_OPS_EXT@ ,
 295 .Xr resolver @FORMAT_EXT@ .
 296 .Sh BUGS
 297 Unexpected effects can happen when you type a name that is not
 298 part of the local domain.  Please always keep in mind the
 299 fact that the local domain name is tacked onto the end of every
 300 name, unless it ends in a dot.  Only if this fails is the name
 301 used unchanged.
 302 .Pp
 303 The
 304 .Dq Fl l
 305 option only tries the first name server listed for the
 306 domain that you have requested.  If this server is dead, you
 307 may need to specify a server manually. E.g., to get a listing
 308 of foo.edu, you could try
 309 .Pp
 310 .D1 Ic host -t ns foo.edu
 311 .Pp
 312 to get a list of all the name servers for foo.edu, and then try
 313 .Pp
 314 .D1 Ic host -l foo.edu xxx
 315 .Pp
 316 for all
 317 .Dq Ic xxx
 318 on the list of name servers, until you find one that works.