1DEBCONF-DEVEL(7)       Miscellaneous Information Manual       DEBCONF-DEVEL(7)
2
3
4

NAME

6       debconf - developers guide
7

DESCRIPTION

9       This is a guide for developing packages that use debconf.
10
11       This  manual  assumes that you are familiar with debconf as a user, and
12       are familiar with the basics of debian package construction.
13
14       This manual begins by explaining two new files that are added to debian
15       packages  that  use  debconf. Then it explains how the debconf protocol
16       works, and points you at some libraries that  will  let  your  programs
17       speak  the protocol. It discusses other maintainer scripts that debconf
18       is typically used in: the postinst and postrm scripts. Then moves on to
19       more advanced topics like shared debconf templates, debugging, and some
20       common techniques and pitfalls of programming with debconf.  It  closes
21       with a discussion of debconf's current shortcomings.
22

THE CONFIG SCRIPT

24       Debconf adds an additional maintainer script, the config script, to the
25       set of maintainer scripts that can be in debian packages (the postinst,
26       preinst,  postrm, and prerm). The config script is responsible for ask‐
27       ing any questions necessary to configure the package.
28
29       Note: It is a little confusing that dpkg refers to running a  package's
30       postinst script as "configuring" the package, since a package that uses
31       debconf is often fully pre-configured, by its config script, before the
32       postinst ever runs. Oh well.
33
34       Like  the  postinst, the config script is passed two parameters when it
35       is run. The first tells what action is being performed, and the  second
36       is  the version of the package that is currently installed. So, like in
37       a postinst, you can use dpkg --compare-versions  on  $2  to  make  some
38       behavior happen only on upgrade from a particular version of a package,
39       and things like that.
40
41       The config script can be run in one of three ways:
42
43       1      If a package is pre-configured, with dpkg-preconfigure, its con‐
44              fig script is run, and is passed the parameters "configure", and
45              installed-version.
46
47       2      When a package's postinst is run, debconf will try  to  run  the
48              config  script  then too, and it will be passed the same parame‐
49              ters it was passed when it is pre-configured. This is  necessary
50              because  the package might not have been pre-configured, and the
51              config script still needs to get a chance to run. See HACKS  for
52              details.
53
54       3      If  a package is reconfigured, with dpkg-reconfigure, its config
55              script it run, and is passed the  parameters  "reconfigure"  and
56              installed-version.
57
58       Note  that  since  a  typical package install or upgrade using apt runs
59       steps 1 and 2, the config script will typically be run twice. It should
60       do  nothing  the second time (to ask questions twice in a row is annoy‐
61       ing), and it should definitely be idempotent. Luckily,  debconf  avoids
62       repeating  questions  by  default,  so this is generally easy to accom‐
63       plish.
64
65       Note that the config script is run before the package is  unpacked.  It
66       should  only  use  commands  that  are  in essential packages. The only
67       dependency of your package that is guaranteed to be met when its config
68       script is run is a dependency (possibly versioned) on debconf itself.
69
70       The  config  script should not need to modify the filesystem at all. It
71       just examines the state of the system, and asks questions, and  debconf
72       stores  the  answers  to be acted on later by the postinst script. Con‐
73       versely, the postinst script should almost never  use  debconf  to  ask
74       questions,  but should instead act on the answers to questions asked by
75       the config script.
76

THE TEMPLATES FILE

