| .\" 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 2021-03-22 "" "Linux Programmer's Manual" |
| .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. |
| .PP |
| 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. |
| .PP |
| 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 |
| .PP |
| where \fIoption\fP is one of the following: |
| .TP |
| \fBdebug\fP |
| .\" Since glibc 2.2? |
| Sets |
| .BR RES_DEBUG |
| in |
| .IR _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 |
| .BR 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 |
| .BR 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 |
| .BR 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 |
| .BR 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\-check\-names |
| .\" since glibc 2.2 |
| Sets |
| .BR 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 |
| .BR 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 2.24)" |
| Sets |
| .BR 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 2.24)" |
| Clear/set |
| .BR 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 in glibc versions up to 2.24, where |
| .BR no\-ip6\-dotint |
| is the default. |
| Since |
| .BR 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 |
| .BR 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 |
| .BR RES_SNGLKUP |
| in |
| .IR _res.options . |
| By default, glibc performs IPv4 and IPv6 lookups in parallel since |
| version 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 |
| .BR 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 |
| .BR 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 |
| .BR 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 |
| .BR 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 |
| .BR 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 version 2.30 and earlier, |
| the AD is not set automatically in queries, |
| and is passed through unchanged to applications in responses. |
| .RE |
| .PP |
| 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. |
| .PP |
| 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. |
| .PP |
| 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. |
| .PP |
| 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) |
| .PP |
| Name Server Operations Guide for BIND |