LFCS 102 🐧 Name Resolution — /etc/hosts and /etc/resolv.conf - KandZ

⏱️ Estimated read: 9 min | |

When a program on a Linux system needs to connect to a hostname, the kernel does not perform the lookup. A userspace library, the GNU C Library (glibc), does. It reads a configuration file called /etc/nsswitch.conf to determine the order of lookup sources, then consults those sources one by one until it finds a match. The two primary local sources are /etc/hosts for static, hardcoded mappings and /etc/resolv.conf for dynamic DNS queries. Understanding how these files interact, and which one wins, is fundamental to Linux networking.

Key point: The order of resolution is not hardcoded. It is defined by the hosts: line in /etc/nsswitch.conf. If files precedes dns, /etc/hosts is checked first. If a name is found there, DNS is never queried.

Why name resolution is split

The static mapping problem. Before DNS existed, computers on the ARPANET shared a single text file (HOSTS.TXT) that mapped names to IP addresses. When the network grew too large to distribute a single file, DNS was invented. But the need for local static overrides remained. /etc/hosts is the modern equivalent: a local, per-machine file that takes precedence over DNS for specific names. It is used for loopback mapping, local network devices, and overriding external DNS for testing .

The dynamic resolution problem. /etc/resolv.conf tells the system which DNS servers to query. Without it, the system relies entirely on /etc/hosts and fails to resolve any external name. The file contains nameserver entries (the IP addresses of DNS resolvers), search domains (suffixes appended to unqualified names), and options (timeouts, attempts, and flags) .

The order problem. A system might have conflicting information: /etc/hosts maps app.local to 127.0.0.1, but a DNS server maps it to 10.0.0.5. The resolution order determines which one wins. The Name Service Switch (/etc/nsswitch.conf) is the arbiter. The line hosts: files dns means “check local files first, then DNS.” The line hosts: dns files means the opposite. The default on most systems is files dns .

The systemd problem. Modern Linux distributions often use systemd-resolved, a local caching resolver that runs on 127.0.0.53. In this setup, /etc/resolv.conf is a symlink to a stub file, and the actual upstream DNS servers are configured elsewhere (via systemd-networkd or NetworkManager). Editing /etc/resolv.conf directly may be overwritten. The exam tests the traditional behavior, but the systemd-resolved setup is increasingly common .

The trade-off. Static mappings in /etc/hosts are fast and reliable but require manual maintenance on every machine. DNS is centralized and scalable but depends on network availability. The combination of both, ordered by nsswitch.conf, provides flexibility at the cost of potential confusion when the two sources disagree.

a. The `/etc/hosts` file

/etc/hosts is a plain text file mapping IP addresses to hostnames. Each line begins with an IP address, followed by one or more hostnames. Comments start with #.

127.0.0.1   localhost localhost.localdomain
::1         localhost localhost.localdomain
192.168.1.10   db01.example.com db01
10.0.0.5       app.internal

The first hostname on a line is the canonical name. Additional hostnames are aliases. The loopback entries (127.0.0.1 and ::1) are required. Without them, localhost resolution fails, which can break many applications .

To test resolution against /etc/hosts specifically, getent hosts <name> is the correct tool. It respects nsswitch.conf and shows the result of the lookup without querying DNS directly .

# Resolve via the configured order
getent hosts db01
# Output: 192.168.1.10    db01.example.com db01

The ping command also uses the system resolver, but it prints the IP address it found, which makes the resolution visible.

b. The `/etc/resolv.conf` file

/etc/resolv.conf configures the DNS client. It is read by glibc (and other resolvers) to determine which nameservers to query and how to handle unqualified names.

nameserver 8.8.8.8
nameserver 1.1.1.1
search example.com internal.corp
options timeout:2 attempts:3

The nameserver directive specifies a DNS resolver. Up to three nameservers can be listed. They are queried in order, with fallback to the next if the first does not respond. The search directive lists domains to append to unqualified names. A query for db01 becomes db01.example.com and then db01.internal.corp. The options directive sets timeouts and retries .

