The DNS resolver configuration on Debian-based systems has become one of those areas where a straightforward file — /etc/resolv.conf — sits at the intersection of multiple competing management layers, and editing it directly is almost always the wrong move even though it looks like the obvious one. This guide documents the full resolver stack behaviour on current Debian and Ubuntu systems: what manages resolv.conf, how systemd-resolved interacts with it, what resolvconf versus resolvectl actually do, the specific pitfalls that cause DNS to silently break after manual edits, and the diagnostic commands that reveal which resolver path your system is actually using. The observations come from configuring and troubleshooting DNS on Debian 11/12, Ubuntu 22.04/24.04, and derived distributions across bare metal, VM, and container environments. This guide is part of the how-to section and connects to the DNS SRV usage technical note and the Linux on Windows topic hub where WSL resolver behaviour introduces additional complexity.

The short version​

What resolv.conf actually does​

At the lowest level, /etc/resolv.conf tells the C library resolver — the getaddrinfo() and gethostbyname() functions that virtually every application uses — where to send DNS queries. The file format is simple: nameserver lines listing DNS server IP addresses, optionally search and domain directives for domain suffix handling, and options for resolver behaviour flags.

nameserver 192.168.1.1
nameserver 8.8.8.8
search home.lan
options timeout:2 attempts:3

This file has existed in essentially the same format since 4.3BSD in the 1980s. The format is not the problem. The problem is that on modern Debian systems, multiple services want to write to this file, and the interactions between them create the confusion.

The management layers​

On a current Debian 12 or Ubuntu 24.04 installation, the resolver stack typically involves three or four layers between your configuration intent and the actual /etc/resolv.conf content:

systemd-resolved​

systemd-resolved is a system service that provides DNS resolution, caching, and DNSSEC validation. When active, it listens on 127.0.0.53:53 as a local DNS stub resolver. Applications send queries to this local address, and systemd-resolved forwards them to the actual upstream DNS servers configured elsewhere.

systemctl status systemd-resolved

When systemd-resolved manages the resolver, /etc/resolv.conf is a symlink to one of several possible targets:

• /run/systemd/resolve/stub-resolv.conf — the stub resolver configuration, containing nameserver 127.0.0.53. This is the recommended and default mode. Applications talk to the local stub, which handles caching and forwarding.
• /run/systemd/resolve/resolv.conf — the "traditional" mode, containing the actual upstream DNS server addresses. Applications bypass the stub resolver and talk to upstream servers directly. No local caching.
• Something else entirely — if someone or something has replaced the symlink with a static file or pointed it elsewhere.

NetworkManager​

NetworkManager manages network connections on most Debian desktop installations and many server configurations. When it establishes a connection — wired, wireless, or VPN — it receives DNS server addresses from DHCP or static configuration and needs to make them available to the system resolver.

NetworkManager can push DNS information to systemd-resolved (the default on modern setups), write to /etc/resolv.conf directly, or use the resolvconf framework. The method depends on the dns setting in /etc/NetworkManager/NetworkManager.conf:

grep -i dns /etc/NetworkManager/NetworkManager.conf

Common values: dns=systemd-resolved (push to resolved), dns=default (write resolv.conf directly), dns=none (do nothing — someone else manages DNS).

resolvconf / openresolv​

resolvconf (or openresolv on some systems) is a framework that mediates between multiple DNS information sources — DHCP clients, VPN clients, manual configuration — and produces a merged /etc/resolv.conf. It predates systemd-resolved and serves a similar coordination role but without the local caching resolver.

On systems where both resolvconf and systemd-resolved are installed, there is potential for conflict. Modern Debian resolves this by having systemd-resolved provide a resolvconf-compatible interface, so services that push DNS information via the resolvconf command end up talking to systemd-resolved rather than the legacy framework.

Determining what manages your resolver​

Before making any DNS configuration changes, establish which management layer is active on your system. The diagnostic sequence:

ls -la /etc/resolv.conf

If the output shows a symlink to /run/systemd/resolve/stub-resolv.conf, systemd-resolved is in stub mode — the standard configuration. If it points to /run/systemd/resolve/resolv.conf, resolved is active but in traditional mode. If it is a regular file (no symlink arrow), something has replaced the managed symlink with a static file.

resolvectl status

This shows the per-interface DNS configuration as systemd-resolved sees it: which DNS servers are configured for each network interface, whether DNSSEC is active, and the current DNS-over-TLS mode. If resolvectl is not available, systemd-resolved is either not installed or not active.

# Which nameserver actually answers?
dig +short example.com @127.0.0.53
dig +short example.com @$(grep nameserver /etc/resolv.conf | head -1 | awk '{print $2}')

If both commands return the same result, the resolution path is working regardless of the management layer. If the first fails but the second succeeds (or vice versa), the resolver configuration is inconsistent.

Configuring DNS servers correctly​

The correct configuration method depends on which layer manages your resolver.

With systemd-resolved​

Edit the systemd-resolved configuration, not resolv.conf:

sudo nano /etc/systemd/resolved.conf

Set the [Resolve] section:

[Resolve]
DNS=9.9.9.9 149.112.112.112
FallbackDNS=1.1.1.1 8.8.8.8
DNSSEC=allow-downgrade
DNSOverTLS=opportunistic

Then restart the service:

sudo systemctl restart systemd-resolved
resolvectl status

