.\"	$OpenBSD: hostname.7,v 1.5 2000/03/14 21:31:37 aaron Exp $
.\" Copyright (c) 1987 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" 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
.\"
.TH HOSTNAME 7 "February 16, 1994"
.UC 5
.SH NAME
hostname \- host name resolution description
.SH DESCRIPTION
Hostnames are domains. A domain is a hierarchical, dot-separated list
of subdomains. For example, the machine \fImonet\fP, in the \fIBerkeley\fP
subdomain of the \fIEDU\fP subdomain of the Internet Domain Name System
would be represented as
.br
	\fImonet\fP.\fIBerkeley\fP.\fIEDU\fP
.br
(with no trailing dot).
.PP
Hostnames are often used with network client and server programs,
which must generally translate the name to an address for use.
(This task is usually performed by the library routine
.IR gethostbyname (3).)
The default method for resolving hostnames by the Internet name resolver is
to follow \s-1RFC\s+1 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-\s-1RFC\s+1 1535 resolvers.
.PP
The default method (using \s-1RFC\s+1 1535 guidelines) follows:
.PP
If the name consists of a single component, i.e., contains no dot, and if the
environment variable ``\s-1HOSTALIASES\s+1'' is set to the name of a file,
that file is searched for a string matching the input hostname.  The file
should consist of lines made up of two strings separated by whitespace, 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 as
is.  The number of dots to cause this action is configurable by setting the
threshold using the ``\fIndots\fP'' option in
.I /etc/resolv.conf
(default: \fI1\fP).  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 'ndots' option) and no further processing is done.
.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
.I /etc/resolv.conf
file or the ``\s-1LOCALDOMAIN\s+1'' environment variable is used, then the
search list of domains contains only the full domain specified by the domain
option (in
.IR /etc/resolv.conf )
or the domain used in the local hostname (see
.IR hostname (1)
and
.IR resolver (5)).
For example, if the ``\fIdomain\fP'' option is set to \fICS.Berkeley.EDU\fP,
then only CS.Berkeley.EDU will be in the search list and will be the only
domain appended to the partial hostname, for example, ``\fIlithium\fP'',
making \fIlithium.CS.Berkeley.EDU\fP the only name to be tried using the
search list.
.PP
If the search option is used in
.I /etc/resolv.conf
or the environment variable, ``\s-1LOCALDOMAIN\s+1'' is set by the user, then
the search list will include what is set by these methods. For
example, if the ``\fIsearch\fP'' option contained
.br
	\fICS.Berkeley.EDU CChem.Berkeley.EDU Berkeley.EDU\fP
.br
then the partial hostname (e.g., ``\fIlithium\fP'') will be tried with each
domainname appended (in the same order specified).  The resulting hostnames
that would be tried are:
.nf
	\fIlithium.CS.Berkeley.EDU\fP
	\fIlithium.CChem.Berkeley.EDU\fP
	\fIlithium.Berkeley.EDU\fP
.fi
.PP
The environment variable ``\s-1LOCALDOMAIN\s+1'' overrides the
``\fIsearch\fP'' and ``\fIdomain\fP'' options, and if both search and domain
options are present in the resolver configuration file, then only the last
one listed is used (see
.IR resolver (5)).
.PP
If the name was not previously tried ``as is'' (i.e., it fell below the
``\fIndots\fP'' threshold or did not contain a dot), then the name as
originally provided is attempted.
.SH SEE ALSO
.IR gethostbyname (3),
.IR resolver (5),
.IR mailaddr (5),
.IR named (8)