Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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