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