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