1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
|
<table class="head">
<tr>
<td class="head-ltitle">RESOLVER(5)</td>
<td class="head-vol">File Formats Manual</td>
<td class="head-rtitle">RESOLVER(5)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">resolver</code> —
<span class="Nd">resolver configuration file</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<table class="Nm">
<tr>
<td><code class="Nm">resolv.conf</code></td>
<td></td>
</tr>
</table>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <a class="Xr">resolver(3)</a> is a set of routines in the C
library which provide access to the Internet Domain Name System. The
resolver configuration file contains information that is read by the
resolver routines the first time they are invoked by a process. The file is
designed to be human readable and contains a list of keywords with values
that provide various types of resolver information.</p>
<p class="Pp">On a normally configured system, setting this file manually should
not be necessary. The only name server(s) to be queried will be on the local
machine or automatically configured using DHCP or a similar mechanism, the
domain name is determined from the host name, and the domain search path is
constructed from the domain name.</p>
<p class="Pp">The different configuration options are:</p>
<dl class="Bl-tag">
<dt id="nameserver"><a class="permalink" href="#nameserver"><b class="Sy">nameserver</b></a></dt>
<dd>IPv4 or IPv6 address of a name server that the resolver should query. Up
to <code class="Dv">MAXNS</code> (currently 3) name servers may be listed,
one per keyword. If there are multiple servers, the resolver library
queries them in the order listed. If no <b class="Sy">nameserver</b>
entries are present, the default is to use the name server on the local
machine. (The algorithm used is to try a name server, and if the query
times out, try the next, until out of name servers, then repeat trying all
the name servers until a maximum number of retries are made).</dd>
<dt id="domain"><a class="permalink" href="#domain"><b class="Sy">domain</b></a></dt>
<dd>Local domain name. Most queries for names within this domain can use short
names relative to the local domain. If no <b class="Sy">domain</b> entry
is present, the domain is determined from the local host name returned by
<a class="Xr">gethostname(3)</a>; the domain part is taken to be
everything after the first ‘<code class="Li">.</code>’.
Finally, if the host name does not contain a domain part, the root domain
is assumed.</dd>
<dt id="search"><a class="permalink" href="#search"><b class="Sy">search</b></a></dt>
<dd>Search list for host-name lookup. The search list is normally determined
from the local domain name; by default, it contains only the local domain
name. This may be changed by listing the desired domain search path
following the <b class="Sy">search</b> keyword with spaces or tabs
separating the names. Most resolver queries will be attempted using each
component of the search path in turn until a match is found. Note that
this process may be slow and will generate a lot of network traffic if the
servers for the listed domains are not local, and that queries will time
out if no server is available for one of the domains.
<p class="Pp">The search list is currently limited to six domains with a
total of 256 characters.</p>
</dd>
<dt id="sortlist"><a class="permalink" href="#sortlist"><b class="Sy">sortlist</b></a></dt>
<dd>Sortlist allows addresses returned by gethostbyname to be sorted. A
sortlist is specified by IP address netmask pairs. If the netmask is not
specified, it defaults to the historical Class A/B/C netmask of the net;
this usage is deprecated. The IP address and network pairs are separated
by slashes. Up to 10 pairs may be specified. E.g.,
<p class="Pp"></p>
<div class="Bd Bd-indent"><code class="Li">sortlist 10.9.1.0/255.255.240.0
10.9.0.0/255.255.0.0</code></div>
</dd>
<dt id="options"><a class="permalink" href="#options"><b class="Sy">options</b></a></dt>
<dd>Options allows certain internal resolver variables to be modified. The
syntax is
<p class="Pp"><b>options</b> <i>option</i> <i>...</i></p>
<p class="Pp" id="option">where
<a class="permalink" href="#option"><b class="Sy">option</b></a> is one
of the following:</p>
<dl class="Bl-tag">
<dt id="debug"><a class="permalink" href="#debug"><b class="Sy">debug</b></a></dt>
<dd>sets <code class="Dv">RES_DEBUG</code> in _res.options.</dd>
<dt id="usevc"><a class="permalink" href="#usevc"><b class="Sy">usevc</b></a></dt>
<dd>sets <code class="Dv">RES_USEVC</code> to use TCP instead of UDP for
queries.</dd>
<dt id="ndots"><a class="permalink" href="#ndots"><b class="Sy">ndots</b></a>:<var class="Ar">n</var></dt>
<dd>sets a threshold for the number of dots which must appear in a name
given to
<a class="permalink" href="#res_query"><code class="Fn" id="res_query">res_query</code></a>()
(see <a class="Xr">resolver(3)</a>) before an
<a class="permalink" href="#initial"><i class="Em" id="initial">initial
absolute query</i></a> will be made. The default for
<a class="permalink" href="#n"><i class="Em" id="n">n</i></a> is
“1”, meaning that if there are any dots in a name, the
name will be tried first as an absolute name before any
<i class="Em">search list</i> elements are appended to it.</dd>
<dt id="timeout"><a class="permalink" href="#timeout"><b class="Sy">timeout</b></a>:<var class="Ar">n</var></dt>
<dd>sets the initial amount of time the resolver will wait for a response
from a remote name server before retrying the query via a different
name server. The resolver may wait longer during subsequent retries of
the current query since an exponential back-off is applied to the
timeout value. Measured in seconds, the default is
<code class="Dv">RES_TIMEOUT</code>, the allowed maximum is
<code class="Dv">RES_MAXRETRANS</code> (see
<code class="In"><<a class="In">resolv.h</a>></code>).</dd>
<dt id="attempts"><a class="permalink" href="#attempts"><b class="Sy">attempts</b></a>:<var class="Ar">n</var></dt>
<dd>sets the number of times the resolver will send a query to each of its
name servers before giving up and returning an error to the calling
application. The default is <code class="Dv">RES_DFLRETRY</code>, the
allowed maximum is <code class="Dv">RES_MAXRETRY</code> (see
<code class="In"><<a class="In">resolv.h</a>></code>).</dd>
<dt id="edns0"><a class="permalink" href="#edns0"><b class="Sy">edns0</b></a></dt>
<dd>Sets <code class="Dv">RES_USE_EDNS0</code>. Attach an OPT pseudo-RR
for the EDNS0 extension, as specified in RFC 2671. This allows the
resolver to advertise a larger UDP receive buffer size, permitting
responses larger than the original 512-byte limit.</dd>
<dt id="inet6"><a class="permalink" href="#inet6"><b class="Sy">inet6</b></a></dt>
<dd>Sets <code class="Dv">RES_USE_INET6</code>. Causes
<a class="Xr">gethostbyname(3)</a> to look up AAAA records before A
records and to map IPv4 responses into IPv6 addresses. The use of this
option is discouraged.</dd>
<dt id="insecure1"><a class="permalink" href="#insecure1"><b class="Sy">insecure1</b></a></dt>
<dd>Sets <code class="Dv">RES_INSECURE1</code>. Disables the check that
the response was received from the same server to which the query was
sent. Use of this option is a security risk and is not
recommended.</dd>
<dt id="insecure2"><a class="permalink" href="#insecure2"><b class="Sy">insecure2</b></a></dt>
<dd>Sets <code class="Dv">RES_INSECURE2</code>. Disables the check that
the response contains a query matching the one that was sent. Use of
this option is a security risk and is not recommended.</dd>
<dt id="no-check-names"><a class="permalink" href="#no-check-names"><b class="Sy">no-check-names</b></a></dt>
<dd>Sets <code class="Dv">RES_NOCHECKNAME</code>. Disables the check of
incoming host names for invalid characters such as underscore,
non-ASCII, or control characters.</dd>
<dt id="no_tld_query"><a class="permalink" href="#no_tld_query"><b class="Sy">no_tld_query</b></a></dt>
<dd>tells the resolver not to attempt to resolve a top level domain name,
that is, a name that contains no dots. Use of this option does not
prevent the resolver from obeying the standard
<b class="Sy">domain</b> and <b class="Sy">search</b> rules with the
given name.</dd>
<dt id="rotate"><a class="permalink" href="#rotate"><b class="Sy">rotate</b></a></dt>
<dd>Sets <code class="Dv">RES_ROTATE</code>. Causes the resolver to
round-robin among the configured name servers, distributing the query
load instead of always trying the first listed server.</dd>
<dt id="reload-period"><a class="permalink" href="#reload-period"><b class="Sy">reload-period</b></a>:<var class="Ar">n</var></dt>
<dd>The resolver checks the modification time of
<span class="Pa">/etc/resolv.conf</span> every <var class="Ar">n</var>
seconds. If <span class="Pa">/etc/resolv.conf</span> has changed, it
is automatically reloaded. The default for <var class="Ar">n</var> is
two seconds. Setting it to zero disables the file check.</dd>
</dl>
<p class="Pp">Options may also be specified as a space or tab separated list
using the <code class="Dv">RES_OPTIONS</code> environment variable.</p>
</dd>
</dl>
<p class="Pp">The <b class="Sy">domain</b> and <b class="Sy">search</b> keywords
are mutually exclusive. If more than one instance of these keywords is
present, the last instance will override.</p>
<p class="Pp">The keyword and value must appear on a single line, and the
keyword (for example, <b class="Sy">nameserver</b>) must start the line. The
value follows the keyword, separated by white space.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
<dl class="Bl-tag Bl-compact">
<dt><span class="Pa">/etc/resolv.conf</span></dt>
<dd>The file <code class="Nm">resolv.conf</code> resides in
<span class="Pa">/etc</span>.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
<p class="Pp">A basic resolv.conf file could be in the following form.</p>
<div class="Bd Pp Bd-indent Li">
<pre># The domain directive is only necessary, if your local
# router advertises something like localdomain and you have
# set up your hostnames via an external domain.
domain localdomain.tld
# In case you a running a local dns server or caching name server
# like local-unbound(8) for example.
nameserver 127.0.0.1
# IP address of the local or ISP name service
nameserver 192.168.2.1
# Fallback nameservers, in this case these from Google.
nameserver 8.8.8.8
nameserver 8.8.4.4
# Attach an OPT pseudo-RR for the EDNS0 extension,
# as specified in RFC 2671.
options edns0</pre>
</div>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">gethostbyname(3)</a>, <a class="Xr">resolver(3)</a>,
<a class="Xr">hostname(7)</a>, <a class="Xr">resolvconf(8)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">resolv.conf</code> file format appeared in
<span class="Ux">4.3BSD</span>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">March 15, 2026</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
