Ubuntu Manpage: resolvconf - manage nameserver information

Provided by: resolvconf_1.79ubuntu10.18.04.3_all

NAME

       resolvconf - manage nameserver information

SYNOPSIS

       cat FILE | resolvconf -a IFACE.PROG

       resolvconf -d IFACE.PROG

       resolvconf -u

       resolvconf --enable-updates | --disable-updates | --updates-are-enabled

DESCRIPTION

       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 that
       information.

       Information is added to or removed from the database using  the  resolvconf  program.   See  the  OPTIONS
       section below for a discussion of the available options.

SUPPLIERS OF NAMESERVER INFORMATION

       Normally  the resolvconf program is run only by network interface configuration programs such as ifup(8),
       ifdown, NetworkManager(8), dhclient(8), and pppd(8); and by local nameservers such as dnsmasq(8).   These
       programs obtain nameserver information from some source and push it to resolvconf.

   dhclient
       The  dhclient  program,  for example, may receive nameserver addresses and domain search list information
       during    its    negotiation    with    the    DHCP    server;     if     so,     its     hook     script
       /etc/dhcp/dhclient-enter-hooks.d/resolvconf pushes this information to resolvconf.

   ifup
       The   ifup   program   can   be   used   to   configure  network  interfaces  according  to  settings  in
       /etc/network/interfaces.  To make ifup push nameserver information to resolvconf when  it  configures  an
       interface  the  administrator  must  add dns- option lines to the relevant iface stanza in interfaces(5).
       The following option names are accepted: dns-nameserver, dns-search, and dns-sortlist.

       To add a nameserver IP address, add an option line consisting of dns-nameserver and the address.  To  add
       multiple nameserver addresses, include multiple such dns-nameserver lines.

           dns-nameserver 192.168.1.254
           dns-nameserver 8.8.8.8

       To add search domain names, add a line beginning with dns-search.

           dns-search foo.org bar.com

       The  dns-nameservers option is also accepted and, unlike dns-nameserver, can be given multiple arguments,
       separated by spaces.

       The dns-domain option is deprecated in favor of dns-search.

       The resulting stanza might look like the following example.

           iface eth0 inet static
               address 192.168.1.3
               netmask 255.255.255.0
               gateway 192.168.1.1
               dns-nameserver 192.168.1.254
               dns-nameserver 8.8.8.8
               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 /etc/resolv.conf file,

       •      the  nameserver  information  in that static file, (which is to say the information on nameserver,
              domain, search and sortlist lines) should be  migrated  to  the  appropriate  iface  stanza(s)  in
              /etc/network/interfaces(5) as just described;

       •      options    (which    is    to    say,    any    options    lines)    should    be    migrated   to
              /etc/resolvconf/resolv.conf.d/base.

   Command line
       The administrator can run resolvconf 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 resolvconf is stored for use by subscribers to resolvconf's
notification service. Subscriber packages that need to know when nameserver information has changed
should install a script in /etc/resolvconf/update.d/ (or in /etc/resolvconf/update-libc.d/: see below).
For example, DNS caches such as dnsmasq(8) and pdnsd(8) 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.

libc
The most important software package that subscribes to the notification service is the GNU C Library
resolver(3). This library is used by many applications that need to resolve domain names. When
nameserver information is updated, the script /etc/resolvconf/update.d/libc generates a new version of
the resolver configuration file, /run/resolvconf/resolv.conf, as described below. If the new version of
the file differs from the previously generated one then the hook scripts found in
/etc/resolvconf/update-libc.d/ are executed.

The dynamically generated resolver configuration file always starts with the contents of
/etc/resolvconf/resolv.conf.d/head and ends with the contents of /etc/resolvconf/resolv.conf.d/tail.
Between head and tail the libc script inserts dynamic nameserver information compiled from, first,
information provided for configured interfaces; second, static information from
/etc/resolvconf/resolv.conf.d/base. Specifically, it writes:

1) up to three nameserver lines, ordered according to /etc/resolvconf/interface-order, possibly fewer
if one of the addresses is a loopback address and the
TRUNCATE_NAMESERVER_LIST_AFTER_LOOPBACK_ADDRESS environment variable is affirmatively set, as
discussed in the ENVIRONMENT VARIABLES section;

