Provided by: debconf-doc_1.4.72ubuntu9_all bug

NAME

       debconf.conf - debconf configuration file

DESCRIPTION

       Debconf    is    a    configuration   system   for   Debian   packages.
       /etc/debconf.conf and ~/.debconfrc are configuration files debconf uses
       to  determine  which  databases it should use. These databases are used
       for storing two types of information;  dynamic  config  data  the  user
       enters  into  it,  and static template data. Debconf offers a flexible,
       extensible database backend. New drivers can be created with a  minimum
       of effort, and sets of drivers can be combined in various ways.

SYNOPSIS

         # This is a sample config file that is
         # sufficient to use debconf.
         Config: configdb
         Templates: templatedb

         Name: configdb
         Driver: File
         Filename: /var/cache/debconf/config.dat

         Name: templatedb
         Driver: File
         Mode: 644
         Filename: /var/cache/debconf/templates.dat

FILE FORMAT

       The  format  of  this file is a series of stanzas, each separated by at
       least one wholly  blank  line.  Comment  lines  beginning  with  a  "#"
       character are ignored.

       The  first  stanza of the file is special, is used to configure debconf
       as a whole. Two fields are required to be in this first stanza:

              Config Specifies the name of the database  from  which  to  load
                     config data.

              Templates
                     Specifies  the  name  of  the  database  to  use  for the
                     template cache.

       Additional fields that can be used include:

              Frontend
                     The frontend Debconf should use, overriding any  frontend
                     set in the debconf database.

              Priority
                     The  priority Debconf should use, overriding any priority
                     set in the debconf database.

              Admin-Email
                     The email address Debconf should send mail to if it needs
                     to  make  sure that the admin has seen an important note.
                     Defaults to "root", but can be set  to  any  valid  email
                     address  to  send  the mail there. If you prefer to never
                     have debconf send you mail, specify a blank address. This
                     can be overridden on the fly with the DEBCONF_ADMIN_EMAIL
                     environment variable.

              Debug  If set, this  will  cause  debconf  to  output  debugging
                     information to standard error. The value it is set to can
                     be something like "user", "developer", "db", or a regular
                     expression. Typically, rather than setting it permanently
                     in a config file, you will only want to temporarily  turn
                     on  debugging, and the DEBCONF_DEBUG environment variable
                     can be set instead to accomplish that.

              NoWarnings
                     If set, this will make debconf not display warnings about
                     various  things.   This can be overridden on the fly with
                     the DEBCONF_NOWARNINGS environment variable.

              Log    Makes debconf log debugging information as  it  runs,  to
                     the  syslog.  The  value  it  is  set to controls that is
                     logged. See Debug, above for an explanation of the values
                     that can be set to control what is logged.

              Terse  If  set  to  "true",  makes  some debconf frontends use a
                     special terse display mode  that  outputs  as  little  as
                     possible.   Defaults   to   false.   Terse  mode  may  be
                     temporarily  set  via   the   DEBCONF_TERSE   environment
                     variable.

       For example, the first stanza of a file might look like this:
         Config: configdb
         Templates: templatedb

       Each remaining stanza in the file sets up a database. A database stanza
       begins by naming the database:
         Name: configdb

       Then it  indicates  what  database  driver  should  be  used  for  this
       database.   See  DRIVERS, below, for information about what drivers are
       available.
         Driver: File

       You can indicate that the database  is  not  essential  to  the  proper
       functioning  of  debconf  by  saying it is not required. This will make
       debconf muddle on if the database fails for some reason.
         Required: false

       You can mark any database  as  readonly  and  debconf  will  not  write
       anything to it.
         Readonly: true

       You  can  also  limit  what types of data can go into the database with
       Accept- and Reject- lines; see ACCESS CONTROLS, below.

       The remainder of each database stanza is used to provide  configuration
       specific  to  that driver. For example, the Text driver needs to know a
       directory to put the database in, so you might say:
         Filename: /var/cache/debconf/config.dat

