Provided by: resolvconf_1.63ubuntu11_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

       Overwrite  (-a)  or  delete  (-d)  the  nameserver  information  record
       IFACE.PROG.   Also  run the update scripts in /etc/resolvconf/update.d/
       if the nameserver information has changed and updating is enabled.

       With -u, just run the update scripts if updating is enabled.

       With -a, -d or  -u  schedule  a  delayed  update  if  updating  is  not
       currently enabled.

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/dhcp/dhclient-
       enter-hooks.d/resolvconf pushes 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 push
       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 /run/resolvconf/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
       /run/resolvconf/resolv.conf.   This   link   is   never   modified   by
       resolvconf(8).  If you find that /etc/resolv.conf is not being updated,
       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 with the GNU C  Library
       resolver) should work with resolvconf(8).

       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 IFACE.PROG
              Add or overwrite the record IFACE.PROG.   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.

       The  string IFACE.PROG name 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 PROG,
       the name of the interface configuration program, e.g., `eth0.dhclient'.

       Following the addition or  deletion  of  the  record,  run  the  update
       scripts (if updating is enabled).

       -u     Just run the update scripts (if updating is 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  default-override 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(8)-generated   resolv.conf  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 update.d/libc script  will  include  no
              more  nameserver addresses after the first loopback address.  In
              IPv4 a loopback address is an 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(8) 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".  A deprecated synonym
              for this variable is TRUNCATE_NAMESERVER_LIST_AFTER_127.

FILES

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

       /run/resolvconf
              This is the location where nameserver information is stored.  It
              will   be   created   if   resolvconf   is   called   with   the
              --create-runtime-directories  option.   Clients  should not make
              any assumptions about the hierarchy that  is  constructed  under
              this directory.

       /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.
              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 if
              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 the latter are always added to the  end  of
              the dynamically generated resolv.conf.

BUGS

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

AUTHOR

       Written by Thomas Hood <jdthood@gmail.com>.

COPYRIGHT

       Copyright (C) 2004, 2011 Thomas Hood
       This is free software; see the source for copying conditions.

SEE ALSO

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