Provided by: debconf-doc_1.5.42ubuntu1_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 message. 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.

                     keybykey
                            Enable access to individual LDAP entries, instead  of  fetching  them
                            all  at  once  in  the  beginning. This is very useful if you want to
                            monitor your LDAP logs for specific debconf keys requested.  In  this
                            way,  you  could  also  write custom handling code on the LDAP server
                            part.

                            Note that when this option is enabled, the  connection  to  the  LDAP
                            server  is kept active during the whole Debconf run. This is a little
                            different from the all-in-one behavior where  two  brief  connections
                            are  made  to LDAP; in the beginning to retrieve all the entries, and
                            in the end to save eventual changes.

              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
                KeyByKey: 0

              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
                KeyByKey: 1

       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)