DNS resolver architecture - how Linux finds names

A Linux host’s DNS resolution involves multiple subsystems that interact in non-obvious ways. Misunderstanding this stack causes the most common DNS configuration mistakes. This lesson explains what each piece does and how they fit.

The stack

Application (curl, ssh, ...)
        |
        v
Resolver library (libc, glibc)
        |
        v
NSS (Name Service Switch) - /etc/nsswitch.conf
        |
        v
NSS modules (nss-files, nss-dns, nss-resolve, ...)
        |
        v
Backend (file: /etc/hosts, dns: /etc/resolv.conf,
         resolve: systemd-resolved, ...)

When an application calls getaddrinfo("example.com"):

1. The resolver library checks NSS for which modules handle “hosts”.
2. NSS modules are tried in order. Default is files dns: first check /etc/hosts, then DNS.
3. The files module reads /etc/hosts.
4. The dns module reads /etc/resolv.conf and queries the configured resolvers.

/etc/nsswitch.conf

grep hosts /etc/nsswitch.conf

Typical output:

hosts:      files dns

This means: for hostname lookups, try /etc/hosts first, then DNS. Other modules exist (e.g. resolve for systemd-resolved, myhostname for systemd’s own hostname generation).

/etc/resolv.conf

The resolver library reads this file directly when NSS uses the dns module:

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

• nameserver: the IP of a DNS resolver. Up to 3 are typically allowed.
• search: domain to append for short names. host becomes host.example.com, then host.example.com.example.com, etc. up to a limit.
• options: per-resolver options. Common: timeout, attempts, rotate (round-robin between resolvers).

The file is regenerated by various subsystems. With systemd-resolved, /etc/resolv.conf is a symlink to /run/systemd/resolve/stub-resolv.conf.

systemd-resolved

systemd-resolved is a local DNS stub resolver that listens on 127.0.0.53:53. It provides:

• Per-interface DNS configuration.
• A cache that survives across queries.
• DNSSEC validation (if enabled).
• DNS-over-TLS support.

When systemd-resolved is in use, applications should talk to 127.0.0.53 (via the stub listener). The actual upstream resolvers are configured per interface in /etc/systemd/resolved.conf.

resolvectl status
resolvectl statistics
resolvectl flush-caches
resolvectl query example.com

resolvectl status shows the configuration for each interface. resolvectl statistics shows cache hit/miss counts. resolvectl flush-caches empties the cache.

The NSS-resolve module

If /etc/nsswitch.conf lists resolve as a hosts source, the resolver library talks to systemd-resolved directly:

hosts:      files resolve [!unavail=continue] dns

The resolve module queries systemd-resolved; if it returns “not available”, fall through to dns. This is the modern configuration on Ubuntu and Fedora.

/etc/hosts

The files module reads this file before consulting DNS:

127.0.0.1   localhost
::1         localhost
10.0.0.10   web01 web01.example.com
192.168.1.5  router

Entries in /etc/hosts override DNS for those names. This is how hosts “see themselves” and is also used for manual overrides during incident response.

Common configuration mistakes

1. /etc/resolv.conf overwritten: a DHCP client overwrites the file on every renewal. With static DNS, configure the DHCP client to preserve custom nameservers.
2. Loop in NSS: nsswitch.conf lists dns twice, or has resolve but systemd-resolved is not running. Lookups hang.
3. Wrong nameserver IP: a typo or a leftover IP from decommissioned infrastructure. Test with dig @<nameserver-ip>.
4. search list too long: each name is appended with the search domains, generating many DNS queries for a short name. Keep to 1-2 entries.
5. Single resolver: one nameserver is a single point of failure. Configure at least two.
6. Ignoring DNSSEC: a validating resolver upstream rejects answers that fail DNSSEC. If your local resolver does not validate, you get unsigned answers.

Diagnose with getent

getent uses the same NSS stack as applications:

getent hosts example.com        # lookup via NSS
getent ahosts example.com       # all addresses (IPv4 + IPv6)

If getent returns one answer but dig returns another, the resolver is misconfigured. If both agree, the issue is elsewhere.

Knowledge check