DRIVERS

       A number of drivers are available, and more can be written with  little
       difficulty.  Drivers  come  in  two general types. First there are real
       drivers -- drivers that actually access and store data in some kind  of
       database,  which  might  be  on  the  local  filesystem, or on a remote
       system. Then there are meta-drivers that combine other drivers together
       to form more interesting systems. Let’s start with the former.

       File
              This  database  driver  allows  debconf  to store a whole
              database in a single flat text file. This makes  it  easy
              to  archive,  transfer  between machines, and edit. It is
              one of the more compact database formats in terms of disk
              space used. It is also one of the slowest.

              On  the  downside, the entire file has to be read in each
              time debconf starts up, and saving it is also slow.

              The following things are configurable for this driver.

                     Filename
                             The file to use as the database. This is a
                             required field.

                      Mode   The permissions to create the file with if
                             it does not exist. Defaults to 600,  since
                             the  file  could contain passwords in some
                             circumstances.

                      Format The format of the file. See FORMATS below.
                             Defaults to using a rfc-822 like format.

                      Backup Whether a backup should be made of the old
                             file  before  changing  it.   Defaults  to
                             true.

              As  example  stanza  setting  up  a  database  using this
              driver:

                Name: mydb
                Driver: File
                Filename: /var/cache/debconf/mydb.dat

       DirTree
              This database driver allows debconf to store  data  in  a
              hierarchical   directory  structure.  The  names  of  the
              various debconf templates and questions are used as-is to
              form  directories with files in them. This format for the
              database is the easiest to  browse  and  fiddle  with  by
              hand.   It  has  very  good load and save speeds. It also
              typically occupies the most space, since a lot  of  small
              files and subdirectories do take up some additional room.

              The following things are configurable for this driver.

                     Directory
                             The  directory  to  put  the   files   in.
                             Required.

                     Extension
                             An extension to add to the names of files.
                             Must  be  set  to  a   non-empty   string;
                             defaults to ".dat"

                      Format The format of the file. See FORMATS below.
                             Defaults to using a rfc-822 like format.

                      Backup Whether a backup should be made of the old
                             file  before  changing  it.   Defaults  to
                             true.

              As example  stanza  setting  up  a  database  using  this
              driver:

                Name: mydb
                Driver: DirTree
                Directory: /var/cache/debconf/mydb
                Extension: .txt

       PackageDir
              This database driver is a compromise between the File and
              DirTree databases. It uses a directory, in which there is
              (approximately)  one  file per package that uses debconf.
              This is fairly fast, while using little  more  room  than
              the File database driver.

              This  driver  is  configurable in the same ways as is the
              DirTree driver, plus:

              Mode   The permissions to create files with. Defaults  to
                     600,  since  the  files could contain passwords in
                     some circumstances.

              As example  stanza  setting  up  a  database  using  this
              driver:

                Name: mydb
                Driver: PackageDir
                Directory: /var/cache/debconf/mydb

       LDAP
              WARNING:  This database driver is currently experimental.
              Use with caution.

              This  database  driver  accesses  a  LDAP  directory  for
              debconf  configuration  data.Due  to  the  nature  of the
              beast, LDAP directories should typically be  accessed  in
              read-only  mode.   This  is because multiple accesses can
              take  place,  and  it’s   generally   better   for   data
              consistency if nobody tries to modify the data while this
              is happening.  Of course, write access is  supported  for
              those  cases  where you do want to update the config data
              in the directory.

              For information  about  setting  up  a  LDAP  server  for
              debconf,    read   /usr/share/doc/debconf-doc/README.LDAP
              (from the debconf-doc package).

              To use this database driver, you must  have  the  libnet-
              ldap-perl   package   installed.  Debconf  suggests  that
              package, but does not depend on it.

              Please carefully consider the  security  implications  of
              using  a  remote  debconf  database. Unless you trust the
              source, and you trust the intervening network, it is  not
              a very safe thing to do.

              The following things are configurable for this driver.

                      server The  host  name  or  IP address of an LDAP
                             server to connect to.

                      port   The port on which to connect to  the  LDAP
                             server.   If  none  is  given, the default
                             port is used.

                      basedn The DN under which all config  items  will
                             be  stored.   Each  config  item  will  be
                             assumed  to  live  in  a  DN  of  cn=<item
                             name>,<Base DN>.  If this structure is not
                             followed, all bets are off.

                      binddn The  DN  to  bind  to  the  directory  as.
                             Anonymous  bind  will  be  used if none is
                             specified.

                     bindpasswd
                             The password to use  in  an  authenticated
                             bind  (used  with  binddn, above).  If not
                             specified, anonymous bind will be used.

                             This option should  not  be  used  in  the
                             general case.  Anonymous binding should be
                             sufficient most of the time for  read-only
                             access.  Specifying a bind DN and password
                             should be reserved for the occasional case
                             where  you  wish  to  update  the  debconf
                             configuration data.

              An example  stanza  setting  up  a  database  using  this
              driver,  assuming  the  remote database is on example.com
              and can be accessed anonymously:

                Name: ldapdb
                Driver: LDAP
                Readonly: true
                Server: example.com
                BaseDN: cn=debconf,dc=example,dc=com

              Another example,  this  time  the  LDAP  database  is  on
              localhost, and can be written to:

                Name: ldapdb
                Driver: LDAP
                Server: localhost
                BaseDN: cn=debconf,dc=domain,dc=com
                BindPasswd: secret

       Pipe
              This special-purpose database driver reads and writes the
              database from standard input/output. It may be useful for
              people with special needs.

              The following things are configurable for this driver.

                      Format The  format to read and write. See FORMATS
                             below. Defaults to using  a  rfc-822  like
                             format.

                      Infd   File   descriptor  number  to  read  from.
                             Defaults to reading from stdin. If set  to
                             "none",  the  database  will  not read any
                             data on startup.

                      Outfd  File  descriptor  number  to   write   to.
                             Defaults  to  writing to stdout. If set to
                             "none", the database will be  thrown  away
                             on shutdown.

       That’s  all of the real drivers, now moving on to meta-drivers..

       Stack
              This driver stacks up a number of other databases (of any
              type),  and  allows  them  to  be  accessed  as one. When
              debconf asks for a value, the first database on the stack
              that  contains  the  value  returns it. If debconf writes
              something to the database, the write normally goes to the
              first  driver  on  the stack that has the item debconf is
              modifying, and if none do, the new item is added  to  the
              first writable database on the stack.

              Things become more interesting if one of the databases on
              the stack is readonly. Consider a stack of the  databases
              foo,  bar,  and baz, where foo and baz are both readonly.
              Debconf wants to change an item, and this  item  is  only
              present  in  baz,  which is readonly. The stack driver is
              smart enough to realize that won’t work, and it will copy
              the  item  from baz to bar, and the write will take place
              in bar. Now the item in baz is shadowed by  the  item  in
              bar, and it will not longer be visible to debconf.

              This  kind of thing is particularly useful if you want to
              point many systems at a central, readonly database, while
              still  allowing  things  to be overridden on each system.
              When access controls are added  to  the  picture,  stacks
              allow  you  to  do  many  other  interesting things, like
              redirect all passwords to one database while  a  database
              underneath it handles everything else.

              Only  one  piece  of  configuration is needed to set up a
              stack:

                      Stack  This is where you specify a list of  other
                             databases,  by name, to tell it what makes
                             up the stack.

              For example:

                Name: megadb
                Driver: stack
                Stack: passworddb, configdb, companydb

              WARNING: The stack driver is not very  well  tested  yet.
              Use at your own risk.

       Backup
              This  driver  passes  all requests on to another database
              driver. But it also copies all write requests to a backup
              database driver.

              You  must  specify  the  following  fields to set up this
              driver:

                      Db     The database to read from and write to.

                     Backupdb
                             The name of the database to send copies of
                             writes to.

              For example:

                Name: backup
                Driver: Backup
                Db: mydb
                Backupdb: mybackupdb

       Debug
              This  driver  passes  all requests on to another database
              driver, outputting verbose  debugging  output  about  the
              request and the result.

              You  must  specify  the  following  fields to set up this
              driver:

                      Db     The database to read from and write to.

