1.\" $OpenBSD: resolv.conf.5,v 1.32 2009/06/05 06:56:51 jmc 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: June 5 2009 $ 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 family 208Specify which type of Internet protocol family to prefer, 209if a host is reachable using different address families. 210By default IPv4 addresses are queried first, 211and then IPv6 addresses. 212The syntax is: 213.Pp 214.D1 family family1 [family2] 215.Pp 216A maximum of two families can be specified, 217where family can be any of: 218.Pp 219.Bl -tag -width "inet4XXX" -offset indent -compact 220.It inet4 221IPv4 queries. 222.It inet6 223IPv6 queries. 224.El 225.It Sy options 226Allows certain internal resolver variables to be modified. 227The syntax is: 228.Pp 229.Sy options option ... 230.Pp 231where option is one of the following: 232.Bl -tag -width insecure1 233.It Sy debug 234Sets RES_DEBUG in _res.options. 235.It Sy edns0 236Attach OPT pseudo-RR for EDNS0 extension specified in RFC 2671, 237to inform DNS server of our receive buffer size. 238The option will allow DNS servers to take advantage of non-default receive 239buffer size, and to send larger replies. 240DNS query packets with EDNS0 extension are not compatible with 241non-EDNS0 DNS servers. 242The option must be used only when all the DNS servers listed in 243.Sy nameserver 244lines are able to handle EDNS0 extension. 245.It Sy inet6 246Enables support for IPv6-only applications, by setting RES_USE_INET6 in 247_res.options (see 248.Xr resolver 3 ) . 249Use of this option is discouraged, and meaningless on 250.Ox . 251.It Sy insecure1 252Do not require IP source address on the reply packet to be equal to the 253server's address. 254.It Sy insecure2 255Do not check if the query section of the reply packet is equal 256to that of the query packet. 257For testing purposes only. 258.It Sy ndots:n 259Sets a threshold for the number of dots which 260must appear in a name given to res_query (see 261.Xr resolver 3 ) 262before an initial absolute query will be made. 263The default for 264.Ar n 265is 1, meaning that if there are any dots in a name, the name will be tried 266first as an absolute name before any search list elements are appended to it. 267.It Sy tcp 268Forces the use of TCP for queries. 269Normal behaviour is to query via UDP but fall back to TCP on failure. 270.El 271.El 272.Pp 273The 274.Sy domain 275and 276.Sy search 277keywords are mutually exclusive. 278If more than one instance of these keywords is present, the last instance 279will override. 280.Pp 281The 282.Sy search 283keyword of a system's 284.Nm resolv.conf 285or 286.Nm resolv.conf.tail 287file can be overridden on a per-process basis by setting the 288environment variable 289.Ev LOCALDOMAIN 290to a space-separated list of search domains. 291.Pp 292The 293.Sy options 294keyword of a system's 295.Nm resolv.conf 296or 297.Nm resolv.conf.tail 298file can be amended on a per-process basis by setting the 299environment variable 300.Ev RES_OPTIONS 301to a space-separated list of resolver options as explained above. 302.Pp 303The keyword and value must appear on a single line, and the keyword (e.g.\& 304.Sy nameserver ) 305must start the line. 306The value follows the keyword, separated by whitespace. 307.Sh FILES 308.Bl -tag -width "/etc/resolv.conf.tailXX" -compact 309.It Pa /etc/resolv.conf 310.It Pa /etc/resolv.conf.tail 311.El 312.Sh SEE ALSO 313.Xr gethostbyname 3 , 314.Xr resolver 3 , 315.Xr hosts 5 , 316.Xr hostname 7 , 317.Xr dhclient-script 8 , 318.Xr dhcp 8 , 319.Xr named 8 320.Rs 321.%T "Name Server Operations Guide for BIND" 322.Re 323.Sh HISTORY 324The 325.Nm 326file format appeared in 327.Bx 4.3 . 328.Sh BUGS 329Due to resolver internal issues, 330.Xr getaddrinfo 3 331may not behave as 332.Sy lookup 333suggests. 334Consequently, userland programs that use 335.Xr getaddrinfo 3 336may behave differently from what 337.Sy lookup 338says. 339