78       A package that uses debconf probably wants to ask some questions. These
79       questions are stored, in template form, in the templates file.
80
81       Like the config script, the templates file is put in the control.tar.gz
82       section of a deb. Its format is similar to a debian control file; a set
83       of  stanzas  separated  by  blank  lines,  with  each  stanza  having a
84       RFC822-like form:
85
86         Template: foo/bar
87         Type: string
88         Default: foo
89         Description: This is a sample string question.
90          This is its extended description.
91          .
92          Notice that:
93           - Like in a debian package description, a dot
94             on its own line sets off a new paragraph.
95           - Most text is word-wrapped, but doubly-indented
96             text is left alone, so you can use it for lists
97             of items, like this list. Be careful, since
98             it is not word-wrapped, if it's too wide
99             it will look bad. Using it for short items
100             is best (so this is a bad example).
101
102         Template: foo/baz
103         Type: boolean
104         Description: Clear enough, no?
105          This is another question, of boolean type.
106
107       For   some    real-life    examples    of    templates    files,    see
108       /var/lib/dpkg/info/debconf.templates,  and  other  .templates  files in
109       that directory.
110
111       Let's look at each of the fields in turn..
112
113       Template
114              The name of the template, in the 'Template' field, is  generally
115              prefixed  with the name of the package. After that the namespace
116              is wide open; you can use a simple  flat  layout  like  the  one
117              above, or set up "subdirectories" containing related questions.
118
119       Type   The  type of the template determines what kind of widget is dis‐
120              played to the user. The currently supported types are:
121
122              string Results in a free-form input field that the user can type
123                     any string into.
124
125              password
126                     Prompts  the  user for a password. Use this with caution;
127                     be aware that the password the user enters will be  writ‐
128                     ten to debconf's database. You should probably clean that
129                     value out of the database as soon as is possible.
130
131              boolean
132                     A true/false choice.
133
134              select A choice between one of a number of values.  The  choices
135                     must  be  specified  in a field named 'Choices'. Separate
136                     the possible values with commas and spaces, like this:
137                       Choices: yes, no, maybe
138
139              multiselect
140                     Like the select data type, except the user can choose any
141                     number  of items from the choices list (or choose none of
142                     them).
143
144              note   Rather than being a question per se, this datatype  indi‐
145                     cates a note that can be displayed to the user. It should
146                     be used only for important notes  that  the  user  really
147                     should  see, since debconf will go to great pains to make
148                     sure the user sees it; halting the install  for  them  to
149                     press  a  key.   It's  best to use these only for warning
150                     about very serious problems, and the  error  datatype  is
151                     often more suitable.
152
153              error  This  datatype  is used for error messages, such as input
154                     validation errors.  Debconf will show a question of  this
155                     type  even  if  the  priority is too high or the user has
156                     already seen it.
157
158              title  This datatype is used for titles, to be set with the SET‐
159                     TITLE command.
160
161              text   This  datatype can be used for fragments of text, such as
162                     labels, that can be used for cosmetic reasons in the dis‐
163                     plays  of some frontends. Other frontends will not use it
164                     at all. There is no point in  using  this  datatype  yet,
165                     since  no  frontends  support  it  well.  It  may even be
166                     removed in the future.
167
168       Default
169              The 'Default' field tells debconf what the default value  should
170              be.  For  multiselect, it can be a list of choices, separated by
171              commas and spaces, similar to the 'Choices' field.  For  select,
172              it  should  be  one of the choices. For boolean, it is "true" or
173              "false", while it can be  anything  for  a  string,  and  it  is
174              ignored for passwords.
175
176              Don't  make  the mistake of thinking that the default field con‐
177              tains the "value" of the question, or that it  can  be  used  to
178              change  the  value  of the question. It does not, and cannot, it
179              just provides a default value for the first time the question is
180              displayed.  To  provide a default that changes on the fly, you'd
181              have to use the SET command to change the value of a question.
182
183       Description
184              The 'Description' field, like the description of a Debian  pack‐
185              age, has two parts: A short description and an extended descrip‐
186              tion. Note that some debconf frontends don't  display  the  long
187              description, or might only display it if the user asks for help.
188              So the short description should be able to stand on its own.
189
190              If you can't think up a long description, then first, think some
191              more.  Post to debian-devel. Ask for help. Take a writing class!
192              That extended description is important. If after  all  that  you
193              still  can't  come up with anything, leave it blank. There is no
194              point in duplicating the short description.
195
196              Text in the extended description will be word-wrapped, unless it
197              is  prefixed  by  additional whitespace (beyond the one required
198              space). You can break it up into separate paragraphs by  putting
199              " ." on a line by itself between them.
200

QUESTIONS

202       A  question is an instantiated template. By asking debconf to display a
203       question, your config script can interact with the user.  When  debconf
204       loads  a  templates  file  (this  happens whenever a config or postinst
205       script is run), it automatically instantiates a question from each tem‐
206       plate. It is actually possible to instantiate several independent ques‐
207       tions from the same template (using the REGISTER command), but that  is
208       rarely  necessary.  Templates  are static data that comes from the tem‐
209       plates file, while questions are used to store dynamic data,  like  the
210       current  value of the question, whether a user has seen a question, and
211       so on. Keep the distinction between a template and a question in  mind,
212       but don't worry too much about it.
213

SHARED TEMPLATES

215       It's  actually  possible  to  have  a  template and a question that are
216       shared among a set of packages. All the packages  have  to  provide  an
217       identical  copy  of  the template in their templates files. This can be
218       useful if a bunch of packages need to ask the same  question,  and  you
219       only  want to bother the user with it once. Shared templates are gener‐
220       ally put in the shared/ pseudo-directory in the debconf template names‐
221       pace.
222

THE DEBCONF PROTOCOL

