1.\" $NetBSD: hostname.7,v 1.11 2010/09/29 14:34:07 wiz Exp $ 2.\" 3.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC") 4.\" 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. 8.\" 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. 16.\" 17.\" Copyright (c) 1987 The Regents of the University of California. 18.\" All rights reserved. 19.\" 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 35.Dt HOSTNAME 7 36.Os 37.Sh NAME 38.Nm hostname 39.Nd host name resolution description 40.Sh DESCRIPTION 41Hostnames are domains. 42A domain is a hierarchical, dot-separated list of subdomains. 43For example, the machine 44.Dq Li monet , 45in the 46.Dq Li Berkeley 47subdomain of the 48.Dq Li EDU 49subdomain of the Internet Domain Name System would be represented as 50.Pp 51.Dl monet.Berkeley.EDU 52.Pp 53(with no trailing dot). 54.Pp 55Hostnames are often used with network client and server programs, 56which must generally translate the name to an address for use. 57(This task is usually performed by the library routine 58.Xr gethostbyname 3 . ) 59The default method for resolving hostnames by the Internet name resolver is 60to follow RFC 1535's security recommendations. 61Actions can be taken by the administrator to override these 62recommendations and to have the resolver behave the same as earlier, 63non-RFC 1535 resolvers. 64.Pp 65The default method (using RFC 1535 guidelines) follows: 66.Pp 67If the name consists of a single component, i.e. contains no dot, and if the 68environment variable 69.Dq Ev HOSTALIASES 70is set to the name of a file, 71that file is searched for a string matching the input hostname. 72The file 73should consist of lines made up of two strings separated by white-space, the 74first of which is the hostname alias, and the second of which is the complete 75hostname to be substituted for that alias. 76If a case-insensitive match is 77found between the hostname to be resolved and the first field of a line in 78the file, the substituted name is looked up with no further processing. 79.Pp 80If there is at least one dot in the name, then the name is first tried 81.Dq as-is . 82The number of dots to cause this action is configurable by setting the 83threshold using the 84.Dq Li ndots 85option in 86.Pa /etc/resolv.conf 87(default: 1). 88If the name ends with a dot, the trailing dot is 89removed, and the remaining name is looked up (regardless of the setting of 90the 91.Li ndots 92option), without further processing. 93.Pp 94If the input name does not end with a trailing dot, it is looked up by 95searching through a list of domains until a match is found. 96If neither the search option in the 97.Pa /etc/resolv.conf 98file or the 99.Dq Ev LOCALDOMAIN 100environment variable is used, then the 101search list of domains contains only the full domain specified by the 102.Li domain 103option (in 104.Pa /etc/resolv.conf ) 105or the domain used in the local hostname. 106For example, if the 107.Dq Li domain 108option is set to 109.Li CS.Berkeley.EDU , 110then only 111.Li CS.Berkeley.EDU 112will be in the search list, and this will be the only 113domain appended to the partial hostname. 114For example, if 115.Dq Li lithium 116is the name to be resolved, this would make 117.Li lithium.CS.Berkeley.EDU 118the only name to be tried using the search list. 119.Pp 120If the 121.Li search 122option is used in 123.Pa /etc/resolv.conf 124or the environment variable 125.Dq Ev LOCALDOMAIN 126is set by the user, then 127the search list will include what is set by these methods. 128For example, if the 129.Dq Li search 130option contained 131.Pp 132.Dl CS.Berkeley.EDU CChem.Berkeley.EDU Berkeley.EDU 133.Pp 134then the partial hostname (e.g., 135.Dq Li lithium ) 136will be tried with 137.Em each 138domain name appended (in the same order specified); the resulting hostnames 139that would be tried are: 140.Bd -literal -offset indent 141lithium.CS.Berkeley.EDU 142lithium.CChem.Berkeley.EDU 143lithium.Berkeley.EDU 144.Ed 145.Pp 146The environment variable 147.Dq Ev LOCALDOMAIN 148overrides the 149.Dq Li search 150and 151.Dq Li domain 152options, and if both 153.Li search 154and 155.Li domain 156options are present in the resolver configuration file, then only the 157.Em last 158one listed is used (see 159.Xr resolver 5 ) . 160.Pp 161If the name was not previously tried 162.Dq as-is 163(i.e., it fell below the 164.Dq Li ndots 165threshold or did not contain a dot), then the name as 166originally provided is attempted. 167.Sh ENVIRONMENT 168.Bl -tag -width "/etc/resolv.conf " 169.It Ev LOCALDOMAIN 170Affects domains appended to partial hostnames. 171.It Ev HOSTALIASES 172Name of file containing 173.Pq Ar host alias , full hostname 174pairs. 175.El 176.Sh FILES 177.Bl -tag -width "/etc/resolv.conf " -compact 178.It Pa /etc/resolv.conf 179See 180.Xr resolver 5 . 181.El 182.Sh SEE ALSO 183.Xr gethostbyname 3 , 184.Xr resolver 5 , 185.Xr mailaddr 7 186