Provided by: debconf-doc_1.5.51ubuntu2_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 does not support prompting with  default
              values.  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 might mail error  messages  to  root,
              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 preseed 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 the 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)