224       Config  scripts  communicate  with  debconf using the debconf protocol.
225       This is a simple line-oriented protocol,  similar  to  common  internet
226       protocols  such  as  SMTP. The config script sends debconf a command by
227       writing the command to standard output.  Then  it  can  read  debconf's
228       reply from standard input.
229
230       Debconf's  reply  can  be  broken down into two parts: A numeric result
231       code (the first word of the reply), and  an  optional  extended  result
232       code  (the remainder of the reply). The numeric code uses 0 to indicate
233       success, and other numbers to indicate various kinds  of  failure.  For
234       full  details,  see  the table in Debian policy's debconf specification
235       document.
236
237       The extended return code is generally free form and unspecified, so you
238       should generally ignore it, and should certainly not try to parse it in
239       a program to work out what debconf is doing. The exception is  commands
240       like  GET,  that  cause  a  value to be returned in the extended return
241       code.
242
243       Generally you'll want to use a language-specific library  that  handles
244       the  nuts and bolts of setting up these connections to debconf and com‐
245       municating with it.
246
247       For now, here are the commands in the protocol. This is not the defini‐
248       tive definition, see Debian policy's debconf specification document for
249       that.
250
251       VERSION number
252              You generally don't need to use this command. It exchanges  with
253              debconf the protocol version number that is being used. The cur‐
254              rent protocol version is 2.0, and versions  in  the  2.x  series
255              will  be backwards-compatible. You may specify the protocol ver‐
256              sion number you are speaking and debconf will return the version
257              of  the  protocol  it speaks in the extended result code. If the
258              version you specify is too low, debconf will reply with  numeric
259              code 30.
260
261       CAPB capabilities
262              You  generally don't need to use this command. It exchanges with
263              debconf a list of supported capabilities (separated by  spaces).
264              Capabilities that both you and debconf support will be used, and
265              debconf will reply with all the capabilities it supports.
266
267              If 'escape' is  found  among  your  capabilities,  debconf  will
268              expect  commands  you  send  it to have backslashes and newlines
269              escaped (as \\ and \n respectively)  and  will  in  turn  escape
270              backslashes  and  newlines in its replies. This can be used, for
271              example, to substitute multi-line strings into templates, or  to
272              get  multi-line extended descriptions reliably using METAGET. In
273              this mode, you must escape input text yourself (you can use deb‐
274              conf-escape(1)  to help with this if you want), but the confmod‐
275              ule libraries will unescape replies for you.
276
277       SETTITLE question
278              This sets the title debconf displays  to  the  user,  using  the
279              short  description  of  the template for the specified question.
280              The template should be of type title. You  rarely  need  to  use
281              this  command  since  debconf can automatically generate a title
282              based on your package's name.
283
284              Setting the title from a template means they are stored  in  the
285              same place as the rest of the debconf questions, and allows them
286              to be translated.
287
288       TITLE string
289              This sets the title debconf displays to the user to  the  speci‐
290              fied string.  Use of the SETTITLE command is normally to be pre‐
291              ferred as it allows for translation of the title.
292
293       INPUT priority question
294              Ask debconf to prepare to display a question to  the  user.  The
295              question is not actually displayed until a GO command is issued;
296              this lets several INPUT commands be given in series, to build up
297              a set of questions, which might all be asked on a single screen.
298
299              The  priority  field tells debconf how important it is that this
300              question be shown to the user. The priority values are:
301
302              low    Very trivial items that have defaults that will  work  in
303                     the  vast  majority  of  cases;  only  control freaks see
304                     these.
305
306              medium Normal items that have reasonable defaults.
307
308              high   Items that don't have a reasonable default.
309
310              critical
311                     Items that will probably break the  system  without  user
312                     intervention.
313
314              Debconf  decides if the question is actually displayed, based on
315              its priority, and whether the user has seen it before, and which
316              frontend  is  being used. If the question will not be displayed,
317              debconf replies with code 30.
318
319       GO
320              Tells debconf to display the accumulated set of questions  (from
321              INPUT commands) to the user.
322
323              If  the  backup  capability  is supported and the user indicates
324              they want to back up a step, debconf replies with code 30.
325
326       CLEAR  Clears the accumulated set of questions  (from  INPUT  commands)
327              without displaying them.
328
329       BEGINBLOCK
330
331       ENDBLOCK
332              Some  debconf frontends can display a number of questions to the
333              user at once.  Maybe in the future a frontend will even be  able
334              to  group  these questions into blocks on screen. BEGINBLOCK and
335              ENDBLOCK can be placed around a set of INPUT commands  to  indi‐
336              cate  blocks of questions (and blocks can even be nested). Since
337              no debconf frontend is so sophisticated yet, these commands  are
338              ignored for now.
339
340       STOP   This command tells debconf that you're done talking to it. Often
341              debconf can detect termination of your program and this  command
342              is not necessary.
343
344       GET question
345              After using INPUT and GO to display a question, you can use this
346              command to get the value the user entered. The value is returned
347              in the extended result code.
348
349       SET question value
350              This  sets  the value of a question, and it can be used to over‐
351              ride the default value with something your program calculates on
352              the fly.
353
354       RESET question
355              This  resets  the question to its default value (as is specified
356              in the 'Default' field of its template).
357
358       SUBST question key value
359              Questions can have substitutions embedded in their 'Description'
360              and  'Choices'  fields (use of substitutions in 'Choices' fields
361              is a bit of a hack though; a better mechanism will eventually be
362              developed).  These  substitutions  look  like "${key}". When the
363              question is displayed, the substitutions are replaced with their
364              values. This command can be used to set the value of a substitu‐
365              tion. This is useful if you need to display some message to  the
366              user that you can't hard-code in the templates file.
367
368              Do  not  try to use SUBST to change the default value of a ques‐
369              tion; it won't work since there is a SET command explicitly  for
370              that purpose.
371
372       FGET question flag
373              Questions  can  have  flags  associated with them. The flags can
374              have a value of "true" or  "false".  This  command  returns  the
375              value of a flag.
376
377       FSET question flag value
378              This  sets  the  value  of  a question's flag. The value must be
379              either "true" or "false".
380
381              One common flag is the "seen" flag. It is normally only set if a
382              user  has already seen a question. Debconf usually only displays
383              questions to users if they have the seen flag set to "false" (or
384              if  it is reconfiguring a package).  Sometimes you want the user
385              to see a question again -- in these cases you can set  the  seen
386              flag to false to force debconf to redisplay it.
387
388       METAGET question field
389              This  returns  the value of any field of a question's associated
390              template (the Description, for example).
391
392       REGISTER template question
393              This creates a new question that is  bound  to  a  template.  By
394              default  each  template has an associated question with the same
395              name. However, any number of questions can really be  associated
396              with a template, and this lets you create more such questions.
397
398       UNREGISTER question
399              This removes a question from the database.
400
401       PURGE  Call this in your postrm when your package is purged. It removes
402              all of your package's questions from debconf's database.
403
404       X_LOADTEMPLATEFILE /path/to/templates [owner]
405              This extension loads the specified template file into  debconf's
406              database.   The owner defaults to the package that is being con‐
407              figured with debconf.
408
409       Here is a simple example of the debconf protocol in action.
410
411         INPUT medium debconf/frontend
412         30 question skipped
413         FSET debconf/frontend seen false
414         0 false
415         INPUT high debconf/frontend
416         0 question will be asked
417         GO
418         [ Here debconf displays a question to the user. ]
419         0 ok
420         GET no/such/question
421         10 no/such/question doesn't exist
422         GET debconf/frontend
423         0 Dialog
424

