The /etc/resolv.conf File

1. Overview

In Linux, the /etc/resolv.conf file is known as the configuration file for DNS queries. In this tutorial, we’ll be learning what is the /etc/resolv.conf file and which aspects of domain name resolution it can configure.

2. The /etc/resolv.conf File

In Linux, the resolver refers to a library that consists of a collection of functions that does domain name translation. Specifically, it translates domain names to IP addresses by querying the Domain Name Server (DNS). The /etc/resolv.conf file is the file that configures the domain name resolver.

On a high level, a process in Linux calls the getaddrinfo function to translate a domain name into its corresponding IP address. The function, in turn, looks at /etc/nsswitch.conf to see what options are available to resolve a domain name. When it is using the dns option to resolve the domain name, it will first get the configuration for DNS resolution from the /etc/resolv.conf file. Therefore, by modifying the /etc/resolv.conf file, we can configure various aspects of the DNS resolution mechanism.

3. The Anatomy of the resolv.conf File

The usual resolv.conf file configures at least 1 nameserver that points to the DNS to query:

$ cat /etc/resolv.conf
nameserver 8.8.4.4

Other than the nameserver, the resolv.conf supports multiple other options for us to configure the DNS query mechanism. Let’s look at the details of each option.

4. nameserver

The nameserver directive specifies the IP address of the domain name server that the resolver can query against. We can configure up to a maximum of three different DNS by specifying the nameserver directive repeatedly. Then, the resolver will query the DNS according to the order of the nameserver. For example, we configure the resolv.conf to point to three different nameservers:

$ cat /etc/resolv.conf
nameserver 8.8.4.4
nameserver 1.1.1.1
nameserver 8.8.8.8

The resolver will first attempt to query the DNS at 8.8.4.4. If it times out, the resolver will query the DNS at 1.1.1.1 next and finally 8.8.8.8 if the DNS at 1.1.1.1 also times out. Note that despite configuring multiple nameservers, they will not be rotated in a round-robin fashion. To change that, we can configure it with the rotate option, which we’ll see in the subsection later.

One tip for configuring the nameserver is that we should put the most reliable DNS at the top. This would prevent unnecessary retry and ultimately reduce the latency of the domain name resolution process.

5. search

The resolv.conf file supports a list of search domains in the form of a search directive. When we query a domain name, the resolver will combine the domain name with the search domain to form a fully qualified domain name (FQDN) for querying. If not specified, the search list will default to the local domain that’s determined by the gethostname function.

For example, we can configure a list of search domains using the search directive:

$ cat /etc/resolv.conf
search departmentA.org departmentB.org
nameserver 8.8.8.8

We define our search domains as departmentA.org and departmentB.org. When the resolver tries to resolve a domain name nodeA, it will first form the FQDN using departmentA.org into nodeA.departmentA.org and perform the DNS query using that FQDN. If it fails, then the resolver tries the next one in line and queries the IP address of nodeA.departmentB.org.

On the other hand, when the resolver tries to resolve the domain name nodeA.com, it will first query nodeA.com as an absolute domain name. If the DNS fails to resolve it, then only the resolver will combine it with the search domain to form nodeA.com.departmentA.org and retry the query.

The decision of whether the first query as an absolute domain name is performed or not depends entirely on the number of dots present in the domain name. By default, a domain name with at least 1 dot will cause the resolver to query it verbatim without combining it with any search domains. The number of dots for an absolute domain name first query is configurable under the option ndots value, which we’ll see later.

6. sortlist

The sortlist allows us to specify a list of the IP addresses that we want to prioritize in the case where 1 domain name resolves to multiple IP addresses. This is especially useful for domain names that resolve to multiple IP addresses. Using sortlist, we can prioritize a particular IP address or a range of IP addresses over the rest. To configure the sortlist, we specify the directive and then followed with a list of IP addresses and netmask pairs:

$ cat /etc/resolv.conf
nameserver 8.8.4.4
sortlist
34.101.0.0/255.255.0.0

The configuration above will ensure that in the event of a domain name with multiple IP addresses is resolved, the one that matches the IP address netmask pair 34.101.0.0/255.255.0.0 will be prioritized first. Finally, if the netmask is not specified, the natural netmask of the IP address will be used. For example, the IP address 34.101.0.0 is a class A subnet and has a natural netmask of 255.0.0.0. Therefore, in the sortlist, entry 34.101.0.0 is the same as 31.101.0.0/255.0.0.0.

7. Options

In addition to the configurations we’ve seen in previous sections, there’s an option configuration. There’re many options we can specify using the option configuration to further tweak our DNS mechanism in Linux.

7.1. Option: timeout

The timeout option is the duration the resolver will wait for the DNS to resolve before its timeout. The option accepts an integer value, and the duration of this argument is measured in seconds. Additionally, the maximum value we can specify is 30 seconds.

For example, we can set the maximum time the resolver should wait before timeout to 5 seconds:

$ cat /etc/resolv.conf
nameserver 8.8.8.8
options timeout:5

With the configuration above, the resolver will wait for the response for at most 5 seconds before it timeouts.

7.2. Option: ndots

The ndots option configures the minimum number of dots a domain name can have, which makes the resolver query it as an absolute domain name. The default value for this option is 1 and the maximum allowed is 15. For example, we can set the ndots to 3 with the entry options ndots:3:

$ cat /etc/resolv.conf
nameserver 8.8.8.8
options ndots:3

For more details, see section 5 of this article.

7.3. Option: attempt

The attempt option set the number of tries the resolver gets to resolve a domain name before it gives up. The default is 2, and the maximum allowable retry value is 5. The way the attempts number work is that it only counts as a retry when all the configured nameservers failed to return the result. For example, if we have configured 3 different nameservers and the first 2 nameservers timeout, from the perspective of the resolver, no retry has been performed yet.

Let’s say we have three nameservers configured:

$ cat /etc/resolv.conf
nameserver 8.8.4.4
nameserver 1.1.1.1
nameserver 8.8.8.8
options attempts:5

Here we have three different nameservers configured. The resolver will first send the query to the nameserver at 8.8.4.4. If it times out, the resolver will continue on to the nameserver at 1.1.1.1. At this point, the resolver does not consider the 2nd query to the nameserver at 1.1.1.1 a retry.  However, if all three nameservers fail to respond in time, then it uses up 1 retry and repeats the query again, starting from the first nameserver.

In our hypothetical example, if all three nameservers fail to respond in time after all the retries, we would’ve sent five query requests to each of the nameservers that total up to 15 queries.

7.4. Option: rotate

The rotate option makes the resolver rotate the list of configured nameservers in a round-robin fashion. Without this option, the resolver will always query the first nameserver in the list and only use the subsequent nameserver if the first one failed. This option has the effect of distributing the load among different nameservers.

8. Conclusion

In this tutorial, we’ve learned that the /etc/resolv.conf file plays an important role in configuring the DNS query mechanism. Specifically, we’ve seen how it’s read by the resolver as part of the domain name resolution process. Furthermore, we’ve learned about the core configurations such as nameserver, search, and sortlist. Finally, we’ve learned an option configuration that offers further tweaking to the DNS resolution mechanism in Linux.