The domain directive is the legacy equivalent of a single-entry search list. Modern configurations use search. If both are present, search overrides domain.

A resolver can also be configured to ignore /etc/hosts entirely with options nofiles, but this is rare and generally not recommended.

c. The Name Service Switch and resolution order

/etc/nsswitch.conf controls the order in which resolution sources are consulted. The relevant line is hosts:.

hosts:      files dns myhostname

The files source reads /etc/hosts. The dns source reads /etc/resolv.conf and performs the network query. The myhostname source (provided by systemd) resolves the local hostname even if /etc/hosts is incomplete. The sources are tried in order, left to right. If files returns a match, dns is never consulted.

To verify the order:

grep '^hosts:' /etc/nsswitch.conf
# Output: hosts:      files dns myhostname

If a name resolves to an unexpected IP address, the first step is to check /etc/hosts. If the name is listed there, the entry is overriding DNS. The second step is to check nsswitch.conf to confirm that files precedes dns (or the reverse, if the intent was to prioritize DNS).

Complete Example Session

# ============================================
# PART 1: CHECK RESOLUTION ORDER
# ============================================

grep '^hosts:' /etc/nsswitch.conf
# Output: hosts:      files dns

# ============================================
# PART 2: ADD A STATIC MAPPING
# ============================================

sudo nano /etc/hosts
# Add:
# 192.168.1.50   testapp.local testapp

# ============================================
# PART 3: VERIFY THE STATIC MAPPING
# ============================================

getent hosts testapp.local
# Output: 192.168.1.50    testapp.local testapp

# ============================================
# PART 4: OBSERVE THE OVERRIDE
# ============================================

# Even if DNS has a different record for testapp.local,
# /etc/hosts wins because 'files' precedes 'dns'.

# ============================================
# PART 5: CHECK DNS CONFIGURATION
# ============================================

cat /etc/resolv.conf
# nameserver 8.8.8.8
# search example.com

# ============================================
# PART 6: TEST DNS RESOLUTION
# ============================================

getent hosts google.com
# Output: 142.250.190.14  google.com

# ============================================
# PART 7: TEST UNQUALIFIED NAME
# ============================================

# With search example.com, an unqualified name
# is appended with the search domain.
getent hosts db01
# Queries db01.example.com

# ============================================
# PART 8: REMOVE THE STATIC MAPPING
# ============================================

sudo sed -i '/testapp.local/d' /etc/hosts
getent hosts testapp.local
# No output (or DNS result if DNS has a record).

# ============================================
# PART 9: CHECK SYSTEMD-RESOLVED (IF USED)
# ============================================

resolvectl status
# Shows the actual upstream DNS servers and search domains.
# /etc/resolv.conf may be a stub pointing to 127.0.0.53.

The nine parts trace resolution: checking order, adding a static mapping, verifying it, observing the precedence over DNS, checking DNS configuration, testing DNS resolution, observing search domain behavior, removing the mapping, and checking the systemd-resolved status.

Quick Reference

/etc/hosts Syntax

Field	Example
IP address	`192.168.1.10`
Canonical name	`db01.example.com`
Aliases	`db01`

/etc/resolv.conf Directives

Directive	Purpose
`nameserver <ip>`	DNS resolver address (max 3)
`search <domain>`	Suffixes for unqualified names
`options timeout:N`	Query timeout in seconds
`options attempts:N`	Retry count

nsswitch.conf `hosts:` Line

Source	Meaning
`files`	`/etc/hosts`
`dns`	`/etc/resolv.conf`
`myhostname`	systemd local hostname
`resolve`	systemd-resolved

Best Practices

✅ Do This:

getent hosts testapp.local
<!-- Verify resolution using system order -->         # ✅

127.0.0.1   localhost
<!-- Always keep loopback entries -->                 # ✅

