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

       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)