Module Name: src
Committed By: christos
Date: Wed Sep 29 13:44:33 UTC 2010
Modified Files:
src/share/man/man7: hostname.7
Log Message:
new from libbind
To generate a diff of this commit:
cvs rdiff -u -r1.9 -r1.10 src/share/man/man7/hostname.7
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man7/hostname.7
diff -u src/share/man/man7/hostname.7:1.9 src/share/man/man7/hostname.7:1.10
--- src/share/man/man7/hostname.7:1.9 Thu Aug 7 06:31:20 2003
+++ src/share/man/man7/hostname.7 Wed Sep 29 09:44:33 2010
@@ -1,44 +1,49 @@
-.\" $NetBSD: hostname.7,v 1.9 2003/08/07 10:31:20 agc Exp $
+.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
.\"
-.\" Copyright (c) 1987, 1990, 1993
-.\" The Regents of the University of California. All rights reserved.
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\" notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\" notice, this list of conditions and the following disclaimer in the
-.\" documentation and/or other materials provided with the distribution.
-.\" 3. Neither the name of the University nor the names of its contributors
-.\" may be used to endorse or promote products derived from this software
-.\" without specific prior written permission.
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
-.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
-.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-.\" SUCH DAMAGE.
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
+.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.\" @(#)hostname.7 8.2 (Berkeley) 12/30/93
+.\" Copyright (c) 1987 The Regents of the University of California.
+.\" All rights reserved.
.\"
-.Dd December 30, 1993
+.\" Redistribution and use in source and binary forms are permitted
+.\" provided that the above copyright notice and this paragraph are
+.\" duplicated in all such forms and that any documentation,
+.\" advertising materials, and other materials related to such
+.\" distribution and use acknowledge that the software was developed
+.\" by the University of California, Berkeley. The name of the
+.\" University may not be used to endorse or promote products derived
+.\" from this software without specific prior written permission.
+.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" @(#)hostname.7 6.4 (Berkeley) 1/16/90
+.\"
+.Dd February 16, 1994
.Dt HOSTNAME 7
-.Os
+.Os BSD 4
.Sh NAME
-.Nm hostname
+.Nm hostname
.Nd host name resolution description
.Sh DESCRIPTION
-Hostnames are domains, where a domain is a hierarchical, dot-separated
-list of subdomains; for example, the machine monet, in the Berkeley
-subdomain of the EDU subdomain of the Internet would be represented as
+Hostnames are domains. A domain is a hierarchical, dot-separated list
+of subdomains. For example, the machine
+.Dq Li monet ,
+in the
+.Dq Li Berkeley
+subdomain of the
+.Dq Li EDU
+subdomain of the Internet Domain Name System would be represented as
.Pp
.Dl monet.Berkeley.EDU
.Pp
@@ -46,46 +51,127 @@
.Pp
Hostnames are often used with network client and server programs,
which must generally translate the name to an address for use.
-(This function is generally performed by the library routine
-.Xr gethostbyname 3 . )
-Hostnames are resolved by the Internet name resolver in the following
-fashion.
-.Pp
-If the name consists of a single component, i.e. contains no dot,
-and if the environment variable
-.Dq Ev HOSTALIASES
+(This task is usually performed by the library routine
+.Xr gethostbyname 3 . )
+The default method for resolving hostnames by the Internet name resolver is
+to follow RFC 1535's security recommendations. Actions can be taken
+by the administrator to override these recommendations and to have the
+resolver behave the same as earlier, non-RFC 1535
+resolvers.
+.Pp
+The default method (using RFC 1535 guidelines) follows:
+.Pp
+If the name consists of a single component, i.e. contains no dot, and if the
+environment variable
+.Dq Ev HOSTALIASES
is set to the name of a file,
-that file is searched for any string matching the input hostname.
-The file should consist of lines made up of two white-space separated strings,
-the first of which is the hostname alias,
-and the second of which is the complete hostname
-to be substituted for that alias.
-If a case-insensitive match is found between the hostname to be resolved
-and the first field of a line in the file, the substituted name is looked
-up with no further processing.
-.Pp
-If the input name ends with a trailing dot,
-the trailing dot is removed,
-and the remaining name is looked up with no further processing.
-.Pp
-If the input name does not end with a trailing dot, it is looked up
-by searching through a list of domains until a match is found.
-The default search list includes first the local domain,
-then its parent domains with at least 2 name components (longest first).
-For example,
-in the domain CS.Berkeley.EDU, the name lithium.CChem will be checked first
-as lithium.CChem.CS.Berkeley.EDU and then as lithium.CChem.Berkeley.EDU.
-Lithium.CChem.EDU will not be tried, as there is only one component
-remaining from the local domain.
-The search path can be changed from the default
-by a system-wide configuration file (see
-.Xr resolv.conf 5 ) .
+that file is searched for a string matching the input hostname. The file
+should consist of lines made up of two strings separated by white-space, the
+first of which is the hostname alias, and the second of which is the complete
+hostname to be substituted for that alias. If a case-insensitive match is
+found between the hostname to be resolved and the first field of a line in
+the file, the substituted name is looked up with no further processing.
+.Pp
+If there is at least one dot in the name, then the name is first tried
+.Dq as-is .
+The number of dots to cause this action is configurable by setting the
+threshold using the
+.Dq Li ndots
+option in
+.Pa /etc/resolv.conf
+(default: 1). If the name ends with a dot, the trailing dot is
+removed, and the remaining name is looked up (regardless of the setting of
+the
+.Li ndots
+option), without further processing.
+.Pp
+If the input name does not end with a trailing dot, it is looked up by
+searching through a list of domains until a match is found. If neither the
+search option in the
+.Pa /etc/resolv.conf
+file or the
+.Dq Ev LOCALDOMAIN
+environment variable is used, then the
+search list of domains contains only the full domain specified by the
+.Li domain
+option (in
+.Pa /etc/resolv.conf )
+or the domain used in the local hostname. For example, if the
+.Dq Li domain
+option is set to
+.Li CS.Berkeley.EDU ,
+then only
+.Li CS.Berkeley.EDU
+will be in the search list, and this will be the only
+domain appended to the partial hostname. For example, if
+.Dq Li lithium
+is the name to be resolved, this would make
+.Li lithium.CS.Berkeley.EDU
+the only name to be tried using the search list.
+.Pp
+If the
+.Li search
+option is used in
+.Pa /etc/resolv.conf
+or the environment variable
+.Dq Ev LOCALDOMAIN
+is set by the user, then
+the search list will include what is set by these methods. For
+example, if the
+.Dq Li search
+option contained
+.Pp
+.Dl CS.Berkeley.EDU CChem.Berkeley.EDU Berkeley.EDU
+.Pp
+then the partial hostname (e.g.,
+.Dq Li lithium )
+will be tried with
+.Em each
+domain name appended (in the same order specified); the resulting hostnames
+that would be tried are:
+.Bd -literal -offset indent
+lithium.CS.Berkeley.EDU
+lithium.CChem.Berkeley.EDU
+lithium.Berkeley.EDU
+.Ed
+.Pp
+The environment variable
+.Dq Ev LOCALDOMAIN
+overrides the
+.Dq Li search
+and
+.Dq Li domain
+options, and if both
+.Li search
+and
+.Li domain
+options are present in the resolver configuration file, then only the
+.Em last
+one listed is used (see
+.Xr resolver 5 ) .
+.Pp
+If the name was not previously tried
+.Dq as-is
+(i.e., it fell below the
+.Dq Li ndots
+threshold or did not contain a dot), then the name as
+originally provided is attempted.
+.Sh ENVIRONMENT
+.Bl -tag -width "/etc/resolv.conf "
+.It Ev LOCALDOMAIN
+Affects domains appended to partial hostnames.
+.It Ev HOSTALIASES
+Name of file containing
+.Pq Ar host alias , full hostname
+pairs.
+.El
+.Sh FILES
+.Bl -tag -width "/etc/resolv.conf " -compact
+.It Pa /etc/resolv.conf
+See
+.Xr resolve 5 .
+.El
.Sh SEE ALSO
.Xr gethostbyname 3 ,
-.Xr resolv.conf 5 ,
+.Xr resolver 5 ,
.Xr mailaddr 7 ,
-.Xr named 8
-.Sh HISTORY
-.Nm
-appeared in
-.Bx 4.2 .
