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