1.\" Copyright (c) 1986, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)resolver.5 8.1 (Berkeley) 6/5/93 29.\" $FreeBSD$ 30.\" 31.Dd November 19, 2022 32.Dt RESOLVER 5 33.Os 34.Sh NAME 35.Nm resolver 36.Nd resolver configuration file 37.Sh SYNOPSIS 38.Nm resolv.conf 39.Sh DESCRIPTION 40The 41.Xr resolver 3 42is a set of routines in the C library 43which provide access to the Internet Domain Name System. 44The resolver configuration file contains information that is read 45by the resolver routines the first time they are invoked by a process. 46The file is designed to be human readable and contains a list of 47keywords with values that provide various types of resolver information. 48.Pp 49On a normally configured system this file should not be necessary. 50The only name server(s) to be queried will be on the local machine 51or automatically configured using DHCP or a similar mechanism, 52the domain name is determined from the host name, 53and the domain search path is constructed from the domain name. 54.Pp 55The different configuration options are: 56.Bl -tag -width nameserver 57.It Sy nameserver 58IPv4 or IPv6 address of a name server 59that the resolver should query. 60Up to 61.Dv MAXNS 62(currently 3) name servers may be listed, 63one per keyword. 64If there are multiple servers, 65the resolver library queries them in the order listed. 66If no 67.Sy nameserver 68entries are present, 69the default is to use the name server on the local machine. 70(The algorithm used is to try a name server, and if the query times out, 71try the next, until out of name servers, 72then repeat trying all the name servers 73until a maximum number of retries are made). 74.It Sy domain 75Local domain name. 76Most queries for names within this domain can use short names 77relative to the local domain. 78If no 79.Sy domain 80entry is present, the domain is determined 81from the local host name returned by 82.Xr gethostname 3 ; 83the domain part is taken to be everything after the first 84.Ql \&. . 85Finally, if the host name does not contain a domain part, the root 86domain is assumed. 87.It Sy search 88Search list for host-name lookup. 89The search list is normally determined from the local domain name; 90by default, it contains only the local domain name. 91This may be changed by listing the desired domain search path 92following the 93.Sy search 94keyword with spaces or tabs separating 95the names. 96Most resolver queries will be attempted using each component 97of the search path in turn until a match is found. 98Note that this process may be slow and will generate a lot of network 99traffic if the servers for the listed domains are not local, 100and that queries will time out if no server is available 101for one of the domains. 102.Pp 103The search list is currently limited to six domains 104with a total of 256 characters. 105.It Sy sortlist 106Sortlist allows addresses returned by gethostbyname to be sorted. 107A sortlist is specified by IP address netmask pairs. 108If the netmask is not specified, 109it defaults to the historical Class A/B/C netmask of the net; 110this usage is deprecated. 111The IP address 112and network pairs are separated by slashes. 113Up to 10 pairs may 114be specified. 115E.g., 116.Pp 117.Dl "sortlist 10.9.1.0/255.255.240.0 10.9.0.0/255.255.0.0" 118.It Sy options 119Options allows certain internal resolver variables to be modified. 120The syntax is 121.Pp 122\fBoptions\fP \fIoption\fP \fI...\fP 123.Pp 124where 125.Sy option 126is one of the following: 127.Bl -tag -width no_tld_query 128.It Sy debug 129sets 130.Dv RES_DEBUG 131in _res.options. 132.It Sy usevc 133sets 134.Dv RES_USEVC 135to use TCP instead of UDP for queries. 136.It Sy ndots : Ns Ar n 137sets a threshold for the number of dots which must appear in a name given to 138.Fn res_query 139(see 140.Xr resolver 3 ) 141before an 142.Em initial absolute query 143will be made. 144The default for 145.Em n 146is 147.Dq 1 , 148meaning that if there are any dots in a name, the name 149will be tried first as an absolute name before any 150.Em search list 151elements are appended to it. 152.It Sy timeout : Ns Ar n 153sets the initial amount of time the resolver will wait 154for a response from a remote 155name server before retrying the query via a different name server. 156The resolver may wait longer during subsequent retries 157of the current query since an exponential back-off is applied to 158the timeout value. 159Measured in seconds, the default is 160.Dv RES_TIMEOUT , 161the allowed maximum is 162.Dv RES_MAXRETRANS 163(see 164.In resolv.h ) . 165.It Sy attempts : Ns Ar n 166sets the number of times the resolver will send a query to each of 167its name servers 168before giving up and returning an error to the calling application. 169The default is 170.Dv RES_DFLRETRY , 171the allowed maximum is 172.Dv RES_MAXRETRY 173(see 174.In resolv.h ) . 175.It Sy no_tld_query 176tells the resolver not to attempt to resolve a top level domain name, that 177is, a name that contains no dots. 178Use of this option does not prevent 179the resolver from obeying the standard 180.Sy domain 181and 182.Sy search 183rules with the given name. 184.It Sy reload-period : Ns Ar n 185The resolver checks the modification time of 186.Pa /etc/resolv.conf 187every 188.Ar n 189seconds. 190If 191.Pa /etc/resolv.conf 192has changed, it is automatically reloaded. 193The default for 194.Ar n 195is two seconds. 196Setting it to zero disables the file check. 197.El 198.Pp 199Options may also be specified as a space or tab separated list using the 200.Dv RES_OPTIONS 201environment variable. 202.El 203.Pp 204The 205.Sy domain 206and 207.Sy search 208keywords are mutually exclusive. 209If more than one instance of these keywords is present, 210the last instance will override. 211.Pp 212The keyword and value must appear on a single line, and the keyword 213.Pq for example, Sy nameserver 214must start the line. 215The value follows the keyword, separated by white space. 216.Sh FILES 217.Bl -tag -width /etc/resolv.conf -compact 218.It Pa /etc/resolv.conf 219The file 220.Nm resolv.conf 221resides in 222.Pa /etc . 223.El 224.Sh EXAMPLES 225A basic resolv.conf file could be in the following form. 226.Bd -literal -offset indent 227# The domain directive is only necessary, if your local 228# router advertises something like localdomain and you have 229# set up your hostnames via an external domain. 230domain localdomain.tld 231 232# In case you a running a local dns server or caching name server 233# like local-unbound(8) for example. 234nameserver 127.0.0.1 235 236# IP address of the local or ISP name service 237nameserver 192.168.2.1 238 239# Fallback nameservers, in this case these from Google. 240nameserver 8.8.8.8 241nameserver 4.4.4.4 242 243# Attach an OPT pseudo-RR for the EDNS0 extension, 244# as specified in RFC 2671. 245options edns0 246.Ed 247.Sh SEE ALSO 248.Xr gethostbyname 3 , 249.Xr resolver 3 , 250.Xr hostname 7 , 251.Xr resolvconf 8 252.Sh HISTORY 253The 254.Nm resolv.conf 255file format appeared in 256.Bx 4.3 . 257