Provided by: debconf-doc_1.4.72ubuntu9_all bug

NAME

       debconf - Debian package configuration system

DESCRIPTION

       Debconf  is  a  configuration  system  for  Debian packages. There is a
       rarely-used command named debconf, documented in debconf(1)

       Debconf provides  a  consistent  interface  for  configuring  packages,
       allowing  you  to  choose  from  several  user  interface frontends. It
       supports preconfiguring  packages  before  they  are  installed,  which
       allows  large  installs  and  upgrades to ask you for all the necessary
       information up front, and then go do the work while  you  do  something
       else.   It  lets  you,  if  you’re in a hurry, skip over less important
       questions and information while installing a package  (and  revisit  it
       later).

Preconfiguring packages

       Debconf can configure packages before they are even installed onto your
       system. This is useful because it lets all the questions  the  packages
       are  going  to ask be asked at the beginning of an install, so the rest
       of the install can proceed while you are away getting a cup of  coffee.

       If  you  use  apt  (version  0.5  or  above),  and  you  have apt-utils
       installed,  each   package   apt   installs   will   be   automatically
       preconfigured. This is controlled via /etc/apt/apt.conf.d/70debconf

       Sometimes you might want to preconfigure a package by hand, when you’re
       not installing it with apt. You can use  dpkg-preconfigure  (8)  to  do
       that,  just  pass  it  the  filenames  of  the  packages  you  want  to
       preconfigure. You will need apt-utils installed for that to work.

Reconfiguring packages

       Suppose you installed the package, and  answered  debconf’s  questions,
       but now that you’ve used it awhile, you realize you want to go back and
       change some of your answers. In the past, reinstalling  a  package  was
       often  the  thing  to  do  when you got in this situation, but when you
       reinstall the package, debconf seems to remember you have answered  the
       questions, and doesn’t ask them again (this is a feature).

       Luckily, debconf makes it easy to reconfigure any package that uses it.
       Suppose you want to reconfigure debconf itself. Just run, as root:
         dpkg-reconfigure debconf

       This will ask  all  the  questions  you  saw  when  debconf  was  first
       installed.   It may ask you other questions as well, since it asks even
       low priority questions that may have been skipped when the package  was
       installed.   You  can use it on any other package that uses debconf, as
       well.

Frontends

       One of debconf’s unique features is that the interface it  presents  to
       you is only one of many, that can be swapped in at will. There are many
       debconf frontends available:

       dialog The default frontend, this uses the whiptail (1) or  dialog  (1)
              programs to display questions to you. It works in text mode.

       readline
              The  most  traditional frontend, this looks quite similar to how
              Debian configuration always has been:  a  series  of  questions,
              printed  out  at  the console using plain text, and prompts done
              using the readline library. It even supports tab completion. The
              libterm-readline-gnu-perl package is strongly recommended if you
              chose to use this frontend; the default  readline  module  isn’t
              really good enough. At the minimum, you’ll need the perl-modules
              package installed to use this frontend.

              This frontend has some special hotkeys. Pageup (or ctrl-u)  will
              go  back  to  the previous question (if that is supported by the
              package that is using debconf), and pagedown  (or  ctrl-v)  will
              skip forward to the next question.

              This  is  the  best  frontend  for remote admin work over a slow
              connection, or for those who are comfortable with unix.

       noninteractive
              This is the anti-frontend. It never interacts with you  at  all,
              and makes the default answers be used for all questions. It will
              occasionally mail root  with  messages  the  package  wanted  to
              display,  but  that’s  it; otherwise it is completely silent and
              unobtrusive, a perfect frontend for automatic installs.  If  you
              are  using  this  front-end,  and require non-default answers to
              questions, you will need to pre-populate the  debconf  database;
              see  the  section  below  on Unattended Package Installation for
              more details.

       gnome  This is a modern X GUI using the gtk  and  gnome  libraries.  Of
              course,  it  requires a valid DISPLAY to work; debconf will fall
              back to other  frontends  if  it  can’t  work.  Note  that  this
              frontend requires you have the libgnome2-perl package installed.

       kde    This frontend provides a  simple  X  GUI  written  with  the  Qt
              library.  It  fits  well  the  KDE desktop. You of course need a
              DISPLAY to use this frontend and must  install  libqt-perl.  The
              frontend  will  fall back to dialog if some of the prerequisites
              are not met.

       editor This is for those fanatics who have to do everything in  a  text
              editor.  It runs your editor on a file that looks something like
              a typical unix config file, and you edit the file to communicate
              with  debconf. Debconf’s author prefers to not comment regarding
              the circumstances that led to this frontend being written.

       web
              This frontend acts as a web server, that  you  connect  to  with
              your  web  browser, to browse the questions and answer them.  It
              has a lot of promise, but is a little rough so far.   When  this
              frontend  starts  up,  it will print out the location you should
              point your web browser to. You have to run the  web  browser  on
              the same machine you are configuring, for security reasons.

              Do keep in mind that this is not a very secure frontend.  Anyone
              who has access to the computer being  configured  can  currently
              access  the  web server and configure things while this frontend
              is running. So this is more of a proof of concept than anything.

       You  can  change  the  default  frontend  debconf uses by reconfiguring
       debconf. On the other hand, if you just want to change the frontend for
       a  minute,  you can set the DEBIAN_FRONTEND environment variable to the
       name of the frontend to use. For example:
         DEBIAN_FRONTEND=readline apt-get install slrn

       The dpkg-reconfigure (8) and dpkg-preconfigure (8)  commands  also  let
       you pass --frontend= to them, followed by the frontend you want them to
       use.

       Note that not all frontends  will  work  in  all  circumstances.  If  a
       frontend  fails  to  start up for some reason, debconf will print out a
       message  explaining  why,  and  fall  back  to  the  next-most  similar
       frontend.

