diff options
Diffstat (limited to 'man/man5/resolv.conf.5')
| -rw-r--r-- | man/man5/resolv.conf.5 | 406 |
1 files changed, 406 insertions, 0 deletions
diff --git a/man/man5/resolv.conf.5 b/man/man5/resolv.conf.5 new file mode 100644 index 0000000..0f726a9 --- /dev/null +++ b/man/man5/resolv.conf.5 @@ -0,0 +1,406 @@ +.\" Copyright (c) 1986 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Redistribution and use in source and binary forms are permitted +.\" provided that the above copyright notice and this paragraph are +.\" duplicated in all such forms and that any documentation, +.\" advertising materials, and other materials related to such +.\" distribution and use acknowledge that the software was developed +.\" by the University of California, Berkeley. The name of the +.\" University may not be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %%%LICENSE_END +.\" +.\" @(#)resolver.5 5.9 (Berkeley) 12/14/89 +.\" $Id: resolver.5,v 8.6 1999/05/21 00:01:02 vixie Exp $ +.\" +.\" Added ndots remark by Bernhard R. Link - debian bug #182886 +.\" +.TH resolv.conf 5 2024-05-02 "Linux man-pages (unreleased)" +.UC 4 +.SH NAME +resolv.conf \- resolver configuration file +.SH SYNOPSIS +.nf +.B /etc/resolv.conf +.fi +.SH DESCRIPTION +The +.I resolver +is a set of routines in the C library +that provide access to the Internet Domain Name System (DNS). +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. +The configuration file is considered a trusted source of DNS information; +see the +.B trust-ad +option below for details. +.P +If this file does not exist, only the name server on the local machine +will be queried, and the search list contains the local domain name +determined from the hostname. +.P +The different configuration options are: +.TP +\fBnameserver\fP Name server IP address +Internet address of a name server that the resolver should query, +either an IPv4 address (in dot notation), +or an IPv6 address in colon (and possibly dot) notation as per RFC 2373. +Up to +.B MAXNS +(currently 3, see \fI<resolv.h>\fP) name servers may be listed, +one per keyword. +If there are multiple servers, +the resolver library queries them in the order listed. +If no \fBnameserver\fP 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.) +.TP +\fBsearch\fP Search list for host-name lookup. +By default, the search list contains one entry, the local domain name. +It is determined from the local hostname returned by +.BR gethostname (2); +the local domain name is taken to be everything after the first +\[aq].\[aq]. +Finally, if the hostname does not contain a \[aq].\[aq], the +root domain is assumed as the local domain name. +.IP +This may be changed by listing the desired domain search path +following the \fIsearch\fP keyword with spaces or tabs separating +the names. +Resolver queries having fewer than +.I ndots +dots (default is 1) in them will be attempted using each component +of the search path in turn until a match is found. +For environments with multiple subdomains please read +.BI "options ndots:" n +below to avoid man-in-the-middle attacks and unnecessary +traffic for the root-dns-servers. +.\" When having a resolv.conv with a line +.\" search subdomain.domain.tld domain.tld +.\" and doing a hostlookup, for example by +.\" ping host.anothersubdomain +.\" it sends dns-requests for +.\" host.anothersubdomain. +.\" host.anothersubdomain.subdomain.domain.tld. +.\" host.anothersubdomain.domain.tld. +.\" thus not only causing unnecessary traffic for the root-dns-servers +.\" but broadcasting information to the outside and making man-in-the-middle +.\" attacks possible. +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. +.IP +If there are multiple +.B search +directives, only the search list from the last instance is used. +.IP +In glibc 2.25 and earlier, the search list is limited to six domains +with a total of 256 characters. +Since glibc 2.26, +.\" glibc commit 3f853f22c87f0b671c0366eb290919719fa56c0e +the search list is unlimited. +.IP +The +.B domain +directive is an obsolete name for the +.B search +directive that handles one search list entry only. +.TP +\fBsortlist\fP +This option allows addresses returned by +.BR gethostbyname (3) +to be sorted. +A sortlist is specified by IP-address-netmask pairs. +The netmask is +optional and defaults to the natural netmask of the net. +The IP address +and optional network pairs are separated by slashes. +Up to 10 pairs may +be specified. +Here is an example: +.IP +.in +4n +sortlist 130.155.160.0/255.255.240.0 130.155.0.0 +.in +.TP +\fBoptions\fP +Options allows certain internal resolver variables to be modified. +The syntax is +.RS +.IP +\fBoptions\fP \fIoption\fP \fI...\fP +.P +where \fIoption\fP is one of the following: +.TP +\fBdebug\fP +.\" Since glibc 2.2? +Sets +.B RES_DEBUG +in +.I _res.options +(effective only if glibc was built with debug support; see +.BR resolver (3)). +.TP +.BI ndots: n +.\" Since glibc 2.2 +Sets a threshold for the number of dots which +must appear in a name given to +.BR res_query (3) +(see +.BR resolver (3)) +before an \fIinitial absolute query\fP will be made. +The default for +\fIn\fP is 1, meaning that if there are any dots in a name, the name +will be tried first as an absolute name before any \fIsearch list\fP +elements are appended to it. +The value for this option is silently capped to 15. +.TP +.BI timeout: n +.\" Since glibc 2.2 +Sets the amount of time the resolver will wait for a +response from a remote name server before retrying the +query via a different name server. +This may +.B not +be the total time taken by any resolver API call and there is no +guarantee that a single resolver API call maps to a single timeout. +Measured in seconds, +the default is +.B RES_TIMEOUT +(currently 5, see \fI<resolv.h>\fP). +The value for this option is silently capped to 30. +.TP +.BI attempts: n +Sets the number of times the resolver will send a +query to its name servers before giving up and returning +an error to the calling application. +The default is +.B RES_DFLRETRY +(currently 2, see \fI<resolv.h>\fP). +The value for this option is silently capped to 5. +.TP +.B rotate +.\" Since glibc 2.2 +Sets +.B RES_ROTATE +in +.IR _res.options , +which causes round-robin selection of name servers from among those listed. +This has the effect of spreading the query load among all listed servers, +rather than having all clients try the first listed server first every time. +.TP +.B no\-aaaa (since glibc 2.36) +.\" f282cdbe7f436c75864e5640a409a10485e9abb2 +Sets +.B RES_NOAAAA +in +.IR _res.options , +which suppresses AAAA queries made by the stub resolver, +including AAAA lookups triggered by NSS-based interfaces such as +.BR getaddrinfo (3). +Only DNS lookups are affected: IPv6 data in +.BR hosts (5) +is still used, +.BR getaddrinfo (3) +with +.B AI_PASSIVE +will still produce IPv6 addresses, +and configured IPv6 name servers are still used. +To produce correct Name Error (NXDOMAIN) results, +AAAA queries are translated to A queries. +This option is intended preliminary for diagnostic purposes, +to rule out that AAAA DNS queries have adverse impact. +It is incompatible with EDNS0 usage and DNSSEC validation by applications. +.TP +.B no\-check\-names +.\" since glibc 2.2 +Sets +.B RES_NOCHECKNAME +in +.IR _res.options , +which disables the modern BIND checking of incoming hostnames and +mail names for invalid characters such as underscore (_), non-ASCII, +or control characters. +.TP +.B inet6 +.\" Since glibc 2.2 +Sets +.B RES_USE_INET6 +in +.IR _res.options . +This has the effect of trying an AAAA query before an A query inside the +.BR gethostbyname (3) +function, and of mapping IPv4 responses in IPv6 "tunneled form" +if no AAAA records are found but an A record set exists. +Since glibc 2.25, +.\" b76e065991ec01299225d9da90a627ebe6c1ac97 +this option is deprecated; applications should use +.BR getaddrinfo (3), +rather than +.BR gethostbyname (3). +.TP +.BR ip6\-bytestring " (since glibc 2.3.4 to glibc 2.24)" +Sets +.B RES_USEBSTRING +in +.IR _res.options . +This causes reverse IPv6 lookups to be made using the bit-label format +described in RFC\ 2673; +if this option is not set (which is the default), then nibble format is used. +This option was removed in glibc 2.25, +since it relied on a backward-incompatible +DNS extension that was never deployed on the Internet. +.TP +.BR ip6\-dotint / no\-ip6\-dotint " (glibc 2.3.4 to glibc 2.24)" +Clear/set +.B RES_NOIP6DOTINT +in +.IR _res.options . +When this option is clear +.RB ( ip6\-dotint ), +reverse IPv6 lookups are made in the (deprecated) +.I ip6.int +zone; +when this option is set +.RB ( no\-ip6\-dotint ), +reverse IPv6 lookups are made in the +.I ip6.arpa +zone by default. +These options are available up to glibc 2.24, where +.B no\-ip6\-dotint +is the default. +Since +.B ip6\-dotint +support long ago ceased to be available on the Internet, +these options were removed in glibc 2.25. +.TP +.BR edns0 " (since glibc 2.6)" +Sets +.B RES_USE_EDNS0 +in +.IR _res.options . +This enables support for the DNS extensions described in RFC\ 2671. +.TP +.BR single\-request " (since glibc 2.10)" +Sets +.B RES_SNGLKUP +in +.IR _res.options . +By default, glibc performs IPv4 and IPv6 lookups in parallel since +glibc 2.9. +Some appliance DNS servers +cannot handle these queries properly and make the requests time out. +This option disables the behavior and makes glibc perform the IPv6 +and IPv4 requests sequentially (at the cost of some slowdown of the +resolving process). +.TP +.BR single\-request\-reopen " (since glibc 2.9)" +Sets +.B RES_SNGLKUPREOP +in +.IR _res.options . +The resolver uses the same socket for the A and AAAA requests. +Some hardware mistakenly sends back only one reply. +When that happens the client system will sit and wait for the second reply. +Turning this option on changes this behavior +so that if two requests from the same port are not handled correctly it will +close the socket and open a new one before sending the second request. +.TP +.BR no\-tld\-query " (since glibc 2.14)" +Sets +.B RES_NOTLDQUERY +in +.IR _res.options . +This option causes +.BR res_nsearch () +to not attempt to resolve an unqualified name +as if it were a top level domain (TLD). +This option can cause problems if the site has ``localhost'' as a TLD +rather than having localhost on one or more elements of the search list. +This option has no effect if neither RES_DEFNAMES or RES_DNSRCH is set. +.TP +.BR use\-vc " (since glibc 2.14)" +Sets +.B RES_USEVC +in +.IR _res.options . +This option forces the use of TCP for DNS resolutions. +.\" aef16cc8a4c670036d45590877d411a97f01e0cd +.TP +.BR no\-reload " (since glibc 2.26)" +Sets +.B RES_NORELOAD +in +.IR _res.options . +This option disables automatic reloading of a changed configuration file. +.TP +.BR trust\-ad " (since glibc 2.31)" +.\" 446997ff1433d33452b81dfa9e626b8dccf101a4 +Sets +.B RES_TRUSTAD +in +.IR _res.options . +This option controls the AD bit behavior of the stub resolver. +If a validating resolver sets the AD bit in a response, +it indicates that the data in the response was verified according +to the DNSSEC protocol. +In order to rely on the AD bit, the local system has to +trust both the DNSSEC-validating resolver and the network path to it, +which is why an explicit opt-in is required. +If the +.B trust\-ad +option is active, the stub resolver sets the AD bit in outgoing DNS +queries (to enable AD bit support), and preserves the AD bit in responses. +Without this option, the AD bit is not set in queries, +and it is always removed from responses before they are returned to the +application. +This means that applications can trust the AD bit in responses if the +.B trust\-ad +option has been set correctly. +.IP +In glibc 2.30 and earlier, +the AD is not set automatically in queries, +and is passed through unchanged to applications in responses. +.RE +.P +The \fIsearch\fP keyword of a system's \fIresolv.conf\fP file can be +overridden on a per-process basis by setting the environment variable +.B LOCALDOMAIN +to a space-separated list of search domains. +.P +The \fIoptions\fP keyword of a system's \fIresolv.conf\fP file can be +amended on a per-process basis by setting the environment variable +.B RES_OPTIONS +to a space-separated list of resolver options +as explained above under \fBoptions\fP. +.P +The keyword and value must appear on a single line, and the keyword +(e.g., \fBnameserver\fP) must start the line. +The value follows the keyword, separated by white space. +.P +Lines that contain a semicolon (;) or hash character (#) +in the first column are treated as comments. +.SH FILES +.IR /etc/resolv.conf , +.I <resolv.h> +.SH SEE ALSO +.BR gethostbyname (3), +.BR resolver (3), +.BR host.conf (5), +.BR hosts (5), +.BR nsswitch.conf (5), +.BR hostname (7), +.BR named (8) +.P +Name Server Operations Guide for BIND |