ACCESS CONTROLS

       When you set up a database, you can  also  use  some  fields  to
       specify  access  controls.  You can specify that a database only
       accepts passwords, for example, or make a database  only  accept
       things with "foo" in their name.

       Readonly
              As  was mentioned earlier, this access control, if set to
              "true", makes a  database  readonly.  Debconf  will  read
              values from it, but will never write anything to it.

       Accept-Name
              The  text  in  this  field  is  a perl-compatible regular
              expression that is matched against the names of items  as
              they  are  requested  from the database. Only if an items
              name matches the regular expression,  will  the  database
              allow debconf to access or modify it.

       Reject-Name
              Like  Accept-Name,  except  any  item  name matching this
              regular expression will be rejected.

       Accept-Type
              Another regular expression, this matches against the type
              of  the  item  that  is  being accessed. Only if the type
              matches the regex will access be granted.

       Reject-Type
              Like Accept-Type, except any type matching  this  regular
              expression will be rejected.

FORMATS

       Some  of  the database drivers use format modules to control the
       actual format in which the database is  stored  on  disk.  These
       formats are currently supported:

       822    This  is  a  file  format  loosely based upon the rfc-822
              format for email message  headers.  Similar  formats  are
              used  throughout  Debian; in the dpkg status file, and so
              on.

