1DEBCONF-DEVEL(7) Miscellaneous Information Manual DEBCONF-DEVEL(7)
2
6 debconf - developers guide
7
9 This is a guide for developing packages that use debconf.
10 This manual assumes that you are familiar with debconf as a user, and
12 are familiar with the basics of debian package construction.
13 This manual begins by explaining two new files that are added to debian
15 packages that use debconf. Then it explains how the debconf protocol
16 works, and points you at some libraries that will let your programs
17 speak the protocol. It discusses other maintainer scripts that debconf
18 is typically used in: the postinst and postrm scripts. Then moves on to
19 more advanced topics like shared debconf templates, debugging, and some
20 common techniques and pitfalls of programming with debconf. It closes
21 with a discussion of debconf's current shortcomings.
22
24 Debconf adds an additional maintainer script, the config script, to the
25 set of maintainer scripts that can be in debian packages (the postinst,
26 preinst, postrm, and prerm). The config script is responsible for ask‐
27 ing any questions necessary to configure the package.
28 Note: It is a little confusing that dpkg refers to running a package's
30 postinst script as "configuring" the package, since a package that uses
31 debconf is often fully pre-configured, by its config script, before the
32 postinst ever runs. Oh well.
33 Like the postinst, the config script is passed two parameters when it
35 is run. The first tells what action is being performed, and the second
36 is the version of the package that is currently installed. So, like in
37 a postinst, you can use dpkg --compare-versions on $2 to make some
38 behavior happen only on upgrade from a particular version of a package,
39 and things like that.
40 The config script can be run in one of three ways:
42 1 If a package is pre-configured, with dpkg-preconfigure, its con‐
44 fig script is run, and is passed the parameters "configure", and
45 installed-version.
46 2 When a package's postinst is run, debconf will try to run the
48 config script then too, and it will be passed the same parame‐
49 ters it was passed when it is pre-configured. This is necessary
50 because the package might not have been pre-configured, and the
51 config script still needs to get a chance to run. See HACKS for
52 details.
53 3 If a package is reconfigured, with dpkg-reconfigure, its config
55 script it run, and is passed the parameters "reconfigure" and
56 installed-version.
57 Note that since a typical package install or upgrade using apt runs
59 steps 1 and 2, the config script will typically be run twice. It should
60 do nothing the second time (to ask questions twice in a row is annoy‐
61 ing), and it should definitely be idempotent. Luckily, debconf avoids
62 repeating questions by default, so this is generally easy to accom‐
63 plish.
64 Note that the config script is run before the package is unpacked. It
66 should only use commands that are in essential packages. The only
67 dependency of your package that is guaranteed to be met when its config
68 script is run is a dependency (possibly versioned) on debconf itself.
69 The config script should not need to modify the filesystem at all. It
71 just examines the state of the system, and asks questions, and debconf
72 stores the answers to be acted on later by the postinst script. Con‐
73 versely, the postinst script should almost never use debconf to ask
74 questions, but should instead act on the answers to questions asked by
75 the config script.
76
78 A package that uses debconf probably wants to ask some questions. These
79 questions are stored, in template form, in the templates file.
80 Like the config script, the templates file is put in the control.tar.gz
82 section of a deb. Its format is similar to a debian control file; a set
83 of stanzas separated by blank lines, with each stanza having a
84 RFC822-like form:
85 Template: foo/bar
87 Type: string
88 Default: foo
89 Description: This is a sample string question.
90 This is its extended description.
91 .
92 Notice that:
93 - Like in a debian package description, a dot
94 on its own line sets off a new paragraph.
95 - Most text is word-wrapped, but doubly-indented
96 text is left alone, so you can use it for lists
97 of items, like this list. Be careful, since
98 it is not word-wrapped, if it's too wide
99 it will look bad. Using it for short items
100 is best (so this is a bad example).
101 Template: foo/baz
103 Type: boolean
104 Description: Clear enough, no?
105 This is another question, of boolean type.
106 For some real-life examples of templates files, see
108 /var/lib/dpkg/info/debconf.templates, and other .templates files in
109 that directory.
110 Let's look at each of the fields in turn..
112 Template
114 The name of the template, in the 'Template' field, is generally
115 prefixed with the name of the package. After that the namespace
116 is wide open; you can use a simple flat layout like the one
117 above, or set up "subdirectories" containing related questions.
118 Type The type of the template determines what kind of widget is dis‐
120 played to the user. The currently supported types are:
121 string Results in a free-form input field that the user can type
123 any string into.
124 password
126 Prompts the user for a password. Use this with caution;
127 be aware that the password the user enters will be writ‐
128 ten to debconf's database. You should probably clean that
129 value out of the database as soon as is possible.
130 boolean
132 A true/false choice.
133 select A choice between one of a number of values. The choices
135 must be specified in a field named 'Choices'. Separate
136 the possible values with commas and spaces, like this:
137 Choices: yes, no, maybe
138 multiselect
140 Like the select data type, except the user can choose any
141 number of items from the choices list (or choose none of
142 them).
143 note Rather than being a question per se, this datatype indi‐
145 cates a note that can be displayed to the user. It should
146 be used only for important notes that the user really
147 should see, since debconf will go to great pains to make
148 sure the user sees it; halting the install for them to
149 press a key. It's best to use these only for warning
150 about very serious problems, and the error datatype is
151 often more suitable.
152 error This datatype is used for error messages, such as input
154 validation errors. Debconf will show a question of this
155 type even if the priority is too high or the user has
156 already seen it.
157 title This datatype is used for titles, to be set with the SET‐
159 TITLE command.
160 text This datatype can be used for fragments of text, such as
162 labels, that can be used for cosmetic reasons in the dis‐
163 plays of some frontends. Other frontends will not use it
164 at all. There is no point in using this datatype yet,
165 since no frontends support it well. It may even be
166 removed in the future.
167 Default
169 The 'Default' field tells debconf what the default value should
170 be. For multiselect, it can be a list of choices, separated by
171 commas and spaces, similar to the 'Choices' field. For select,
172 it should be one of the choices. For boolean, it is "true" or
173 "false", while it can be anything for a string, and it is
174 ignored for passwords.
175 Don't make the mistake of thinking that the default field con‐
177 tains the "value" of the question, or that it can be used to
178 change the value of the question. It does not, and cannot, it
179 just provides a default value for the first time the question is
180 displayed. To provide a default that changes on the fly, you'd
181 have to use the SET command to change the value of a question.
182 Description
184 The 'Description' field, like the description of a Debian pack‐
185 age, has two parts: A short description and an extended descrip‐
186 tion. Note that some debconf frontends don't display the long
187 description, or might only display it if the user asks for help.
188 So the short description should be able to stand on its own.
189 If you can't think up a long description, then first, think some
191 more. Post to debian-devel. Ask for help. Take a writing class!
192 That extended description is important. If after all that you
193 still can't come up with anything, leave it blank. There is no
194 point in duplicating the short description.
195 Text in the extended description will be word-wrapped, unless it
197 is prefixed by additional whitespace (beyond the one required
198 space). You can break it up into separate paragraphs by putting
199 " ." on a line by itself between them.
200
202 A question is an instantiated template. By asking debconf to display a
203 question, your config script can interact with the user. When debconf
204 loads a templates file (this happens whenever a config or postinst
205 script is run), it automatically instantiates a question from each tem‐
206 plate. It is actually possible to instantiate several independent ques‐
207 tions from the same template (using the REGISTER command), but that is
208 rarely necessary. Templates are static data that comes from the tem‐
209 plates file, while questions are used to store dynamic data, like the
210 current value of the question, whether a user has seen a question, and
211 so on. Keep the distinction between a template and a question in mind,
212 but don't worry too much about it.
213
215 It's actually possible to have a template and a question that are
216 shared among a set of packages. All the packages have to provide an
217 identical copy of the template in their templates files. This can be
218 useful if a bunch of packages need to ask the same question, and you
219 only want to bother the user with it once. Shared templates are gener‐
220 ally put in the shared/ pseudo-directory in the debconf template names‐
221 pace.
222
224 Config scripts communicate with debconf using the debconf protocol.
225 This is a simple line-oriented protocol, similar to common internet
226 protocols such as SMTP. The config script sends debconf a command by
227 writing the command to standard output. Then it can read debconf's
228 reply from standard input.
229 Debconf's reply can be broken down into two parts: A numeric result
231 code (the first word of the reply), and an optional extended result
232 code (the remainder of the reply). The numeric code uses 0 to indicate
233 success, and other numbers to indicate various kinds of failure. For
234 full details, see the table in Debian policy's debconf specification
235 document.
236 The extended return code is generally free form and unspecified, so you
238 should generally ignore it, and should certainly not try to parse it in
239 a program to work out what debconf is doing. The exception is commands
240 like GET, that cause a value to be returned in the extended return
241 code.
242 Generally you'll want to use a language-specific library that handles
244 the nuts and bolts of setting up these connections to debconf and com‐
245 municating with it.
246 For now, here are the commands in the protocol. This is not the defini‐
248 tive definition, see Debian policy's debconf specification document for
249 that.
250 VERSION number
252 You generally don't need to use this command. It exchanges with
253 debconf the protocol version number that is being used. The cur‐
254 rent protocol version is 2.0, and versions in the 2.x series
255 will be backwards-compatible. You may specify the protocol ver‐
256 sion number you are speaking and debconf will return the version
257 of the protocol it speaks in the extended result code. If the
258 version you specify is too low, debconf will reply with numeric
259 code 30.
260 CAPB capabilities
262 You generally don't need to use this command. It exchanges with
263 debconf a list of supported capabilities (separated by spaces).
264 Capabilities that both you and debconf support will be used, and
265 debconf will reply with all the capabilities it supports.
266 If 'escape' is found among your capabilities, debconf will
268 expect commands you send it to have backslashes and newlines
269 escaped (as \\ and \n respectively) and will in turn escape
270 backslashes and newlines in its replies. This can be used, for
271 example, to substitute multi-line strings into templates, or to
272 get multi-line extended descriptions reliably using METAGET. In
273 this mode, you must escape input text yourself (you can use deb‐
274 conf-escape(1) to help with this if you want), but the confmod‐
275 ule libraries will unescape replies for you.
276 SETTITLE question
278 This sets the title debconf displays to the user, using the
279 short description of the template for the specified question.
280 The template should be of type title. You rarely need to use
281 this command since debconf can automatically generate a title
282 based on your package's name.
283 Setting the title from a template means they are stored in the
285 same place as the rest of the debconf questions, and allows them
286 to be translated.
287 TITLE string
289 This sets the title debconf displays to the user to the speci‐
290 fied string. Use of the SETTITLE command is normally to be pre‐
291 ferred as it allows for translation of the title.
292 INPUT priority question
294 Ask debconf to prepare to display a question to the user. The
295 question is not actually displayed until a GO command is issued;
296 this lets several INPUT commands be given in series, to build up
297 a set of questions, which might all be asked on a single screen.
298 The priority field tells debconf how important it is that this
300 question be shown to the user. The priority values are:
301 low Very trivial items that have defaults that will work in
303 the vast majority of cases; only control freaks see
304 these.
305 medium Normal items that have reasonable defaults.
307 high Items that don't have a reasonable default.
309 critical
311 Items that will probably break the system without user
312 intervention.
313 Debconf decides if the question is actually displayed, based on
315 its priority, and whether the user has seen it before, and which
316 frontend is being used. If the question will not be displayed,
317 debconf replies with code 30.
318 GO
320 Tells debconf to display the accumulated set of questions (from
321 INPUT commands) to the user.
322 If the backup capability is supported and the user indicates
324 they want to back up a step, debconf replies with code 30.
325 CLEAR Clears the accumulated set of questions (from INPUT commands)
327 without displaying them.
328 BEGINBLOCK
330 ENDBLOCK
332 Some debconf frontends can display a number of questions to the
333 user at once. Maybe in the future a frontend will even be able
334 to group these questions into blocks on screen. BEGINBLOCK and
335 ENDBLOCK can be placed around a set of INPUT commands to indi‐
336 cate blocks of questions (and blocks can even be nested). Since
337 no debconf frontend is so sophisticated yet, these commands are
338 ignored for now.
339 STOP This command tells debconf that you're done talking to it. Often
341 debconf can detect termination of your program and this command
342 is not necessary.
343 GET question
345 After using INPUT and GO to display a question, you can use this
346 command to get the value the user entered. The value is returned
347 in the extended result code.
348 SET question value
350 This sets the value of a question, and it can be used to over‐
351 ride the default value with something your program calculates on
352 the fly.
353 RESET question
355 This resets the question to its default value (as is specified
356 in the 'Default' field of its template).
357 SUBST question key value
359 Questions can have substitutions embedded in their 'Description'
360 and 'Choices' fields (use of substitutions in 'Choices' fields
361 is a bit of a hack though; a better mechanism will eventually be
362 developed). These substitutions look like "${key}". When the
363 question is displayed, the substitutions are replaced with their
364 values. This command can be used to set the value of a substitu‐
365 tion. This is useful if you need to display some message to the
366 user that you can't hard-code in the templates file.
367 Do not try to use SUBST to change the default value of a ques‐
369 tion; it won't work since there is a SET command explicitly for
370 that purpose.
371 FGET question flag
373 Questions can have flags associated with them. The flags can
374 have a value of "true" or "false". This command returns the
375 value of a flag.
376 FSET question flag value
378 This sets the value of a question's flag. The value must be
379 either "true" or "false".
380 One common flag is the "seen" flag. It is normally only set if a
382 user has already seen a question. Debconf usually only displays
383 questions to users if they have the seen flag set to "false" (or
384 if it is reconfiguring a package). Sometimes you want the user
385 to see a question again -- in these cases you can set the seen
386 flag to false to force debconf to redisplay it.
387 METAGET question field
389 This returns the value of any field of a question's associated
390 template (the Description, for example).
391 REGISTER template question
393 This creates a new question that is bound to a template. By
394 default each template has an associated question with the same
395 name. However, any number of questions can really be associated
396 with a template, and this lets you create more such questions.
397 UNREGISTER question
399 This removes a question from the database.
400 PURGE Call this in your postrm when your package is purged. It removes
402 all of your package's questions from debconf's database.
403 X_LOADTEMPLATEFILE /path/to/templates [owner]
405 This extension loads the specified template file into debconf's
406 database. The owner defaults to the package that is being con‐
407 figured with debconf.
408 Here is a simple example of the debconf protocol in action.
410 INPUT medium debconf/frontend
412 30 question skipped
413 FSET debconf/frontend seen false
414 0 false
415 INPUT high debconf/frontend
416 0 question will be asked
417 GO
418 [ Here debconf displays a question to the user. ]
419 0 ok
420 GET no/such/question
421 10 no/such/question doesn't exist
422 GET debconf/frontend
423 0 Dialog
424
426 Setting things up so you can talk to debconf, and speaking the debconf
427 protocol by hand is a little too much work, so some thin libraries
428 exist to relieve this minor drudgery.
429 For shell programming, there is the /usr/share/debconf/confmodule
431 library, which you can source at the top of a shell script, and talk to
432 debconf in a fairly natural way, using lower-case versions of the deb‐
433 conf protocol commands, that are prefixed with "db_" (ie, "db_input"
434 and "db_go"). For details, see confmodule(3)
435 .
436 Perl programmers can use the Debconf::Client::ConfModule(3pm) perl mod‐
438 ule, and python programmers can use the debconf python module.
439 The rest of this manual will use the /usr/share/debconf/confmodule
441 library in example shell scripts. Here is an example config script
442 using that library, that just asks a question:
443 #!/bin/sh
445 set -e
446 . /usr/share/debconf/confmodule
447 db_set mypackage/reboot-now false
448 db_input high mypackage/reboot-now || true
449 db_go || true
450 Notice the uses of "|| true" to prevent the script from dying if deb‐
452 conf decides it can't display a question, or the user tries to back up.
453 In those situations, debconf returns a non-zero exit code, and since
454 this shell script is set -e, an untrapped exit code would make it
455 abort.
456 And here is a corresponding postinst script, that uses the user's
458 answer to the question to see if the system should be rebooted (a
459 rather absurd example..):
460 #!/bin/sh
462 set -e
463 . /usr/share/debconf/confmodule
464 db_get mypackage/reboot-now
465 if [ "$RET" = true ]; then
466 shutdown -r now
467 fi
468 Notice the use of the $RET variable to get at the extended return code
470 from the GET command, which holds the user's answer to the question.
471
473 The last section had an example of a postinst script that uses debconf
474 to get the value of a question, and act on it. Here are some things to
475 keep in mind when writing postinst scripts that use debconf:
476 * Avoid asking questions in the postinst. Instead, the config
478 script should ask questions using debconf, so that pre-configu‐
479 ration will work.
480 * Always source /usr/share/debconf/confmodule at the top of your
482 postinst, even if you won't be running any db_* commands in it.
483 This is required to make sure the config script gets a chance to
484 run (see HACKS for details).
485 * Avoid outputting anything to stdout in your postinst, since that
487 can confuse debconf, and postinst should not be verbose anyway.
488 Output to stderr is ok, if you must.
489 * If your postinst launches a daemon, make sure you tell debconf
491 to STOP at the end, since debconf can become a little confused
492 about when your postinst is done otherwise.
493 * Make your postinst script accept a first parameter of "reconfig‐
495 ure". It can treat it just like "configure". This will be used
496 in a later version of debconf to let postinsts know when they
497 are reconfigured.
498
500 Besides the config script and postinst, you can use debconf in any of
501 the other maintainer scripts. Most commonly, you'll be using debconf in
502 your postrm, to call the PURGE command when your package is purged, to
503 clean out its entries in the debconf database. (This is automatically
504 set up for you by dh_installdebconf(1), by the way.)
505 A more involved use of debconf would be if you want to use it in the
507 postrm when your package is purged, to ask a question about deleting
508 something. Or maybe you find you need to use it in the preinst or prerm
509 for some reason. All of these uses will work, though they'll probably
510 involve asking questions and acting on the answers in the same program,
511 rather than separating the two activities as is done in the config and
512 postinst scripts.
513 Note that if your package's sole use of debconf is in the postrm, you
515 should make your package's postinst source /usr/share/debconf/confmod‐
516 ule, to give debconf a chance to load up your templates file into its
517 database. Then the templates will be available when your package is
518 being purged.
519 You can also use debconf in other, standalone programs. The issue to
521 watch out for here is that debconf is not intended to be, and must not
522 be used as a registry. This is unix after all, and programs are config‐
523 ured by files in /etc, not by some nebulous debconf database (that is
524 only a cache anyway and might get blown away). So think long and hard
525 before using debconf in a standalone program.
526 There are times when it can make sense, as in the apt-setup program
528 which uses debconf to prompt the user in a manner consistent with the
529 rest of the debian install process, and immediately acts on their
530 answers to set up apt's sources.list.
531
533 Debconf supports localization of templates files. This is accomplished
534 by adding more fields, with translated text in them. Any of the fields
535 can be translated. For example, you might want to translate the
536 description into Spanish. Just make a field named 'Description-es' that
537 holds the translation. If a translated field is not available, debconf
538 falls back to the normal English field.
539 Besides the 'Description' field, you should translate the 'Choices'
541 field of a select or multiselect template. Be sure to list the trans‐
542 lated choices in the same order as they appear in the main 'Choices'
543 field. You do not need to translate the 'Default' field of a select or
544 multiselect question, and the value of the question will be automati‐
545 cally returned in English.
546 You will find it easier to manage translations if you keep them in sep‐
548 arate files; one file per translation. In the past, the debconf-get‐
549 lang(1) and debconf-mergetemplate(1) programs were used to manage
550 debian/template.ll files. This has been superseded by the po-debconf(7)
551 package, which lets you deal with debconf translations in .po files,
552 just like any other translations. Your translators will thank you for
553 using this new improved mechanism.
554 For the details on po-debconf, see its man page. If you're using deb‐
556 helper, converting to po-debconf is as simple as running the debconf-
557 gettextize(1) command once, and adding a Build-Dependency on po-debconf
558 and on debhelper (>= 4.1.13).
559
561 So you have a config script, a templates file, a postinst script that
562 uses debconf, and so on. Putting these pieces together into a debian
563 package isn't hard. You can do it by hand, or can use dh_installdeb‐
564 conf(1) which will merge your translated templates, copy the files into
565 the right places for you, and can even generate the call to PURGE that
566 should go in your postrm script. Make sure that your package depends on
567 debconf (>= 0.5), since earlier versions were not compatible with
568 everything described in this manual. And you're done.
569 Well, except for testing, debugging, and actually using debconf for
571 more interesting things than asking a few basic questions. For that,
572 read on..
573
575 So you have a package that's supposed to use debconf, but it doesn't
576 quite work. Maybe debconf is just not asking that question you set up.
577 Or maybe something weirder is happening; it spins forever in some kind
578 of loop, or worse. Luckily, debconf has plenty of debugging facilities.
579 DEBCONF_DEBUG
581 The first thing to reach for is the DEBCONF_DEBUG environment
582 variable. If you set and export DEBCONF_DEBUG=developer, deb‐
583 conf will output to stderr a dump of the debconf protocol as
584 your program runs. It'll look something like this -- the typo is
585 made clear:
586 debconf (developer): <-- input high debconf/frontand
588 debconf (developer): --> 10 "debconf/frontand" doesn't exist
589 debconf (developer): <-- go
590 debconf (developer): --> 0 ok
591 It's rather useful to use debconf's readline frontend when
593 you're debugging (in the author's opinion), as the questions
594 don't get in the way, and all the debugging output is easily
595 preserved and logged.
596 DEBCONF_C_VALUES
598 If this environment variable is set to 'true', the frontend will
599 display the values in Choices-C fields (if present) of select
600 and multiselect templates rather than the descriptive values.
601 debconf-communicate
603 Another useful tool is the debconf-communicate(1) program. Fire
604 it up and you can speak the raw debconf protocol to debconf,
605 interactively. This is a great way to try stuff out on the fly.
606 debconf-show
608 If a user is reporting a problem, debconf-show(1) can be used to
609 dump out all the questions owned by your package, displaying
610 their values and whether the user has seen them.
611 .debconfrc
613 To avoid the often tedious build/install/debug cycle, it can be
614 useful to load up your templates with debconf-loadtemplate(1)
615 and run your config script by hand with the debconf(1) command.
616 However, you still have to do that as root, right? Not so good.
617 And ideally you'd like to be able to see what a fresh installa‐
618 tion of your package looks like, with a clean debconf database.
619 It turns out that if you set up a ~/.debconfrc file for a normal
621 user, pointing at a personal config.dat and template.dat for the
622 user, you can load up templates and run config scripts all you
623 like, without any root access. If you want to start over with a
624 clean database, just blow away the *.dat files.
625 For details about setting this up, see debconf.conf(5), and note
627 that /etc/debconf.conf makes a good template for a personal
628 ~/.debconfrc file.
629
631 Config file handling
632 Many of you seem to want to use debconf to help manage config files
633 that are part of your package. Perhaps there is no good default to ship
634 in a conffile, and so you want to use debconf to prompt the user, and
635 write out a config file based on their answers. That seems easy enough
636 to do, but then you consider upgrades, and what to do when someone mod‐
637 ifies the config file you generate, and dpkg-reconfigure, and ...
638 There are a lot of ways to do this, and most of them are wrong, and
640 will often earn you annoyed bug reports. Here is one right way to do
641 it. It assumes that your config file is really just a series of shell
642 variables being set, with comments in between, and so you can just
643 source the file to "load" it. If you have a more complicated format,
644 reading (and writing) it becomes a bit trickier.
645 Your config script will look something like this:
647 #!/bin/sh
649 CONFIGFILE=/etc/foo.conf
650 set -e
651 . /usr/share/debconf/confmodule
652 # Load config file, if it exists.
654 if [ -e $CONFIGFILE ]; then
655 . $CONFIGFILE || true
656 # Store values from config file into
658 # debconf db.
659 db_set mypackage/foo "$FOO"
660 db_set mypackage/bar "$BAR"
661 fi
662 # Ask questions.
664 db_input medium mypackage/foo || true
665 db_input medium mypackage/bar || true
666 db_go || true
667 And the postinst will look something like this:
669 #!/bin/sh
671 CONFIGFILE=/etc/foo.conf
672 set -e
673 . /usr/share/debconf/confmodule
674 # Generate config file, if it doesn't exist.
676 # An alternative is to copy in a template
677 # file from elsewhere.
678 if [ ! -e $CONFIGFILE ]; then
679 echo "# Config file for my package" > $CONFIGFILE
680 echo "FOO=" >> $CONFIGFILE
681 echo "BAR=" >> $CONFIGFILE
682 fi
683 # Substitute in the values from the debconf db.
685 # There are obvious optimizations possible here.
686 # The cp before the sed ensures we do not mess up
687 # the config file's ownership and permissions.
688 db_get mypackage/foo
689 FOO="$RET"
690 db_get mypackage/bar
691 BAR="$RET"
692 cp -a -f $CONFIGFILE $CONFIGFILE.tmp
693 # If the admin deleted or commented some variables but then set
695 # them via debconf, (re-)add them to the conffile.
696 test -z "$FOO" || grep -Eq '^ *FOO=' $CONFIGFILE || \
697 echo "FOO=" >> $CONFIGFILE
698 test -z "$BAR" || grep -Eq '^ *BAR=' $CONFIGFILE || \
699 echo "BAR=" >> $CONFIGFILE
700 sed -e "s/^ *FOO=.*/FOO=\"$FOO\"/" \
702 -e "s/^ *BAR=.*/BAR=\"$BAR\"/" \
703 < $CONFIGFILE > $CONFIGFILE.tmp
704 mv -f $CONFIGFILE.tmp $CONFIGFILE
705 Consider how these two scripts handle all the cases. On fresh installs
707 the questions are asked by the config script, and a new config file
708 generated by the postinst. On upgrades and reconfigures, the config
709 file is read in, and the values in it are used to change the values in
710 the debconf database, so the admin's manual changes are not lost. The
711 questions are asked again (and may or may not be displayed). Then the
712 postinst substitutes the values back into the config file, leaving the
713 rest of it unchanged.
714 Letting the user back up
716 Few things are more frustrating when using a system like debconf than
717 being asked a question, and answering it, then moving on to another
718 screen with a new question on it, and realizing that hey, you made a
719 mistake, with that last question, and you want to go back to it, and
720 discovering that you can't.
721 Since debconf is driven by your config script, it can't jump back to a
723 previous question on its own but with a little help from you, it can
724 accomplish this feat. The first step is to make your config script let
725 debconf know it is capable of handling the user pressing a back button.
726 You use the CAPB command to do this, passing backup as a parameter.
727 Then after each GO command, you must test to see if the user asked to
729 back up (debconf returns a code of 30), and if so jump back to the pre‐
730 vious question.
731 There are several ways to write the control structures of your program
733 so it can jump back to previous questions when necessary. You can write
734 goto-laden spaghetti code. Or you can create several functions and use
735 recursion. But perhaps the cleanest and easiest way is to construct a
736 state machine. Here is a skeleton of a state machine that you can fill
737 out and expand.
738 #!/bin/sh
740 set -e
741 . /usr/share/debconf/confmodule
742 db_capb backup
743 STATE=1
745 while true; do
746 case "$STATE" in
747 1)
748 # Two unrelated questions.
749 db_input medium my/question || true
750 db_input medium my/other_question || true
751 ;;
752 2)
753 # Only ask this question if the
754 # first question was answered in
755 # the affirmative.
756 db_get my/question
757 if [ "$RET" = "true" ]; then
758 db_input medium my/dep_question || true
759 fi
760 ;;
761 *)
762 # The default case catches when $STATE is greater than the
763 # last implemented state, and breaks out of the loop. This
764 # requires that states be numbered consecutively from 1
765 # with no gaps, as the default case will also be entered
766 # if there is a break in the numbering
767 break # exits the enclosing "while" loop
768 ;;
769 esac
770 if db_go; then
772 STATE=$(($STATE + 1))
773 else
774 STATE=$(($STATE - 1))
775 fi
776 done
777 if [ $STATE -eq 0 ]; then
779 # The user has asked to back up from the first
780 # question. This case is problematical. Regular
781 # dpkg and apt package installation isn't capable
782 # of backing up questions between packages as this
783 # is written, so this will exit leaving the package
784 # unconfigured - probably the best way to handle
785 # the situation.
786 exit 10
787 fi
788 Note that if all your config script does is ask a few unrelated ques‐
790 tions, then there is no need for the state machine. Just ask them all,
791 and GO; debconf will do its best to present them all in one screen, and
792 the user won't need to back up.
793 Preventing infinite loops
795 One gotcha with debconf comes up if you have a loop in your config
796 script. Suppose you're asking for input and validating it, and looping
797 if it's not valid:
798 ok=''
800 do while [ ! "$ok" ];
801 db_input low foo/bar || true
802 db_go || true
803 db_get foo/bar
804 if [ "$RET" ]; then
805 ok=1
806 fi
807 done
808 This looks ok at first glance. But consider what happens if the value
810 of foo/bar is "" when this loop is entered, and the user has their pri‐
811 ority set high, or is using a non-interactive frontend, and so they are
812 not really asked for input. The value of foo/bar is not changed by the
813 db_input, and so it fails the test and loops. And loops ...
814 One fix for this is to make sure that before the loop is entered, the
816 value of foo/bar is set to something that will pass the test in the
817 loop. So for example if the default value of foo/bar is "1", then you
818 could RESET foo/bar just before entering the loop.
819 Another fix is to check the return code of the INPUT command. If it is
821 30 then the user is not being shown the question you asked them, and
822 you should break out of the loop.
823 Choosing among related packages
825 Sometimes a set of related packages can be installed, and you want to
826 prompt the user which of the set should be used by default. Examples of
827 such sets are window managers, or ispell dictionary files.
828 While it would be possible for each package in the set to simply
830 prompt, "Should this package be default?", this leads to a lot of
831 repetitive questions if several of the packages are installed. It's
832 possible with debconf to present a list of all the packages in the set
833 and allow the user to choose between them. Here's how.
834 Make all the packages in the set use a shared template. Something like
836 this:
837 Template: shared/window-manager
839 Type: select
840 Choices: ${choices}
841 Description: Select the default window manager.
842 Select the window manager that will be started by
843 default when X starts.
844 Each package should include a copy of the template. Then it should
846 include some code like this in its config script:
847 db_metaget shared/window-manager owners
849 OWNERS=$RET
850 db_metaget shared/window-manager choices
851 CHOICES=$RET
852 if [ "$OWNERS" != "$CHOICES" ]; then
854 db_subst shared/window-manager choices $OWNERS
855 db_fset shared/window-manager seen false
856 fi
857 db_input medium shared/window-manager || true
859 db_go || true
860 A bit of an explanation is called for. By the time your config script
862 runs, debconf has already read in all the templates for the packages
863 that are being installed. Since the set of packages share a question,
864 debconf records that fact in the owners field. By a strange coinci‐
865 dence, the format of the owners field is the same as that of the
866 choices field (a comma and space delimited list of values).
867 The METAGET command can be used to get the list of owners and the list
869 of choices. If they are different, then a new package has been
870 installed. So use the SUBST command to change the list of choices to be
871 the same as the list of owners, and ask the question.
872 When a package is removed, you probably want to see if that package is
874 the currently selected choice, and if so, prompt the user to select a
875 different package to replace it.
876 This can be accomplished by adding something like this to the prerm
878 scripts of all related packages (replacing <package> with the package
879 name):
880 if [ -e /usr/share/debconf/confmodule ]; then
882 . /usr/share/debconf/confmodule
883 # I no longer claim this question.
884 db_unregister shared/window-manager
885 # See if the shared question still exists.
887 if db_get shared/window-manager; then
888 db_metaget shared/window-manager owners
889 db_subst shared/window-manager choices $RET
890 db_metaget shared/window-manager value
891 if [ "<package>" = "$RET" ] ; then
892 db_fset shared/window-manager seen false
893 db_input high shared/window-manager || true
894 db_go || true
895 fi
896 # Now do whatever the postinst script did
898 # to update the window manager symlink.
899 fi
900 fi
901
903 Debconf is currently not fully integrated into dpkg (but I want to
904 change this in the future), and so some messy hacks are currently
905 called for.
906 The worst of these involves getting the config script to run. The way
908 that works now is the config script will be run when the package is
909 pre-configured. Then, when the postinst script runs, it starts up deb‐
910 conf again. Debconf notices it is being used by the postinst script,
911 and so it goes off and runs the config script. This can only work if
912 your postinst loads up one of the debconf libraries though, so postin‐
913 sts always have to take care to do that. We hope to address this later
914 by adding explicit support to dpkg for debconf. The debconf(1) program
915 is a step in this direction.
916 A related hack is getting debconf running when a config script,
918 postinst, or other program that uses it starts up. After all, they
919 expect to be able to talk to debconf right away. The way this is accom‐
920 plished for now is that when such a script loads a debconf library
921 (like /usr/share/debconf/confmodule), and debconf is not already run‐
922 ning, it is started up, and a new copy of the script is re-execed. The
923 only noticeable result is that you need to put the line that loads a
924 debconf library at the very top of the script, or weird things will
925 happen. We hope to address this later by changing how debconf is
926 invoked, and turning it into something more like a transient daemon.
927 It's rather hackish how debconf figures out what templates files to
929 load, and when it loads them. When the config, preinst, and postinst
930 scripts invoke debconf, it will automatically figure out where the tem‐
931 plates file is, and load it. Standalone programs that use debconf will
932 cause debconf to look for templates files in /usr/share/debconf/tem‐
933 plates/progname.templates. And if a postrm wants to use debconf at
934 purge time, the templates won't be available unless debconf had a
935 chance to load them in its postinst. This is messy, but rather unavoid‐
936 able. In the future some of these programs may be able to use debconf-
937 loadtemplate by hand though.
938 /usr/share/debconf/confmodule's historic behavior of playing with file
940 descriptors and setting up a fd #3 that talks to debconf, can cause all
941 sorts of trouble when a postinst runs a daemon, since the daemon ends
942 up talking to debconf, and debconf can't figure out when the script
943 terminates. The STOP command can work around this. In the future, we
944 are considering making debconf communication happen over a socket or
945 some other mechanism than stdio.
946 Debconf sets DEBCONF_RECONFIGURE=1 before running postinst scripts, so
948 a postinst script that needs to avoid some expensive operation when
949 reconfigured can look at that variable. This is a hack because the
950 right thing would be to pass $1 = "reconfigure", but doing so without
951 breaking all the postinsts that use debconf is difficult. The migration
952 plan away from this hack is to encourage people to write postinsts that
953 accept "reconfigure", and once they all do, begin passing that parame‐
954 ter.
955
957 debconf(7) is the debconf user's guide.
958 The debconf specification in debian policy is the canonical definition
960 of the debconf protocol. /usr/share/doc/debian-policy/debconf_specifi‐
961 cation.txt.gz
962 debconf.conf(5) has much useful information, including some info about
964 the backend database.
965
967 Joey Hess <joeyh@debian.org>
968 DEBCONF-DEVEL(7)