Ubuntu Manpage: debconf.conf - debconf configuration file

Provided by: debconf-doc_1.5.51ubuntu2_all

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

AUTHOR

       Joey Hess <joeyh@debian.org>

                                                                                                 DEBCONF.CONF(5)

NAME

DESCRIPTION

SYNOPSIS

FILE FORMAT

DRIVERS

ACCESS CONTROLS

FORMATS

EXAMPLE

NOTES

PLANNED ENHANCEMENTS

FILES

SEE ALSO

AUTHOR