resolvconf


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  name-
       server 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  resolv-
       conf  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  con-
       figuration  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/resolv-
       conf 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 adminis-
       trator must add dns- option lines  to  the  relevant  iface  stanza  in
       interfaces(5).   The  following  option  names are supported: dns-name-
       servers, dns-search, and dns-sortlist.  The dns-domain option is depre-
       cated in favor of dns-search.

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

           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.


       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 sub-
       scribers  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/resolv-
       conf/update-libc.d/: see below).  For example, DNS caches such as  dns-
       masq(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 infor-
       mation is updated, the script /etc/resolvconf/update.d/libc generates a
       new   version   of   the   resolver  configuration  file,  /run/resolv-
       conf/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.  Specifi-
       cally, it writes:

         1) up to three nameserver lines, ordered  according  to  /etc/resolv-
            conf/interface-order,  possibly fewer if one of the addresses is a
            loopback  address  and  the   TRUNCATE_NAMESERVER_LIST_AFTER_LOOP-
            BACK_ADDRESS  environment  variable  is affirmatively set, as dis-
            cussed 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 configura-
       tion  file  the  administrator should ensure that /etc/resolv.conf is a
       symbolic link to /run/resolvconf/resolv.conf.  This  link  is  normally
       conf/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
              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  trunca-
              tion.  The default is "yes".

              A   deprecated  synonym  for  this  variable  is  TRUNCATE_NAME-
              SERVER_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 con-
              figuration file.  Normally this is just a comment line.

       /etc/resolvconf/resolv.conf.d/tail
              File to be appended to the dynamically generated  resolver  con-
              figuration  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 instal-
              lation of resolvconf are still reachable after  installation  of
              resolvconf  even though at that point not all suppliers of name-

AUTHOR
       Written by Thomas Hood <jdthood@gmail.com> with contributions by Nathan
       Stratton Treadway.

COPYRIGHT
       Copyright (C) 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.



resolvconf                        28 May 2012                    RESOLVCONF(8)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2018 Hurricane Electric. All Rights Reserved.