LIBRARIES

426       Setting things up so you can talk to debconf, and speaking the  debconf
427       protocol  by  hand  is  a  little too much work, so some thin libraries
428       exist to relieve this minor drudgery.
429
430       For  shell  programming,  there  is  the  /usr/share/debconf/confmodule
431       library, which you can source at the top of a shell script, and talk to
432       debconf in a fairly natural way, using lower-case versions of the  deb‐
433       conf  protocol  commands,  that are prefixed with "db_" (ie, "db_input"
434       and "db_go"). For details, see confmodule(3)
435        .
436
437       Perl programmers can use the Debconf::Client::ConfModule(3pm) perl mod‐
438       ule, and python programmers can use the debconf python module.
439
440       The  rest  of  this  manual  will use the /usr/share/debconf/confmodule
441       library in example shell scripts. Here  is  an  example  config  script
442       using that library, that just asks a question:
443
444         #!/bin/sh
445         set -e
446         . /usr/share/debconf/confmodule
447         db_set mypackage/reboot-now false
448         db_input high mypackage/reboot-now || true
449         db_go || true
450
451       Notice  the  uses of "|| true" to prevent the script from dying if deb‐
452       conf decides it can't display a question, or the user tries to back up.
453       In  those  situations,  debconf returns a non-zero exit code, and since
454       this shell script is set -e, an  untrapped  exit  code  would  make  it
455       abort.
456
457       And  here  is  a  corresponding  postinst  script, that uses the user's
458       answer to the question to see if  the  system  should  be  rebooted  (a
459       rather absurd example..):
460
461         #!/bin/sh
462         set -e
463         . /usr/share/debconf/confmodule
464         db_get mypackage/reboot-now
465         if [ "$RET" = true ]; then
466            shutdown -r now
467         fi
468
469       Notice  the use of the $RET variable to get at the extended return code
470       from the GET command, which holds the user's answer to the question.
471

THE POSTINST SCRIPT

473       The last section had an example of a postinst script that uses  debconf
474       to  get the value of a question, and act on it. Here are some things to
475       keep in mind when writing postinst scripts that use debconf:
476
477       *      Avoid asking questions in  the  postinst.  Instead,  the  config
478              script  should ask questions using debconf, so that pre-configu‐
479              ration will work.
480
481       *      Always source /usr/share/debconf/confmodule at the top  of  your
482              postinst,  even if you won't be running any db_* commands in it.
483              This is required to make sure the config script gets a chance to
484              run (see HACKS for details).
485
486       *      Avoid outputting anything to stdout in your postinst, since that
487              can confuse debconf, and postinst should not be verbose  anyway.
488              Output to stderr is ok, if you must.
489
490       *      If  your  postinst launches a daemon, make sure you tell debconf
491              to STOP at the end, since debconf can become a  little  confused
492              about when your postinst is done otherwise.
493
494       *      Make your postinst script accept a first parameter of "reconfig‐
495              ure". It can treat it just like "configure". This will  be  used
496              in  a  later  version of debconf to let postinsts know when they
497              are reconfigured.
498

OTHER SCRIPTS