grep '^hosts:' /etc/nsswitch.conf
<!-- Confirm resolution order -->                     # ✅

❌ Don’t Do This:

# Edit /etc/resolv.conf directly on systemd-resolved systems
<!-- Changes may be overwritten -->                   # ❌

# Assume DNS is queried first
<!-- files usually precedes dns -->                   # ❌

# Leave stale entries in /etc/hosts
<!-- Overrides DNS unexpectedly -->                   # ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
Name resolves to wrong IP	Stale `/etc/hosts` entry	Remove or update the entry
DNS not working	`/etc/resolv.conf` missing nameserver	Add `nameserver` directive
Unqualified names fail	No `search` domain	Add `search` directive
Direct edit overwritten	systemd-resolved manages file	Use `resolvectl` or network config
`localhost` resolution fails	Loopback entries missing	Restore `127.0.0.1 localhost`

Real-World Examples

1. Check Resolution Order

grep '^hosts:' /etc/nsswitch.conf

2. Add Host Entry

192.168.1.50   testapp.local testapp

3. Verify Resolution

getent hosts testapp

4. View DNS Servers

cat /etc/resolv.conf

5. Add DNS Server

nameserver 1.1.1.1

6. Add Search Domain

search example.com

7. Test DNS Query

getent hosts google.com

8. Remove Host Entry

sudo sed -i '/testapp.local/d' /etc/hosts

9. Check systemd-resolved

resolvectl status

10. Flush DNS Cache

sudo resolvectl flush-caches

Visual

Resolution Flow

┌──────────────────────────────────────────────┐
│  Application calls getaddrinfo("db01")       │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  /etc/nsswitch.conf: hosts: files dns        │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  1. Check /etc/hosts                         │
│     ├─ Found → return IP                     │
│     └─ Not found → continue                  │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  2. Query DNS via /etc/resolv.conf           │
│     ├─ Found → return IP                     │
│     └─ Not found → return error              │
└──────────────────────────────────────────────┘

The order in nsswitch.conf determines which source wins.

File Interaction

┌──────────────────────────────────────────────┐
│  /etc/nsswitch.conf                          │
│  (controls order)                            │
└──────────────────┬───────────────────────────┘
                   │
        ┌──────────┴──────────┐
        │                     │
        ▼                     ▼
┌───────────────┐     ┌───────────────┐
│  /etc/hosts   │     │/etc/resolv.conf│
│  (static)     │     │  (dynamic)    │
└───────────────┘     └───────────────┘

nsswitch.conf is the arbiter. Without it, neither file is consulted.

Summary

Item	Value
Static mappings	`/etc/hosts`
Dynamic DNS config	`/etc/resolv.conf`
Resolution order	`/etc/nsswitch.conf` (`hosts:` line)
Default order	`files dns`
Verification tool	`getent hosts <name>`
Max nameservers	3
systemd-resolved stub	`127.0.0.53`
Cache flush	`resolvectl flush-caches`

Key takeaways:

Resolution order is defined by nsswitch.conf. The hosts: line lists sources in order. If files precedes dns, /etc/hosts is checked first and a match there overrides DNS .
/etc/hosts is static and manual. It maps IP addresses to hostnames for local use. The loopback entries are mandatory .
/etc/resolv.conf configures DNS. The nameserver, search, and options directives control which servers are queried and how unqualified names are resolved .
getent hosts is the verification tool. It respects nsswitch.conf and shows how the system resolves a name without bypassing the configured order.
systemd-resolved changes the workflow. When it is active, /etc/resolv.conf is a stub, and the real configuration is managed through resolvectl or network manager settings .

Remember: Name resolution is a pipeline: application calls getaddrinfo, nsswitch.conf decides the order, /etc/hosts and /etc/resolv.conf are consulted in that order, and the first match wins. Understanding the pipeline is the prerequisite for debugging any name resolution failure.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!