DEBCONF.CONF(5)

💖 NAME 💖

okay so bestie, this is DEBCONF.CONF(5) — yep, the File Formats Manual one — and it's literally all about debconf.conf, the debconf configuration file. ✨

🌸 DESCRIPTION 🌸

Debconf is a configuration system for Debian packages. /etc/debconf.conf and ~/.debconfrc are configuration files debconf uses to figure out which databases it should use. These databases store two types of info: dynamic config data the user enters into it, and static template data. Debconf offers a flexible, extensible database backend, no cap. 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 — turns on access to individual LDAP entries one at a time instead of pulling the whole lot down at the start. This is genuinely so useful if you wanna keep an eye on your LDAP logs for specific debconf keys being requested — and it also means you could write your own custom handling code on the LDAP server side. 🎀

Heads up bestie: when this is enabled, the connection to the LDAP server stays active for the entire Debconf run. That's a lil different from the all-in-one behaviour, where two short connections get made to LDAP — one at the beginning to grab all the entries, and one at the end to save whatever changed. 💅

So here's an example stanza setting up a database with this driver, assuming the remote database lives 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

And another one, this time the LDAP database is on localhost and you can actually write to it:

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

🌈 Pipe

This is a special-purpose database driver that reads and writes the database straight from standard input/output. Lowkey made for people with special needs, and honestly? Iconic of it. ✨

Here's what you can configure for this driver:

• Format — the format to read and write. See FORMATS below. Defaults to using a rfc-822 like format.
• Infd — the file descriptor number to read from. Defaults to reading from stdin. If you set it to "none", the database won't read any data on startup.
• Outfd — the file descriptor number to write to. Defaults to writing to stdout. If you set it to "none", the database gets thrown away on shutdown. 💀

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

👑 Stack

This driver stacks up a bunch of other databases (of any type) and lets you access them all as if they were one. When debconf asks for a value, the first database on the stack that has the value returns it. If debconf writes something, the write normally goes to the first driver on the stack that has the item debconf is modifying — and if none of them do, the new item gets added to the first writable database on the stack.

Things get more interesting when one of the databases on the stack is readonly. Picture a stack of the databases foo, bar and baz, where foo and baz are both readonly. Debconf wants to change an item, and that item only exists in baz, which is readonly. The stack driver is smart enough to realise that won't work, so it copies the item from baz to bar, and the write happens in bar. Now the item in baz is shadowed by the item in bar, and it's no longer visible to debconf. Periodt. 💅

This kind of thing is particularly useful if you want to point a whole bunch of systems at one central, readonly database while still letting things be overridden on each individual system. And once access controls enter the picture, stacks let you do so many other interesting things — like redirecting 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. Two birds, one vibe. 🫶

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, and outputs verbose debugging output about the request and the result. It's giving "tell me everything." 😭

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 say a database only accepts passwords, for example, or make a database only accept things with "foo" in their name. Gatekeeping, but make it config. 💅

• 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 gets matched against the names of items as they're requested from the database. Only if an item's 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 one matches against the type of the item 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 all throughout Debian; in the dpkg status file, and so on.

---

🌸 EXAMPLE

Here is a more complicated example of a debconf.conf file. Buckle up bestie, it's a long one. 🦋

# 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. Don't mix those two up, iykyk. 🙈

---

🔮 PLANNED ENHANCEMENTS

More drivers and formats, coming to a future near you. 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. Manifesting all of these fr fr. ⭐

---

📂 FILES

• /etc/debconf.conf
• ~/.debconfrc

---

👀 SEE ALSO

• debconf(7)

---

💖 AUTHOR

Joey Hess <joeyh@debian.org>

---

And that's a wrap on the DEBCONF.CONF(5) page — shoutout to the source it came from and its date stamp at the bottom of the original. Go forth and configure your databases, bestie, you're gonna slay. 💅✨🎀