500       Besides the config script and postinst, you can use debconf in  any  of
501       the other maintainer scripts. Most commonly, you'll be using debconf in
502       your postrm, to call the PURGE command when your package is purged,  to
503       clean  out  its entries in the debconf database. (This is automatically
504       set up for you by dh_installdebconf(1), by the way.)
505
506       A more involved use of debconf would be if you want to use  it  in  the
507       postrm  when  your  package is purged, to ask a question about deleting
508       something. Or maybe you find you need to use it in the preinst or prerm
509       for  some  reason. All of these uses will work, though they'll probably
510       involve asking questions and acting on the answers in the same program,
511       rather  than separating the two activities as is done in the config and
512       postinst scripts.
513
514       Note that if your package's sole use of debconf is in the  postrm,  you
515       should  make your package's postinst source /usr/share/debconf/confmod‐
516       ule, to give debconf a chance to load up your templates file  into  its
517       database.  Then  the  templates  will be available when your package is
518       being purged.
519
520       You can also use debconf in other, standalone programs.  The  issue  to
521       watch  out for here is that debconf is not intended to be, and must not
522       be used as a registry. This is unix after all, and programs are config‐
523       ured  by  files in /etc, not by some nebulous debconf database (that is
524       only a cache anyway and might get blown away). So think long  and  hard
525       before using debconf in a standalone program.
526
527       There  are  times  when  it can make sense, as in the apt-setup program
528       which uses debconf to prompt the user in a manner consistent  with  the
529       rest  of  the  debian  install  process,  and immediately acts on their
530       answers to set up apt's sources.list.
531

LOCALIZATION

533       Debconf supports localization of templates files. This is  accomplished
534       by  adding more fields, with translated text in them. Any of the fields
535       can be translated.  For  example,  you  might  want  to  translate  the
536       description into Spanish. Just make a field named 'Description-es' that
537       holds the translation. If a translated field is not available,  debconf
538       falls back to the normal English field.
539
540       Besides  the  'Description'  field,  you should translate the 'Choices'
541       field of a select or multiselect template. Be sure to list  the  trans‐
542       lated  choices  in  the same order as they appear in the main 'Choices'
543       field. You do not need to translate the 'Default' field of a select  or
544       multiselect  question,  and the value of the question will be automati‐
545       cally returned in English.
546
547       You will find it easier to manage translations if you keep them in sep‐
548       arate  files;  one  file per translation. In the past, the debconf-get‐
549       lang(1) and  debconf-mergetemplate(1)  programs  were  used  to  manage
550       debian/template.ll files. This has been superseded by the po-debconf(7)
551       package, which lets you deal with debconf translations  in  .po  files,
552       just  like  any other translations. Your translators will thank you for
553       using this new improved mechanism.
554
555       For the details on po-debconf, see its man page. If you're  using  deb‐
556       helper,  converting  to po-debconf is as simple as running the debconf-
557       gettextize(1) command once, and adding a Build-Dependency on po-debconf
558       and on debhelper (>= 4.1.13).
559

PUTTING IT ALL TOGETHER

561       So  you  have a config script, a templates file, a postinst script that
562       uses debconf, and so on. Putting these pieces together  into  a  debian
563       package  isn't  hard.  You can do it by hand, or can use dh_installdeb‐
564       conf(1) which will merge your translated templates, copy the files into
565       the  right places for you, and can even generate the call to PURGE that
566       should go in your postrm script. Make sure that your package depends on
567       debconf  (>=  0.5),  since  earlier  versions  were not compatible with
568       everything described in this manual. And you're done.
569
570       Well, except for testing, debugging, and  actually  using  debconf  for
571       more  interesting  things  than asking a few basic questions. For that,
572       read on..
573

DEBUGGING

575       So you have a package that's supposed to use debconf,  but  it  doesn't
576       quite  work. Maybe debconf is just not asking that question you set up.
577       Or maybe something weirder is happening; it spins forever in some  kind
578       of loop, or worse. Luckily, debconf has plenty of debugging facilities.
579
580       DEBCONF_DEBUG
581              The  first  thing  to reach for is the DEBCONF_DEBUG environment
582              variable.  If you set and export  DEBCONF_DEBUG=developer,  deb‐
583              conf  will  output  to  stderr a dump of the debconf protocol as
584              your program runs. It'll look something like this -- the typo is
585              made clear:
586
587               debconf (developer): <-- input high debconf/frontand
588               debconf (developer): --> 10 "debconf/frontand" doesn't exist
589               debconf (developer): <-- go
590               debconf (developer): --> 0 ok
591
592              It's  rather  useful  to  use  debconf's  readline frontend when
593              you're debugging (in the author's  opinion),  as  the  questions
594              don't  get  in  the  way, and all the debugging output is easily
595              preserved and logged.
596
597       DEBCONF_C_VALUES
598              If this environment variable is set to 'true', the frontend will
599              display  the  values  in Choices-C fields (if present) of select
600              and multiselect templates rather than the descriptive values.
601
602       debconf-communicate
603              Another useful tool is the debconf-communicate(1) program.  Fire
604              it  up  and  you  can speak the raw debconf protocol to debconf,
605              interactively. This is a great way to try stuff out on the fly.
606
607       debconf-show
608              If a user is reporting a problem, debconf-show(1) can be used to
609              dump  out  all  the  questions owned by your package, displaying
610              their values and whether the user has seen them.
611
612       .debconfrc
613              To avoid the often tedious build/install/debug cycle, it can  be
614              useful  to  load  up your templates with debconf-loadtemplate(1)
615              and run your config script by hand with the debconf(1)  command.
616              However,  you still have to do that as root, right? Not so good.
617              And ideally you'd like to be able to see what a fresh  installa‐
618              tion of your package looks like, with a clean debconf database.
619
620              It turns out that if you set up a ~/.debconfrc file for a normal
621              user, pointing at a personal config.dat and template.dat for the
622              user,  you  can load up templates and run config scripts all you
623              like, without any root access. If you want to start over with  a
624              clean database, just blow away the *.dat files.
625
626              For details about setting this up, see debconf.conf(5), and note
627              that /etc/debconf.conf makes a  good  template  for  a  personal
628              ~/.debconfrc file.
629

