Debian Codegraph @

doc/man/debconf-devel.7

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