Debian Codegraph @

doc/man/debconf.conf.5

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