ADVANCED PROGRAMMING WITH DEBCONF

631   Config file handling
632       Many  of  you  seem  to want to use debconf to help manage config files
633       that are part of your package. Perhaps there is no good default to ship
634       in  a  conffile, and so you want to use debconf to prompt the user, and
635       write out a config file based on their answers. That seems easy  enough
636       to do, but then you consider upgrades, and what to do when someone mod‐
637       ifies the config file you generate, and dpkg-reconfigure, and ...
638
639       There are a lot of ways to do this, and most of  them  are  wrong,  and
640       will  often  earn  you annoyed bug reports. Here is one right way to do
641       it. It assumes that your config file is really just a series  of  shell
642       variables  being  set,  with  comments  in between, and so you can just
643       source the file to "load" it.  If you have a more  complicated  format,
644       reading (and writing) it becomes a bit trickier.
645
646       Your config script will look something like this:
647
648        #!/bin/sh
649        CONFIGFILE=/etc/foo.conf
650        set -e
651        . /usr/share/debconf/confmodule
652
653        # Load config file, if it exists.
654        if [ -e $CONFIGFILE ]; then
655            . $CONFIGFILE || true
656
657            # Store values from config file into
658            # debconf db.
659            db_set mypackage/foo "$FOO"
660            db_set mypackage/bar "$BAR"
661        fi
662
663        # Ask questions.
664        db_input medium mypackage/foo || true
665        db_input medium mypackage/bar || true
666        db_go || true
667
668       And the postinst will look something like this:
669
670        #!/bin/sh
671        CONFIGFILE=/etc/foo.conf
672        set -e
673        . /usr/share/debconf/confmodule
674
675        # Generate config file, if it doesn't exist.
676        # An alternative is to copy in a template
677        # file from elsewhere.
678        if [ ! -e $CONFIGFILE ]; then
679            echo "# Config file for my package" > $CONFIGFILE
680            echo "FOO=" >> $CONFIGFILE
681            echo "BAR=" >> $CONFIGFILE
682        fi
683
684        # Substitute in the values from the debconf db.
685        # There are obvious optimizations possible here.
686        # The cp before the sed ensures we do not mess up
687        # the config file's ownership and permissions.
688        db_get mypackage/foo
689        FOO="$RET"
690        db_get mypackage/bar
691        BAR="$RET"
692        cp -a -f $CONFIGFILE $CONFIGFILE.tmp
693
694        # If the admin deleted or commented some variables but then set
695        # them via debconf, (re-)add them to the conffile.
696        test -z "$FOO" || grep -Eq '^ *FOO=' $CONFIGFILE || \
697            echo "FOO=" >> $CONFIGFILE
698        test -z "$BAR" || grep -Eq '^ *BAR=' $CONFIGFILE || \
699            echo "BAR=" >> $CONFIGFILE
700
701        sed -e "s/^ *FOO=.*/FOO=\"$FOO\"/" \
702            -e "s/^ *BAR=.*/BAR=\"$BAR\"/" \
703            < $CONFIGFILE > $CONFIGFILE.tmp
704        mv -f $CONFIGFILE.tmp $CONFIGFILE
705
706       Consider  how these two scripts handle all the cases. On fresh installs
707       the questions are asked by the config script, and  a  new  config  file
708       generated  by  the  postinst.  On upgrades and reconfigures, the config
709       file is read in, and the values in it are used to change the values  in
710       the  debconf  database, so the admin's manual changes are not lost. The
711       questions are asked again (and may or may not be displayed).  Then  the
712       postinst  substitutes the values back into the config file, leaving the
713       rest of it unchanged.
714
715   Letting the user back up
716       Few things are more frustrating when using a system like  debconf  than
717       being  asked  a  question,  and answering it, then moving on to another
718       screen with a new question on it, and realizing that hey,  you  made  a
719       mistake,  with  that  last question, and you want to go back to it, and
720       discovering that you can't.
721
722       Since debconf is driven by your config script, it can't jump back to  a
723       previous  question  on  its own but with a little help from you, it can
724       accomplish this feat. The first step is to make your config script  let
725       debconf know it is capable of handling the user pressing a back button.
726       You use the CAPB command to do this, passing backup as a parameter.
727
728       Then after each GO command, you must test to see if the user  asked  to
729       back up (debconf returns a code of 30), and if so jump back to the pre‐
730       vious question.
731
732       There are several ways to write the control structures of your  program
733       so it can jump back to previous questions when necessary. You can write
734       goto-laden spaghetti code. Or you can create several functions and  use
735       recursion.  But  perhaps the cleanest and easiest way is to construct a
736       state machine. Here is a skeleton of a state machine that you can  fill
737       out and expand.
738
739        #!/bin/sh
740        set -e
741        . /usr/share/debconf/confmodule
742        db_capb backup
743
744        STATE=1
745        while true; do
746            case "$STATE" in
747            1)
748                 # Two unrelated questions.
749                 db_input medium my/question || true
750                 db_input medium my/other_question || true
751            ;;
752            2)
753                 # Only ask this question if the
754                 # first question was answered in
755                 # the affirmative.
756                 db_get my/question
757                 if [ "$RET" = "true" ]; then
758                      db_input medium my/dep_question || true
759                 fi
760            ;;
761            *)
762                 # The default case catches when $STATE is greater than the
763                 # last implemented state, and breaks out of the loop. This
764                 # requires that states be numbered consecutively from 1
765                 # with no gaps, as the default case will also be entered
766                 # if there is a break in the numbering
767                 break # exits the enclosing "while" loop
768            ;;
769            esac
770
771            if db_go; then
772                 STATE=$(($STATE + 1))
773            else
774                 STATE=$(($STATE - 1))
775            fi
776        done
777
778        if [ $STATE -eq 0 ]; then
779            # The user has asked to back up from the first
780            # question. This case is problematical. Regular
781            # dpkg and apt package installation isn't capable
782            # of backing up questions between packages as this
783            # is written, so this will exit leaving the package
784            # unconfigured - probably the best way to handle
785            # the situation.
786            exit 10
787        fi
788
789       Note  that  if all your config script does is ask a few unrelated ques‐
790       tions, then there is no need for the state machine. Just ask them  all,
791       and GO; debconf will do its best to present them all in one screen, and
792       the user won't need to back up.
793
794   Preventing infinite loops
795       One gotcha with debconf comes up if you have  a  loop  in  your  config
796       script.  Suppose you're asking for input and validating it, and looping
797       if it's not valid:
798
799        ok=''
800        do while [ ! "$ok" ];
801            db_input low foo/bar || true
802            db_go || true
803            db_get foo/bar
804            if [ "$RET" ]; then
805                 ok=1
806            fi
807        done
808
809       This looks ok at first glance. But consider what happens if  the  value
810       of foo/bar is "" when this loop is entered, and the user has their pri‐
811       ority set high, or is using a non-interactive frontend, and so they are
812       not  really asked for input. The value of foo/bar is not changed by the
813       db_input, and so it fails the test and loops. And loops ...
814
815       One fix for this is to make sure that before the loop is  entered,  the
816       value  of  foo/bar  is  set to something that will pass the test in the
817       loop. So for example if the default value of foo/bar is "1",  then  you
818       could RESET foo/bar just before entering the loop.
819
820       Another  fix is to check the return code of the INPUT command. If it is
821       30 then the user is not being shown the question you  asked  them,  and
822       you should break out of the loop.
823
824   Choosing among related packages
825       Sometimes  a  set of related packages can be installed, and you want to
826       prompt the user which of the set should be used by default. Examples of
827       such sets are window managers, or ispell dictionary files.
828
829       While  it  would  be  possible  for  each  package in the set to simply
830       prompt, "Should this package be default?",  this  leads  to  a  lot  of
831       repetitive  questions  if  several  of the packages are installed. It's
832       possible with debconf to present a list of all the packages in the  set
833       and allow the user to choose between them. Here's how.
834
835       Make  all the packages in the set use a shared template. Something like
836       this:
837
838        Template: shared/window-manager
839        Type: select
840        Choices: ${choices}
841        Description: Select the default window manager.
842         Select the window manager that will be started by
843         default when X starts.
844
845       Each package should include a copy of  the  template.  Then  it  should
846       include some code like this in its config script:
847
848        db_metaget shared/window-manager owners
849        OWNERS=$RET
850        db_metaget shared/window-manager choices
851        CHOICES=$RET
852
853        if [ "$OWNERS" != "$CHOICES" ]; then
854            db_subst shared/window-manager choices $OWNERS
855            db_fset shared/window-manager seen false
856        fi
857
858        db_input medium shared/window-manager || true
859        db_go || true
860
861       A  bit  of an explanation is called for. By the time your config script
862       runs, debconf has already read in all the templates  for  the  packages
863       that  are  being installed. Since the set of packages share a question,
864       debconf records that fact in the owners field.  By  a  strange  coinci‐
865       dence,  the  format  of  the  owners  field  is the same as that of the
866       choices field (a comma and space delimited list of values).
867
868       The METAGET command can be used to get the list of owners and the  list
869       of  choices.  If  they  are  different,  then  a  new  package has been
870       installed. So use the SUBST command to change the list of choices to be
871       the same as the list of owners, and ask the question.
872
873       When  a package is removed, you probably want to see if that package is
874       the currently selected choice, and if so, prompt the user to  select  a
875       different package to replace it.
876
877       This  can  be  accomplished  by adding something like this to the prerm
878       scripts of all related packages (replacing <package> with  the  package
879       name):
880
881        if [ -e /usr/share/debconf/confmodule ]; then
882            . /usr/share/debconf/confmodule
883            # I no longer claim this question.
884            db_unregister shared/window-manager
885
886            # See if the shared question still exists.
887            if db_get shared/window-manager; then
888                 db_metaget shared/window-manager owners
889                 db_subst shared/window-manager choices $RET
890                 db_metaget shared/window-manager value
891                 if [ "<package>" = "$RET" ] ; then
892                      db_fset shared/window-manager seen false
893                      db_input high shared/window-manager || true
894                      db_go || true
895                 fi
896
897                 # Now do whatever the postinst script did
898                 # to update the window manager symlink.
899            fi
900        fi
901

