Provided by: resolvconf_1.44ubuntu1_all bug

NAME

       resolvconf - manage nameserver information

SYNOPSIS

       cat FILE | resolvconf -a INTERFACE

       resolvconf -d INTERFACE

       resolvconf -u

DESCRIPTION

       Overwrite  (-a)  or  delete  (-d) the nameserver information record for
       network  interface  INTERFACE   and   run   the   update   scripts   in
       /etc/resolvconf/update.d/ if the nameserver information has changed.

       With -u, just run the update scripts.

PUBLICATION

       Normally  resolvconf  is  run  only by hook scripts attached to network
       interface configurers such as pppd(8) (for  ppp  interfaces),  to  DHCP
       clients  such  as dhclient(8), to ifup(8) and ifdown, and to DNS caches
       such as dnsmasq(8) (for the loopback interface).   These  hook  scripts
       furnish  resolvconf  with  information about nameservers.  For example,
       dhclient  receives  one  or  more  nameserver  addresses   during   its
       negotiation  with the DHCP server; its hook script /etc/dhcp3/dhclient-
       enter-hooks.d/resolvconf publishes this information to resolvconf.

       The ifup(8)  program  can  be  used  to  configure  network  interfaces
       according  to  settings  in  /etc/network/interfaces(5).   To make ifup
       publish nameserver information to  resolvconf  when  it  configures  an
       interface,   add   dns-   lines   to   the  relevant  iface  stanza  in
       /etc/network/interfaces.   To  add  nameserver  addresses  add  a  line
       beginning with dns-nameservers.

           dns-nameservers 11.22.33.44 55.66.77.88

       Note  that  one or more addresses can be given, and note the ‘s’ at the
       end of the option  name.   (Contrast  with  the  resolv.conf(5)  option
       nameserver.)  For each other valid resolv.conf(5) configuration option,
       you can include, in the stanza, one line  beginning  with  that  option
       name  with  a  dns-  prefix.   The resulting stanza might look like the
       following example.

           iface eth0 inet static
               address 192.168.3.3
               netmask 255.255.255.0
               gateway 192.168.3.1
               dns-nameservers 192.168.3.45 192.168.8.10
               dns-search foo.org bar.com

       See the resolvconf package’s README file for more detailed information.
       For  more  information  about  the dns-* options, e.g., dns-search, see
       resolv.conf(5).

       The administrator can run resolvconf from the command line  to  add  or
       delete nameserver information, but this is not normally necessary.

SUBSCRIPTION

       Nameserver  information  provided  to  resolvconf  is stored for use by
       subscribers to resolvconf’s  notification  service.   Subscribers  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.

       The   most   important   piece  of  software  that  subscribes  to  the
       notification service is the set of functions that make  up  the  GNU  C
       Library resolver(3).  When nameserver information is updated the script
       /etc/resolvconf/update.d/libc writes a new resolver configuration  file
       to   /etc/resolvconf/run/resolv.conf  and  then  runs  the  scripts  in
       /etc/resolvconf/update-libc.d/.   To  make   the   resolver   use   the
       dynamically  generated  resolver  configuration  file the administrator
       should  ensure  that   /etc/resolv.conf   is   a   symbolic   link   to
       /etc/resolvconf/run/resolv.conf.    This  link  is  never  modified  by
       /sbin/resolvconf.  If you  find  that  /etc/resolv.conf  is  not  being
       updated, check to see 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 with the GNU C Library
       resolver) should work with resolvconf.

       Subscribers 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/.   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/.   Examples  of  packages  that  do  this  are
       fetchmail(1) and squid(8).

       Client  hook  scripts  will  find  the  files   containing   nameserver
       information in the current directory.

OPTIONS

       -a INTERFACE
              Add  or  overwrite  the  record for network interface INTERFACE.
              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 INTERFACE
              Delete the record for network interface INTERFACE.

       The  INTERFACE  name  may  not contain spaces, slashes or initial dots,
       hyphens or tildes.

       Following the addition or deletion of the record, resolvconf  runs  the
       update scripts as described in the CLIENTS section.

       -u     Just run the update scripts.

ENVIRONMENT VARIABLES

       The following variables can be set in /etc/default/resolvconf.

       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 resolv.conf file.  Set to "no" to prevent the printing
              of this message.  The default is "yes".

       TRUNCATE_NAMESERVER_LIST_AFTER_127
              If set to "yes" then the update.d/libc script  will  include  no
              more  nameserver  addresses  after the first address that starts
              with "127."  This is usually  the  preferable  behavior  if  the
              nameserver  at  127.*  is  a  local  caching nameserver since it
              inhibits unnecessary changes to resolv.conf.  When an  interface
              is  brought  up  the  local  caching  nameserver  is informed by
              resolvconf of any new nameserver addresses  and  the  additional
              name  service is made available to applications that make use of
              the resolver and the local caching nameserver; the  applications
              themselves  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  this
              truncation feature.  The default is "yes".

FILES

       /etc/default/resolvconf
              See the ENVIRONMENT VARIABLES section.  /etc/resolvconf/run This
              is either a directory where nameserver information can be stored
              or a symbolic link to such a directory.  Clients should not make
              any assumptions about the canonical location of  this  directory
              or the hierarchy that is constructed under it.

       /etc/resolvconf/interface-order
              Determines the order in which nameserver information records are
              processed.  See 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.

BUGS

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

AUTHOR

       Written by Thomas Hood <jdthood@yahoo.co.uk>.

COPYRIGHT

       Copyright © 2008 Thomas Hood
       This is free software; see the source for copying conditions.  There is
       NO  warranty;  not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
       PURPOSE.

SEE ALSO

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