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

SEE ALSO

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