external/bsd/libbind/dist/doc/hostname.7

   1 .\"     $NetBSD$
   2 .\"
   3 .\" Copyright (C) 2009  Internet Systems Consortium, Inc. ("ISC")
   4 .\"
   5 .\" Permission to use, copy, modify, and/or distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11 .\" AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15 .\" PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .\" Id: hostname.7,v 1.3 2009/01/22 23:49:23 tbox Exp
  18 .\"
  19 .Dd February 16, 1994
  20 .Dt HOSTNAME @DESC_EXT_U@
  21 .Os BSD 4
  22 .Sh NAME
  23 .Nm hostname
  24 .Nd host name resolution description
  25 .Sh DESCRIPTION
  26 Hostnames are domains.  A domain is a hierarchical, dot-separated list
  27 of subdomains.  For example, the machine
  28 .Dq Li monet ,
  29 in the
  30 .Dq Li Berkeley
  31 subdomain of the
  32 .Dq Li EDU
  33 subdomain of the Internet Domain Name System would be represented as
  34 .Pp
  35 .Dl monet.Berkeley.EDU
  36 .Pp
  37 (with no trailing dot).
  38 .Pp
  39 Hostnames are often used with network client and server programs,
  40 which must generally translate the name to an address for use.
  41 (This task is usually performed by the library routine
  42 .Xr gethostbyname  @LIB_NETWORK_EXT@ . )
  43 The default method for resolving hostnames by the Internet name resolver is
  44 to follow RFC 1535's security recommendations.  Actions can be taken
  45 by the administrator to override these recommendations and to have the
  46 resolver behave the same as earlier, non-RFC 1535
  47 resolvers.
  48 .Pp
  49 The default method (using RFC 1535 guidelines) follows:
  50 .Pp
  51 If the name consists of a single component, i.e. contains no dot, and if the
  52 environment variable
  53 .Dq Ev HOSTALIASES
  54 is set to the name of a file,
  55 that file is searched for a string matching the input hostname.  The file
  56 should consist of lines made up of two strings separated by white-space, the
  57 first of which is the hostname alias, and the second of which is the complete
  58 hostname to be substituted for that alias.  If a case-insensitive match is
  59 found between the hostname to be resolved and the first field of a line in
  60 the file, the substituted name is looked up with no further processing.
  61 .Pp
  62 If there is at least one dot in the name, then the name is first tried
  63 .Dq as-is .
  64 The number of dots to cause this action is configurable by setting the
  65 threshold using the
  66 .Dq Li ndots
  67 option in
  68 .Pa /etc/resolv.conf
  69 (default:  1).  If the name ends with a dot, the trailing dot is
  70 removed, and the remaining name is looked up (regardless of the setting of
  71 the
  72 .Li ndots
  73 option), without further processing.
  74 .Pp
  75 If the input name does not end with a trailing dot, it is looked up by
  76 searching through a list of domains until a match is found.  If neither the
  77 search option in the
  78 .Pa /etc/resolv.conf
  79 file or the
  80 .Dq Ev LOCALDOMAIN
  81 environment variable is used, then the
  82 search list of domains contains only the full domain specified by the
  83 .Li domain
  84 option (in
  85 .Pa /etc/resolv.conf )
  86 or the domain used in the local hostname.  For example, if the
  87 .Dq Li domain
  88 option is set to
  89 .Li CS.Berkeley.EDU ,
  90 then only
  91 .Li CS.Berkeley.EDU
  92 will be in the search list, and this will be the only
  93 domain appended to the partial hostname.  For example, if
  94 .Dq Li lithium
  95 is the name to be resolved, this would make
  96 .Li lithium.CS.Berkeley.EDU
  97 the only name to be tried using the search list.
  98 .Pp
  99 If the
 100 .Li search
 101 option is used in
 102 .Pa /etc/resolv.conf
 103 or the environment variable
 104 .Dq Ev LOCALDOMAIN
 105 is set by the user, then
 106 the search list will include what is set by these methods.  For
 107 example, if the
 108 .Dq Li search
 109 option contained
 110 .Pp
 111 .Dl CS.Berkeley.EDU CChem.Berkeley.EDU Berkeley.EDU
 112 .Pp
 113 then the partial hostname (e.g.,
 114 .Dq Li lithium )
 115 will be tried with
 116 .Em each
 117 domain name appended (in the same order specified); the resulting hostnames
 118 that would be tried are:
 119 .Bd -literal -offset indent
 120 lithium.CS.Berkeley.EDU
 121 lithium.CChem.Berkeley.EDU
 122 lithium.Berkeley.EDU
 123 .Ed
 124 .Pp
 125 The environment variable
 126 .Dq Ev LOCALDOMAIN
 127 overrides the
 128 .Dq Li search
 129 and
 130 .Dq Li domain
 131 options, and if both
 132 .Li search
 133 and
 134 .Li domain
 135 options are present in the resolver configuration file, then only the
 136 .Em last
 137 one listed is used (see
 138 .Xr resolver @FORMAT_EXT@ ) .
 139 .Pp
 140 If the name was not previously tried
 141 .Dq as-is
 142 (i.e., it fell below the
 143 .Dq Li ndots
 144 threshold or did not contain a dot), then the name as
 145 originally provided is attempted.
 146 .Sh ENVIRONMENT
 147 .Bl -tag -width "/etc/resolv.conf  "
 148 .It Ev LOCALDOMAIN
 149 Affects domains appended to partial hostnames.
 150 .It Ev HOSTALIASES
 151 Name of file containing
 152 .Pq Ar host alias , full hostname
 153 pairs.
 154 .El
 155 .Sh FILES
 156 .Bl -tag -width "/etc/resolv.conf  " -compact
 157 .It Pa /etc/resolv.conf
 158 See
 159 .Xr resolve @FORMAT_EXT@ .
 160 .El
 161 .Sh SEE ALSO
 162 .Xr gethostbyname @LIB_NETWORK_EXT@ ,
 163 .Xr resolver @FORMAT_EXT@ ,
 164 .Xr mailaddr @DESC_EXT@ ,