HACKS

903       Debconf  is  currently  not  fully  integrated into dpkg (but I want to
904       change this in the future), and  so  some  messy  hacks  are  currently
905       called for.
906
907       The  worst  of these involves getting the config script to run. The way
908       that works now is the config script will be run  when  the  package  is
909       pre-configured.  Then, when the postinst script runs, it starts up deb‐
910       conf again. Debconf notices it is being used by  the  postinst  script,
911       and  so  it  goes off and runs the config script. This can only work if
912       your postinst loads up one of the debconf libraries though, so  postin‐
913       sts  always have to take care to do that. We hope to address this later
914       by adding explicit support to dpkg for debconf. The debconf(1)  program
915       is a step in this direction.
916
917       A  related  hack  is  getting  debconf  running  when  a config script,
918       postinst, or other program that uses it  starts  up.  After  all,  they
919       expect to be able to talk to debconf right away. The way this is accom‐
920       plished for now is that when such a  script  loads  a  debconf  library
921       (like  /usr/share/debconf/confmodule),  and debconf is not already run‐
922       ning, it is started up, and a new copy of the script is re-execed.  The
923       only  noticeable  result  is that you need to put the line that loads a
924       debconf library at the very top of the script,  or  weird  things  will
925       happen.  We  hope  to  address  this  later  by changing how debconf is
926       invoked, and turning it into something more like a transient daemon.
927
928       It's rather hackish how debconf figures out  what  templates  files  to
929       load,  and  when  it loads them. When the config, preinst, and postinst
930       scripts invoke debconf, it will automatically figure out where the tem‐
931       plates  file is, and load it. Standalone programs that use debconf will
932       cause debconf to look for templates  files  in  /usr/share/debconf/tem‐
933       plates/progname.templates.   And  if  a  postrm wants to use debconf at
934       purge time, the templates won't  be  available  unless  debconf  had  a
935       chance to load them in its postinst. This is messy, but rather unavoid‐
936       able. In the future some of these programs may be able to use  debconf-
937       loadtemplate by hand though.
938
939       /usr/share/debconf/confmodule's  historic behavior of playing with file
940       descriptors and setting up a fd #3 that talks to debconf, can cause all
941       sorts  of  trouble when a postinst runs a daemon, since the daemon ends
942       up talking to debconf, and debconf can't figure  out  when  the  script
943       terminates.  The  STOP  command can work around this. In the future, we
944       are considering making debconf communication happen over  a  socket  or
945       some other mechanism than stdio.
946
947       Debconf  sets DEBCONF_RECONFIGURE=1 before running postinst scripts, so
948       a postinst script that needs to avoid  some  expensive  operation  when
949       reconfigured  can  look  at  that  variable. This is a hack because the
950       right thing would be to pass $1 = "reconfigure", but doing  so  without
951       breaking all the postinsts that use debconf is difficult. The migration
952       plan away from this hack is to encourage people to write postinsts that
953       accept  "reconfigure", and once they all do, begin passing that parame‐
954       ter.
955

SEE ALSO

957       debconf(7) is the debconf user's guide.
958
959       The debconf specification in debian policy is the canonical  definition
960       of  the debconf protocol. /usr/share/doc/debian-policy/debconf_specifi‐
961       cation.txt.gz
962
963       debconf.conf(5) has much useful information, including some info  about
964       the backend database.
965

AUTHOR

967       Joey Hess <joeyh@debian.org>
968
969
970
971                                                              DEBCONF-DEVEL(7)
Impressum