Provided by: debconf-doc_1.5.26ubuntu3_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)