Configure resolv.conf Safely and Verify DNS Lookups

You will finish with a small, testable /etc/resolv.conf configuration and a way to tell whether a failure is caused by the resolver file, the network, or the application. The examples match the installed Linux man-pages 6.7 description and glibc 2.39 on this machine.

Allow about fifteen minutes. You need a shell and a working account on the Linux host. Reading and testing are ordinary user actions. Editing /etc/resolv.conf requires elevated privileges and can interrupt name resolution for other processes, so keep a recovery copy and check whether another service owns the file first.

1. Inspect the current resolver setup

Start without changing anything. Read the file, check whether it is a symlink, and identify the resolver library version:

$ ls -l /etc/resolv.conf
$ sed -n '1,80p' /etc/resolv.conf
$ getconf GNU_LIBC_VERSION
glibc 2.39

Your file may be generated by NetworkManager, systemd-resolved, a container runtime or another network manager. A symlink is a warning not to replace the target blindly. Find the owner through your normal host documentation before making a persistent edit. The resolver manpage describes the file read by glibc routines; it does not promise that a network manager will preserve manual changes.

2. Test name resolution before editing

Use a new process and the libc name-service interface. This avoids treating a successful command from a different DNS client as proof that applications using glibc will behave the same way:

$ getent ahosts example.com | head -n 3
93.184.216.34   STREAM example.com
93.184.216.34   DGRAM
93.184.216.34   RAW

The addresses and even the number of lines are environment-dependent. A zero exit status and at least one address are the useful result. If this fails, check connectivity and the current nameserver addresses before editing. getent ahosts localhost is only a local hosts-file test, so it cannot prove that DNS is working.

3. Choose a minimal file

A resolver file needs one or more nameserver lines. Each value is an IPv4 or IPv6 address, and glibc uses at most three entries. With several entries it tries them in listed order when a query times out, then retries according to its resolver algorithm.

Use search only when short names are genuinely useful. For example, a machine in office.example might use:

nameserver 192.0.2.53
nameserver 2001:db8::53
search office.example example
options timeout:2 attempts:2

The addresses in this example are documentation ranges, not working public resolvers. Replace them with addresses supplied by your network administrator or service. Do not copy them into a live file.

With the default ndots:1, a name containing a dot is first tried as an absolute name. A name with fewer dots is tried with each search suffix. A long or remote search list can therefore create delays, extra traffic and unintended disclosure of internal-looking names. If you use several search domains, choose an ndots value deliberately, and test the resulting query pattern.

4. Back up before a privileged edit

This is the first state-changing step. Make a copy before editing, and stop if the file is a symlink whose target you have not identified:

$ test ! -L /etc/resolv.conf || echo 'resolver file is a symlink; stop and identify its owner'
$ sudo cp -a /etc/resolv.conf /etc/resolv.conf.bak

Check that the backup exists before continuing:

$ sudo test -s /etc/resolv.conf.bak && echo 'backup created'
backup created

Do not use a blind shell redirection such as sudo sh -c '... > /etc/resolv.conf' with unreviewed content. It can truncate the file before you notice a typo, and a bad nameserver can affect package updates, remote access and service discovery.

5. Install and verify the configuration

Edit the file with your preferred editor, keeping each directive on one line. Comments begin with # or ; in the first column. For the example above, the finished file would contain the four lines shown in step 3.

Then inspect the result and perform a real lookup from a fresh process:

$ sed -n '1,80p' /etc/resolv.conf
$ getent ahosts example.com | head -n 3
93.184.216.34   STREAM example.com

Exact addresses vary. If the lookup hangs, the configured timeout is not the total time for every resolver API call, and retries can involve more than one nameserver. Check the addresses, routing, firewall rules and whether your network permits DNS to those servers. A successful lookup does not prove that every application uses this file, because applications can use their own resolver libraries or external services.

6. Make a process-local test instead

For troubleshooting, you can amend resolver options for one process without editing the file. RES_OPTIONS accepts the same option names, while LOCALDOMAIN supplies a process-local search list:

$ RES_OPTIONS='timeout:1 attempts:1' getent ahosts example.com | head -n 3
$ LOCALDOMAIN='office.example' getent ahosts printer | head -n 3

The second command will only succeed if the configured DNS can resolve printer.office.example. These variables are useful for a controlled comparison, but they do not change other processes and do not rewrite /etc/resolv.conf.

On glibc 2.39, options no-aaaa is available for preliminary diagnosis of troublesome AAAA lookups. It suppresses DNS AAAA queries by the stub resolver, is incompatible with EDNS0 and DNSSEC validation by applications, and is not a general IPv6 fix. Remove it after the test unless you have a documented reason to keep it.

7. Recover from a bad edit

If lookups fail immediately after your change, restore the backup during a maintenance window:

$ sudo cp -a /etc/resolv.conf.bak /etc/resolv.conf
$ getent ahosts example.com | head -n 3

If a manager recreates the file, this manual restore may be temporary. Undo the change in the manager's configuration instead, then rerun the verification command. A process may have already read the old settings; testing with a new process makes the comparison clearer. The no-reload option can disable automatic reloading for a process, so do not assume a long-running service notices every edit.