Priorities

       Another  nice  feature of debconf is that the questions it asks you are
       prioritized. If you don’t want to be bothered about every little thing,
       you  can  set  up debconf to only ask you the most important questions.
       On the other hand, if you are a control freak, you can make it show you
       all  questions.  Each  question  has a priority. In increasing order of
       importance:

       low    Very trivial questions that have defaults that will work in  the
              vast majority of cases.

       medium Normal questions that have reasonable defaults.

       high   Questions that don’t have a reasonable default.

       critical
              Questions that you really, really need to see (or else).

       Only  questions  with  a priority equal to or greater than the priority
       you choose will be shown to you. You can  set  the  priority  value  by
       reconfiguring  debconf,  or temporarily by passing --priority= followed
       by the value to the  dpkg-reconfigure  (8)  and  dpkg-preconfigure  (8)
       commands, or by setting the DEBIAN_PRIORITY environment variable.

Backend Database

       Debconf  uses  a  rather  flexible  and potentially complicated backend
       database for storing data such as the answers to  questions.  The  file
       /etc/debconf.conf  is  used  to configure this database. If you need to
       set up something complicated, like make debconf read a remote  database
       to  get  defaults,  with local overrides, read the debconf.conf (5) man
       page for all the gory  details.  Generally,  the  backend  database  is
       located in /var/cache/debconf/

Unattended Package Installation

       If you have many machines to manage you will sometimes find yourself in
       the position of  needing  to  perform  an  unattended  installation  or
       upgrade  of  packages on many systems, when the default answers to some
       configuration questions are not acceptable.  There  are  many  ways  to
       approach this; all involve setting up a database and making debconf use
       it to get the answers you want.

       You should really read debconf.conf (5) before  this  section,  as  you
       need to understand how debconf’s databases work.

       The  easiest  way  to set up the database is to install the packages on
       one machine and answer their questions as usual. Or you might just  use
       dpkg-preconfigure(8)  to  configure  a set of packages without actually
       installing them. Or you might even decide to write a plain text debconf
       database by hand or something.

       Once  you  have  the  database,  you  need to figure out how to make te
       remote systems use it. This depends of course on the  configuration  of
       those systems and what database types they are set up to use.

       If you are using the LDAP debconf database, an entire network of debian
       machines can also  have  any  or  all  package  installation  questions
       answered automatically by a single LDAP server.

       But  perhaps you’re using something a little bit easier to set up like,
       say, the default debconf database configuration, or you just don’t want
       your  remote  systems  to  use LDAP all the time. In this case the best
       approach is to temporarily configure the remote systems to  stack  your
       database  underneath their own existing databases, so they pull default
       values  out  of  it.  Debconf   offers   two   environment   variables,
       DEBCONF_DB_FALLBACK and DEBCONF_DB_OVERRIDE, to make it easy to do this
       on the fly. Here is a sample use:

          cat /var/cache/debconf/config.dat | \
          ssh root@target "DEBIAN_FRONTEND=noninteractive \
                         DEBCONF_DB_FALLBACK=Pipe apt-get upgrade"

       This makes the debconf on the remote host read  in  the  data  that  is
       piped across the ssh connection and interpret it as a plain text format
       debconf database. It then uses that database as a fallback database  --
       a  read-only  database  that is queried for answers to questions if the
       system’s main debconf database lacks answers.

       Here’s another way to use the DEBCONF_DB_FALLBACK environment variable:

         ssh -R 389:ldap:389 root@target \
            "DEBCONF_DB_FALLBACK=’LDAP{host:localhost}’ apt-get upgrade"

       Here  ssh is used to set up a tunneled LDAP connection and run debconf.
       Debconf is told to use the LDAP server as the fallback  database.  Note
       the  use  of  "{host:localhost}"  to configure how debconf accesses the
       LDAP  database  by  providing  the  "host"  field  with  a   value   of
       "localhost".

       Here’s another method:

         scp config.dat root@target:
         ssh root@target "DEBCONF_DB_FALLBACK=’File{/root/config.dat}’ apt-get
       upgrade

       Here you copy the database over with scp, and then ssh  over  and  make
       debconf  use the file you copied over. This illustrates a shorthand you
       can use in the DEBCONF_DB_FALLBACK parameters -- if  a  field  name  is
       left off, it defaults to "filename".

       There  is  only  one problem with these uses of the DEBCONF_DB_FALLBACK
       parameter: While the fallback database can provide answers to questions
       the  other  debconf  databases have never seen, it is only queried as a
       fallback; after the other databases. If you need to instead temporarily
       override  an  existing value on the remote host, you should instead use
       the DEBCONF_DB_OVERRIDE variable. Like DEBCONF_DB_FALLBACK, it sets  up
       a temporary database, but this database is consulted before any others,
       and can be used to override existing values.