The resolvectl status output should now show your configured DNS servers. The /etc/resolv.conf symlink continues to point at the stub resolver (127.0.0.53), and systemd-resolved forwards queries to your specified upstream servers.

With NetworkManager​

For systems where NetworkManager manages DNS, configure it per-connection:

nmcli connection modify "Wired connection 1" ipv4.dns "9.9.9.9 149.112.112.112"
nmcli connection modify "Wired connection 1" ipv4.ignore-auto-dns yes
nmcli connection up "Wired connection 1"

The ipv4.ignore-auto-dns yes prevents DHCP-provided DNS servers from overriding your manual configuration. Without it, the DHCP-provided servers are prepended to your list on the next renewal.

With Netplan (Ubuntu)​

Ubuntu server installations commonly use Netplan, which generates configuration for either NetworkManager or systemd-networkd:

network:
  version: 2
  ethernets:
    eth0:
      dhcp4: true
      nameservers:
        addresses:
          - 9.9.9.9
          - 149.112.112.112
        search:
          - home.lan

sudo netplan apply

For more detail on the Debian project's documentation of resolver management, the Debian wiki resolv.conf page covers the distribution-specific defaults and integration points.

What changed across Debian releases​

The resolver management approach has shifted significantly between Debian versions, and guides written for older releases give advice that actively breaks newer systems.

Ubuntu's parallel evolution​

Ubuntu adopted systemd-resolved earlier and more aggressively than Debian. Since Ubuntu 18.04, the stub resolver at 127.0.0.53 has been the default, and /etc/resolv.conf has been a symlink. This means Ubuntu-specific advice written after 2018 generally applies to Debian 11+, but Debian-specific advice written before 2021 may assume a static file that no longer exists on current installations.

Diagnostic commands​

When DNS resolution fails or behaves unexpectedly, these commands reveal the actual resolver state:

cat /etc/resolv.conf

resolvectl status
resolvectl dns

dig example.com @127.0.0.53

dig example.com @9.9.9.9

sudo ss -tlnp | grep :53

If ss shows systemd-resolved listening on 127.0.0.53:53, the stub resolver is active. If nothing is listening on port 53, the system is resolving directly to upstream servers without a local resolver. If dnsmasq or unbound is listening, a third-party resolver is in the path.

Container and WSL considerations​

Container environments and WSL instances add another layer of resolver complexity.

Docker containers​

Docker containers on Debian hosts inherit the host's DNS configuration by default, but the mechanism depends on the Docker network mode. In the default bridge mode, Docker generates a container-local /etc/resolv.conf based on the host's resolver configuration at container creation time. If the host uses the systemd-resolved stub at 127.0.0.53, Docker detects this and substitutes the upstream DNS servers instead — because 127.0.0.53 inside the container would try to reach a stub resolver that does not exist in the container's network namespace.

WSL instances​

WSL 2 generates /etc/resolv.conf automatically from the Windows host's DNS configuration. The generated file typically contains the Windows host's virtual network adapter IP as the nameserver. This works for most cases but breaks when VPN software on the Windows side changes the DNS configuration without WSL's knowledge.

Common failure patterns and fixes​

DNS works for some domains but not others​

This usually indicates a DNSSEC validation failure. systemd-resolved with DNSSEC=yes will refuse to return results for domains with broken DNSSEC chains. Set DNSSEC=allow-downgrade in /etc/systemd/resolved.conf to permit fallback to unauthenticated resolution when DNSSEC validation fails.

DNS stops working after VPN connects​

VPN clients often push their own DNS servers and search domains. If the VPN DNS servers are only reachable through the VPN tunnel, and the system tries to use them for all DNS queries (not just the VPN's split-tunnel domains), resolution fails for everything outside the VPN's domain scope. The fix is per-interface DNS routing in systemd-resolved:

resolvectl dns tun0 10.0.0.1
resolvectl domain tun0 "~corp.example.com"

The ~ prefix tells systemd-resolved to use the VPN's DNS server only for queries within corp.example.com, and the default DNS servers for everything else.

resolv.conf is empty or contains only comments​

This happens when the symlink target is regenerated but the management service has no DNS servers configured. Check resolvectl status — if no DNS servers are shown for any interface, the problem is upstream: DHCP is not providing servers, or the static configuration is empty. Fix the source, not the symlink.

Changes to resolved.conf have no effect​

The most common cause is forgetting to restart the service. systemd-resolved reads its configuration at startup and does not monitor the file for changes:

sudo systemctl restart systemd-resolved

If the restart does not apply the changes, verify the configuration syntax. systemd-resolved silently ignores malformed lines — a typo in a DNS server address will not produce an error, it will simply be skipped.

Practical recommendations​

For Debian 12 and Ubuntu 24.04 systems, the cleanest resolver configuration is:

1. Let systemd-resolved manage /etc/resolv.conf as a stub symlink
2. Configure your preferred upstream DNS servers in /etc/systemd/resolved.conf
3. Use resolvectl for diagnostics, not cat /etc/resolv.conf
4. Set DNSSEC=allow-downgrade unless you have a specific reason to enforce strict validation
5. Use per-interface DNS routing for VPN and split-tunnel configurations

For server installations where systemd-resolved is not installed and you want a static file, that is a valid configuration — but commit to it. Do not install systemd-resolved later and expect the static file to survive.

For the DNS SRV record usage patterns that frequently arise alongside resolver configuration, the DNS SRV usage technical note covers the application-layer DNS features that depend on the resolver stack working correctly.