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