resolver.5

   1 .\" Copyright (c) 1986 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms are permitted
   5 .\" provided that the above copyright notice and this paragraph are
   6 .\" duplicated in all such forms and that any documentation,
   7 .\" advertising materials, and other materials related to such
   8 .\" distribution and use acknowledge that the software was developed
   9 .\" by the University of California, Berkeley.  The name of the
  10 .\" University may not be used to endorse or promote products derived
  11 .\" from this software without specific prior written permission.
  12 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
  13 .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  14 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  15 .\"
  16 .\"     @(#)resolver.5  5.9 (Berkeley) 12/14/89
  17 .\"     $Id$
  18 .\"
  19 .Dd November 11, 1993
  20 .Dt RESOLVER 5
  21 .Os BSD 4
  22 .Sh NAME
  23 .Nm resolver
  24 .Nd resolver configuration file
  25 .Sh SYNOPSIS
  26 .Pa /etc/resolv.conf
  27 .Sh DESCRIPTION
  28 The
  29 .Nm resolver
  30 is a set of routines in the C library
  31 .Pq Xr resolve 3
  32 that provide access to the Internet Domain Name System.
  33 The
  34 .Nm resolver
  35 configuration file contains information that is read
  36 by the
  37 .Nm resolver
  38 routines the first time they are invoked by a process.
  39 The file is designed to be human readable and contains a list of
  40 keywords with values that provide various types of
  41 .Nm resolver
  42 information.
  43 .Pp
  44 On a normally configured system, this file should not be necessary.
  45 The only name server to be queried will be on the local machine,
  46 the domain name is determined from the host name,
  47 and the domain search path is constructed from the domain name.
  48 .Pp
  49 The different configuration directives are:
  50 .Bl -tag -width "nameser"
  51 .It Li nameserver
  52 Internet address (in dot notation) of a name server that the
  53 .Nm resolver
  54 should query.  Up to
  55 .Dv MAXNS
  56 (see
  57 .Pa <resolv.h> )
  58 name servers may be listed, one per keyword.
  59 If there are multiple servers, the
  60 .Nm resolver
  61 library queries them in the order listed.
  62 If no
  63 .Li nameserver
  64 entries are present, the default is to use the name server on the local machine.
  65 (The algorithm used is to try a name server, and if the query times out,
  66 try the next, until out of name servers,
  67 then repeat trying all the name servers
  68 until a maximum number of retries are made).
  69 .It Li domain
  70 Local domain name.
  71 Most queries for names within this domain can use short names
  72 relative to the local domain.
  73 If no
  74 .Li domain
  75 entry is present, the domain is determined from the local host name returned by
  76 .Xr gethostname 2 ;
  77 the domain part is taken to be everything after the first
  78 .Sq \&. .
  79 Finally, if the host name does not contain a domain part, the root
  80 domain is assumed.
  81 .It Li search
  82 Search list for host-name lookup.
  83 The search list is normally determined from the local domain name;
  84 by default, it contains only the local domain name.
  85 This may be changed by listing the desired domain search path
  86 following the
  87 .Li search
  88 keyword with spaces or tabs separating the names.
  89 Most
  90 .Nm resolver
  91 queries will be attempted using each component
  92 of the search path in turn until a match is found.
  93 Note that this process may be slow and will generate a lot of network
  94 traffic if the servers for the listed domains are not local,
  95 and that queries will time out if no server is available
  96 for one of the domains.
  97 .Pp
  98 The search list is currently limited to six domains
  99 with a total of 256 characters.
 100 .It Li sortlist
 101 Allows addresses returned by gethostbyname to be sorted.
 102 A
 103 .Li sortlist
 104 is specified by IP address netmask pairs. The netmask is
 105 optional and defaults to the natural netmask of the net. The IP address
 106 and optional network pairs are separated by slashes. Up to 10 pairs may
 107 be specified.  For example:
 108 .Bd -literal -offset indent
 109 sortlist 130.155.160.0/255.255.240.0 130.155.0.0
 110 .Ed
 111 .It Li options
 112 Allows certain internal
 113 .Nm resolver
 114 variables to be modified.
 115 The syntax is
 116 .D1 Li options Ar option ...
 117 where
 118 .Ar option
 119 is one of the following:
 120 .Bl -tag -width "ndots:n "
 121 .It Li debug
 122 sets
 123 .Dv RES_DEBUG
 124 in
 125 .Ft _res.options .
 126 .It Li ndots: Ns Ar n
 127 sets a threshold for the number of dots which
 128 must appear in a name given to
 129 .Fn res_query
 130 (see
 131 .Xr resolver 3 )
 132 before an
 133 .Em initial absolute query
 134 will be made.  The default for
 135 .Ar n
 136 is
 137 .Dq 1 ,
 138 meaning that if there are
 139 .Em any
 140 dots in a name, the name will be tried first as an absolute name before any
 141 .Em search list
 142 elements are appended to it.
 143 .It Li timeout: Ns Ar n
 144 sets the amount of time the resolver will wait for a response from a remote
 145 name server before retrying the query via a different name server.  Measured in
 146 seconds, the default is
 147 .Dv RES_TIMEOUT
 148 (see
 149 .Pa <resolv.h> ).
 150 .It Li attempts: Ns Ar n
 151 sets the number of times the resolver will send a query to its name servers
 152 before giving up and returning an error to the calling application.  The
 153 default is
 154 .Dv RES_DFLRETRY
 155 (see
 156 .Pa <resolv.h> ).
 157 .It Li rotate
 158 sets
 159 .Dv RES_ROTATE
 160 in
 161 .Ft _res.options ,
 162 which causes round robin selection of nameservers from among those listed.
 163 This has the effect of spreading the query load among all listed servers,
 164 rather than having all clients try the first listed server first every time.
 165 .It Li no-check-names
 166 sets
 167 .Dv RES_NOCHECKNAME
 168 in
 169 .Ft _res.options ,
 170 which disables the modern BIND checking of incoming host names and mail names
 171 for invalid characters such as underscore (_), non-ASCII, or control characters.
 172 .It Li inet6
 173 sets
 174 .Dv RES_USE_INET6
 175 in
 176 .Ft _res.options .
 177 This has the effect of trying a AAAA query before an A query inside the
 178 .Ft gethostbyname
 179 function, and of mapping IPv4 responses in IPv6 ``tunnelled form'' if no
 180 AAAA records are found but an A record set exists.
 181 .El
 182 .El
 183 .Pp
 184 The
 185 .Li domain
 186 and
 187 .Li search
 188 keywords are mutually exclusive.
 189 If more than one instance of these keywords is present,
 190 the last instance wins.
 191 .Pp
 192 The
 193 .Li search
 194 keyword of a system's
 195 .Pa resolv.conf
 196 file can be
 197 overridden on a per-process basis by setting the environment variable
 198 .Dq Ev LOCALDOMAIN
 199 to a space-separated list of search domains.
 200 .Pp
 201 The
 202 .Li options
 203 keyword of a system's
 204 .Pa resolv.conf
 205 file can be amended on a per-process basis by setting the environment variable
 206 .Dq Ev RES_OPTIONS to a space-separated list of
 207 .Nm resolver
 208 options as explained above under
 209 .Li options .
 210 .Pp
 211 The keyword and value must appear on a single line, and the keyword
 212 (e.g.,
 213 .Li nameserver )
 214 must start the line.  The value follows the keyword, separated by white space.
 215 .Sh FILES
 216 .Pa /etc/resolv.conf
 217 .Pa <resolv.h>
 218 .Sh SEE ALSO
 219 .Xr gethostbyname 3 ,
 220 .Xr hostname 7 ,
 221 .Xr named 8 ,
 222 .Xr resolver 3 ,
 223 .Xr resolver 5 .
 224 .Dq Name Server Operations Guide for Sy BIND