2) up to one search line containing the combined domain search list from all "domain" and "search"
input lines, also ordered according to interface-order(5);

3) all other non-comment input lines.

To make the resolver use this dynamically generated resolver configuration file the administrator should
ensure that /etc/resolv.conf is a symbolic link to /run/resolvconf/resolv.conf. This link is normally
created on installation of the resolvconf package. The link is never modified by the resolvconf program
itself. If you find that /etc/resolv.conf is not being updated, please check to make sure that the link
is intact.

The GNU C Library resolver library isn't the only resolver library available. However, any resolver
library that reads /etc/resolv.conf (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 /etc/resolvconf/update-libc.d/ rather than in /etc/resolvconf/update.d/. (For
example, two packages that install update-libc.d/ hook scripts are fetchmail and squid.) This is
important for synchronization purposes: scripts in update-libc.d/ are run after resolv.conf has been
updated; the same is not necessarily true of scripts in update.d/.

OPTIONS

       -a IFACE.PROG
              Add  or  overwrite the record IFACE.PROG then run the update scripts if updating is enabled.  When
              this option is used the information must be provided to resolvconf on its standard  input  in  the
              format of the resolv.conf(5) file.  Each line in the file must be terminated by a newline.

       -d IFACE.PROG
              Delete the record IFACE.PROG then run the update scripts if updating is enabled.

       The  string  IFACE.PROG  may not contain spaces, slashes, an initial dot, an initial hyphen or an initial
       tilde.  It is conventionally formed from IFACE, the name of the interface involved, a dot, and IPROG, the
       name of the interface configuration program, e.g., "eth0.dhclient".

       -u     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.

       --enable-updates
              Set the flag indicating that resolvconf should run update scripts when invoked in the future  with
              -a, -d or -u.  If a delayed update was scheduled then run update scripts.

       --disable-updates
              Clear the flag.

       --updates-are-enabled
              Return 0 if the flag is set, otherwise return 1.

ENVIRONMENT VARIABLES

The following variables can be set in the configuration file /etc/default/resolvconf. If the file does
not exist you will have to create it.

REPORT_ABSENT_SYMLINK
If set to "yes" then resolvconf will print a message when /etc/resolv.conf is not a symbolic link
to the resolvconf-generated resolver configuration file. Set to "no" to prevent the printing of
this message. The default is "yes".

TRUNCATE_NAMESERVER_LIST_AFTER_LOOPBACK_ADDRESS
If set to "yes" then the libc 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 resolv.conf and thus reduces the number of instances in which the
update-libc.d/ 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 TRUNCATE_NAMESERVER_LIST_AFTER_127.

FILES

       /etc/default/resolvconf
              See the ENVIRONMENT VARIABLES section.

       /etc/resolvconf/interface-order
              Determines the order of precedence of nameserver addresses and search domain names.  See above and
              interface-order(5).

       /etc/resolvconf/resolv.conf.d/base
              File  containing  basic resolver information.  The lines in this file are included in the resolver
              configuration file even when no interfaces are configured.

       /etc/resolvconf/resolv.conf.d/head
              File to be prepended to the dynamically generated resolver configuration file.  Normally  this  is
              just a comment line.

       /etc/resolvconf/resolv.conf.d/tail
              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  options  line  if  one  is
              needed, e.g.,

                  options inet6

       /etc/resolvconf/resolv.conf.d/original
              Copy  of  the /etc/resolv.conf file before the resolvconf package was installed.  This file has no
              effect on the functioning of resolvconf; it is retained so that /etc/resolv.conf 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  information  to
              resolvconf(8).

              Note    also    that   the   administrator   can   choose   to   create   a   symbolic   link   in
              /etc/resolvconf/resolv.conf.d/ from tail to original so that the contents of original  are  always
              added to the end of the dynamically generated file.

BUGS

       Currently resolvconf does not check the sanity of the information provided to it.

AUTHOR

       Written by Thomas Hood <jdthood@gmail.com> with contributions by Nathan Stratton Treadway.

COPYRIGHT

       Copyright © 2004-2013 Thomas Hood.
       This is free software; see the source for copying conditions.