Developing for Debconf

       Package developers and others who want to  develop  packages  that  use
       debconf should read debconf-devel(7).

       Briefly, debconf communicates with maintainer scripts or other programs
       via standard input and output, using  a  simple  line-oriented  command
       language  similar  to  that  used  by common internet protocols such as
       SMTP. Programs use this protocol to ask debconf to display questions to
       the user, and retrieve the user’s answers. The questions themselves are
       defined in a separate file, called the "templates file",  which  has  a
       format not unlike a debian control file.

       Debian  packages  which  use debconf typically provide both a templates
       file and a "config" script (run to preconfigure  the  package)  in  the
       control metadata section of the package.

ENVIRONMENT

       DEBIAN_FRONTEND
              Used to temporarily change the frontend debconf uses. See above.

       DEBIAN_PRIORITY
              Used to temporarily change  the  minimum  priority  of  question
              debconf will display. See above.

       DEBCONF_DEBUG
              Turns  on  debugging  output  on standard error. May be set to a
              facility name or a regular expression which matches  a  facility
              name (such as ’.*’ to output all debug info). The facility names
              include:

              user   Debugging info of interest to a debconf user.

              developer
                     Debugging info of interest to a package developer.

              db     Debugging info about the backend database.

       DEBCONF_NOWARNINGS
              Set to "yes" to disable some warnings that debconf may  display.
              Does not suppress display of fatal errors.

       DEBCONF_TERSE
              Set  to  "yes"  to enable terse mode, in which debconf frontends
              cut down on the verbiage as much as possible.

       DEBCONF_DB_FALLBACK
              Stack a database after the normally used databases, so  that  it
              is used as a fallback to get configuration information from. See
              "Unattended Package Installation" above. If  the  value  of  the
              variable  is  the  name of an existing database in debconf.conf,
              then that database will be  used.   Otherwise,  the  environment
              variable  can  be  used  to  configure a database on the fly, by
              telling the type of database, and optionally passing field:value
              settings, inside curly braces after the type. Spaces are used to
              separate fields, so you cannot specify a field value  containing
              whitespace.

       Thus, this uses the fallbackdb in debconf.conf:
         DEBCONF_DB_FALLBACK=fallbackdb

       While this sets up a new database of type File, and tells it a filename
       to use and turns off backups:
         DEBCONF_DB_FALLBACK=File{Filename:/root/config.dat Backup:no}

       And as a shorthand, this sets  up  a  database  of  type  File  with  a
       filename:
         DEBCONF_DB_FALLBACK=File{/root/config.dat}

       Note that if a fallback database is set up on the fly, it will be read-
       only by default.

       DEBCONF_DB_OVERRIDE
              Stack a database before the normally used databases, so that  it
              can  override  values from them. The value of the variable works
              the same as does the value of DEBCONF_DB_FALLBACK.

       DEBCONF_DB_REPLACE
              Use a given database instead of  the  normally  used  databases.
              This  may be useful for testing with a separate database without
              having to create a separate debconf.conf, or  to  avoid  locking
              the normal databases.

       DEBCONF_SYSTEMRC
              If  this  environment  variable  is  set,  debconf will ignore a
              user’s ~/.debconfrc file, and use the system one instead.  If it
              is set to the name of a regular file, debconf will use that file
              in preference to the system configuration files.

       DEBCONF_FORCE_DIALOG
              If this environment variable is set, debconf will use dialog  in
              preference to whiptail for the dialog frontend.

       DEBCONF_FORCE_XDIALOG
              If this environment variable is set, debconf will use Xdialog in
              preference to whiptail for the dialog frontend.

       DEBCONF_NONINTERACTIVE_SEEN
              Set to "true" to cause the seen flag to  be  set  for  questions
              asked in the noninteractive frontend.

BUGS

       Probably quite a few, there’s a lot of code here.

       If  you  do  file  a  bug  report,  be  sure  to  include the following
       information:

       *      The debconf frontend you were using when the problem occurred

       *      What you did to trigger the problem.

       *      The full text of any error messages. If you  can  reproduce  the
              bug, do so with DEBCONF_DEBUG=’.*’ set and exported. This speeds
              up debugging a lot.

SEE ALSO

       debconf.conf(5),    debconf-devel(7),    dpkg-preconfigure(8),    dpkg-
       reconfigure(8), debconf(1),

AUTHOR

       Joey Hess <joeyh@debian.org>

                                                                    DEBCONF(7)