1DEBCONF.CONF(5) File Formats Manual DEBCONF.CONF(5)
2
6 debconf.conf - debconf configuration file
7
9 Debconf is a configuration system for Debian packages. /etc/deb‐
10 conf.conf and ~/.debconfrc are configuration files debconf uses to
11 determine which databases it should use. These databases are used for
12 storing two types of information; dynamic config data the user enters
13 into it, and static template data. Debconf offers a flexible, extensi‐
14 ble database backend. New drivers can be created with a minimum of
15 effort, and sets of drivers can be combined in various ways.
16
18 # This is a sample config file that is
19 # sufficient to use debconf.
20 Config: configdb
21 Templates: templatedb
22 Name: configdb
24 Driver: File
25 Filename: /var/cache/debconf/config.dat
26 Name: templatedb
28 Driver: File
29 Mode: 644
30 Filename: /var/cache/debconf/templates.dat
31
33 The format of this file is a series of stanzas, each separated by at
34 least one wholly blank line. Comment lines beginning with a "#" charac‐
35 ter are ignored.
36 The first stanza of the file is special, is used to configure debconf
38 as a whole. Two fields are required to be in this first stanza:
39 Config Specifies the name of the database from which to load
41 config data.
42 Templates
44 Specifies the name of the database to use for the tem‐
45 plate cache.
46 Additional fields that can be used include:
48 Frontend
50 The frontend Debconf should use, overriding any frontend
51 set in the debconf database.
52 Priority
54 The priority Debconf should use, overriding any priority
55 set in the debconf database.
56 Admin-Email
58 The email address Debconf should send mail to if it needs
59 to make sure that the admin has seen an important mes‐
60 sage. Defaults to "root", but can be set to any valid
61 email address to send the mail there. If you prefer to
62 never have debconf send you mail, specify a blank
63 address. This can be overridden on the fly with the DEB‐
64 CONF_ADMIN_EMAIL environment variable.
65 Debug If set, this will cause debconf to output debugging
67 information to standard error. The value it is set to can
68 be something like "user", "developer", "db", or a regular
69 expression. Typically, rather than setting it permanently
70 in a config file, you will only want to temporarily turn
71 on debugging, and the DEBCONF_DEBUG environment variable
72 can be set instead to accomplish that.
73 NoWarnings
75 If set, this will make debconf not display warnings about
76 various things. This can be overridden on the fly with
77 the DEBCONF_NOWARNINGS environment variable.
78 Log Makes debconf log debugging information as it runs, to
80 the syslog. The value it is set to controls that is
81 logged. See Debug, above for an explanation of the values
82 that can be set to control what is logged.
83 Terse If set to "true", makes some debconf frontends use a spe‐
85 cial terse display mode that outputs as little as possi‐
86 ble. Defaults to false. Terse mode may be temporarily set
87 via the DEBCONF_TERSE environment variable.
88 For example, the first stanza of a file might look like this:
90 Config: configdb
91 Templates: templatedb
92 Each remaining stanza in the file sets up a database. A database stanza
94 begins by naming the database:
95 Name: configdb
96 Then it indicates what database driver should be used for this data‐
98 base. See DRIVERS, below, for information about what drivers are
99 available.
100 Driver: File
101 You can indicate that the database is not essential to the proper func‐
103 tioning of debconf by saying it is not required. This will make debconf
104 muddle on if the database fails for some reason.
105 Required: false
106 You can mark any database as readonly and debconf will not write any‐
108 thing to it.
109 Readonly: true
110 You can also limit what types of data can go into the database with
112 Accept- and Reject- lines; see ACCESS CONTROLS, below.
113 The remainder of each database stanza is used to provide configuration
115 specific to that driver. For example, the Text driver needs to know a
116 directory to put the database in, so you might say:
117 Filename: /var/cache/debconf/config.dat
118
120 A number of drivers are available, and more can be written with little
121 difficulty. Drivers come in two general types. First there are real
122 drivers -- drivers that actually access and store data in some kind of
123 database, which might be on the local filesystem, or on a remote sys‐
124 tem. Then there are meta-drivers that combine other drivers together to
125 form more interesting systems. Let's start with the former.
126 File
129 This database driver allows debconf to store a whole
130 database in a single flat text file. This makes it easy
131 to archive, transfer between machines, and edit. It is
132 one of the more compact database formats in terms of disk
133 space used. It is also one of the slowest.
134 On the downside, the entire file has to be read in each
136 time debconf starts up, and saving it is also slow.
137 The following things are configurable for this driver.
139 Filename
141 The file to use as the database. This is a
142 required field.
143 Mode The permissions to create the file with if
145 it does not exist. Defaults to 600, since
146 the file could contain passwords in some
147 circumstances.
148 Format The format of the file. See FORMATS below.
150 Defaults to using a rfc-822 like format.
151 Backup Whether a backup should be made of the old
153 file before changing it. Defaults to true.
154 As example stanza setting up a database using this
156 driver:
157 Name: mydb
159 Driver: File
160 Filename: /var/cache/debconf/mydb.dat
161 DirTree
163 This database driver allows debconf to store data in a
164 hierarchical directory structure. The names of the vari‐
165 ous debconf templates and questions are used as-is to
166 form directories with files in them. This format for the
167 database is the easiest to browse and fiddle with by
168 hand. It has very good load and save speeds. It also
169 typically occupies the most space, since a lot of small
170 files and subdirectories do take up some additional room.
171 The following things are configurable for this driver.
173 Directory
175 The directory to put the files in.
176 Required.
177 Extension
179 An extension to add to the names of files.
180 Must be set to a non-empty string; defaults
181 to ".dat"
182 Format The format of the file. See FORMATS below.
184 Defaults to using a rfc-822 like format.
185 Backup Whether a backup should be made of the old
187 file before changing it. Defaults to true.
188 As example stanza setting up a database using this
190 driver:
191 Name: mydb
193 Driver: DirTree
194 Directory: /var/cache/debconf/mydb
195 Extension: .txt
196 PackageDir
198 This database driver is a compromise between the File and
199 DirTree databases. It uses a directory, in which there is
200 (approximately) one file per package that uses debconf.
201 This is fairly fast, while using little more room than
202 the File database driver.
203 This driver is configurable in the same ways as is the
205 DirTree driver, plus:
206 Mode The permissions to create files with. Defaults to
208 600, since the files could contain passwords in
209 some circumstances.
210 As example stanza setting up a database using this
212 driver:
213 Name: mydb
215 Driver: PackageDir
216 Directory: /var/cache/debconf/mydb
217 LDAP
219 WARNING: This database driver is currently experimental.
220 Use with caution.
221 This database driver accesses a LDAP directory for deb‐
223 conf configuration data. Due to the nature of the beast,
224 LDAP directories should typically be accessed in read-
225 only mode. This is because multiple accesses can take
226 place, and it's generally better for data consistency if
227 nobody tries to modify the data while this is happening.
228 Of course, write access is supported for those cases
229 where you do want to update the config data in the direc‐
230 tory.
231 For information about setting up a LDAP server for deb‐
233 conf, read /usr/share/doc/debconf-doc/README.LDAP (from
234 the debconf-doc package).
235 To use this database driver, you must have the libnet-
237 ldap-perl package installed. Debconf suggests that pack‐
238 age, but does not depend on it.
239 Please carefully consider the security implications of
241 using a remote debconf database. Unless you trust the
242 source, and you trust the intervening network, it is not
243 a very safe thing to do.
244 The following things are configurable for this driver.
246 server The host name or IP address of an LDAP
248 server to connect to.
249 port The port on which to connect to the LDAP
251 server. If none is given, the default port
252 is used.
253 basedn The DN under which all config items will be
255 stored. Each config item will be assumed to
256 live in a DN of cn=<item name>,<Base DN>.
257 If this structure is not followed, all bets
258 are off.
259 binddn The DN to bind to the directory as. Anony‐
261 mous bind will be used if none is speci‐
262 fied.
263 bindpasswd
265 The password to use in an authenticated
266 bind (used with binddn, above). If not
267 specified, anonymous bind will be used.
268 This option should not be used in the gen‐
270 eral case. Anonymous binding should be suf‐
271 ficient most of the time for read-only
272 access. Specifying a bind DN and password
273 should be reserved for the occasional case
274 where you wish to update the debconf con‐
275 figuration data.
276 keybykey
278 Enable access to individual LDAP entries,
279 instead of fetching them all at once in the
280 beginning. This is very useful if you want
281 to monitor your LDAP logs for specific deb‐
282 conf keys requested. In this way, you could
283 also write custom handling code on the LDAP
284 server part.
285 Note that when this option is enabled, the
287 connection to the LDAP server is kept
288 active during the whole Debconf run. This
289 is a little different from the all-in-one
290 behavior where two brief connections are
291 made to LDAP; in the beginning to retrieve
292 all the entries, and in the end to save
293 eventual changes.
294 An example stanza setting up a database using this
296 driver, assuming the remote database is on example.com
297 and can be accessed anonymously:
298 Name: ldapdb
300 Driver: LDAP
301 Readonly: true
302 Server: example.com
303 BaseDN: cn=debconf,dc=example,dc=com
304 KeyByKey: 0
305 Another example, this time the LDAP database is on local‐
307 host, and can be written to:
308 Name: ldapdb
310 Driver: LDAP
311 Server: localhost
312 BaseDN: cn=debconf,dc=domain,dc=com
313 BindPasswd: secret
314 KeyByKey: 1
315 Pipe
317 This special-purpose database driver reads and writes the
318 database from standard input/output. It may be useful for
319 people with special needs.
320 The following things are configurable for this driver.
322 Format The format to read and write. See FORMATS
324 below. Defaults to using a rfc-822 like
325 format.
326 Infd File descriptor number to read from.
328 Defaults to reading from stdin. If set to
329 "none", the database will not read any data
330 on startup.
331 Outfd File descriptor number to write to.
333 Defaults to writing to stdout. If set to
334 "none", the database will be thrown away on
335 shutdown.
336 That's all of the real drivers, now moving on to meta-drivers..
338 Stack
340 This driver stacks up a number of other databases (of any
341 type), and allows them to be accessed as one. When deb‐
342 conf asks for a value, the first database on the stack
343 that contains the value returns it. If debconf writes
344 something to the database, the write normally goes to the
345 first driver on the stack that has the item debconf is
346 modifying, and if none do, the new item is added to the
347 first writable database on the stack.
348 Things become more interesting if one of the databases on
350 the stack is readonly. Consider a stack of the databases
351 foo, bar, and baz, where foo and baz are both readonly.
352 Debconf wants to change an item, and this item is only
353 present in baz, which is readonly. The stack driver is
354 smart enough to realize that won't work, and it will copy
355 the item from baz to bar, and the write will take place
356 in bar. Now the item in baz is shadowed by the item in
357 bar, and it will not longer be visible to debconf.
358 This kind of thing is particularly useful if you want to
360 point many systems at a central, readonly database, while
361 still allowing things to be overridden on each system.
362 When access controls are added to the picture, stacks
363 allow you to do many other interesting things, like redi‐
364 rect all passwords to one database while a database
365 underneath it handles everything else.
366 Only one piece of configuration is needed to set up a
368 stack:
369 Stack This is where you specify a list of other
371 databases, by name, to tell it what makes
372 up the stack.
373 For example:
375 Name: megadb
377 Driver: stack
378 Stack: passworddb, configdb, companydb
379 WARNING: The stack driver is not very well tested yet.
381 Use at your own risk.
382 Backup
384 This driver passes all requests on to another database
385 driver. But it also copies all write requests to a backup
386 database driver.
387 You must specify the following fields to set up this
389 driver:
390 Db The database to read from and write to.
392 Backupdb
394 The name of the database to send copies of
395 writes to.
396 For example:
398 Name: backup
400 Driver: Backup
401 Db: mydb
402 Backupdb: mybackupdb
403 Debug
405 This driver passes all requests on to another database
406 driver, outputting verbose debugging output about the
407 request and the result.
408 You must specify the following fields to set up this
410 driver:
411 Db The database to read from and write to.
413
415 When you set up a database, you can also use some fields to
416 specify access controls. You can specify that a database only
417 accepts passwords, for example, or make a database only accept
418 things with "foo" in their name.
419 Readonly
421 As was mentioned earlier, this access control, if set to
422 "true", makes a database readonly. Debconf will read val‐
423 ues from it, but will never write anything to it.
424 Accept-Name
426 The text in this field is a perl-compatible regular
427 expression that is matched against the names of items as
428 they are requested from the database. Only if an items
429 name matches the regular expression, will the database
430 allow debconf to access or modify it.
431 Reject-Name
433 Like Accept-Name, except any item name matching this reg‐
434 ular expression will be rejected.
435 Accept-Type
437 Another regular expression, this matches against the type
438 of the item that is being accessed. Only if the type
439 matches the regex will access be granted.
440 Reject-Type
442 Like Accept-Type, except any type matching this regular
443 expression will be rejected.
444
446 Some of the database drivers use format modules to control the
447 actual format in which the database is stored on disk. These
448 formats are currently supported:
449 822 This is a file format loosely based upon the rfc-822 for‐
451 mat for email message headers. Similar formats are used
452 throughout Debian; in the dpkg status file, and so on.
453
455 Here is a more complicated example of a debconf.conf file.
456 # This stanza is used for general debconf setup.
458 Config: stack
459 Templates: templates
460 Log: developer
461 Debug: developer
462 # This is my own local database.
464 Name: mydb
465 Driver: DirTree
466 Directory: /var/cache/debconf/config
467 # This is another database that I use to hold
469 # only X server configuration.
470 Name: X
471 Driver: File
472 Filename: /etc/X11/debconf.dat
473 Mode: 644
474 # It's sorta hard to work out what questions
475 # belong to X; it should be using a deeper
476 # tree structure so I could just match on ^X/
477 # Oh well.
478 Accept-Name: xserver|xfree86|xbase
479 # This is our company's global, read-only
481 # (for me!) debconf database.
482 Name: company
483 Driver: LDAP
484 Server: debconf.foo.com
485 BaseDN: cn=debconf,dc=foo,dc=com
486 BindDN: uid=admin,dc=foo,dc=com
487 BindPasswd: secret
488 Readonly: true
489 # I don't want any passwords that might be
490 # floating around in there.
491 Reject-Type: password
492 # If this db is not accessible for whatever
493 # reason, carry on anyway.
494 Required: false
495 # I use this database to hold
497 # passwords safe and secure.
498 Name: passwords
499 Driver: File
500 Filename: /etc/debconf/passwords
501 Mode: 600
502 Accept-Type: password
503 # Let's put them all together
505 # in a database stack.
506 Name: stack
507 Driver: Stack
508 Stack: passwords, X, mydb, company
509 # So, all passwords go to the password database.
510 # Most X configuration stuff goes to the X
511 # database, and anything else goes to my main
512 # database. Values are looked up in each of those
513 # in turn, and if none has a particular value, it
514 # is looked up in the company-wide LDAP database
515 # (unless it's a password).
516 # A database is also used to hold templates. We
518 # don't need to make this as fancy.
519 Name: templates
520 Driver: File
521 Mode: 644
522 Format: 822
523 Filename: /var/cache/debconf/templates
524
526 If you use something like ${HOME} in this file, it will be
527 replaced with the value of the named environment variable.
528 Environment variables can also be used to override the databases
530 on the fly, see debconf(7)
531 The field names (the part of the line before the colon) is case-
533 insensitive. The values, though, are case sensitive.
534
536 More drivers and formats. Some ideas include: A SQL driver, with
537 the capability to access a remote database. A DHCP driver, that
538 makes available some special things like hostname, IP address,
539 and DNS servers. A driver that pulls values out of public DNS
540 records TXT fields. A format that is compatible with the output
541 of cdebconf. An override driver, which can override the value
542 field or flags of all requests that pass through it.
543
545 /etc/debconf.conf
546 ~/.debconfrc
548
550 debconf(7)
551
553 Joey Hess <joeyh@debian.org>
554 DEBCONF.CONF(5)