| 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]> |