share/man/man5/resolv.conf.5

   1 .\"     $NetBSD: resolv.conf.5,v 1.23 2003/09/07 16:22:29 wiz 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 January 16, 1999
  33 .Dt RESOLV.CONF 5
  34 .Os
  35 .Sh NAME
  36 .Nm resolv.conf
  37 .Nd resolver configuration file
  38 .Sh DESCRIPTION
  39 The
  40 .Nm resolv.conf
  41 file specifies how the
  42 .Xr resolver 3
  43 routines in the C library
  44 (which provide access to the Internet Domain Name System) should operate.
  45 The resolver configuration file contains information that is read
  46 by the resolver routines the first time they are invoked by a process.
  47 The file is designed to be human readable and contains a list of
  48 keywords with values that provide various types of resolver information.
  49 .Pp
  50 On a normally configured system this file should not be necessary.
  51 The only name server to be queried will be on the local machine,
  52 the domain name is determined from the host name,
  53 and the domain search path is constructed from the domain name.
  54 .Pp
  55 The different configuration options are:
  56 .Bl -tag -width nameserver
  57 .It Sy nameserver
  58 IPv4 address
  59 .Pq in dot notation
  60 or IPv6 address
  61 .Pq in hex-and-colon notation
  62 of a name server that the resolver should query.
  63 Scoped IPv6 address notation is accepted as well
  64 .Po
  65 see
  66 .Xr inet6 4
  67 for details
  68 .Pc .
  69 Up to
  70 .Dv MAXNS
  71 (currently 3) name servers may be listed,
  72 one per keyword.
  73 If there are multiple servers,
  74 the resolver library queries them in the order listed.
  75 If no
  76 .Sy nameserver
  77 entries are present,
  78 the 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,
  80 try the next, until out of name servers,
  81 then repeat trying all the name servers
  82 until a maximum number of retries are made).
  83 .It Sy domain
  84 Local domain name.
  85 Most queries for names within this domain can use short names
  86 relative to the local domain.
  87 If no
  88 .Sy domain
  89 entry is present, the domain is determined
  90 from the local host name returned by
  91 .Xr gethostname 3 ;
  92 the domain part is taken to be everything after the first `.'.
  93 Finally, if the host name does not contain a domain part, the root
  94 domain is assumed.
  95 .It Sy lookup
  96 This keyword is now ignored: its function has been superseded by
  97 features of
  98 .Xr nsswitch.conf 5 .
  99 .Pp
 100 .It Sy search
 101 Search list for host-name lookup.
 102 The search list is normally determined from the local domain name;
 103 by default, it begins with the local domain name, then successive
 104 parent domains that have at least two components in their names.
 105 This may be changed by listing the desired domain search path
 106 following the
 107 .Sy search
 108 keyword with spaces or tabs separating
 109 the names.
 110 Most resolver queries will be attempted using each component
 111 of the search path in turn until a match is found.
 112 Note that this process may be slow and will generate a lot of network
 113 traffic if the servers for the listed domains are not local,
 114 and that queries will time out if no server is available
 115 for one of the domains.
 116 .Pp
 117 The search list is currently limited to six domains
 118 with a total of 1024 characters.
 119 .It Sy sortlist
 120 Sortlist allows addresses returned by gethostbyname to
 121 be sorted.
 122 A sortlist is specified by IP address netmask pairs.
 123 The netmask is optional and defaults to the natural
 124 netmask of the net.
 125 The IP address and optional network pairs are separated by
 126 slashes.
 127 Up to 10 pairs may be specified, ie.
 128 .Pp
 129 .Sy sortlist 130.155.160.0/255.255.240.0 130.155.0.0
 130 .It Sy options
 131 Options allows certain internal resolver variables to be modified.
 132 The syntax is:
 133 .Pp
 134 .Sy options option ...
 135 .Pp
 136 where option is one of the following:
 137 .Bl -tag -width insecure1
 138 .It Sy debug
 139 enable debugging information, by setting RES_DEBUG in _res.options
 140 (see
 141 .Xr resolver 3 ) .
 142 .It Sy edns0
 143 attach OPT pseudo-RR for ENDS0 extension specified in RFC 2671,
 144 to inform DNS server of our receive buffer size.
 145 The option will allow DNS servers to take advantage of non-default receive
 146 buffer size, and to send larger replies.
 147 DNS query packets with EDNS0 extension is not compatible with
 148 non-EDNS0 DNS servers.
 149 The option must be used only when all the DNS servers listed in
 150 .Sy nameserver
 151 lines are able to handle EDNS0 extension.
 152 .It Sy inet6
 153 enable support for IPv6-only applications, by setting RES_USE_INET6 in
 154 _res.options (see
 155 .Xr resolver 3 ) .
 156 The option is meaningful with certain kernel configuration only and
 157 use of this option is discouraged.
 158 .It Sy insecure1
 159 Do not require IP source address on the reply packet to be equal to the
 160 servers' address.
 161 .It Sy insecure2
 162 Do not check if the query section of the reply packet is equal
 163 to that of the query packet.
 164 For testing purposes only.
 165 .It Sy ndots:n
 166 sets a threshold for the number of dots which
 167 must appear in a name given to res_query (see
 168 .Xr resolver 3 )
 169 before an initial absolute query will be made.
 170 The default for n is 1, meaning that if there are any
 171 dots in a name, the name will be tried first as an absolute
 172 name before any search list elements are appended to it.
 173 .El
 174 .El
 175 .Pp
 176 The
 177 .Sy domain
 178 and
 179 .Sy search
 180 keywords are mutually exclusive.
 181 If more than one instance of these keywords is present,
 182 the last instance will override.
 183 .Pp
 184 The
 185 .Sy search
 186 keyword of a system's
 187 .Pa resolv.conf
 188 file can be overridden on a per-process basis by setting the
 189 environment variable
 190 .Ev LOCALDOMAIN
 191 to a space-separated list of search domains.
 192 .Pp
 193 The
 194 .Sy options
 195 keyword of a system's
 196 .Pa resolv.conf
 197 file can be amended on a per-process basis by setting the
 198 environment variable
 199 .Ev RES_OPTIONS
 200 to a space-separated list of resolver options as explained above.
 201 .Pp
 202 The keyword and value must appear on a single line, and the keyword
 203 (e.g.
 204 .Sy nameserver )
 205 must start the line.  The value follows
 206 the keyword, separated by white space.
 207 .Sh FILES
 208 .Bl -tag -width /etc/resolv.conf -compact
 209 .It Pa /etc/resolv.conf
 210 The file
 211 .Nm resolv.conf
 212 resides in
 213 .Pa /etc .
 214 .El
 215 .Sh SEE ALSO
 216 .Xr gethostbyname 3 ,
 217 .Xr resolver 3 ,
 218 .Xr nsswitch.conf 5 ,
 219 .Xr hostname 7 ,
 220 .Xr named 8
 221 .Rs
 222 .%T "Name Server Operations Guide for BIND"
 223 .Re
 224 .Sh HISTORY
 225 The
 226 .Nm resolv.conf
 227 file format appeared in
 228 .Bx 4.3 .