1.\" $OpenBSD: resolv.conf.5,v 1.30 2008/08/15 14:57:19 djm Exp $ 2.\" $NetBSD: resolv.conf.5,v 1.7 1996/03/06 18:22:16 scottr Exp $ 3.\" 4.\" Copyright (c) 1986, 1991 The Regents of the University of California. 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)resolver.5 5.12 (Berkeley) 5/10/91 32.\" 33.Dd $Mdocdate: August 15 2008 $ 34.Dt RESOLV.CONF 5 35.Os 36.Sh NAME 37.Nm resolv.conf , resolv.conf.tail 38.Nd resolver configuration files 39.Sh DESCRIPTION 40The 41.Nm 42file specifies how the 43.Xr resolver 3 44routines in the C library 45(which provide access to the Internet Domain Name System) should operate. 46The resolver configuration file contains information that is read 47by the resolver routines the first time they are invoked by a process. 48If the 49.Nm resolv.conf 50file does not exist, only the local host file 51.Pa /etc/hosts 52will be consulted, 53i.e. the Domain Name System will not be used to resolve hosts. 54.Pp 55The file is designed to be human readable and contains a list of 56keywords with values that provide various types of resolver information. 57A resolv.conf file is not required for some setups, so this file is optional. 58It can be created manually, and is also created as part of the 59.Ox 60install process 61if use of the DHCP protocol is specified for any interface. 62.Pp 63If 64.Xr dhclient 8 65is used to configure the network, 66the DHCP client back-end 67.Xr dhclient-script 8 68will normally overwrite the 69.Nm resolv.conf 70file with updated information such as nameserver addresses, 71losing any previous values the file contained. 72In order to force options to be passed to the 73.Xr resolver 3 74routines, the file 75.Nm resolv.conf.tail 76may be created manually. 77This file will be appended to the generated 78.Nm resolv.conf 79file by 80.Xr dhclient-script 8 , 81ensuring options remain. 82.Pp 83On a machine whose network connection does not change frequently (such as a desktop 84machine on a local-area network), the 85.Nm resolv.conf.tail 86file should not be necessary. 87However the 88.Nm resolv.conf.tail 89file may be useful on notebooks, to search multiple domains, 90to refer to hard-coded information in local files, or otherwise 91override the defaults. 92.Pp 93A hash mark 94.Ql # 95or semicolon 96.Ql \&; 97in the file indicates the beginning of a comment; 98subsequent characters up to the end of the line are not interpreted by 99the routines that read the file. 100.Pp 101The configuration options (which may be placed in either file) are: 102.Bl -tag -width nameserver 103.It Sy nameserver 104IPv4 address (in dot notation) 105or IPv6 address (in hex-and-colon notation) 106of a name server that the resolver should query. 107Scoped IPv6 address notation is accepted as well 108(see 109.Xr inet6 4 110for details). 111A non-standard port may be specified using 112.Ar [host]:port 113syntax. 114.Pp 115Up to 116.Dv MAXNS 117(currently 3) name servers may be listed, one per line. 118If there are multiple servers, the resolver library queries them in the 119order listed. 120If no 121.Sy nameserver 122entries are present, the default is to use the name server on the local machine. 123(The algorithm used is to try a name server, and if the query times out, 124try the next, until out of name servers, then repeat trying all name servers 125until a maximum number of retries are performed.) 126.It Sy domain 127Local domain name. 128Most queries for names within this domain can use short names 129relative to the local domain. 130If no 131.Sy domain 132entry is present, the domain is determined 133from the local host name returned by 134.Xr gethostname 3 ; 135the domain part is taken to be everything after the first 136.Dq \&. . 137Finally, if the host name does not contain a domain part, the root 138domain is assumed. 139.It Sy lookup 140This keyword is used by the library routines 141.Xr gethostbyname 3 142and 143.Xr gethostbyaddr 3 . 144It specifies which databases should be searched, and the order to do so. 145The legal space-separated values are: 146.Pp 147.Bl -tag -width bind -compact 148.It Sy bind 149Use the Domain Name server by querying 150.Xr named 8 . 151.It Sy file 152Search for entries in 153.Pa /etc/hosts . 154.It Sy yp 155Talk to the YP system if 156.Xr ypbind 8 157is running. 158.El 159.Pp 160If the 161.Sy lookup 162keyword is not used in the system's 163.Pa resolv.conf 164file then the assumed order is 165.Sy bind file . 166Furthermore, if the system's 167.Pa resolv.conf 168file does not exist, then the only database used is 169.Sy file . 170.Pp 171.It Sy search 172Search list for hostname lookup. 173The search list is normally determined from the local domain name; 174by default, it begins with the local domain name, then successive 175parent domains that have at least two components in their names. 176This may be changed by listing the desired domain search path following the 177.Sy search 178keyword with spaces or tabs separating the names. 179Most resolver queries will be attempted using each component 180of the search path in turn until a match is found. 181Note that this process may be slow and will generate a lot of network 182traffic if the servers for the listed domains are not local, 183and that queries will time out if no server is available 184for one of the domains. 185.Pp 186The search list is currently limited to six domains 187with a total of 1024 characters. 188Only one 189.Nm search 190line should appear; if more than one is present, the last one found 191overwrites any values found in earlier lines. 192So if such a line appears in the 193.Nm resolv.conf.tail 194file, it should include all the domains that need to be searched. 195.It Sy sortlist 196Allows addresses returned by 197.Xr gethostbyname 3 198to be sorted. 199A 200.Sy sortlist 201is specified by IP address netmask pairs. 202The netmask is optional and defaults to the natural netmask of the net. 203The IP address and optional network pairs are separated by slashes. 204Up to 10 pairs may be specified, e.g.: 205.Pp 206.Sy sortlist 130.155.160.0/255.255.240.0 130.155.0.0 207.It Sy options 208Allows certain internal resolver variables to be modified. 209The syntax is: 210.Pp 211.Sy options option ... 212.Pp 213where option is one of the following: 214.Bl -tag -width insecure1 215.It Sy debug 216Sets RES_DEBUG in _res.options. 217.It Sy edns0 218Attach OPT pseudo-RR for EDNS0 extension specified in RFC 2671, 219to inform DNS server of our receive buffer size. 220The option will allow DNS servers to take advantage of non-default receive 221buffer size, and to send larger replies. 222DNS query packets with EDNS0 extension are not compatible with 223non-EDNS0 DNS servers. 224The option must be used only when all the DNS servers listed in 225.Sy nameserver 226lines are able to handle EDNS0 extension. 227.It Sy inet6 228Enables support for IPv6-only applications, by setting RES_USE_INET6 in 229_res.options (see 230.Xr resolver 3 ) . 231Use of this option is discouraged, and meaningless on 232.Ox . 233.It Sy insecure1 234Do not require IP source address on the reply packet to be equal to the 235server's address. 236.It Sy insecure2 237Do not check if the query section of the reply packet is equal 238to that of the query packet. 239For testing purposes only. 240.It Sy ndots:n 241Sets a threshold for the number of dots which 242must appear in a name given to res_query (see 243.Xr resolver 3 ) 244before an initial absolute query will be made. 245The default for 246.Ar n 247is 1, meaning that if there are any dots in a name, the name will be tried 248first as an absolute name before any search list elements are appended to it. 249.It Sy tcp 250Forces the use of TCP for queries. 251Normal behaviour is to query via UDP but fall back to TCP on failure. 252.El 253.El 254.Pp 255The 256.Sy domain 257and 258.Sy search 259keywords are mutually exclusive. 260If more than one instance of these keywords is present, the last instance 261will override. 262.Pp 263The 264.Sy search 265keyword of a system's 266.Nm resolv.conf 267or 268.Nm resolv.conf.tail 269file can be overridden on a per-process basis by setting the 270environment variable 271.Ev LOCALDOMAIN 272to a space-separated list of search domains. 273.Pp 274The 275.Sy options 276keyword of a system's 277.Nm resolv.conf 278or 279.Nm resolv.conf.tail 280file can be amended on a per-process basis by setting the 281environment variable 282.Ev RES_OPTIONS 283to a space-separated list of resolver options as explained above. 284.Pp 285The keyword and value must appear on a single line, and the keyword (e.g.\& 286.Sy nameserver ) 287must start the line. 288The value follows the keyword, separated by whitespace. 289.Sh FILES 290.Bl -tag -width "/etc/resolv.conf.tailXX" -compact 291.It Pa /etc/resolv.conf 292.It Pa /etc/resolv.conf.tail 293.El 294.Sh SEE ALSO 295.Xr gethostbyname 3 , 296.Xr resolver 3 , 297.Xr hosts 5 , 298.Xr hostname 7 , 299.Xr dhclient-script 8 , 300.Xr dhcp 8 , 301.Xr named 8 302.Rs 303.%T "Name Server Operations Guide for BIND" 304.Re 305.Sh HISTORY 306The 307.Nm 308file format appeared in 309.Bx 4.3 . 310.Sh BUGS 311Due to resolver internal issues, 312.Xr getaddrinfo 3 313may not behave as 314.Sy lookup 315suggests. 316Consequently, userland programs that use 317.Xr getaddrinfo 3 318may behave differently from what 319.Sy lookup 320says. 321