resolvconf
Resolvconf is a framework and command-line tool primarily used in Debian-based Linux distributions to dynamically manage the system's DNS resolver configuration by aggregating and updating nameserver information from multiple sources, such as DHCP clients, VPN software, and static network interface settings, thereby maintaining a centralized and conflict-free /etc/resolv.conf file.[1] It operates as an intermediary database that stores runtime nameserver data and notifies dependent applications or services of changes through a hook-based notification system.[1] Developed to address the limitations of statically editing /etc/resolv.conf in multi-network environments, resolvconf ensures seamless DNS resolution across varying connection scenarios without manual intervention.[2] Originating in the Debian project around the early 2000s, resolvconf was authored by Thomas Hood to provide a standardized mechanism for handling dynamic DNS updates, particularly in response to the growing use of automated network configuration tools like dhclient and ifupdown.[3] It has since been adopted in other distributions, including Ubuntu and Arch Linux (via the openresolv implementation), and remains part of Debian's core networking infrastructure as of 2025, with ongoing maintenance reflected in package updates. The tool's design emphasizes modularity, allowing network management programs to "add" or "delete" interface-specific DNS profiles using commands likeresolvconf -a or resolvconf -d, which update an internal database without directly overwriting the resolver file.[1]
In operation, resolvconf requires /etc/resolv.conf to be a symbolic link to a dynamically generated file, typically /run/resolvconf/resolv.conf, which is rebuilt by concatenating prioritized entries from sources like /etc/network/interfaces or environment variables set by DHCP.[2] Subscribers, such as the GNU C Library's resolver routines or caching services like dnsmasq, are notified via executable scripts in /etc/resolvconf/update.d/, enabling real-time adaptation to network changes.[1] Configuration options, defined in /etc/default/resolvconf or interface stanzas (e.g., dns-nameservers 8.8.8.8), allow customization of search domains, nameserver truncation, and interface ordering to prioritize reliable DNS sources.
While resolvconf continues to be a reliable choice for systems using traditional networking stacks, modern alternatives like systemd-resolved have gained prominence in distributions with systemd integration, offering similar dynamic management but with additional features such as DNSSEC validation and local caching.[2] Its lightweight nature and compatibility with legacy tools ensure ongoing relevance, particularly in server environments or minimal installations where simplicity is prioritized over advanced DNS features.[1]
Overview
Purpose and Role
Resolvconf is a centralized framework in Unix-like operating systems designed to dynamically manage the DNS resolver configuration file, typically /etc/resolv.conf, by aggregating inputs from various network configuration sources such as DHCP clients, VPN software, and static network setups.[1] It serves as an intermediary layer, allowing multiple programs to contribute DNS settings—like nameservers and search domains—without directly overwriting the file, thereby preventing conflicts and ensuring consistent resolution behavior across the system.[4] Historically, /etc/resolv.conf was manually edited or updated by a single network client, but in environments with multiple interfaces or daemons—such as wired Ethernet, Wi-Fi, and VPN connections—these direct updates often led to overwrites, causing manual changes to be lost during network events like interface activations or disconnections.[4] Resolvconf addresses this by employing a database-driven approach: contributing programs register their DNS information in a runtime database rather than modifying the file directly, and resolvconf then generates an optimized /etc/resolv.conf (often as a symlink to a dynamically created version in /run/resolvconf/) by merging and prioritizing these entries based on interface order.[1] For instance, on a laptop switching between Wi-Fi networks via DHCP—which provides temporary nameservers—and a VPN client that injects its own secure DNS servers, resolvconf seamlessly merges these contributions into a single, functional configuration, appending search domains and limiting nameserver entries to avoid resolution delays.[1] This mechanism ensures that applications relying on the system's resolver library receive up-to-date information only when changes occur, minimizing disruptions.[1]Key Components
The resolvconf database serves as a central repository for runtime DNS configuration information, functioning as a simple key-value store that aggregates data from various network interfaces and protocols. It is typically implemented using files located in the/run/resolvconf/interface/ directory, where each entry is named according to the format IFACE.PROG—for instance, eth0.dhclient for DNS details supplied by the dhclient program on the eth0 interface. These files contain per-interface DNS data, including lists of nameservers (via the nameserver directive) and domain search paths (via the search or domain directives), allowing resolvconf to collect and organize resolver settings without directly modifying the global /etc/resolv.conf file.[1]
Hooks in resolvconf provide a mechanism for processing and propagating changes in the database to consumer applications, consisting of executable scripts placed in the /etc/resolvconf/update.d/ directory. These hooks are invoked whenever the database is updated, enabling actions such as regenerating the consolidated /run/resolvconf/resolv.conf file, which serves as a symlink target for /etc/resolv.conf and incorporates the merged DNS settings. For example, scripts in the /etc/resolvconf/update-libc.d/ subdirectory are specifically executed after the resolv.conf file is updated to notify the C library resolver of the changes, ensuring seamless integration with system-wide name resolution.[1]
Interface profiles define how individual network interfaces contribute their DNS configurations to the resolvconf database, with profile files residing in the /etc/resolvconf/interface/ directory—each named after an interface type, such as eth for Ethernet or ppp for PPP connections. When an interface is brought up (e.g., via ifupdown), the corresponding profile script determines whether and how to supply DNS information, often sourcing it from network configuration files like /etc/[network](/page/Network)/interfaces using options such as dns-nameservers or dns-search. This allows each interface, like eth0 or ppp0, to uniquely append or update its DNS data in the database without interfering with others.[1]
The resolvconf database employs a last-write-wins policy to resolve conflicting entries from the same interface, overwriting prior data with the most recent submission while performing no input validation or sanity checks on the provided information. Additionally, global overrides are supported through static configuration files, such as those in /etc/resolvconf/resolv.conf.d/base, which can supersede dynamic interface-supplied data, particularly when no active interfaces are configured.[1]
History
Origins and Development
Resolvconf originated in 2003, developed by Thomas Hood as part of Debian's network configuration initiatives to manage the /etc/resolv.conf file's volatility in dynamic networking scenarios. The tool addressed challenges arising from multiple network managers overwriting resolver settings, particularly in environments with read-only root filesystems. The concept was initially proposed by Emile van Bergen during Debian developer discussions, with Hood handling the implementation to create a centralized framework for nameserver information.[5] This development responded directly to issues in early 2000s dial-up and broadband setups, where conflicting tools like PPP daemons and DHCP clients—such as the pump client—frequently disrupted DNS resolution by altering /etc/resolv.conf without coordination. By providing a database and notification system, resolvconf enabled these components to contribute resolver data cooperatively, reducing conflicts and improving reliability for laptop users switching networks or embedded systems.[5] Key milestones included the package's announcement on the Debian development mailing list in July 2003, followed by the release of version 0.28 later that month, which introduced core scripts for integration with tools like ifupdown. Over the subsequent year, it evolved to include explicit support for PPP and various DHCP clients, including dhcp3-client and dhcpcd, solidifying its role in Debian's network stack. Influenced by earlier DHCP tools like pump, resolvconf was adopted as a recommended standard in Debian policy for handling dynamic DNS configurations.[5][6]Adoption in Distributions
Resolvconf was initially developed and introduced as a package in Debian, where it became the standard framework for dynamically managing the /etc/resolv.conf file by acting as an intermediary between DNS-supplying programs like DHCP clients and applications requiring name resolution.[2] It was later adopted in Ubuntu through the resolvconf package, which integrates with network management tools to handle DNS updates, though Ubuntu has since shifted toward systemd-resolved as the default resolver starting with version 17.10 in 2017.[7] In Arch Linux, resolvconf functionality is provided by the optional openresolv package, which serves as an implementation for coordinating multiple applications' modifications to /etc/resolv.conf, often used alongside DHCP clients or network managers like netcfg in earlier configurations.[8] Gentoo Linux utilizes openresolv as its resolvconf-compatible tool, available via the net-dns/openresolv package, enabling dynamic updates to /etc/resolv.conf in response to network changes from various sources.[9] Specific adoption events highlight evolving preferences in major distributions. Fedora never widely adopted resolvconf, instead relying on NetworkManager to directly populate and manage /etc/resolv.conf since the early 2010s, effectively bypassing dedicated resolvconf tools.[10] Ubuntu began deprecating resolvconf in favor of systemd-resolved with the release of Ubuntu 18.04 in 2018, where the latter provides a local stub resolver at 127.0.0.53, though the resolvconf package remains installable for compatibility.[7] In contrast, resolvconf continues to be maintained in Debian 13 (released in 2025), where it is available as a package and can be selected alongside alternatives like openresolv for systems requiring flexible DNS management.[2][11] Distributions exhibit variations in resolvconf integration. Slackware has never adopted resolvconf, opting instead for manual editing of /etc/resolv.conf to specify nameservers and search domains, reflecting its emphasis on straightforward, user-controlled configuration.[12] As of 2025, resolvconf is considered a legacy tool in many desktop-oriented environments due to the rise of integrated resolvers like systemd-resolved, but it remains active and relevant in server setups, particularly those using legacy DHCP tools such as dhclient for compatibility.[2]Functionality
Database Management
Resolvconf maintains a database of DNS configuration records sourced from various network interfaces and programs. In the original Debian implementation, these are stored in the directory/var/run/resolvconf/interface/. Each record is identified by a combination of the interface name and the program that generated it (e.g., eth0.dhclient), and these records contain data in the format of the standard /etc/resolv.conf file, including nameserver addresses, search domains, and options.[13] In openresolv, the state directory is /run/resolvconf, with per-interface files stored similarly for compatibility.[3]
Database operations are performed using specific command-line options. The -a option adds or overwrites a record for a given interface-program pair, accepting input from standard input in resolv.conf syntax; for example, piping a configuration file to resolvconf -a eth0.dhclient updates the corresponding entry. The -d option deletes a specified record, while the -u option triggers an update process without adding new data, propagating changes through associated scripts. These operations ensure dynamic management of per-interface DNS settings without directly editing the global resolver file.[13][3]
The merging logic constructs the final DNS configuration by prioritizing records according to the List of Interfaces (LOI). In the original implementation, this is defined in /etc/resolvconf/interface-order using shell glob patterns to order interfaces (e.g., lo* for loopback, followed by eth* for Ethernet, wlan* for wireless, ppp* for dial-up, and * for others). In openresolv (as of 2025), ordering is configured via variables such as first_keys and next_keys in /etc/resolvconf.conf, using similar patterns (e.g., lo lo[0-9]*).[14][15] This determines the precedence for including nameservers and search domains. Nameservers are collected from the ordered interfaces, limited to three entries, with duplicates removed to avoid redundancy; if a loopback address (e.g., 127.0.0.1) appears and truncation is enabled (default in original; configurable in openresolv), no further nameservers are appended. Search domains from all relevant records are concatenated into a single line, ordered by interface priority. Static content is incorporated via files in /etc/resolvconf/resolv.conf.d/ in the original: head for prefixes (e.g., options), base for fallback static data when no interfaces provide input, and tail for suffixes (e.g., additional comments). Openresolv supports similar static content via head_content, base_content, and tail_content variables in /etc/resolvconf.conf.[13][15]
Querying the database is achieved with the -l option, which lists all stored records in a format mimicking resolv.conf syntax, prefixed with comments indicating the source interface and program (e.g., # resolv.conf from eth0.dhclient). This output provides a view of the raw database contents before merging, useful for debugging and verification. The LOI ensures consistent ordering in both merging and listing, excluding empty or irrelevant records (e.g., loopback if truncation applies) to focus on active network configurations.[13][3]
Update Mechanisms
Resolvconf propagates changes from its database to the active/etc/[resolv.conf](/page/Resolv.conf) file primarily through the -u option, which forces the execution of update scripts to regenerate the configuration without adding or deleting records. This option is invoked by network scripts, such as ifup and ifdown from the ifupdown package or hooks in dhclient-script from the isc-dhcp-client package, ensuring that DNS settings from interfaces or DHCP leases are reflected promptly.[1][2]
The update process relies on a hook system implemented via executable scripts. In the original implementation, these are run in lexicographical order for every database modification from the /etc/[resolvconf](/page/Resolv.conf)/update.d/ directory. These scripts handle tasks such as filtering invalid entries, validating syntax, or notifying dependent services like [dnsmasq](/page/Dnsmasq); the default libc hook merges nameserver and search domain data from the database, prioritizing interfaces as specified in /etc/[resolvconf](/page/Resolv.conf)/interface-order, and outputs up to three nameserver lines followed by a single search line, appending static content from /etc/[resolvconf](/page/Resolv.conf)/resolv.conf.d/head and /etc/[resolvconf](/page/Resolv.conf)/resolv.conf.d/tail. Additional post-update hooks in /etc/[resolvconf](/page/Resolv.conf)/update-libc.d/ can further process the generated file for applications like email clients. In openresolv (Debian as of 2025), subscribers are in /usr/lib/[resolvconf](/page/Resolv.conf)/ and post-libc in /usr/lib/[resolvconf](/page/Resolv.conf)/libc.d/.[1][3]
Conflicts arising from multiple interfaces providing overlapping DNS information are resolved automatically through the interface priority mechanism, where the order (e.g., listing loopback first, followed by Ethernet and wireless) determines the sequence of nameservers and domains included in the merged output, preventing duplication and favoring higher-priority sources. To disable automatic propagation and operate in manual mode, administrators can configure resolvconf=NO in /etc/default/[resolvconf](/page/Resolv.conf) or the sourced script /etc/resolvconf/resolvconf.conf (original) or via options in /etc/[resolvconf](/page/Resolv.conf).conf (openresolv), which prevents the execution of update subscribers while allowing direct database manipulation via command-line options like -a or -d.[1][15]
In symlink mode, which is established during installation, /etc/[resolv.conf](/page/Resolv.conf) is replaced by a symbolic link to the dynamically generated /run/[resolvconf](/page/Resolv.conf)/resolv.conf, enabling seamless updates while permitting reversion to a static file by removing the link and restoring the original content if dynamic management is no longer required. This setup ensures that the resolver configuration remains current across network state changes without manual intervention. Note that as of Ubuntu 24.04, systemd-resolved is used by default instead of resolvconf, which is legacy and not installed unless explicitly added.[1][2][16]
Configuration
Installation Process
The installation of resolvconf, a framework for dynamically managing DNS resolver information, varies by Linux distribution and typically involves using the system's package manager to install the relevant package, followed by verification and any necessary post-installation steps to integrate it with the network configuration. Prerequisites generally include a compatible network management tool, such as ifupdown on Debian-based systems or equivalents like NetworkManager or dhcpcd on others, to ensure resolvconf can receive and process DNS updates from network events.[2][13] On Debian and Ubuntu systems, resolvconf is available in the default repositories and can be installed using the Advanced Package Tool (APT). Run the commandsudo apt install [resolvconf](/page/Resolv.conf) to download and install the package. Upon installation, resolvconf automatically creates a symbolic link from /etc/[resolv.conf](/page/Resolv.conf) to /run/resolvconf/resolv.conf if one does not already exist, enabling dynamic management of DNS settings. To verify the installation, use [dpkg](/page/Dpkg) -l | [grep](/page/Grep) [resolvconf](/page/Resolv.conf), which should list the package if successfully installed. As of 2025, the installation process may display warnings regarding potential conflicts or migration needs when systemd-resolved is active, as the two tools compete for control of /etc/[resolv.conf](/page/Resolv.conf); users may need to disable systemd-resolved via sudo systemctl disable --now systemd-resolved before proceeding.[13][17][18]
For Arch Linux, the recommended implementation is openresolv, a portable fork of resolvconf available in the official repositories. Install it with sudo pacman -S openresolv. Post-installation, generate the initial /etc/resolv.conf by running resolvconf -u; openresolv manages /etc/resolv.conf as a regular file and does not require a symbolic link. This setup requires a compatible network manager like dhcpcd or NetworkManager to interface with openresolv for DNS updates.[8][19][20]
In Gentoo, the openresolv package serves as the primary resolvconf implementation and is installed via the Portage package manager with emerge --ask net-dns/openresolv. After installation, basic configuration occurs through editing /etc/[resolvconf](/page/Resolv.conf).conf, where options like nameserver priorities can be set. Like other distributions, integration depends on a network tool such as dhcpcd or wpa_supplicant to supply DNS information to openresolv. Verification can be done by checking the package status with equery list openresolv.[21][9]
Core Configuration Files
The core configuration of resolvconf is handled through dedicated files and directories that enable customization of the DNS resolver settings generated in /etc/resolv.conf. These files allow administrators to specify static content, fallback options, and interface-specific behaviors while adhering to the standard resolver syntax. Configurations may vary slightly between the Debian resolvconf implementation and the openresolv fork used in other distributions; the following primarily describes the Debian setup, with notes for openresolv.[1] The directory /etc/resolvconf/resolv.conf.d/ holds key files for static portions of the resolver configuration. The head file is prepended to the dynamically generated content and is ideal for unchanging header elements, such as resolver options; for example, a line likeoptions timeout:2 can limit query timeouts. The base file serves as a fallback, providing essential nameserver or search domain entries that apply even without active network interfaces. The tail file is appended after dynamic content, commonly used for static footers like additional options (e.g., options ndots:1). These files ensure persistent settings regardless of network changes.[13]
Per-interface configurations are managed through files in /etc/resolvconf/interface/, which define settings tailored to specific network interfaces, including options for domain usage and exclusive domain handling. These files are typically populated by network management tools based on static definitions in /etc/network/interfaces, using directives such as dns-nameservers 8.8.8.8 for IP addresses or dns-search example.com for search domains. This allows resolvconf to incorporate interface-specific DNS information into the overall configuration.[1]
Global behavior for the Debian implementation is controlled via /etc/default/resolvconf, which sets environment variables to fine-tune operations. For instance, the INTERFACE_ORDER variable prioritizes interfaces during nameserver processing, while other flags like TRUNCATE_NAMESERVER_LIST_AFTER_LOOPBACK_ADDRESS limit the inclusion of loopback addresses in the final list. For openresolv, global settings such as interface ordering and nameserver handling are configured in /etc/resolvconf.conf, a shell script sourced by the resolvconf command.[1][22]
Configuration entries across these files follow the syntax defined in resolv.conf(5). Nameservers are specified with nameserver 8.8.8.8, search domains with search example.com, and options with options timeout:2 ndots:1. Comments are supported using # at the start of a line, such as # Default fallback DNS. After modifications, running resolvconf -u regenerates /etc/resolv.conf to apply changes.[23]
Usage
Command-Line Operations
Theresolvconf command provides a command-line interface for manually adding, deleting, and updating DNS configuration entries in its database, which in turn affects the generation of /etc/resolv.conf. The basic syntax includes resolvconf -a iface to add or overwrite an entry for the specified interface (reading configuration data in resolv.conf format from standard input), resolvconf -d iface to delete an entry for the interface, and resolvconf -u to force an update that propagates changes to subscribers like /etc/resolv.conf. The interface name may include a program suffix, such as eth0.dhclient.[1][13]
Key options include -l [iface] to list the contents of the database in resolv.conf format for the specified interface or all interfaces if omitted. Interface priority is determined by metrics assigned in the /etc/resolvconf/interface-order file, where lower metrics indicate higher precedence.[1]
Common operations involve managing entries for dynamic interfaces. To delete stale entries from disconnected networks, use resolvconf -d interface (e.g., resolvconf -d eth0.dhclient), which removes the associated DNS data and triggers an update if enabled. Forcing an update with resolvconf -u regenerates /etc/resolv.conf based on the current database without adding or deleting entries. Querying the database can be done with resolvconf -l | grep nameserver to extract active nameserver addresses.[1][13][24]
A specific example for VPN integration is resolvconf -a tun0 < vpn-dns.conf, which adds VPN-provided DNS settings (from vpn-dns.conf). To ensure precedence, assign a low metric to the tun0 entry in /etc/resolvconf/interface-order.[25]
Integration with Network Tools
Resolvconf integrates seamlessly with DHCP clients like dhclient to automate DNS configuration updates upon receiving network leases. The dhclient utility employs hook scripts in the /etc/dhcp/dhclient-enter-hooks.d/ directory to invoke theresolvconf -a command, appending nameservers and search domains provided by the DHCP server to the resolvconf database without directly overwriting /etc/resolv.conf. This mechanism ensures that DNS settings from dynamic IP assignments are dynamically incorporated into the system's resolver configuration.[13][26]
For PPP and VPN connections, resolvconf is invoked through scripts associated with tools like pppd and OpenVPN to manage DNS for tunnel interfaces. In PPP setups, pppd's ip-up and ip-down scripts call resolvconf to add or delete interface-specific DNS entries during connection establishment and teardown. Similarly, OpenVPN configurations often specify up /etc/openvpn/update-resolv-conf and down /etc/openvpn/update-resolv-conf directives in the .ovpn file, where the update-resolv-conf script uses resolvconf -a tun0 to integrate VPN-provided nameservers and domains into the database. This approach prevents DNS leaks and ensures temporary VPN DNS takes precedence as needed.[13][27]
NetworkManager supports resolvconf as a DNS backend to centralize management of /etc/resolv.conf across multiple connections. Administrators configure this integration by adding dns=resolvconf under the [main] section in /etc/NetworkManager/NetworkManager.conf or drop-in files in /etc/NetworkManager/conf.d/, directing NetworkManager to update the resolvconf database via resolvconf -a and resolvconf -d calls instead of writing directly to the resolv.conf file. This setup allows NetworkManager-handled connections, such as Wi-Fi or Ethernet, to contribute DNS information dynamically while maintaining compatibility with other tools.[28][13]
In systems using ifupdown for interface management, the /etc/network/if-up.d/resolvconf script automatically handles DNS updates on interface up and down events. When ifup activates an interface defined in /etc/network/interfaces with dns-nameservers or dns-search options, the script parses these settings and calls resolvconf -a to add them to the database; ifdown triggers resolvconf -d for removal. Common integration issues, such as missing DNS updates, often stem from absent or non-executable hook scripts in /etc/network/if-up.d/ or /etc/dhcp/dhclient-enter-hooks.d/, which can be resolved by verifying package installations like resolvconf and ensuring scripts have proper permissions (e.g., chmod +x).[13]
Alternatives
openresolv
openresolv is a portable and actively maintained implementation of the resolvconf framework, developed by Roy Marples in 2007 as a BSD-licensed alternative to address limitations in the original Debian resolvconf, such as limited cross-platform compatibility.[29][22] It serves as a database for managing DNS resolver configurations from multiple sources, ensuring coordinated updates to/etc/resolv.conf without conflicts, and is widely adopted in lightweight and embedded systems for its POSIX compliance and minimal dependencies.[30]
Key enhancements in openresolv include expanded support for execution hooks via scripts in the /lib/resolvconf/ or /usr/lib/resolvconf/ directory, improved handling of IPv6 nameservers through native integration in configuration options, and greater flexibility for third-party resolvers beyond the standard libc.[31][8] Configuration occurs primarily through /etc/resolvconf.conf, a shell script sourcing variables like prepend_nameservers to add static DNS servers at the beginning of the generated list, alongside options for interface-specific privacy and resolver forwarding.[32]
openresolv has seen broad adoption as the default in Void Linux and is available via ports in FreeBSD, with integration in Gentoo and Alpine Linux, particularly musl-based environments.[33][34][35] As of November 2025, the latest version 3.17.0 incorporates stubs for systemd-resolved compatibility, allowing seamless operation in mixed environments while maintaining its core database model. A notable enhancement is its approach to protecting /etc/resolv.conf by generating content dynamically without relying solely on symlinks, reducing overwrite risks from uncoordinated tools compared to the original implementation.[22]