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