1.\" $NetBSD: resolv.conf.5,v 1.30 2012/09/09 18:09:24 christos Exp $ 2.\" 3.\" Copyright (c) 1986, 1991 The Regents of the University of California. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)resolver.5 5.12 (Berkeley) 5/10/91 31.\" 32.Dd September 9, 2012 33.Dt RESOLV.CONF 5 34.Os 35.Sh NAME 36.Nm resolv.conf 37.Nd resolver configuration file 38.Sh DESCRIPTION 39The 40.Nm resolv.conf 41file specifies how the 42.Xr resolver 3 43routines in the C library 44(which provide access to the Internet Domain Name System) should operate. 45The resolver configuration file contains information that is read 46by the resolver routines the first time they are invoked by a process. 47The file is designed to be human readable and contains a list of 48keywords with values that provide various types of resolver information. 49.Pp 50On a normally configured system this file should not be necessary. 51The only name server to be queried will be on the local machine, 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 address 59.Pq in dot notation 60or IPv6 address 61.Pq in hex-and-colon notation 62of a name server that the resolver should query. 63Scoped IPv6 address notation is accepted as well 64.Po 65see 66.Xr inet6 4 67for details 68.Pc . 69Up to 70.Dv MAXNS 71(currently 3) name servers may be listed, 72one per keyword. 73If there are multiple servers, 74the resolver library queries them in the order listed. 75If no 76.Sy nameserver 77entries are present, 78the default is to use the name server on the local machine. 79(The algorithm used is to try a name server, and if the query times out, 80try the next, until out of name servers, 81then repeat trying all the name servers 82until a maximum number of retries are made). 83.It Sy domain 84Local domain name. 85Most queries for names within this domain can use short names 86relative to the local domain. 87If no 88.Sy domain 89entry is present, the domain is determined 90from the local host name returned by 91.Xr gethostname 3 ; 92the domain part is taken to be everything after the first 93.Sq \&. . 94Finally, if the host name does not contain a domain part, the root 95domain is assumed. 96.It Sy lookup 97This keyword is now ignored: its function has been superseded by 98features of 99.Xr nsswitch.conf 5 . 100.Pp 101.It Sy search 102Search list for host-name lookup. 103The search list is normally determined from the local domain name; 104by default, it begins with the local domain name, then successive 105parent domains that have at least two components in their names. 106This may be changed by listing the desired domain search path 107following the 108.Sy search 109keyword with spaces or tabs separating 110the names. 111Most resolver queries will be attempted using each component 112of the search path in turn until a match is found. 113Note that this process may be slow and will generate a lot of network 114traffic if the servers for the listed domains are not local, 115and that queries will time out if no server is available 116for one of the domains. 117.Pp 118The search list is currently limited to six domains 119with a total of 1024 characters. 120.It Sy sortlist 121Sortlist allows addresses returned by gethostbyname to 122be sorted. 123A sortlist is specified by IP address netmask pairs. 124The netmask is optional and defaults to the natural 125netmask of the net. 126The IP address and optional network pairs are separated by 127slashes. 128Up to 10 pairs may be specified, ie. 129.Pp 130.Sy sortlist 130.155.160.0/255.255.240.0 130.155.0.0 131.It Sy options 132Options allows certain internal resolver variables to be modified. 133The syntax is: 134.Pp 135.Sy options option ... 136.Pp 137where option is one of the following: 138.Bl -tag -width no-check-names 139.It Sy debug 140enable debugging information, by setting RES_DEBUG in _res.options 141(see 142.Xr resolver 3 ) . 143.It Sy ndots:n 144sets a threshold for the number of dots which 145must appear in a name given to res_query (see 146.Xr resolver 3 ) 147before an initial absolute query will be made. 148The default for n is 1, meaning that if there are any 149dots in a name, the name will be tried first as an absolute 150name before any search list elements are appended to it. 151.It Sy timeout:n 152sets the amount of time the resolver will wait for a response from a remote 153name server before retrying the query via a different name server. 154Measured in seconds, the default is 155.Dv RES_TIMEOUT 156(see 157.Aq Pa resolv.h ) . 158.It Sy attempts:n 159sets the number of times the resolver will send a query to its name servers 160before giving up and returning an error to the calling application. 161The default is 162.Dv RES_DFLRETRY 163(see 164.Aq Pa resolv.h ) . 165.It Sy rotate 166sets 167.Dv RES_ROTATE 168in 169.Ft _res.options , 170which causes round robin selection of nameservers from among those listed. 171This has the effect of spreading the query load among all listed servers, 172rather than having all clients try the first listed server first every time. 173.It Sy no-check-names 174sets 175.Dv RES_NOCHECKNAME 176in 177.Ft _res.options , 178which disables the modern BIND checking of incoming host names and mail names 179for invalid characters such as underscore 180.Pq Sq _ , 181non-ASCII, or control characters. 182This is the default. 183.It Sy check-names 184clears 185.Dv RES_NOCHECKNAME 186in 187.Ft _res.options , 188which enables the modern BIND checking of incoming host names and mail names 189as described above. 190.It Sy edns0 191attach OPT pseudo-RR for ENDS0 extension specified in RFC 2671, 192to inform DNS server of our receive buffer size. 193The option will allow DNS servers to take advantage of non-default receive 194buffer size, and to send larger replies. 195DNS query packets with EDNS0 extension is not compatible with 196non-EDNS0 DNS servers. 197The option must be used only when all the DNS servers listed in 198.Sy nameserver 199lines are able to handle EDNS0 extension. 200.It Sy inet6 201enable support for IPv6-only applications, by setting RES_USE_INET6 in 202_res.options (see 203.Xr resolver 3 ) . 204The option is meaningful with certain kernel configuration only and 205use of this option is discouraged. 206.It Sy insecure1 207Do not require IP source address on the reply packet to be equal to the 208servers' address. 209.It Sy insecure2 210Do not check if the query section of the reply packet is equal 211to that of the query packet. 212For testing purposes only. 213.It Sy no-tld-query 214sets 215.Dv RES_NOTLDQUERY 216in 217.Ft _res.options . 218This option causes 219.Fn res_nsearch 220to not attempt to resolve a unqualified name as if it were a top level 221domain (TLD). 222This option can cause problems if the site has 223.Dq localhost 224as a TLD rather 225than having localhost on one or more elements of the search list. 226This option has no effect if neither 227.Dv RES_DEFNAMES 228or 229.Dv RES_DNSRCH 230is set. 231.El 232.El 233.Pp 234The 235.Sy domain 236and 237.Sy search 238keywords are mutually exclusive. 239If more than one instance of these keywords is present, 240the last instance will override. 241.Pp 242The 243.Sy search 244keyword of a system's 245.Pa resolv.conf 246file can be overridden on a per-process basis by setting the 247environment variable 248.Ev LOCALDOMAIN 249to a space-separated list of search domains. 250.Pp 251The 252.Sy options 253keyword of a system's 254.Pa resolv.conf 255file can be amended on a per-process basis by setting the 256environment variable 257.Ev RES_OPTIONS 258to a space-separated list of resolver options as explained above. 259.Pp 260The keyword and value must appear on a single line, and the keyword 261(e.g. 262.Sy nameserver ) 263must start the line. 264The value follows the keyword, separated by white space. 265.Sh FILES 266.Bl -tag -width /etc/resolv.conf -compact 267.It Pa /etc/resolv.conf 268The file 269.Nm resolv.conf 270resides in 271.Pa /etc . 272.El 273.Sh SEE ALSO 274.Xr gethostbyname 3 , 275.Xr resolver 3 , 276.Xr nsswitch.conf 5 , 277.Xr hostname 7 , 278.Xr named 8 , 279.Xr resolvconf 8 280.Rs 281.%A Paul Vixie 282.%A Kevin J. Dunlap 283.%A Michael J. Karels 284.%T "Name Server Operations Guide for BIND" 285.%N Release 4.9.4 286.%I CSRG , 287.%I Department of Electrical Engineering and Computer Sciences , 288.%I University of California, Berkeley 289.%D July 16, 1996 290.%U http://www.dns.net/dnsrd/docs/bog/bog.html 291.Re 292.Sh HISTORY 293The 294.Nm resolv.conf 295file format appeared in 296.Bx 4.3 . 297