DNS guide

What DNS does

The Domain Name System maps human-readable names (like api.example.com) to records such as A/AAAA (IP addresses), CNAME (aliases), MX (mail), and TXT (verification, SPF). Applications rarely speak DNS directly — they call libc functions like getaddrinfo(), and the OS resolver handles the rest.

How DNS resolution works on Linux

When a program needs to resolve a hostname, the typical workflow is:

1. Application — calls getaddrinfo("api.example.com", ...) (or legacy gethostbyname)
2. Name Service Switch (NSS) — reads /etc/nsswitch.conf to decide the order of lookup sources for the hosts database
3. files — if listed first, checks /etc/hosts for a static mapping
4. dns — if not found locally, queries the system resolver via /etc/resolv.conf (or through systemd-resolved)
5. Upstream DNS — the configured nameserver(s) recurse the query until an answer (or NXDOMAIN) is returned
6. Result cached — the answer may be cached by the resolver (systemd-resolved, nscd, or the application itself) before returning to the caller

A default /etc/nsswitch.conf line looks like:

That means /etc/hosts wins over DNS. A typo or stale entry in /etc/hosts can override a correct public record — a common troubleshooting surprise.

The same principle applies in Active Directory environments, an outdated entry in /etc/hosts for a domain controller can silently bypass DNS, causing authentication failures that appear to be DNS issues.

Key files and services

• /etc/hosts — static hostname-to-IP mappings
• /etc/resolv.conf — nameserver(s), search domains, options (ndots, timeout)
• systemd-resolved — on many modern distros, manages DNS and may symlink /etc/resolv.conf to /run/systemd/resolve/stub-resolv.conf
• /etc/systemd/resolved.conf — upstream DNS, DNSSEC, caching settings when using systemd-resolved

Record types to know

• A / AAAA — IPv4 and IPv6 address for a hostname
• CNAME — alias pointing to another hostname (not allowed at zone apex)
• MX — mail exchanger priority and target
• TXT — arbitrary text (SPF, DKIM, domain verification)
• PTR — reverse DNS (IP → hostname), used in mail and logging
• NS / SOA — delegation and zone authority metadata

Search domains and FQDNs

If you query db instead of db.internal.example.com, the resolver appends entries from the search or domain directive in /etc/resolv.conf. This is convenient but can cause unexpected results when short names collide across search paths.

Learning resources

• hosts(5) — man7.org/linux/man-pages/man5/hosts.5 (/etc/hosts file format)
• resolv.conf(5) — man7.org/linux/man-pages/man5/resolv.conf.5 (resolver configuration)
• nsswitch.conf(5) — man7.org/linux/man-pages/man5/nsswitch.conf.5 (name service switch)
• systemd-resolved(8) — man7.org/linux/man-pages/man8/systemd-resolved.8 (modern Linux DNS stub resolver)
• Cloudflare Learning — DNS — cloudflare.com/learning/dns (DNS concepts explained)