                          README file for
                            resolvconf

Contents
~~~~~~~~
News
Introduction
Rationale
HOWTO
Objectives
Technical overview
Usage information for developers
Usage information for administrators
FAQ
TODO
DONE
Credits

News
~~~~
* Last updated 1 June 2004 for version 1.14

Introduction
~~~~~~~~~~~~
Resolvconf is a framework for keeping track of the system's information
about currently available nameservers.  It sets itself up as the
intermediary between programs that supply nameserver information and
applications that need nameserver information.

Rationale
~~~~~~~~~
/etc/resolv.conf was once a simple static configuration file where the
sysadmin placed a few directives that rarely needed to be changed.  That
changed with the advent of mobile computing: a computer can now move
from one network to another quite often.  Debian currently includes many
packages that alter resolv.conf more or less automatically.  Some of
them are listed below, along with a short description of what they do
which I have tried to keep up to date.  (Figures in parentheses show the
package's popularity-contest score on 29 April 2004.)

pcmcia-cs (421)
    Can overwrite resolv.conf with no backup unless (as of 3.2.5-1)
    resolvconf is installed.  By default, doesn't.
ppp (1022)
    pppd optionally overwrites /etc/ppp/resolv.conf .  By default, does.
pppconfig (392)
    Moves resolv.conf out of the way and puts it back when done.
pppoeconf (314)
    Prior to version 1.0, overwrites resolv.conf, attempting to merge
    its stuff with the existing contents.  Creates a backup in /etc/ but
    doesn't restore it.
xisp (removed)
    Adds lines to /etc/resolv.conf on PPP interface up and deletes those
    lines on interface down.
totd (4)
    PPP hook scripts can do things to /etc/resolv.conf but SFAICT are
    effectively no-ops if resolvconf is installed.  Hard to tell.
    Postinst does things to /etc/resolv.conf and also threatens to
    rewrite dhclient_enter_hooks.  Nightmare package.
dhcp-client (1054)
    Prior to version 2.0pl5-17, overwrites resolv.conf without making a
    backup.
dhcp3-client (229)
    Overwrites resolv.conf unless make_resolv_conf() is redefined.
    Resolvconf redefines it.
dhcpcd (54)
    Optionally overwrites resolv.conf .  Default is not to do so.  Prior
    to version 1:1.3.22pl4-8, hook script overwrites
    /etc/dhcpc/resolv.conf unless (as of 1:1.3.22pl4-7) resolvconf is
    installed.
pump (265)
    Prior to version 0.8.15, blindly overwrites resolv.conf unless nodns
    option is used.  No backup.  As of version 0.8.15 pump calls
    resolvconf if it is installed instead of overwriting
    /etc/resolv.conf.
udhcpc (11)
    Blindly overwrites resolv.conf.  No backup.
netenv (35)
    Contains sample code that, if uncommented, would overwrite
    /etc/resolv.conf without backing it up
switchconf (8)
    Forcibly links selected resolv.conf file into place without making a
    backup.
divine (6)
    Symlinks in a resolv.conf for the selected network.  Appears to
    trash whatever was in resolv.conf when it starts.
intuitively (4)
    If a resolv.conf file is included in /etc/intuitively/NETWORK,
    blindly overwrites /etc/resolv.conf .
laptop-netconf (4)
    Symlinks in a resolv.conf for the detected network.  Seems to make a
    backup of resolv.conf but doesn't restore it.
whereami (10)
    Contains utility scripts that modify resolv.conf
laptop-net (44 installed)
    Overwrites resolv.conf unless (as of 2.20) resolvconf is installed.

Several other packages recommend to the user that scripts be written to
alter or replace resolv.conf.

These packages do not cooperate; they simply overwrite one another's
changes.  Even those that back up and restore the file will corrupt it
if interfaces are brought up and down in other than a LIFO order.  Few
of them support the use of a local DNS cache.

Resolvconf (score: 84) has been written in order to provide a framework
for managing the resolv.conf file in an way that avoids the above
problems.

HOWTO
~~~~~
Resolvconf works with most interface configurers in Debian:
   ppp
   dhcp3-client, dhcp-client, dhcpcd, pump
   ifupdown
and DNS caches:
   dnsmasq, pdnsd, bind9
and with any program that uses a DNS client library that consults
/etc/resolv.conf to obtain its list of nameservers:
   the GNU C Library resolver library
   adns
   the djbdns resolver library
   FireDNS

Take the following steps to set things up.  Unfortunately, it is not
always simply a matter of installing the resolvconf package --
especially if you have already tried to deal with the above problems
locally by customizing your configuration.

0. You may have already installed resolvconf at this point.  OK.
1. Stop obsolete programs from writing to /etc/resolv.conf
  * netenv
    + Purge or make sure that /sbin/netenv hasn't been configured such
      that it overwrites /etc/resolv.conf
  * switchconf
    + Purge or make sure that there are no resolv.conf files under the
      /etc/switchconf/ directory
  * totd
    + Purge
  * divine
    + Purge
  * intuitively
    + Purge or make sure that there are no resolv.conf files under the
      /etc/intuitively/ directory
  * laptop-netconf
    + Purge or edit configuration files such as
      /etc/laptop-netconf/<profile> so that these will not touch
      /etc/resolv.conf
  * whereami
      Purge or make sure that you aren't using the "setresolver",
      "bind-forwarders" or "setdnsmasq" utility scripts.
  * udhcpc
    + Purge and install another DHCP client, or modify
      /etc/udhcpc/default.bound and /etc/udhcpc/default.renew so that
      they send resolver information to /sbin/resolvconf instead of
      writing it directly to /etc/resolv.conf ; modify
      /etc/udhcpc/default.deconfig so that it tells resolvconf to delete
      that information.  (Currently resolvconf Conflicts: with udhcpc so
      the latter alternative is ruled out.)
  * etc.
      Eliminate or disable local scripts of any kind that futz with
      /etc/resolv.conf
2. Configure programs so as not to write to /etc/resolv.conf
  * pppoeconf
      Delete or evacuate /etc/ppp/ip-up.d/000usepeerdns
      N.B.: The ppp package's /etc/ppp/ip-up.d/0000usepeerdns and
      /etc/ppp/ip-down.d/0000usepeerdns (with four zeroes in the name)
      do not have to be deleted.
  * xisp
      If the program was ever installed and removed then PURGE it now.
      Otherwise eliminate the parts of /etc/ppp/ip-up.d/0xisp-dns and
      /etc/ppp/ip-down.d/0xisp-dns that overwrite /etc/resolv.conf .
  * dhcpcd
      Make sure that SET_DNS is not set anywhere in /etc/dhcpc/config .
      (In recent versions of dhcpcd, on initial installation, SET_DNS
      is not set.)
  * ifupdown
      Remove any "up" or "down" commands from /etc/network/interfaces
      that futz with /etc/resolv.conf and remove any scripts from
      /etc/network/if-*.d/ that futz with /etc/resolv.conf .
3. Update packages to versions that are compatible with resolvconf
  * dhcp3-client and dhcp3-common >= 3.0+3.0.1rc11-5
      Earlier versions lack the hooks required to stop dhclient from
      overwriting /etc/resolv.conf and to interface with resolvconf.
      You may need to upgrade samba in order to upgrade dhcp3-*.
  * dhcp-client >= 2.0pl5-18
      Earlier versions overwrite the target of /etc/resolv.conf and
      don't interface with resolvconf
  * dhcpcd >= 1:1.3.22pl4-7
      Earlier versions lack the hooks to interface with resolvconf
  * pump >= 0.8.15-1
      Earlier versions overwrite the target of /etc/resolv.conf and
      don't interface with resolvconf
  * pcmcia-cs >= 3.2.5-1
      Earlier versions overwrite /etc/resolv.conf if certain 
      configuration options are enabled in /etc/pcmcia/network.opts
  * dnsmasq >= 1.18-2
      Versions earlier than 1.13-2 lack the hooks to interface with
      resolvconf.
      Versions earlier than 1.18-2 fail when installed or upgraded
      at the same time as resolvconf is first installed.
  * pdnsd >= 1.1.10par-4
      Versions earlier than 1.1.10par-1 lack the hooks to interface
      with resolvconf.
      Versions earlier than 1.1.10par-4 don't interface properly
      with resolvconf.
  * pppconfig >= 2.3.1
      Some earlier versions contain PPP hook scripts
        /etc/ppp/ip-up.d/0dns-up
        /etc/ppp/ip-down.d/0dns-down
      that futz with /etc/resolv.conf.  Make sure that you tell dpkg to
      install the scripts that ship with the latest version of the
      package.  Also make sure that they have execute permission if you
      want to use them to incorporate per-provider resolver
      configuration options into the resolver configuration file.
  * pppoeconf >= 1.0
      Earlier versions contain a PPP hook script
        /etc/ppp/ip-up.d/000usepeerdns
      that futzes with /etc/resolv.conf.  After upgrading pppoeconf make
      sure that this script is not present.  N.B.: The ppp package's
      /etc/ppp/ip-up.d/0000usepeerdns and
      /etc/ppp/ip-down.d/0000usepeerdns (with four zeroes) are OK: they
      disable themselves if resolvconf is installed.
  * laptop-net >= 2.21-1
      Earlier versions can't be prevented from overwriting
      /etc/resolv.conf and don't interface with resolvconf.
4. Configure packages to work with resolvconf
  4.1 ppp
    * Make sure that the usepeerdns option is used.  With this option,
      pppd will obtain nameserver addresses from the peer and these will
      be added to resolvconf's database.
  4.2 pump
    * Make sure that neither the nodns nor the noresolvconf option is
      used -- either in pump.conf or on the command line
  4.3 ifupdown
    * For each inet static logical interface through which a nameserver is
      accessible, add lines like the following to /etc/network/interfaces .

          dns-nameservers 11.22.33.44 55.66.77.88
          dns-search foo.org bar.com

      Other recognized option words are 'dns-domain' and 'dns-sortlist'.
      These option names correspond to the option names used in the
      resolv.conf file with one exception: whereas one lists several
      nameserver addresses in /etc/resolv.conf on several "nameserver"
      lines, here one should list them all on a single "dns-nameservers"
      line.  See resolv.conf(5) for more information.  The lines entered
      in /etc/network/interfaces will be added to the resolver
      configuration file (without the "dns-" prefix, of course) when a
      physical interface is brought up as that logical interface.
      Note that the resolver configuration is updated AFTER all the "up"
      commands have been run; therefore "up" commands cannot make use of
      nameservers listed on "dns-nameservers" lines in the same logical
      interface stanza.  Changing this will require modifying ifupdown
      so that it talks to resolvconf; currently resolvconf hooks into
      ifupdown using the script /etc/network/if-up.d/000resolvconf. Note
      too that scripts in /etc/network/if-up.d/ CAN make use of the
      added nameservers because those scripts run after 000resolvconf.
  4.4 bind9
    * Change the /etc/bind/named.conf file so that it includes
      /var/run/bind/named.options instead of /etc/bind/named.conf.options.
      The former will be generated from the latter, as needed, by
      inserting or updating the "forwarders" statement inside the
      "options" statement with a current list of forwarders.
  4.5 bind
    * Change the /etc/bind/named.conf file so that it includes
      /var/run/bind/named.options instead of /etc/bind/named.conf.options.
      The former will be generated from the latter, as needed, by
      inserting or updating the "forwarders" statement inside the
      "options" statement with a current list of forwarders.
    * Change /etc/init.d/bind to:
      + At the bottom of start(), after the start-stop-daemon line, add:
            if [ "$?" = 0 ] && [ -x /sbin/resolvconf ] ; then
                echo "nameserver 127.0.0.1" | /sbin/resolvconf -a lo.named
            fi
      + At top of stop(), before the start-stop-daemon line, add:
            if [ -x /sbin/resolvconf ] ; then
                /sbin/resolvconf -d lo.named
            fi
      This tells resolvconf when named is available to resolve names.
5. Install the resolvconf package if you have not already done so.
   If you have already done so then consider dpkg-reconfigure'ing it.
   Agree to symlink /etc/resolv.conf to /etc/resolvconf/run/resolv.conf.
   You can decline the offer to append the original static resolver
   configuration file to the end of the dynamically generated resolver
   configuration file because you have already modified
   /etc/network/interfaces as directed above.
6. Ifdown and then ifup all interfaces; restart DNS caches.
7. Check /etc/resolv.conf to make sure that its contents make sense.

Objectives
~~~~~~~~~~
I hope that resolvconf meets the following objectives
* Be opaque
    Resolvconf must be as opaque as possible.  It must have a stable
    interface and mustn't require that maintainers know about its
    internals.
* Be order-independent
    Interfaces going up and down in arbitrary order must be handled
    properly.
* Be locally configurable
    Administrator choices must be respected.
* Support DNS caches
    Local DNS cache programs must be able to arrange for nameserver
    addresses supplied by interfaces to be passed to them for use as
    forwarders.  The libc resolver should use any local DNS caches that
    are available.
* Be compatible with a read-only root filesystem
    Variable files must be easily relocated out of /etc/.
* Be portable
* Be simple

Technical overview
~~~~~~~~~~~~~~~~~~
* The /etc/resolvconf/ directory contains:
  + resolv.conf.d/
    Files related to the libc resolv.conf file
    - resolv.conf.d/head
      The head of the dynamically generated resolv.conf
    - resolv.conf.d/tail
      The tail of the dynamically generated resolv.conf
    - resolv.conf.d/base
      Information always included in the resolv.conf file.  Dynamic
      information gets merged with this information.  E.g., if base
      contains 'search a.b.c' and another record is added that contains
      'search x.y.z' then the resulting file will have
      'search a.b.c x.y.z'.
  + run/
    Directory where run time files are stored.  This can be replaced by
    a symlink to a directory on another filesystem if the admin so
    desires -- e.g., to /dev/shm/resolvconf/ .
  + update.d/
    Scripts to run when nameserver information is updated
  + update-libc.d/
    Scripts to run when the resolv.conf file changes
* Symlink /etc/resolv.conf -> /etc/resolvconf/run/resolv.conf
* Configurers of interfaces call /sbin/resolvconf to provide
  resolv.conf-like information after the interface is brought up.  They
  call it again to delete the information when the interface is brought
  down.  /sbin/resolvconf then does the equivalent of
  "/etc/init.d/resolvconf reload".
* "/etc/init.d/resolvconf reload" calls DNS cache update scripts in
  /etc/resolvconf/update.d/ to update DNS cache configuration file
  fragments and reload daemons.  It then regenerates
  /etc/resolvconf/run/resolv.conf and then calls scripts in
  /etc/resolvconf/update-libc.d/ if the latter has changed.

Usage information for developers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Interface configurers send resolver information to resolvconf in the
format of the familiar /etc/resolv.conf file.  Thus, for example, a
program that has configured interface $IFACE would do the following
after generating a resolv.conf file named 'new-resolv.conf'.

      resolvconf -a $IFACE < new-resolv.conf

This command updates the resolver information related to interface
$IFACE.  Any information previously sent for this interface is
overwritten.  On bringing the interface down, the configurer would do
the following.  

      resolvconf -d $IFACE

For another example, the proxy script for pppd forwards to
resolvconf the resolver information that is made available to
ip-up.d/ and ip-down.d/ scripts in environment variables DNS1, etc.

      echo "nameserver $DNS1" | resolvconf -a $IFACE

For additional examples, look at the hook scripts for dhcp3-client
and ifupdown.  Support for other configurers including dhcpcd, pump
and laptop-net has been added to those packages.

In general, any package that currently overwrites /etc/resolv.conf
can be adapted to work with resolvconf while preserving backward
compatibility by introducing a code fragment like the following.

    if [ -x /sbin/resolvconf ] ; then
      if [ "$DIRECTION" = "up" ] ; then
         echo -n "$RESOLVINFO" | /sbin/resolvconf -a "$IFACE"
      else
         /sbin/resolvconf -d "$IFACE"
      fi
    else
         (... existing resolv.conf cleverness ...)
    fi

/sbin/resolvconf stores the information sent to it and then runs the
scripts in /etc/resolvconf/update.d/ .  One of the latter generates
the libc resolver configuration file.  Another generates the options
portion of the BIND named configuration file, containing a
"forwarders" statement listing available nameserver forwarders.
(This allows named effectively to be used as a DNS cache on a system
whose network environment varies, e.g., on a laptop.)  Others
generate lists of forwarders for dnsmasq or pdnsd to use.  Any other
program that needs to take action when resolver information is
updated could likewise employ a script in /etc/resolvconf/update.d/ .

Usage information for administrators
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The generation of the resolv.conf file can be controlled by editing
/etc/resolvconf/update.d/libc .  Different strategies can be
followed.  E.g., one possible strategy would be to put only the most
recently provided information into resolv.conf .  The current default
strategy is to put *all* available resolver information into
resolv.conf, ordered by interface type as follows: lo, eth*, ppp* .

The admin can of course disable resolv.conf automagic by deleting the
/etc/resolv.conf symlink and putting a static file at that location.

Once you have installed resolvconf properly you don't normally need
to run /sbin/resolvconf from the command line.  However, I once
encountered a situation in which I did that.  Perhaps it is a useful
illustration.  My ISP's nameserver went down and thus my caching
nameserver could not resolve names.  I knew of another host belonging
to by ISP that I could use so I simply did:
    # echo "nameserver ww.xx.yy.zz" | resolvconf -a dummy
This added the necessary nameserver line to /etc/resolv.conf and to
dnsmasq's nameserver list.  When my ISP's regular nameserver was fixed
I did:
    # resolvconf -d dummy
to restore the original situation.

FAQ
~~~
Q. Why call it 'resolvconf' instead of 'update-resolver' or so?
A. Debian's update-* commands are mostly maintainer programs that update
   static configuration files in /etc/.  Mostly they run at package
   install time.  Resolvconf, in contrast, is a run-time configurer.
Q. Why use 'dns-nameservers' instead of 'dns-nameserver' as the option
   name in /etc/network/interfaces?
A. Because 'dns-nameservers' can take several address arguments whereas
   the 'nameserver' line in /etc/resolv.conf can take only a single
   argument, and because there can be only one instance of any given
   option in a logical interface definition.

TODO (with popcon scores)
~~~~
  * resolvconf
    # 213591: Implement locking
      Currently there is nothing that prevents two instances of
      resolvconf from running at the same time.  One can imagine
      scenarios in which this would have sub-optimal results.
    * -n option?
      If a caller needs to change several records then the only way to
      do it is to call resolvconf several times.  In such a case we
      don't want resolvconf to run the update scripts several times;
      therefore an option (e.g., -n) would be needed that would prevent
      resolvconf from running update scripts.  This option would be used
      on all but the last invocation.  I haven't implemented this yet
      because I haven't seen a case where someone needs to call
      resolvconf more than once.
  * ppp
    # 208095: Suggest resolvconf
      - Marked "wontfix"
  * udhcpc
    + Support resolvconf without requiring local configuration
      - I haven't bothered to push for this because there are four other
        DHCP clients in Debian, all more popular than this one, all
        supporting resolvconf out of the box.  Nevertheless I would be
        pleased if this one worked properly with resolvconf too.
  * ifupdown
    + Handle dns-* commands natively so that the resolver is configured
      before "up" commands are run
  * bind9
    + Adopt /etc/resolvconf/update.d/bind
      - The right thing to do, in theory.  Low priority.
    + Automatically use /var/run/bind/named.options if present instead of
      /etc/bind/named.conf.options
  * bind
    + Modify initscript to support resolvconf
      - Low priority since this package is obsolete
    + same changes as in bind9
  * (djbdns) dnscache
    + Someone should investigate whether it should be supported
      - Currently it is not packaged for Debian; however the 
        djbdns-installer package assists Debian users in installing it.
  * maradns
    + Add resolvconf support
      - Needs more investigation
      - Its initscript should probably do
	    echo "nameserver 127.0.0.1" | resolvconf -a lo
	as dnsmasq and pdnsd do.
      - Could it have an update script that sets the "upstream_servers"
	variable?
  * nscd
    # 252251: Please add resolvconf support
      - PATCH provided; awaiting response from nscd maintainers
  * libadns1
    + It consults resolv.conf so it should already be supported.
      However, someone should test it.
  * libares0
    + It consults resolv.conf so it should already be supported.
      However, someone should test it.
  * libdjbdns1
    + It consults resolv.conf so it should already be supported.
      However, someone should test it.
    + Someone should investigate whether it could be supported better.
      Perhaps /etc/dnsrewrite should be dynamically updated?
  * libfiredns0.9
    + It consults resolv.conf so it should already be supported.
      However, someone should test it.
    + Someone should investigate whether it could be supported better.
      Perhaps /etc/firedns.conf should be dynamically updated?
  * Net::DNS
    + It consults resolv.conf so it should already be supported.
      However, someone should test it.
    + Someone should investigate whether it could be supported better.
  * Users of resolver libraries
    For any package that contains a program that uses resolver(3) or a
    compatible library, add a /etc/resolvconf/update-libc.d/ script to
    notify running instances of the program that the resolver
    configuration file has changed.

DONE
~~~~
  * resolvconf
    + Created and added to dialup and broadband tasks
  * ppp
    + Use resolvconf via /etc/ppp/ip-(up|down).d/
      - DONE in resolvconf package
  * pppconfig
    # 242092: Disable pppconfig's futzing with /etc/resolv.conf
      - DONE in 2.3.1
  * pppoeconf
    # 212756: Eliminate /etc/ppp/ip-up.d/000usepeerdns
      - DONE in 1.0
  * dhcp3-client
    + Use resolvconf via /etc/dhcp3/dhclient-enter-hooks
      - DONE in resolvconf package
    # 171798: dhclient-script should source hook scripts, not run-parts them
      - DONE in 3.0+3.0.1rc11-5
  * dhcp-client
    # 248399: Needs resolvconf support
      - DONE in 2.0pl5-18
  * dhcpcd
    + Support resolvconf without requiring local changes
      - DONE in 1:1.3.22pl4-7
  * pump
    # 194204: Please add proper resolvconf support
      - DONE in 0.8.15-1
  * pcmcia-cs
    # 212823: pcmcia-cs: please add support for the resolvconf package
      - DONE in 3.2.5-1
  * laptop-net
    + Use resolvconf instead of overwriting /etc/resolv.conf .
      - DONE in 2.21-1
  * ifupdown
    + Use resolvconf via /etc/network/if-(up|down).d/
      - DONE in resolvconf package
  * bind9 and bind
    + Create script /etc/resolvconf/update.d/bind to:
      * Convert /etc/bind/named.options.sed into /var/run/bind/named.options
        (which is to be included in /etc/bind/named.conf)
      * Then run "/etc/init.d/bind9 reload" or "/etc/init.d/bind reload"
      - DONE in resolvconf package
  * bind9
    # 199255: Please support resolvconf
      - DONE in 1:9.2.3-1
  * dnsmasq
    + Create script /etc/resolvconf/update.d/dnsmasq to
      generate /var/run/dnsmasq/resolv.conf
      - DONE in resolvconf package
    + Support resolvconf without requiring local changes 
      - DONE in 1.13-2
    + Include /etc/resolvconf/update.d/dnsmasq
      - DONE in 1.13-3
  * pdnsd
    # 247946: Fix resolvconf support
      - DONE in pdnsd 1.1.10par-4
  * fetchmail
    + Use resolvconf to trigger restart on change of nameserver info
      - DONE in 6.2.5-4
  * postfix
    # 212552: Please reload on change of /etc/resolv.conf -- resolvconf hook
      - DONE in 2.0.16-4
  * squid
    # 200572: Please use resolvconf resolver-update notification
      - DONE in 2.5.3-7

Credits
~~~~~~~
The basic idea for resolvconf was expressed by Emile van Bergen on
debian-devel. I claim any braindamage in the implementation as my own.

I thank all the maintainers who have helped with this effort by adding
resolvconf support to their packages.

Werner Heuser, Joe Nahmias and Andreas Barth have been helpful sponsors.

This document was written by Thomas Hood <jdthood_AT_yahoo.co.uk> using
some material written by John Hasler.

This document is part of resolvconf.