EXAMPLE

       Here is a more complicated example of a debconf.conf file.

         # This stanza is used for general debconf setup.
         Config: stack
         Templates: templates
         Log: developer
         Debug: developer

         # This is my own local database.
         Name: mydb
         Driver: DirTree
         Directory: /var/cache/debconf/config

         # This is another database that I use to hold
         # only X server configuration.
         Name: X
         Driver: File
         Filename: /etc/X11/debconf.dat
         Mode: 644
         # It’s sorta hard to work out what questions
         # belong to X; it should be using a deeper
         # tree structure so I could just match on ^X/
         # Oh well.
         Accept-Name: xserver|xfree86|xbase

         # This is our company’s global, read-only
         # (for me!) debconf database.
         Name: company
         Driver: LDAP
         Server: debconf.foo.com
         BaseDN: cn=debconf,dc=foo,dc=com
         BindDN: uid=admin,dc=foo,dc=com
         BindPasswd: secret
         Readonly: true
         # I don’t want any passwords that might be
         # floating around in there.
         Reject-Type: password
         # If this db is not accessible for whatever
         # reason, carry on anyway.
         Required: false

         # I use this database to hold
         # passwords safe and secure.
         Name: passwords
         Driver: File
         Filename: /etc/debconf/passwords
         Mode: 600
         Accept-Type: password

         # Let’s put them all together
         # in a database stack.
         Name: stack
         Driver: Stack
         Stack: passwords, X, mydb, company
         # So, all passwords go to the password database.
         # Most X configuration stuff goes to the X
         # database, and anything else goes to my main
         # database. Values are looked up in each of those
         # in turn, and if none has a particular value, it
         # is looked up in the company-wide LDAP database
         # (unless it’s a password).

         # A database is also used to hold templates. We
         # don’t need to make this as fancy.
         Name: templates
         Driver: File
         Mode: 644
         Format: 822
         Filename: /var/cache/debconf/templates

NOTES

       If you use something like ${HOME}  in  this  file,  it  will  be
       replaced with the value of the named environment variable.

       Environment variables can also be used to override the databases
       on the fly, see debconf(7)

       The field names (the part of the line before the colon) is case-
       insensitive. The values, though, are case sensitive.

PLANNED ENHANCEMENTS

       More drivers and formats. Some ideas include: A SQL driver, with
       the capability to access a remote database.  A DHCP driver, that
       makes  available  some special things like hostname, IP address,
       and DNS servers.  A driver that pulls values out of  public  DNS
       records TXT fields.  A format that is compatible with the output
       of cdebconf.  An override driver, which can override  the  value
       field or flags of all requests that pass through it.

FILES

       /etc/debconf.conf

       ~/.debconfrc

SEE ALSO

       debconf(7)

AUTHOR

       Joey Hess <joeyh@debian.org>

                                                               DEBCONF.CONF(5)