Resolvectl: Inspecting Per-Interface DNS Configurations, Flushing Resolver Caches, and Triaging DNS-over-TLS Routing in Production
In moments of high stress, muscle memory takes command. You immediately open /etc/resolv.conf, the venerable configuration file that Unix administrators have relied upon since the dawn of the internet, fully expecting to spot a botched nameserver address or a corrupted text entry. Instead, you are greeted by an unhelpful, immutable stub entry: nameserver 127.0.0.53. You run standard diagnostic tools like dig or nslookup, and both cheerfully announce that every domain under the sun resolves without a hitch. You are caught in a classic systems engineering trap: your diagnostic utilities are lying to you because they bypass the operating system's local resolution pipeline, querying external nameservers directly rather than tracing the path your production software must navigate.
Modern Linux operating systems have largely abandoned the static text files of decades past in favour of a dynamic, event-driven name-resolution subsystem managed by systemd-resolved.service(8). Rather than forcing every physical Ethernet card, Wi-Fi adapter, and VPN tunnel to share a single, monolithic list of upstream nameservers, modern systems manage domain lookups, security rules, and encrypted tunnels independently on a per-network-interface basis. The primary command-line tool for inspecting, controlling, and troubleshooting this sophisticated machinery is resolvectl.
If you ever find yourself struggling to understand why an application cannot resolve an internal service address, or which DNS server is handling your queries, you do not need to decipher convoluted configuration files. The single most useful command you can run to cut through the fog is:
resolvectl status
Executing this command provides an immediate, link-by-link inventory of your server's entire name-resolution topology across all active network interfaces:
Global
Protocols: -LLMNR -mDNS +DNSOverTLS DNSSEC=allow-downgrade/supported
resolv.conf mode: stub
Current DNS Server: 1.1.1.1
DNS Servers: 1.1.1.1 8.8.8.8
DNS Domain: ~.
Link 2 (eth0)
Current Scopes: DNS
Protocols: +DefaultRoute -LLMNR -mDNS +DNSOverTLS DNSSEC=allow-downgrade/supported
Current DNS Server: 1.1.1.1
DNS Servers: 1.1.1.1 8.8.8.8
DNS Domain: ~.
Link 3 (wg0)
Current Scopes: DNS
Protocols: -DefaultRoute -LLMNR -mDNS -DNSOverTLS DNSSEC=no
Current DNS Server: 10.200.0.1
DNS Servers: 10.200.0.1
DNS Domain: ~internal.net ~10.in-addr.arpa
With just a few lines of output, the mystery clears: public internet traffic flows through eth0 via 1.1.1.1 with encrypted DNS-over-TLS enabled, while private corporate hostnames ending in .internal.net and internal IP reverse lookups are directed through the WireGuard virtual interface wg0 straight to 10.200.0.1.
1. What It Does in Plain English
In contemporary Linux environments, resolvectl is the dedicated administrative control plane used to inspect, configure, and troubleshoot how the operating system translates human-readable domain names (such as api.internal.network) into machine-routable IP addresses.
Instead of forcing all network interfaces to share a single, static list of name servers, the underlying systemd-resolved.service(8) manages distinct DNS servers, security parameters, and routing domains on a per-network-interface basis.
resolvectl enables administrators to:
- Dynamically bind upstream DNS servers to specific network adapters (such as physical Ethernet links, Wi-Fi interfaces, or WireGuard and IPsec VPN tunnels).
- Isolate internal corporate domains using routing scopes so sensitive queries never leak onto public upstream networks.
- Audit and enforce cryptographic DNSSEC validation chains.
- Instantaneously flush poisoned or stale resource record caches.
- Enforce strict transport-layer encryption (DNS-over-TLS) across outbound traffic without restarting system networking daemons.
2. Core Architecture & Pedagogical Foundation
The Demise of Monolithic /etc/resolv.conf and the Rise of the Local Stub
For decades, Unix-like operating systems relied on the standard POSIX resolver(3) library embedded within glibc. When an application called getaddrinfo(3) or gethostbyname(3), the library synchronously read /etc/resolv.conf on every single invocation.
While straightforward, this static design suffered from severe limitations in dynamic, cloud-native, and multi-homed networking environments:
1. The Three-Nameserver Ceiling: It supported a maximum of three nameserver directives, which were queried in a rigid sequential order with punishing timeout penalties when an upstream server stalled.
2. No Split-Horizon Routing: It had no native ability to route queries for specific domain suffixes exclusively across specific network interfaces.
3. No Centralized Local Caching: Every application had to independently query upstream resolvers, generating unnecessary network traffic and adding latency.
4. Configuration Clashes: Concurrent network configuration utilities (such as NetworkManager, systemd-networkd, DHCP clients, and VPN tunnels) continuously overwrote /etc/resolv.conf, triggering race conditions and configuration flapping.
Modern Linux distributions eliminate these bottlenecks through architectural separation:
The operating system initializes a local loopback stub resolver listening on 127.0.0.53:53 (and optionally 127.0.0.54:54). The file /etc/resolv.conf becomes a symbolic link pointing to /run/systemd/resolve/stub-resolv.conf. Legacy tools sending standard DNS queries to 127.0.0.53 are intercepted locally by systemd-resolved.
Concurrently, modern applications linked against glibc utilize the nss-resolve(8) Name Service Switch module configured in /etc/nsswitch.conf:
hosts: resolve [!UNAVAIL=return] files mymachines myhostname dns
When an application queries a domain name via nss-resolve, the request bypasses standard network sockets altogether, communicating directly with systemd-resolved over high-speed D-Bus inter-process communication or the local socket /run/systemd/resolve/io.systemd.Resolve.
Query Routing Logic and Split-Horizon Domains
systemd-resolved organizes query dispatching around interface-specific routing domains configured via resolvectl domain:
- Standard Search Domain (
example.com): Appended automatically to single-label hostnames (e.g.,server1expands toserver1.example.com) while also acting as a routing directive. - Exclusive Routing Domain (
~example.com): The tilde (~) prefix designates a domain as an exclusive routing scope. Queries matching this domain suffix are dispatched only to the nameservers assigned to that specific interface, preventing private enterprise lookups from leaking across public gateways. - Default Routing Scope (
~.): The tilde-dot notation marks an interface as the preferred default route for any domain that does not match a more specific routing prefix on another adapter.
If multiple active interfaces share identical routing scopes, systemd-resolved balances queries across them in parallel or adheres to link-metric routing preferences established by your network configuration.
3. Core Flags & Quick Start
The resolvectl utility unifies status reporting, diagnostic querying, and runtime configuration into a clean syntax:
| Command / Flag | Operational Scope | Administrative Objective |
|---|---|---|
resolvectl status [LINK] |
Global / Per-Link | Visualizes active upstream resolvers, fallback servers, search domains, DNSSEC status, and transport protocol configurations. |
resolvectl query [NAME...] |
Query Pipeline | Resolves IPv4/IPv6 addresses and arbitrary resource records (RRsets) while displaying cryptographic validation and latency. |
resolvectl dns [LINK] [IP...] |
Per-Link Configuration | Dynamically binds one or more upstream DNS server addresses to a designated network interface. |
resolvectl domain [LINK] [DOM...] |
Per-Link Configuration | Configures search domains and exclusive routing scopes (~domain) for a designated network interface. |
resolvectl default-route [LINK] [BOOL] |
Per-Link Configuration | Enforces or revokes whether a specific network interface acts as the default resolver route (~.). |
resolvectl flush-caches |
Global Runtime | Flushes all in-memory resource record caches (both positive and negative) across all managed interfaces. |
resolvectl statistics |
Global Telemetry | Returns runtime cache hits, cache misses, DNSSEC verification verdicts, transaction counts, and memory stats. |
resolvectl dnsovertls [LINK] [MODE] |
Transport Security | Enforces DNS-over-TLS encryption policy (no, opportunistic, or yes) globally or on a per-interface basis. |
4. Five Real-World Production Use-Cases
| # | Incident / Objective | Primary Diagnostic Command | Target Interface |
|---|---|---|---|
| 1 | Resolver Topology Auditing | resolvectl status eth0 |
eth0 / Physical Link |
| 2 | Record Querying & DNSSEC Triage | resolvectl query --type=TXT ... |
Runtime Resolver |
| 3 | Cache Invalidation & Telemetry | resolvectl statistics |
Global Cache Layer |
| 4 | Split-Horizon Route Isolation | resolvectl domain wg0 "~corp.internal" |
wg0 / VPN Overlay |
| 5 | Strict DNS-over-TLS Enforcement | resolvectl dnsovertls eth0 yes |
eth0 / Public Egress |
Case 1: Inspecting Global and Per-Interface Resolver Topologies
Scenario
A Kubernetes worker node running on a multi-homed bare-metal server experiences intermittent connection timeouts when pulling container images from an external registry. Engineers suspect a recent DHCP lease renewal on a secondary provisioning network (eth1) accidentally configured a default DNS route that collides with the primary public gateway (eth0).
Command
resolvectl status eth0
Realistic Terminal Output
Link 2 (eth0)
Current Scopes: DNS
Protocols: +DefaultRoute +LLMNR -mDNS -DNSOverTLS DNSSEC=allow-downgrade/supported
Current DNS Server: 192.0.2.53
DNS Servers: 192.0.2.53 198.51.100.53
Fallback DNS Servers: 1.1.1.1 8.8.8.8
DNS Domain: prod.datacenter.internal ~.
Output Dissection
Link 2 (eth0): Identifies the kernel interface index and interface name under evaluation.Current Scopes: DNS: Confirms that standard unicast DNS resolution is actively operating on this interface (as opposed to LLMNR or mDNS).Protocols: +DefaultRoute: The+prefix confirms this interface acts as the default resolver route (~.), meaning general, un-scoped queries will travel through its upstream nameservers.Current DNS Server: 192.0.2.53: The active upstream nameserver currently handling live queries for this link.DNS Servers: 192.0.2.53 198.51.100.53: The ordered list of primary and secondary nameservers configured for this interface.Fallback DNS Servers: 1.1.1.1 8.8.8.8: Built-in or configured fallback resolvers defined inresolved.conf(5)that step in only if all primary nameservers fail.DNSSEC=allow-downgrade/supported: Indicates that DNSSEC validation is attempted; if an upstream server lacks DNSSEC support, validation drops back gracefully rather than returning a fatalSERVFAIL.
Action Plan
The administrator inspects the secondary interface with resolvectl status eth1. If eth1 also exhibits +DefaultRoute, a routing collision is confirmed. The engineer removes the default route from the secondary interface by executing resolvectl default-route eth1 false, restoring deterministic query dispatching through eth0.
Case 2: Targeted Resource Record Querying & DNSSEC Verification
Scenario
An automated pipeline deploying TLS certificates fails during an ACME DNS-01 validation challenge. The engineer needs to confirm whether the challenge TXT record has propagated through the local resolver daemon and determine whether strict DNSSEC validation is rejecting the record due to a broken signature chain.
Command
resolvectl query --type=TXT _acme-challenge.secure.enterprise.io
Realistic Terminal Output
_acme-challenge.secure.enterprise.io IN TXT "v=spf1 include:_spf.google.com ~all" -- link: eth0
_acme-challenge.secure.enterprise.io IN TXT "L9kP_Z4mN2qR8sT1uV3wX5yZ7aB9cE1g" -- link: eth0
-- Information acquired via protocol DNS in 24.3ms.
-- Data is authenticated: yes; Data was acquired via local or encrypted transport: yes
-- Data from: network
Output Dissection
IN TXT "..." -- link: eth0: Displays the returned record payload and identifieseth0as the network link that fulfilled the request.Information acquired via protocol DNS in 24.3ms: Quantifies the full round-trip query latency, helping isolate upstream network delays.Data is authenticated: yes: CRITICAL. Proves thatsystemd-resolvedsuccessfully validated cryptographic RRSIG signatures from the root trust anchor (.) through to the authoritative zone key.Data was acquired via local or encrypted transport: yes: Confirms the lookup was transmitted across an authenticated medium (such as DNS-over-TLS or loopback D-Bus IPC).Data from: network: Indicates the record was retrieved live from upstream nameservers rather than being returned from local cache (Data from: cache).
Action Plan
If Data is authenticated: displays no for a zone requiring cryptographic proof, the engineer queries the key signing records directly using resolvectl query --type=DNSKEY secure.enterprise.io and resolvectl query --type=DS secure.enterprise.io to ensure the parent delegation record matches the public key published in the child zone.
Case 3: Cache Flushing & Real-Time Resolution Telemetry
Scenario
During a blue-green infrastructure migration, a primary database endpoint (db-primary.cloud.internal) was updated to point to a new IP address. Applications running on the host continue trying to reach the old, decommissioned server due to lingering cache records inside systemd-resolved. The sysadmin needs to purge the local cache and inspect resolver telemetry to ensure lookup patterns return to normal.
Command
resolvectl flush-caches && resolvectl statistics
Realistic Terminal Output
Transactions
Total Transactions: 148293
Current Transactions: 2
Cache
Current Cache Size: 0
Cache Hits: 94102
Cache Misses: 54191
DNSSEC Verdicts
Secure: 42109
Insecure: 12082
Bogus: 3
Indeterminate: 0
Output Dissection
Total Transactions: 148293: Cumulative number of DNS transactions processed by the daemon since it started.Current Transactions: 2: Active asynchronous queries currently waiting for an upstream response.Current Cache Size: 0: Confirms thatflush-cachesexecuted immediately, resetting the in-memory cache allocation to zero across all interfaces.Cache Hits: 94102vsCache Misses: 54191: Demonstrates a cache hit ratio of roughly 63.4%, verifying that local caching is significantly reducing network overhead.DNSSEC Verdicts -> Bogus: 3: Reveals that three historical transactions failed validation due to corrupted signatures, expired keys, or upstream tampering.DNSSEC Verdicts -> Insecure: 12082: Tracks queries for zones that do not publish DNSSEC records.
Action Plan
With the cache cleared, the engineer runs resolvectl query db-primary.cloud.internal to trigger an immediate, fresh authoritative query and verifies that applications connect to the updated database endpoint.
Case 4: Configuring Link-Specific Split-Horizon DNS & Routing Scopes
Scenario
A server establishes a WireGuard VPN tunnel (wg0) to access private corporate resources. However, internal domain queries for *.corp.internal are leaking across the public internet connection (eth0), where public resolvers reject them. The engineer must dynamically configure wg0 to capture all queries for corp.internal and the reverse lookup zone 10.in-addr.arpa.
Command
resolvectl dns wg0 10.200.0.1 10.200.0.2 && \
resolvectl domain wg0 "~corp.internal" "~10.in-addr.arpa" && \
resolvectl default-route wg0 false
Realistic Terminal Output
# Verify the updated interface configuration
resolvectl status wg0
Link 4 (wg0)
Current Scopes: DNS
Protocols: -DefaultRoute -LLMNR -mDNS -DNSOverTLS DNSSEC=no
Current DNS Server: 10.200.0.1
DNS Servers: 10.200.0.1 10.200.0.2
DNS Domain: ~corp.internal ~10.in-addr.arpa
Output Dissection
resolvectl dns wg0 10.200.0.1 10.200.0.2: Assigns the internal nameservers10.200.0.1and10.200.0.2directly to interfacewg0.resolvectl domain wg0 "~corp.internal" "~10.in-addr.arpa": The tilde (~) designates an exclusive routing scope. Any lookup matching*.corp.internalor reverse PTR lookups for10.0.0.0/8are routed strictly throughwg0.resolvectl default-route wg0 false: Ensures general internet traffic (such as queries forgoogle.com) is not directed through the corporate VPN nameservers, preventing unnecessary latency and privacy leaks.
Action Plan
The administrator tests routing separation by querying an internal service followed by a public domain:
resolvectl query api.corp.internal
resolvectl query kernel.org
The output confirms api.corp.internal is resolved via wg0 through 10.200.0.1, while kernel.org routes via eth0 to public upstream resolvers.
Case 5: Enforcing DNS-over-TLS (DoT) & Strict Encryption Policies
Scenario
Under enterprise compliance mandates (such as PCI-DSS or HIPAA), a systems architect must guarantee that all outbound DNS queries leaving a host are encrypted over the wire to protect against eavesdropping and transit inspection, using RFC 7858 (DNS-over-TLS).
Command
resolvectl dns eth0 1.1.1.1#cloudflare-dns.com 9.9.9.9#dns.quad9.net && \
resolvectl dnsovertls eth0 yes
Realistic Terminal Output
# Test secure resolution over the wire
resolvectl query cloudflare.com
cloudflare.com: 104.16.132.229 -- link: eth0
104.16.133.229 -- link: eth0
2606:4700::6810:84e5 -- link: eth0
2606:4700::6810:85e5 -- link: eth0
-- Information acquired via protocol DNS in 18.1ms.
-- Data is authenticated: yes; Data was acquired via local or encrypted transport: yes
-- Data from: network
Output Dissection
1.1.1.1#cloudflare-dns.com: The hash (#) syntax specifies the Server Name Indication (SNI) TLS hostname.systemd-resolvedvalidates the upstream server's X.509 certificate against this domain during the TLS handshake.resolvectl dnsovertls eth0 yes: Enforces strict DNS-over-TLS mode. Unlikeopportunisticmode (which falls back to unencrypted UDP port 53 if TLS negotiation fails),yesmandates that lookups will fail outright if TLS cannot be established on TCP port 853, preventing silent downgrade attacks.Data was acquired via local or encrypted transport: yes: Confirms that query transmission was encrypted from the local host to the upstream recursive resolver over TCP/853.
Action Plan
To verify that encrypted connections are active and unencrypted DNS traffic is blocked, the engineer checks active socket connections using ss:
ss -t -a '( dport = :853 or sport = :853 )'
State Recv-Q Send-Q Local Address:Port Peer Address:Port
ESTAB 0 0 192.0.2.100:49212 1.1.1.1:853
The output confirms an established, persistent TLS connection to the upstream resolver on port 853.
5. What Can Go Wrong: Diagnostic Failure Scenarios & Recovery
Even experienced engineers run into subtle pitfalls when navigating systemd-resolved and resolvectl. Here are three common failure modes and how to resolve them.
1. The Severed /etc/resolv.conf Symlink Trap
The Failure
Legacy configuration scripts, third-party software, or older VPN clients occasionally overwrite /etc/resolv.conf with a static text file instead of preserving it as a symbolic link to the dynamic stub generated by systemd-resolved.
ls -l /etc/resolv.conf
# Output: -rw-r--r-- 1 root root /etc/resolv.conf (Regular file, NOT a symlink)
When this occurs, any runtime changes made with resolvectl appear to have no effect because legacy applications read the static file directly rather than querying the local stub at 127.0.0.53 or using the D-Bus interface.
The Remediation
Recreate the standardized symbolic link pointing back to the dynamic stub configuration:
ln -sf /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf
systemctl restart systemd-resolved
Verify that /etc/resolv.conf correctly links to /run/systemd/resolve/stub-resolv.conf.
2. The Missing Tilde: Routing Domain Leaks
The Failure
An administrator attempts to bind a private corporate domain to a VPN interface (tun0) using resolvectl domain tun0 corp.internal, accidentally omitting the leading tilde (~).
Without the ~ prefix, corp.internal is registered as a general Search Domain rather than an Exclusive Routing Domain. As a result:
1. Single-label hostnames like server expand to server.corp.internal.
2. Explicit lookups for service.corp.internal are broadcast across all active network interfaces (including public physical links like eth0), leaking private hostnames onto public networks.
The Remediation
Always include the tilde prefix when establishing routing boundaries for private infrastructure:
# Incorrect: Search domain only; leaks queries across default routes
resolvectl domain tun0 corp.internal
# Correct: Exclusive routing domain; directs queries solely to tun0
resolvectl domain tun0 "~corp.internal"
3. DNSSEC Validation Failures (SERVFAIL)
The Failure
An administrator enables strict DNSSEC validation globally via DNSSEC=yes in /etc/systemd/resolved.conf. Soon after, applications start failing to resolve specific external domain names:
resolvectl query broken-dnssec.example.com
broken-dnssec.example.com: resolve call failed: DNSSEC validation failed: bogus
The authoritative zone for broken-dnssec.example.com has an expired cryptographic signature (RRSIG), an unsupported signing algorithm, or a mismatched DS record at the registrar. Strict validation causes systemd-resolved to return a hard SERVFAIL to protect applications from potential spoofing.
The Remediation
For critical environments where external third-party zones are misconfigured, adjust the validation policy to allow-downgrade dynamically while the upstream zone is being repaired:
# Temporarily permit resolution of unsigned or misconfigured upstream domains
resolvectl dnssec eth0 allow-downgrade
# Flush caches to clear the 'bogus' validation state
resolvectl flush-caches
For persistent production setups, review the systemd DNSSEC documentation to verify that your upstream resolvers properly support EDNS0 packet sizes and TCP fallback for large cryptographic payloads.
6. Today's Takeaway
The modern Linux network stack no longer treats DNS resolution as a static text file sitting on disk, but as a live, per-interface routing matrix. Open your terminal right now and run resolvectl status to inspect your active link configurations: check whether your search domains are leaking across interfaces without the ~ prefix, examine your cache hit ratios with resolvectl statistics, and test whether your system is ready for encrypted name resolution by switching an interface to resolvectl dnsovertls <interface> opportunistic. Taking five minutes to explore resolvectl today transforms mysterious network timeouts into clear, predictable, and manageable system behaviour.