DEBCONF.CONF(5) File Formats Manual DEBCONF.CONF(5)
NAME
debconf.conf - debconf configuration file
DESCRIPTION
Debconf is a configuration system for Debian packages. /etc/deb-
conf.conf and ~/.debconfrc are configuration files debconf uses to de-
termine 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, extensi-
ble database backend. New drivers can be created with a minimum of ef-
fort, 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 "#" charac-
ter 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 tem-
plate 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 mes-
sage. 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 ad-
dress. This can be overridden on the fly with the DEB-
CONF_ADMIN_EMAIL environment variable.
Debug If set, this will cause debconf to output debugging in-
formation 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 spe-
cial terse display mode that outputs as little as possi-
ble. 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 data-
base. See DRIVERS, below, for information about what drivers are
available.
Driver: File
You can indicate that the database is not essential to the proper func-
tioning 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 any-
thing to it.
Readonly: true
You can also limit what types of data can go into the database with Ac-
cept- 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 sys-
tem. 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 data-
base 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 de-
bconf 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 re-
quired 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. De-
faults 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 hierar-
chical 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. De-
faults 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 (ap-
proximately) 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 circum-
stances.
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 con-
figuration data. Due to the nature of the beast, LDAP directo-
ries should typically be accessed in read-only mode. This is be-
cause multiple accesses can take place, and it's generally bet-
ter 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 deb-
conf 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 connec-
tion 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 connec-
tions are made to LDAP; in the beginning to re-
trieve all the entries, and in the end to save
eventual changes.
An example stanza setting up a database using this driver, as-
suming 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 data-
base 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 allow-
ing things to be overridden on each system. When access controls
are added to the picture, stacks allow you to do many other in-
teresting 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 data-
bases, 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 ac-
cess 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 ex-
pression, will the database allow debconf to access or modify
it.
Reject-Name
Like Accept-Name, except any item name matching this regular ex-
pression 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 expres-
sion 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 cur-
rently supported:
822 This is a file format loosely based upon the rfc-822 format for
email message headers. Similar formats are used throughout De-
bian; 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-insen-
sitive. 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 re-
quests that pass through it.
FILES
/etc/debconf.conf
~/.debconfrc
SEE ALSO
debconf(7)
AUTHOR
Joey Hess <joeyh@debian.org>
DEBCONF.CONF(5)
Generated by dwww version 1.14 on Sun Jan 12 03:16:51 CET 2025.