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