/etc/resolv.conf - the resolver configuration file

/etc/resolv.conf is the file the resolver library reads to find DNS resolvers. It looks simple but has three sources of truth: manual edits, DHCP, and systemd-resolved. Understanding who owns the file is essential to keeping DNS configuration stable.

The file

nameserver 10.0.0.1
nameserver 10.0.0.2
search example.com
options timeout:5 attempts:3

Every directive

nameserver

nameserver 10.0.0.1
nameserver 10.0.0.2

The IP of a DNS resolver. The resolver library queries them in order, falling through on failure. Up to 3 entries are commonly allowed (MAXNS).

Configure at least two for redundancy. The two should be on different upstream paths (different uplinks, different physical networks) to survive single-path failures.

search

search example.com
search lab.example.com corp.example.com

The search list is appended to short names. With the example above, host is tried as host.example.com, then host.lab.example.com, then host.corp.example.com.

Keep the search list short. Each entry generates additional DNS queries for every short name. With 4 entries in search and a hostname that does not match, the resolver makes 4 queries per getent hosts host call.

domain

domain example.com

Sets the local domain. Equivalent to a search list with one entry. Use search instead of domain if you have multiple domains.

sortlist

sortlist 10.0.0.0/24

Affects the order of returned A records. Rarely used.

options

options timeout:5 attempts:3 rotate ndots:1

Common options:

• timeout:N: seconds to wait for a resolver response. Default 5.
• attempts:N: number of times to try each resolver. Default 2.
• rotate: round-robin between resolvers (default is try-first-then-fallback).
• ndots:N: the number of dots a name must contain before the resolver tries it as an absolute name first. Default 1. man 5 resolv.conf states it precisely: with the default of 1, “if there are any dots in a name, the name will be tried first as an absolute name before any search list elements are appended to it”. So under ndots:1, db01 (0 dots) goes to the search list first, and db01.internal (1 dot) is tried absolute first and only then against the search list. The value is silently capped at 15.
• use-vc: use TCP instead of UDP for DNS queries.

Who owns the file

/etc/resolv.conf is regenerated by:

1. systemd-resolved: writes a symlink to /run/systemd/resolve/stub-resolv.conf. The file content is generated from per-interface configuration.
2. dhclient: writes the file on every DHCP renewal.
3. NetworkManager: writes the file when network configuration changes.
4. netconfig (SUSE): writes the file on every network change.
5. resolvconf (legacy): writes the file on every service change.

If you edit the file manually, expect it to be overwritten on the next DHCP renewal or network event. To prevent this, use chattr +i (immutable) or configure the writer to preserve your edits.

Check who wrote the file

ls -l /etc/resolv.conf
cat /etc/resolv.conf
file /etc/resolv.conf
stat /etc/resolv.conf

If the file is a symlink to /run/systemd/resolve/..., systemd-resolved owns it. The actual configuration is in /etc/systemd/resolved.conf and per-interface settings in Netplan or NetworkManager.

Stop DHCP from overwriting

In dhclient.conf, add:

supersede domain-name "example.com";
supersede domain-search "example.com";
supersede nameservers 10.0.0.1, 10.0.0.2;

Or to prevent any change:

supersede domain-name "";
supersede nameservers 10.0.0.1;

In NetworkManager, configure per-connection DNS in /etc/NetworkManager/system-connections/:

[ipv4]
method=manual
dns=10.0.0.1;10.0.0.2;
dns-search=example.com;
ignore-auto-dns=yes

ignore-auto-dns=yes prevents DHCP-provided DNS from being used.

Configure systemd-resolved

In /etc/systemd/resolved.conf:

[Resolve]
DNS=10.0.0.1 10.0.0.2
FallbackDNS=
Domains=example.com ~example.com
DNSSEC=yes
DNSOverTLS=opportunistic

Reload:

sudo systemctl restart systemd-resolved
resolvectl status

Two directives are routinely misread here.

Domains= does not restrict DNS= to the listed zones. An entry without a ~ prefix is only a search suffix: it is appended to single-label names, and it routes nothing. An entry prefixed with ~ is a route-only domain: queries for that zone are sent to this configuration’s servers. Both spellings of example.com appear above because both jobs are wanted. Queries outside the listed domains still go to DNS=, because the global DNS= is the default route unless a link claims the query with a more specific ~ domain.

FallbackDNS= is not a failover for an unreachable DNS=. It is used only when no DNS server is known from any source. If 10.0.0.1 and 10.0.0.2 are down, resolution fails - it does not silently drift to a public resolver. Setting it empty, as above, is deliberate on an internal network: it stops internal names leaking to the internet when the configuration is incomplete.

linux-systemd-resolved covers domain routing and split DNS in full.

Persistent manual configuration

To prevent any subsystem from overwriting the file:

sudo chattr +i /etc/resolv.conf

Now even root cannot edit the file until you remove the attribute:

sudo chattr -i /etc/resolv.conf

This is a strong measure and only appropriate when the file is truly static (e.g. an isolated network with manual resolver configuration).

Knowledge check