Provided by: resolvconf_1.69ubuntu1_all bug

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   |
       --create-runtime-directories | --wipe-runtime-directories

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 pppd(8) (for ppp interfaces); by DHCP clients such as dhclient(8); by ifup(8) and
       ifdown; and by DNS caches such as dnsmasq(8) (for the loopback interface).  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  supported:  dns-nameservers,
       dns-search, and dns-sortlist.  The dns-domain option is deprecated in favor of dns-search.

       To add nameserver addresses, add a single line beginning with dns-nameservers.

           dns-nameservers 192.168.1.254 8.8.8.8

       Note  that  one or more addresses can be given on this line, separated by spaces, and note
       the "s" at the end of the option name, in contrast with  the  resolv.conf(5)  option  name
       nameserver.   Remember  that  in  interfaces(5)  each  option can be used at most once per
       stanza.

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

           dns-search foo.org bar.com

       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-nameservers 192.168.1.254 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 should be migrated to the appropriate iface stanza(s) in interfaces(5).

   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.

       --create-runtime-directories
              Create  the directories where resolver information records and other run-time files
              are stored.

       --wipe-runtime-directories
              Delete everything in the directories where resolver information records  and  other
              run-time files are stored.

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-2012 Thomas Hood.
       This is free software; see the source for copying conditions.

SEE ALSO

       interface-order(5), resolv.conf(5), resolver(3).

       Read the resolvconf package README file for more in-depth information.