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