1.\" $NetBSD: resolver.5,v 1.1.1.2 2012/09/09 16:07:44 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: resolver.5,v 1.3 2009/01/22 23:49:23 tbox Exp 18.\" 19.Dd November 11, 1993 20.Dt RESOLVER @FORMAT_EXT_U@ 21.Os BSD 4 22.Sh NAME 23.Nm resolver 24.Nd resolver configuration file 25.Sh SYNOPSIS 26.Pa /etc/resolv.conf 27.Sh DESCRIPTION 28The 29.Nm resolver 30is a set of routines in the C library 31.Pq Xr resolve @LIB_NETWORK_EXT@ 32that provide access to the Internet Domain Name System. 33The 34.Nm resolver 35configuration file contains information that is read 36by the 37.Nm resolver 38routines the first time they are invoked by a process. 39The file is designed to be human readable and contains a list of 40keywords with values that provide various types of 41.Nm resolver 42information. 43.Pp 44On a normally configured system, this file should not be necessary. 45The only name server to be queried will be on the local machine, 46the domain name is determined from the host name, 47and the domain search path is constructed from the domain name. 48.Pp 49The different configuration directives are: 50.Bl -tag -width "nameser" 51.It Li nameserver 52Internet address (in dot notation) of a name server that the 53.Nm resolver 54should query. Up to 55.Dv MAXNS 56(see 57.Pa <resolv.h> ) 58name servers may be listed, one per keyword. 59If there are multiple servers, the 60.Nm resolver 61library queries them in the order listed. 62If no 63.Li nameserver 64entries are present, the default is to use the name server on the local machine. 65(The algorithm used is to try a name server, and if the query times out, 66try the next, until out of name servers, 67then repeat trying all the name servers 68until a maximum number of retries are made). 69.It Li domain 70Local domain name. 71Most queries for names within this domain can use short names 72relative to the local domain. 73If no 74.Li domain 75entry is present, the domain is determined from the local host name returned by 76.Xr gethostname @BSD_SYSCALL_EXT@ ; 77the domain part is taken to be everything after the first 78.Sq \&. . 79Finally, if the host name does not contain a domain part, the root 80domain is assumed. 81.It Li search 82Search list for host-name lookup. 83The search list is normally determined from the local domain name; 84by default, it contains only the local domain name. 85This may be changed by listing the desired domain search path 86following the 87.Li search 88keyword with spaces or tabs separating the names. 89Most 90.Nm resolver 91queries will be attempted using each component 92of the search path in turn until a match is found. 93Note that this process may be slow and will generate a lot of network 94traffic if the servers for the listed domains are not local, 95and that queries will time out if no server is available 96for one of the domains. 97.Pp 98The search list is currently limited to six domains 99with a total of 256 characters. 100.It Li sortlist 101Allows addresses returned by gethostbyname to be sorted. 102A 103.Li sortlist 104is specified by IP address netmask pairs. The netmask is 105optional and defaults to the natural netmask of the net. The IP address 106and optional network pairs are separated by slashes. Up to 10 pairs may 107be specified. For example: 108.Bd -literal -offset indent 109sortlist 130.155.160.0/255.255.240.0 130.155.0.0 110.Ed 111.It Li options 112Allows certain internal 113.Nm resolver 114variables to be modified. 115The syntax is 116.D1 Li options Ar option ... 117where 118.Ar option 119is one of the following: 120.Bl -tag -width "ndots:n " 121.It Li debug 122sets 123.Dv RES_DEBUG 124in 125.Ft _res.options . 126.It Li ndots: Ns Ar n 127sets a threshold for the number of dots which 128must appear in a name given to 129.Fn res_query 130(see 131.Xr resolver @LIB_NETWORK_EXT@ ) 132before an 133.Em initial absolute query 134will be made. The default for 135.Ar n 136is 137.Dq 1 , 138meaning that if there are 139.Em any 140dots in a name, the name will be tried first as an absolute name before any 141.Em search list 142elements are appended to it. 143.It Li timeout: Ns Ar n 144sets the amount of time the resolver will wait for a response from a remote 145name server before retrying the query via a different name server. Measured in 146seconds, the default is 147.Dv RES_TIMEOUT 148(see 149.Pa <resolv.h> ) . 150.It Li attempts: Ns Ar n 151sets the number of times the resolver will send a query to its name servers 152before giving up and returning an error to the calling application. The 153default is 154.Dv RES_DFLRETRY 155(see 156.Pa <resolv.h> ) . 157.It Li rotate 158sets 159.Dv RES_ROTATE 160in 161.Ft _res.options , 162which causes round robin selection of nameservers from among those listed. 163This has the effect of spreading the query load among all listed servers, 164rather than having all clients try the first listed server first every time. 165.It Li no-check-names 166sets 167.Dv RES_NOCHECKNAME 168in 169.Ft _res.options , 170which disables the modern BIND checking of incoming host names and mail names 171for invalid characters such as underscore (_), non-ASCII, or control characters. 172.It Li inet6 173sets 174.Dv RES_USE_INET6 175in 176.Ft _res.options . 177This has the effect of trying a AAAA query before an A query inside the 178.Ft gethostbyname 179function, and of mapping IPv4 responses in IPv6 ``tunnelled form'' if no 180AAAA records are found but an A record set exists. 181.It Li no-tld-query 182sets 183.Dv RES_NOTLDQUERY 184in 185.Ft _res.options . 186This option causes 187.Fn res_nsearch 188to not attempt to resolve a unqualified name as if it were a top level 189domain (TLD). 190This option can cause problems if the site has "localhost" as a TLD rather 191than having localhost on one or more elements of the search list. 192This option has no effect if neither 193.Dv RES_DEFNAMES 194or 195.Dv RES_DNSRCH 196is set. 197.El 198.El 199.Pp 200The 201.Li domain 202and 203.Li search 204keywords are mutually exclusive. 205If more than one instance of these keywords is present, 206the last instance wins. 207.Pp 208The 209.Li search 210keyword of a system's 211.Pa resolv.conf 212file can be 213overridden on a per-process basis by setting the environment variable 214.Dq Ev LOCALDOMAIN 215to a space-separated list of search domains. 216.Pp 217The 218.Li options 219keyword of a system's 220.Pa resolv.conf 221file can be amended on a per-process basis by setting the environment variable 222.Dq Ev RES_OPTIONS to a space-separated list of 223.Nm resolver 224options as explained above under 225.Li options . 226.Pp 227The keyword and value must appear on a single line, and the keyword 228(e.g., 229.Li nameserver ) 230must start the line. The value follows the keyword, separated by white space. 231.Sh FILES 232.Pa /etc/resolv.conf 233.Pa <resolv.h> 234.Sh SEE ALSO 235.Xr gethostbyname @LIB_NETWORK_EXT@ , 236.Xr hostname @DESC_EXT@ , 237.Xr resolver @LIB_NETWORK_EXT@ , 238.Xr resolver @FORMAT_EXT@ . 239.Dq Name Server Operations Guide for Sy BIND 240