resolvconf
Manage system DNS resolver configuration
TLDR
Add or override the IFACE.PROG record and run the update scripts if updating is enabled
Delete the IFACE.PROG record and run the update scripts if updating is enabled
Just run the update scripts if updating is enabled
Set the flag indicating whether resolvconf should run update scripts when invoked with -a, -d or -u
Clear the flag indicating whether to run updates
Check whether updates are enabled
SYNOPSIS
resolvconf [-a | -d | -u | -l | -I | -x | -m | -p | -f | -V] [interface]
PARAMETERS
-a interface
Adds nameserver and domain information for the specified interface. The information is read from standard input in the format of resolv.conf.
-d interface
Deletes all nameserver and domain information stored for the specified interface.
-u
Updates /etc/resolv.conf. This command is often called automatically by network management tools after changes are submitted.
-l [interface]
Lists the currently stored nameserver and domain information for all interfaces, or specifically for the given interface.
-I
Lists all interfaces for which resolvconf currently has stored information.
-x
Enables "exclusive" mode. When used, only the nameservers specified by the submitting script are included in /etc/resolv.conf, typically used for VPNs to enforce specific DNS.
-m metric
Sets a metric (priority) for the submitted information. A lower metric value indicates higher priority, influencing the order in resolv.conf.
-p
Pushes (activates) the currently stored information. This is an older method, often replaced by -u.
-f
Forces an update of /etc/resolv.conf even if no changes were detected.
-V
Displays the version of resolvconf.
DESCRIPTION
resolvconf is a framework for managing the system's DNS resolver configuration file, /etc/resolv.conf. Unlike directly editing the file, resolvconf acts as a central nameserver information policy agent. Network configuration scripts, such as DHCP clients or VPN clients, submit DNS information (nameservers, search domains) to resolvconf via standard input. resolvconf then aggregates this information from all active interfaces, applies configurable ordering and policies, and generates the final /etc/resolv.conf file. This mechanism prevents conflicts and race conditions that arise when multiple network services attempt to write to /etc/resolv.conf simultaneously. It ensures that the resolver configuration is consistently maintained based on the most relevant and up-to-date network information.
CAVEATS
While effective for managing /etc/resolv.conf, resolvconf relies on proper integration with network management tools (e.g., DHCP clients, VPN software) to submit and retract DNS information. Its role has somewhat diminished in distributions that predominantly use systemd-resolved, which offers its own DNS resolution capabilities and often manages /etc/resolv.conf via a symlink to /run/systemd/resolve/stub-resolv.conf or similar. Users might find debugging challenging if the various components (DHCP client, VPN, resolvconf, and potentially systemd-resolved) are not correctly configured to interact.
HOW IT WORKS
resolvconf doesn't directly manage network interfaces. Instead, it provides an intermediary layer. Network scripts pipe DNS information to resolvconf -a <interface>. This information is stored in a temporary database. When an update is triggered (either explicitly via resolvconf -u or implicitly by a submitting script), resolvconf consolidates all stored entries, applies policies (like interface ordering, metrics), and then writes the final, aggregated configuration to /etc/resolv.conf.
COMMON USAGE
A typical use case involves a DHCP client. When it receives DNS server addresses, it might run a script that executes echo "nameserver 8.8.8.8" | resolvconf -a eth0. When the DHCP lease expires or the interface goes down, the client would then call resolvconf -d eth0 to remove the information. resolvconf handles the aggregation and final /etc/resolv.conf update seamlessly.
HISTORY
resolvconf originated in the Debian and Ubuntu ecosystems as a robust solution to the long-standing problem of managing /etc/resolv.conf in dynamic network environments. Before its widespread adoption, multiple network services often competed to write to this file, leading to unreliable DNS resolution. It provided a standardized, conflict-free way for DHCP clients, VPN clients, and other network components to register their DNS requirements. Over time, it became a de facto standard for many distributions, though its prominence has been challenged by the emergence of systemd-resolved as a more integrated, systemd-native solution for DNS management on some modern Linux systems.
SEE ALSO
resolv.conf(5), dhclient(8), NetworkManager(8), systemd-resolved(8)