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

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