Section: resolvconf (8)
Updated: 3 Feb 2013
resolvconf - manage nameserver information
The resolvconf package comprises a simple database
for run-time nameserver information
and a simple framework
for notifying applications of changes in that information.
Resolvconf thus sets itself up as the intermediary between programs that
supply nameserver information and applications that use
Information is added to
or removed from
the database using the
section below for a discussion of the available options.
SUPPLIERS OF NAMESERVER INFORMATION
program is run only by network interface configuration programs
and by local nameservers such as
These programs obtain nameserver information from some source
and push it to
may receive nameserver addresses
and domain search list information
during its negotiation with the DHCP server;
if so, its hook script
pushes this information to
program can be used to configure network interfaces
according to settings in
push nameserver information to
when it configures an interface
the administrator must add
option lines to the relevant
The following option names are accepted:
To add a nameserver IP address,
add an option line consisting of
and the address.
To add multiple nameserver addresses,
include multiple such
To add search domain names, add a line beginning with
dns-search foo.org bar.com
option is also accepted and, unlike
can be given multiple arguments,
separated by spaces.
option is deprecated in favor of
The resulting stanza might look like the following example.
iface eth0 inet static
dns-search foo.org bar.com
N.B.: On a machine where resolvconf
has just been or is about to be installed
and which previously relied on a static
the nameserver information in that static file,
(which is to say the information on
should be migrated to the appropriate
as just described;
(which is to say, any
should be migrated to
from the command line to add or delete nameserver information,
but this is not normally necessary or advisable.
CONSUMERS OF NAMESERVER INFORMATION
Nameserver information provided to
is stored for use by subscribers to
Subscriber packages that need to know when nameserver information has changed
should install a script in
For example, DNS caches such as
subscribe to the notification service so that they know
whither to forward queries.
Client hook scripts will find the files containing nameserver
information in the current directory.
The most important software package
that subscribes to the notification service
is the GNU C Library
This library is used by many applications
that need to resolve domain names.
When nameserver information is updated, the script
generates a new version of the resolver configuration file,
as described below.
If the new version of the file differs
from the previously generated one
then the hook scripts found in
The dynamically generated resolver configuration file
always starts with the contents of
and ends with the contents of
dynamic nameserver information
information provided for configured interfaces;
static information from
Specifically, it writes:
up to three
ordered according to
if one of the addresses is a loopback address and the
environment variable is affirmatively set, as discussed in the
up to one
line containing the combined domain search list from all
"domain" and "search" input lines,
also ordered according to
all other non-comment input lines.
The GNU C Library resolver library isn't the only resolver library available.
However, any resolver library that reads
(and most of them do, in order to be compatible)
should work fine with resolvconf.
Subscriber packages that need to know only when the resolver configuration file
has changed should install a script in
rather than in
(For example, two packages that install
hook scripts are
This is important for synchronization purposes:
has been updated;
the same is not necessarily true of scripts in
- -a IFACE.PROG
Add or overwrite the record
then run the update scripts if updating is enabled.
When this option is used the information must be provided to
on its standard input in the format of the
Each line in the file must be terminated by a newline.
- -d IFACE.PROG
Delete the record
then run the update scripts if updating is enabled.
may not contain
an initial dot,
an initial hyphen
or an initial tilde.
It is conventionally formed from
the name of the interface involved,
the name of the interface configuration program,
Just run the update scripts
(if updating is enabled).
- With -a, -d or -u:
if updating is not enabled, schedule a delayed update.
The delayed update will be carried out when updates are enabled.
Set the flag indicating that
should run update scripts
when invoked in the future with -a, -d or -u.
If a delayed update was scheduled then run update scripts.
Clear the flag.
Return 0 if the flag is set,
otherwise return 1.
The following variables can be set in the configuration file
If the file does not exist you will have to create it.
If set to "yes" then the
script will include
no more nameserver addresses
after the first nameserver address
that is a loopback address.
(In IPv4 a loopback address is any one that starts with "127.".
In IPv6 the loopback address is "::1".)
The advantage of truncating the nameserver list after a loopback address
is that doing so inhibits unnecessary changes to
and thus reduces the number of instances in which the
scripts have to be run.
When an interface is brought up or down
the local caching nameserver
that listens on the loopback address
is still informed of the change and adapts accordingly;
the clients of the resolver which use the local caching nameserver
do not need to be notified of the change.
A disadvantage of this mode of operation is that applications have
no secondary or tertiary nameserver address to fall back on should
the local caching nameserver crash.
Insofar as a local nameserver crash can be regarded
as an unlikely event,
this is a relatively minor disadvantage.
Set to "no" to disable truncation.
The default is "yes".
A deprecated synonym for this variable is
See the ENVIRONMENT VARIABLES section.
This is a symbolic link to a location where nameserver information is stored.
The location must be on a filesystem that is writable
early in the boot sequence.
In Debian the default location is
in the future this will be
the only supported location;
configurability of the location via
will be dropped.
Nevertheless, clients should not make any assumptions
about the location or the canonical path of this directory
or the hierarchy that is constructed under it.
Determines the order of precedence of nameserver addresses and search domain names.
See above and
File containing basic resolver information.
The lines in this file are included in the resolver configuration file
even when no interfaces are configured.
File to be prepended to the dynamically generated resolver configuration file.
Normally this is just a comment line.
File to be appended to the dynamically generated resolver configuration file.
To append nothing, make this an empty file.
This file is a good place to put a resolver
line if one is needed, e.g.,
Copy of the
file before the resolvconf package was installed.
This file has no effect on the functioning of resolvconf;
it is retained so that
can be restored to its original state
if the resolvconf package is removed.
Note also that a copy of this file is included in the database
until the first reboot after installation of the resolvconf package;
this ensures that nameservers reachable before installation of resolvconf
are still reachable after installation of resolvconf even though
at that point
not all suppliers of nameserver information may have supplied their
that the administrator can choose to create a symbolic link in
so that the contents of
are always added to the end of the
dynamically generated file.
does not check the sanity of the information provided to it.
Written by Thomas Hood <email@example.com
with contributions by Nathan Stratton Treadway.
Copyright © 2004-2013 Thomas Hood.
This is free software; see the source for copying conditions.
Read the resolvconf package
file for more in-depth information.