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