1.\" $OpenBSD: resolv.conf.5,v 1.34 2010/04/15 09:52:58 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: April 15 2010 $ 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 62or if any DNS nameservers are configured. 63.Pp 64If 65.Xr dhclient 8 66is used to configure the network, 67the DHCP client back-end 68.Xr dhclient-script 8 69will normally overwrite the 70.Nm resolv.conf 71file with updated information such as nameserver addresses, 72losing any previous values the file contained. 73In order to force options to be passed to the 74.Xr resolver 3 75routines, the file 76.Nm resolv.conf.tail 77may be created manually. 78This file will be appended to the generated 79.Nm resolv.conf 80file by 81.Xr dhclient-script 8 , 82ensuring options remain. 83.Pp 84On a machine whose network connection does not change frequently (such as a desktop 85machine on a local-area network), the 86.Nm resolv.conf.tail 87file should not be necessary. 88However the 89.Nm resolv.conf.tail 90file may be useful on notebooks, to search multiple domains, 91to refer to hard-coded information in local files, or otherwise 92override the defaults. 93.Pp 94A hash mark 95.Ql # 96or semicolon 97.Ql \&; 98in the file indicates the beginning of a comment; 99subsequent characters up to the end of the line are not interpreted by 100the routines that read the file. 101.Pp 102The configuration options (which may be placed in either file) are: 103.Bl -tag -width nameserver 104.It Sy nameserver 105IPv4 address (in dot notation) 106or IPv6 address (in hex-and-colon notation) 107of a name server that the resolver should query. 108Scoped IPv6 address notation is accepted as well 109(see 110.Xr inet6 4 111for details). 112A non-standard port may be specified using 113.Bo Ar host Bc : Ns Ar port 114syntax. 115When a non-standard port is specified the host 116address must be enclosed in square brackets. 117For example: 118.Bd -literal -offset indent 119nameserver [10.0.0.1]:5353 120nameserver [::1]:5353 121.Ed 122.Pp 123Up to 124.Dv MAXNS 125(currently 3) name servers may be listed, one per line. 126If there are multiple servers, the resolver library queries them in the 127order listed. 128If no 129.Sy nameserver 130entries are present, the default is to use the name server on the local machine. 131(The algorithm used is to try a name server, and if the query times out, 132try the next, until out of name servers, then repeat trying all name servers 133until a maximum number of retries are performed.) 134.It Sy domain 135Local domain name. 136Most queries for names within this domain can use short names 137relative to the local domain. 138If no 139.Sy domain 140entry is present, the domain is determined 141from the local host name returned by 142.Xr gethostname 3 ; 143the domain part is taken to be everything after the first 144.Dq \&. . 145Finally, if the host name does not contain a domain part, the root 146domain is assumed. 147.It Sy lookup 148This keyword is used by the library routines 149.Xr gethostbyname 3 150and 151.Xr gethostbyaddr 3 . 152It specifies which databases should be searched, and the order to do so. 153The legal space-separated values are: 154.Pp 155.Bl -tag -width bind -compact 156.It Sy bind 157Use the Domain Name server by querying 158.Xr named 8 . 159.It Sy file 160Search for entries in 161.Pa /etc/hosts . 162.It Sy yp 163Talk to the YP system if 164.Xr ypbind 8 165is running. 166.El 167.Pp 168If the 169.Sy lookup 170keyword is not used in the system's 171.Pa resolv.conf 172file then the assumed order is 173.Sy bind file . 174Furthermore, if the system's 175.Pa resolv.conf 176file does not exist, then the only database used is 177.Sy file . 178.Pp 179.It Sy search 180Search list for hostname lookup. 181The search list is normally determined from the local domain name; 182by default, it begins with the local domain name, then successive 183parent domains that have at least two components in their names. 184This may be changed by listing the desired domain search path following the 185.Sy search 186keyword with spaces or tabs separating the names. 187Most resolver queries will be attempted using each component 188of the search path in turn until a match is found. 189Note that this process may be slow and will generate a lot of network 190traffic if the servers for the listed domains are not local, 191and that queries will time out if no server is available 192for one of the domains. 193.Pp 194The search list is currently limited to six domains 195with a total of 1024 characters. 196Only one 197.Nm search 198line should appear; if more than one is present, the last one found 199overwrites any values found in earlier lines. 200So if such a line appears in the 201.Nm resolv.conf.tail 202file, it should include all the domains that need to be searched. 203.It Sy sortlist 204Allows addresses returned by 205.Xr gethostbyname 3 206to be sorted. 207A 208.Sy sortlist 209is specified by IP address netmask pairs. 210The netmask is optional and defaults to the natural netmask of the net. 211The IP address and optional network pairs are separated by slashes. 212Up to 10 pairs may be specified, e.g.: 213.Pp 214.Sy sortlist 130.155.160.0/255.255.240.0 130.155.0.0 215.It Sy family 216Specify which type of Internet protocol family to prefer, 217if a host is reachable using different address families. 218By default IPv4 addresses are queried first, 219and then IPv6 addresses. 220The syntax is: 221.Pp 222.D1 family family1 [family2] 223.Pp 224A maximum of two families can be specified, 225where family can be any of: 226.Pp 227.Bl -tag -width "inet4XXX" -offset indent -compact 228.It inet4 229IPv4 queries. 230.It inet6 231IPv6 queries. 232.El 233.It Sy options 234Allows certain internal resolver variables to be modified. 235The syntax is: 236.Pp 237.Sy options option ... 238.Pp 239where option is one of the following: 240.Bl -tag -width insecure1 241.It Sy debug 242Sets RES_DEBUG in _res.options. 243.It Sy edns0 244Attach OPT pseudo-RR for EDNS0 extension specified in RFC 2671, 245to inform DNS server of our receive buffer size. 246The option will allow DNS servers to take advantage of non-default receive 247buffer size, and to send larger replies. 248DNS query packets with EDNS0 extension are not compatible with 249non-EDNS0 DNS servers. 250The option must be used only when all the DNS servers listed in 251.Sy nameserver 252lines are able to handle EDNS0 extension. 253.It Sy inet6 254Enables support for IPv6-only applications, by setting RES_USE_INET6 in 255_res.options (see 256.Xr resolver 3 ) . 257Use of this option is discouraged, and meaningless on 258.Ox . 259.It Sy insecure1 260Do not require IP source address on the reply packet to be equal to the 261server's address. 262.It Sy insecure2 263Do not check if the query section of the reply packet is equal 264to that of the query packet. 265For testing purposes only. 266.It Sy ndots:n 267Sets a threshold for the number of dots which 268must appear in a name given to res_query (see 269.Xr resolver 3 ) 270before an initial absolute query will be made. 271The default for 272.Ar n 273is 1, meaning that if there are any dots in a name, the name will be tried 274first as an absolute name before any search list elements are appended to it. 275.It Sy tcp 276Forces the use of TCP for queries. 277Normal behaviour is to query via UDP but fall back to TCP on failure. 278.El 279.El 280.Pp 281The 282.Sy domain 283and 284.Sy search 285keywords are mutually exclusive. 286If more than one instance of these keywords is present, the last instance 287will override. 288.Pp 289The 290.Sy search 291keyword of a system's 292.Nm resolv.conf 293or 294.Nm resolv.conf.tail 295file can be overridden on a per-process basis by setting the 296environment variable 297.Ev LOCALDOMAIN 298to a space-separated list of search domains. 299.Pp 300The 301.Sy options 302keyword of a system's 303.Nm resolv.conf 304or 305.Nm resolv.conf.tail 306file can be amended on a per-process basis by setting the 307environment variable 308.Ev RES_OPTIONS 309to a space-separated list of resolver options as explained above. 310.Pp 311The keyword and value must appear on a single line, and the keyword (e.g.\& 312.Sy nameserver ) 313must start the line. 314The value follows the keyword, separated by whitespace. 315.Sh FILES 316.Bl -tag -width "/etc/resolv.conf.tailXX" -compact 317.It Pa /etc/resolv.conf 318.It Pa /etc/resolv.conf.tail 319.El 320.Sh SEE ALSO 321.Xr gethostbyname 3 , 322.Xr resolver 3 , 323.Xr hosts 5 , 324.Xr hostname 7 , 325.Xr dhclient-script 8 , 326.Xr dhcp 8 , 327.Xr named 8 328.Rs 329.%T "Name Server Operations Guide for BIND" 330.Re 331.Sh HISTORY 332The 333.Nm 334file format appeared in 335.Bx 4.3 . 336.Sh BUGS 337Due to resolver internal issues, 338.Xr getaddrinfo 3 339may not behave as 340.Sy lookup 341suggests. 342Consequently, userland programs that use 343.Xr getaddrinfo 3 344may behave differently from what 345.Sy lookup 346says. 347