Provided by: debconf-doc_1.5.42ubuntu1_all bug

NAME

       debconf - developers guide

DESCRIPTION

       This is a guide for developing packages that use debconf.

       This  manual  assumes that you are familiar with debconf as a user, and
       are familiar with the basics of debian package construction.

       This manual begins by explaining two new files that are added to debian
       packages  that  use  debconf. Then it explains how the debconf protocol
       works, and points you at some libraries that  will  let  your  programs
       speak  the protocol. It discusses other maintainer scripts that debconf
       is typically used in: the postinst and postrm scripts. Then moves on to
       more advanced topics like shared debconf templates, debugging, and some
       common techniques and pitfalls of programming with debconf.  It  closes
       with a discussion of debconf's current shortcomings.

THE CONFIG SCRIPT

       Debconf adds an additional maintainer script, the config script, to the
       set of maintainer scripts that can be in debian packages (the postinst,
       preinst,  postrm,  and  prerm).  The  config  script is responsible for
       asking any questions necessary to configure the package.

       Note: It is a little confusing that dpkg refers to running a  package's
       postinst script as "configuring" the package, since a package that uses
       debconf is often fully pre-configured, by its config script, before the
       postinst ever runs. Oh well.

       Like  the  postinst, the config script is passed two parameters when it
       is run. The first tells what action is being performed, and the  second
       is  the version of the package that is currently installed. So, like in
       a postinst, you can use dpkg --compare-versions  on  $2  to  make  some
       behavior happen only on upgrade from a particular version of a package,
       and things like that.

       The config script can be run in one of three ways:

       1      If a package  is  pre-configured,  with  dpkg-preconfigure,  its
              config  script is run, and is passed the parameters "configure",
              and installed-version.

       2      When a package's postinst is run, debconf will try  to  run  the
              config  script  then  too,  and  it  will  be  passed  the  same
              parameters it was passed when  it  is  pre-configured.  This  is
              necessary   because   the  package  might  not  have  been  pre-
              configured, and the config script still needs to get a chance to
              run. See HACKS for details.

       3      If  a package is reconfigured, with dpkg-reconfigure, its config
              script it run, and is passed the  parameters  "reconfigure"  and
              installed-version.

       Note  that  since  a  typical package install or upgrade using apt runs
       steps 1 and 2, the config script will typically be run twice. It should
       do  nothing  the  second  time  (to  ask  questions  twice  in a row is
       annoying), and it should definitely  be  idempotent.  Luckily,  debconf
       avoids  repeating  questions  by  default, so this is generally easy to
       accomplish.

       Note that the config script is run before the package is  unpacked.  It
       should  only  use  commands  that  are  in essential packages. The only
       dependency of your package that is guaranteed to be met when its config
       script is run is a dependency (possibly versioned) on debconf itself.

       The  config  script should not need to modify the filesystem at all. It
       just examines the state of the system, and asks questions, and  debconf
       stores  the  answers  to  be  acted  on  later  by the postinst script.
       Conversely, the postinst script should almost never use debconf to  ask
       questions,  but should instead act on the answers to questions asked by
       the config script.

THE TEMPLATES FILE

       A package that uses debconf probably wants to ask some questions. These
       questions are stored, in template form, in the templates file.

       Like the config script, the templates file is put in the control.tar.gz
       section of a deb. Its format is similar to a debian control file; a set
       of  stanzas  separated  by  blank  lines,  with  each  stanza  having a
       RFC822-like form:

         Template: foo/bar
         Type: string
         Default: foo
         Description: This is a sample string question.
          This is its extended description.
          .
          Notice that:
           - Like in a debian package description, a dot
             on its own line sets off a new paragraph.
           - Most text is word-wrapped, but doubly-indented
             text is left alone, so you can use it for lists
             of items, like this list. Be careful, since
             it is not word-wrapped, if it's too wide
             it will look bad. Using it for short items
             is best (so this is a bad example).

         Template: foo/baz
         Type: boolean
         Description: Clear enough, no?
          This is another question, of boolean type.

       For   some    real-life    examples    of    templates    files,    see
       /var/lib/dpkg/info/debconf.templates,  and  other  .templates  files in
       that directory.

       Let's look at each of the fields in turn..

       Template
              The name of the template, in the 'Template' field, is  generally
              prefixed  with the name of the package. After that the namespace
              is wide open; you can use a simple  flat  layout  like  the  one
              above, or set up "subdirectories" containing related questions.

       Type   The  type  of  the  template  determines  what kind of widget is
              displayed to the user. The currently supported types are:

              string Results in a free-form input field that the user can type
                     any string into.

              password
                     Prompts  the  user for a password. Use this with caution;
                     be aware that  the  password  the  user  enters  will  be
                     written  to debconf's database. You should probably clean
                     that value out of the database as soon as is possible.

              boolean
                     A true/false choice.

              select A choice between one of a number of values.  The  choices
                     must  be  specified  in a field named 'Choices'. Separate
                     the possible values with commas and spaces, like this:
                       Choices: yes, no, maybe

              multiselect
                     Like the select data type, except the user can choose any
                     number  of items from the choices list (or choose none of
                     them).

              note   Rather than  being  a  question  per  se,  this  datatype
                     indicates  a  note  that can be displayed to the user. It
                     should be used only for important  notes  that  the  user
                     really  should  see, since debconf will go to great pains
                     to make sure the user sees it; halting  the  install  for
                     them  to  press  a  key.  It's best to use these only for
                     warning  about  very  serious  problems,  and  the  error
                     datatype is often more suitable.

              error  This  datatype  is used for error messages, such as input
                     validation errors.  Debconf will show a question of  this
                     type  even  if  the  priority is too high or the user has
                     already seen it.

              title  This datatype is used for titles,  to  be  set  with  the
                     SETTITLE command.

              text   This  datatype can be used for fragments of text, such as
                     labels, that can be used  for  cosmetic  reasons  in  the
                     displays  of some frontends. Other frontends will not use
                     it at all. There is no point in using this datatype  yet,
                     since  no  frontends  support  it  well.  It  may even be
                     removed in the future.

       Default
              The 'Default' field tells debconf what the default value  should
              be.  For  multiselect, it can be a list of choices, separated by
              commas and spaces, similar to the 'Choices' field.  For  select,
              it  should  be  one of the choices. For boolean, it is "true" or
              "false", while it can be  anything  for  a  string,  and  it  is
              ignored for passwords.

              Don't  make  the  mistake  of  thinking  that  the default field
              contains the "value" of the question, or that it can be used  to
              change  the  value  of the question. It does not, and cannot, it
              just provides a default value for the first time the question is
              displayed.  To  provide a default that changes on the fly, you'd
              have to use the SET command to change the value of a question.

       Description
              The 'Description'  field,  like  the  description  of  a  Debian
              package,  has  two  parts:  A  short description and an extended
              description. Note that some debconf frontends don't display  the
              long  description, or might only display it if the user asks for
              help. So the short description should be able to  stand  on  its
              own.

              If you can't think up a long description, then first, think some
              more. Post to debian-devel. Ask for help. Take a writing  class!
              That  extended  description  is important. If after all that you
              still can't come up with anything, leave it blank. There  is  no
              point in duplicating the short description.

              Text in the extended description will be word-wrapped, unless it
              is prefixed by additional whitespace (beyond  the  one  required
              space).  You can break it up into separate paragraphs by putting
              " ." on a line by itself between them.

QUESTIONS

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

SHARED TEMPLATES

       It's actually possible to have a  template  and  a  question  that  are
       shared  among  a  set  of packages. All the packages have to provide an
       identical copy of the template in their templates files.  This  can  be
       useful  if  a  bunch of packages need to ask the same question, and you
       only want to bother  the  user  with  it  once.  Shared  templates  are
       generally  put  in the shared/ pseudo-directory in the debconf template
       namespace.

THE DEBCONF PROTOCOL

       Config scripts communicate with debconf  using  the  debconf  protocol.
       This  is  a  simple  line-oriented protocol, similar to common internet
       protocols such as SMTP. The config script sends debconf  a  command  by
       writing  the  command  to  standard  output. Then it can read debconf's
       reply from standard input.

       Debconf's reply can be broken down into two  parts:  A  numeric  result
       code  (the  first  word  of the reply), and an optional extended result
       code (the remainder of the reply). The numeric code uses 0 to  indicate
       success,  and  other  numbers to indicate various kinds of failure. For
       full details, see the table in Debian  policy's  debconf  specification
       document.

       The extended return code is generally free form and unspecified, so you
       should generally ignore it, and should certainly not try to parse it in
       a  program to work out what debconf is doing. The exception is commands
       like GET, that cause a value to be  returned  in  the  extended  return
       code.

       Generally  you'll  want to use a language-specific library that handles
       the nuts and bolts of setting  up  these  connections  to  debconf  and
       communicating with it.

       For  now,  here  are  the  commands  in  the  protocol. This is not the
       definitive  definition,  see  Debian  policy's  debconf   specification
       document for that.

       VERSION number
              You  generally don't need to use this command. It exchanges with
              debconf the protocol version number  that  is  being  used.  The
              current  protocol version is 2.0, and versions in the 2.x series
              will be  backwards-compatible.  You  may  specify  the  protocol
              version  number  you  are  speaking  and debconf will return the
              version of the protocol it speaks in the extended  result  code.
              If  the  version you specify is too low, debconf will reply with
              numeric code 30.

       CAPB capabilities
              You generally don't need to use this command. It exchanges  with
              debconf a list of supported capabilities. Capabilities that both
              you and debconf support will be used,  and  debconf  will  reply
              with all the capabilities it supports.

              If  'escape'  is  found  among  your  capabilities, debconf will
              expect commands you send it to  have  backslashes  and  newlines
              escaped  (as  \\  and  \n  respectively) and will in turn escape
              backslashes and newlines in its replies. This can be  used,  for
              example,  to substitute multi-line strings into templates, or to
              get multi-line extended descriptions reliably using METAGET.  In
              this  mode,  you  must  escape  input text yourself (you can use
              debconf-escape(1) to help  with  this  if  you  want),  but  the
              confmodule libraries will unescape replies for you.

       SETTITLE question
              This  sets  the  title  debconf  displays to the user, using the
              short description of the template for  the  specified  question.
              The  template  should  be  of type title. You rarely need to use
              this command since debconf can automatically  generate  a  title
              based on your package's name.

              Setting  the  title from a template means they are stored in the
              same place as the rest of the debconf questions, and allows them
              to be translated.

       TITLE string
              This  sets  the  title  debconf  displays  to  the  user  to the
              specified string.  Use of the SETTITLE command is normally to be
              preferred as it allows for translation of the title.

       INPUT priority question
              Ask  debconf  to  prepare to display a question to the user. The
              question is not actually displayed until a GO command is issued;
              this lets several INPUT commands be given in series, to build up
              a set of questions, which might all be asked on a single screen.

              The priority field tells debconf how important it is  that  this
              question be shown to the user. The priority values are:

              low    Very  trivial  items that have defaults that will work in
                     the vast majority  of  cases;  only  control  freaks  see
                     these.

              medium Normal items that have reasonable defaults.

              high   Items that don't have a reasonable default.

              critical
                     Items  that  will  probably break the system without user
                     intervention.

              Debconf decides if the question is actually displayed, based  on
              its priority, and whether the user has seen it before, and which
              frontend is being used. If the question will not  be  displayed,
              debconf replies with code 30.

       GO
              Tells  debconf to display the accumulated set of questions (from
              INPUT commands) to the user.

              If the backup capability is supported  and  the  user  indicates
              they want to back up a step, debconf replies with code 30.

       CLEAR  Clears  the  accumulated  set of questions (from INPUT commands)
              without displaying them.

       BEGINBLOCK

       ENDBLOCK
              Some debconf frontends can display a number of questions to  the
              user  at once.  Maybe in the future a frontend will even be able
              to group these questions into blocks on screen.  BEGINBLOCK  and
              ENDBLOCK  can  be  placed  around  a  set  of  INPUT commands to
              indicate blocks of questions (and blocks can  even  be  nested).
              Since  no  debconf  frontend  is  so  sophisticated  yet,  these
              commands are ignored for now.

       STOP   This command tells debconf that you're done talking to it. Often
              debconf  can detect termination of your program and this command
              is not necessary.

       GET question
              After using INPUT and GO to display a question, you can use this
              command to get the value the user entered. The value is returned
              in the extended result code.

       SET question value
              This sets the value of  a  question,  and  it  can  be  used  to
              override   the   default   value  with  something  your  program
              calculates on the fly.

       RESET question
              This resets the question to its default value (as  is  specified
              in the 'Default' field of its template).

       SUBST question key value
              Questions can have substitutions embedded in their 'Description'
              and 'Choices' fields (use of substitutions in  'Choices'  fields
              is a bit of a hack though; a better mechanism will eventually be
              developed). These substitutions look  like  "${key}".  When  the
              question is displayed, the substitutions are replaced with their
              values. This  command  can  be  used  to  set  the  value  of  a
              substitution. This is useful if you need to display some message
              to the user that you can't hard-code in the templates file.

              Do not try to use  SUBST  to  change  the  default  value  of  a
              question;  it won't work since there is a SET command explicitly
              for that purpose.

       FGET question flag
              Questions can have flags associated with  them.  The  flags  can
              have  a  value  of  "true"  or "false". This command returns the
              value of a flag.

       FSET question flag value
              This sets the value of a question's  flag.  The  value  must  be
              either "true" or "false".

              One common flag is the "seen" flag. It is normally only set if a
              user has already seen a question. Debconf usually only  displays
              questions to users if they have the seen flag set to "false" (or
              if it is reconfiguring a package).  Sometimes you want the  user
              to  see  a question again -- in these cases you can set the seen
              flag to false to force debconf to redisplay it.

       METAGET question field
              This returns the value of any field of a  question's  associated
              template (the Description, for example).

       REGISTER template question
              This  creates  a  new  question  that is bound to a template. By
              default each template has an associated question with  the  same
              name.  However, any number of questions can really be associated
              with a template, and this lets you create more such questions.

       UNREGISTER question
              This removes a question from the database.

       PURGE  Call this in your postrm when your package is purged. It removes
              all of your package's questions from debconf's database.

       X_LOADTEMPLATEFILE /path/to/templates [owner]
              This  extension loads the specified template file into debconf's
              database.  The owner defaults  to  the  package  that  is  being
              configured with debconf.

       Here is a simple example of the debconf protocol in action.

         INPUT medium debconf/frontend
         30 question skipped
         FSET debconf/frontend seen false
         0 false
         INPUT high debconf/frontend
         0 question will be asked
         GO
         [ Here debconf displays a question to the user. ]
         0 ok
         GET no/such/question
         10 no/such/question doesn't exist
         GET debconf/frontend
         0 Dialog

LIBRARIES

       Setting  things up so you can talk to debconf, and speaking the debconf
       protocol by hand is a little too much  work,  so  some  thin  libraries
       exist to relieve this minor drudgery.

       For  shell  programming,  there  is  the  /usr/share/debconf/confmodule
       library, which you can source at the top of a shell script, and talk to
       debconf  in  a  fairly  natural  way,  using lower-case versions of the
       debconf protocol commands, that are prefixed with "db_" (ie, "db_input"
       and "db_go"). For details, see confmodule(3)
        .

       Perl  programmers  can  use  the  Debconf::Client::ConfModule(3pm) perl
       module, and python programmers can use the debconf python module.

       The rest of this  manual  will  use  the  /usr/share/debconf/confmodule
       library  in  example  shell  scripts.  Here is an example config script
       using that library, that just asks a question:

         #!/bin/sh
         set -e
         . /usr/share/debconf/confmodule
         db_set mypackage/reboot-now false
         db_input high mypackage/reboot-now || true
         db_go || true

       Notice the uses of "|| true"  to  prevent  the  script  from  dying  if
       debconf  decides it can't display a question, or the user tries to back
       up. In those situations, debconf returns  a  non-zero  exit  code,  and
       since this shell script is set -e, an untrapped exit code would make it
       abort.

       And here is a corresponding  postinst  script,  that  uses  the  user's
       answer  to  the  question  to  see  if the system should be rebooted (a
       rather absurd example..):

         #!/bin/sh
         set -e
         . /usr/share/debconf/confmodule
         db_get mypackage/reboot-now
         if [ "$RET" = true ]; then
            shutdown -r now
         fi

       Notice the use of the $RET variable to get at the extended return  code
       from the GET command, which holds the user's answer to the question.

THE POSTINST SCRIPT

       The  last section had an example of a postinst script that uses debconf
       to get the value of a question, and act on it. Here are some things  to
       keep in mind when writing postinst scripts that use debconf:

       *      Avoid  asking  questions  in  the  postinst. Instead, the config
              script  should  ask  questions  using  debconf,  so  that   pre-
              configuration will work.

       *      Always  source  /usr/share/debconf/confmodule at the top of your
              postinst, even if you won't be running any db_* commands in  it.
              This is required to make sure the config script gets a chance to
              run (see HACKS for details).

       *      Avoid outputting anything to stdout in your postinst, since that
              can  confuse debconf, and postinst should not be verbose anyway.
              Output to stderr is ok, if you must.

       *      If your postinst launches a daemon, make sure you  tell  debconf
              to  STOP  at the end, since debconf can become a little confused
              about when your postinst is done otherwise.

       *      Make  your  postinst  script  accept  a   first   parameter   of
              "reconfigure".  It can treat it just like "configure". This will
              be used in a later version of debconf to let postinsts know when
              they are reconfigured.

OTHER SCRIPTS

       Besides  the  config script and postinst, you can use debconf in any of
       the other maintainer scripts. Most commonly, you'll be using debconf in
       your  postrm, to call the PURGE command when your package is purged, to
       clean out its entries in the debconf database. (This  is  automatically
       set up for you by dh_installdebconf(1), by the way.)

       A  more  involved  use of debconf would be if you want to use it in the
       postrm when your package is purged, to ask a  question  about  deleting
       something. Or maybe you find you need to use it in the preinst or prerm
       for some reason. All of these uses will work, though  they'll  probably
       involve asking questions and acting on the answers in the same program,
       rather than separating the two activities as is done in the config  and
       postinst scripts.

       Note  that  if your package's sole use of debconf is in the postrm, you
       should      make       your       package's       postinst       source
       /usr/share/debconf/confmodule, to give debconf a chance to load up your
       templates file into its database. Then the templates will be  available
       when your package is being purged.

       You  can  also  use debconf in other, standalone programs. The issue to
       watch out for here is that debconf is not intended to be, and must  not
       be  used  as  a  registry.  This  is  unix  after all, and programs are
       configured by files in /etc, not  by  some  nebulous  debconf  database
       (that  is  only a cache anyway and might get blown away). So think long
       and hard before using debconf in a standalone program.

       There are times when it can make sense, as  in  the  apt-setup  program
       which  uses  debconf to prompt the user in a manner consistent with the
       rest of the debian install  process,  and  immediately  acts  on  their
       answers to set up apt's sources.list.

LOCALIZATION

       Debconf  supports localization of templates files. This is accomplished
       by adding more fields, with translated text in them. Any of the  fields
       can  be  translated.  For  example,  you  might  want  to translate the
       description into Spanish. Just make a field named 'Description-es' that
       holds  the translation. If a translated field is not available, debconf
       falls back to the normal English field.

       Besides the 'Description' field, you  should  translate  the  'Choices'
       field  of  a  select  or  multiselect  template.  Be  sure  to list the
       translated choices in the  same  order  as  they  appear  in  the  main
       'Choices'  field. You do not need to translate the 'Default' field of a
       select or multiselect question, and the value of the question  will  be
       automatically returned in English.

       You  will  find  it  easier  to manage translations if you keep them in
       separate files; one file per translation. In  the  past,  the  debconf-
       getlang(1)  and  debconf-mergetemplate(1)  programs were used to manage
       debian/template.ll files. This has been superseded by the po-debconf(7)
       package,  which  lets  you deal with debconf translations in .po files,
       just like any other translations. Your translators will thank  you  for
       using this new improved mechanism.

       For  the  details  on  po-debconf,  see  its  man page. If you're using
       debhelper, converting  to  po-debconf  is  as  simple  as  running  the
       debconf-gettextize(1)  command  once,  and adding a Build-Dependency on
       po-debconf and on debhelper (>= 4.1.13).

PUTTING IT ALL TOGETHER

       So you have a config script, a templates file, a postinst  script  that
       uses  debconf,  and  so on. Putting these pieces together into a debian
       package  isn't  hard.  You  can   do   it   by   hand,   or   can   use
       dh_installdebconf(1)  which  will merge your translated templates, copy
       the files into the right places for you, and can even generate the call
       to  PURGE  that  should  go  in your postrm script. Make sure that your
       package depends on debconf (>= 0.5), since earlier  versions  were  not
       compatible with everything described in this manual. And you're done.

       Well,  except  for  testing,  debugging, and actually using debconf for
       more interesting things than asking a few basic  questions.  For  that,
       read on..

DEBUGGING

       So  you  have  a package that's supposed to use debconf, but it doesn't
       quite work. Maybe debconf is just not asking that question you set  up.
       Or  maybe something weirder is happening; it spins forever in some kind
       of loop, or worse. Luckily, debconf has plenty of debugging facilities.

       DEBCONF_DEBUG
              The first thing to reach for is  the  DEBCONF_DEBUG  environment
              variable.    If  you  set  and  export  DEBCONF_DEBUG=developer,
              debconf will output to stderr a dump of the debconf protocol  as
              your program runs. It'll look something like this -- the typo is
              made clear:

               debconf (developer): <-- input high debconf/frontand
               debconf (developer): --> 10 "debconf/frontand" doesn't exist
               debconf (developer): <-- go
               debconf (developer): --> 0 ok

              It's rather useful  to  use  debconf's  readline  frontend  when
              you're  debugging  (in  the  author's opinion), as the questions
              don't get in the way, and all the  debugging  output  is  easily
              preserved and logged.

       DEBCONF_C_VALUES
              If this environment variable is set to 'true', the frontend will
              display the values in Choices-C fields (if  present)  of  select
              and multiselect templates rather than the descriptive values.

       debconf-communicate
              Another  useful tool is the debconf-communicate(1) program. Fire
              it up and you can speak the raw  debconf  protocol  to  debconf,
              interactively. This is a great way to try stuff out on the fly.

       debconf-show
              If a user is reporting a problem, debconf-show(1) can be used to
              dump out all the questions owned  by  your  package,  displaying
              their values and whether the user has seen them.

       .debconfrc
              To  avoid the often tedious build/install/debug cycle, it can be
              useful to load up your  templates  with  debconf-loadtemplate(1)
              and  run your config script by hand with the debconf(1) command.
              However, you still have to do that as root, right? Not so  good.
              And  ideally  you'd  like  to  be  able  to  see  what  a  fresh
              installation of your package looks like, with  a  clean  debconf
              database.

              It turns out that if you set up a ~/.debconfrc file for a normal
              user, pointing at a personal config.dat and template.dat for the
              user,  you  can load up templates and run config scripts all you
              like, without any root access. If you want to start over with  a
              clean database, just blow away the *.dat files.

              For details about setting this up, see debconf.conf(5), and note
              that /etc/debconf.conf makes a  good  template  for  a  personal
              ~/.debconfrc file.

ADVANCED PROGRAMMING WITH DEBCONF

   Config file handling
       Many  of  you  seem  to want to use debconf to help manage config files
       that are part of your package. Perhaps there is no good default to ship
       in  a  conffile, and so you want to use debconf to prompt the user, and
       write out a config file based on their answers. That seems easy  enough
       to  do,  but  then  you  consider upgrades, and what to do when someone
       modifies the config file you generate, and dpkg-reconfigure, and ...

       There are a lot of ways to do this, and most of  them  are  wrong,  and
       will  often  earn  you annoyed bug reports. Here is one right way to do
       it. It assumes that your config file is really just a series  of  shell
       variables  being  set,  with  comments  in between, and so you can just
       source the file to "load" it.  If you have a more  complicated  format,
       reading (and writing) it becomes a bit trickier.

       Your config script will look something like this:

        #!/bin/sh
        CONFIGFILE=/etc/foo.conf
        set -e
        . /usr/share/debconf/confmodule

        # Load config file, if it exists.
        if [ -e $CONFIGFILE ]; then
            . $CONFIGFILE || true

            # Store values from config file into
            # debconf db.
            db_set mypackage/foo "$FOO"
            db_set mypackage/bar "$BAR"
        fi

        # Ask questions.
        db_input medium mypackage/foo || true
        db_input medium mypackage/bar || true
        db_go || true

       And the postinst will look something like this:

        #!/bin/sh
        CONFIGFILE=/etc/foo.conf
        set -e
        . /usr/share/debconf/confmodule

        # Generate config file, if it doesn't exist.
        # An alternative is to copy in a template
        # file from elsewhere.
        if [ ! -e $CONFIGFILE ]; then
            echo "# Config file for my package" > $CONFIGFILE
            echo "FOO=" >> $CONFIGFILE
            echo "BAR=" >> $CONFIGFILE
        fi

        # Substitute in the values from the debconf db.
        # There are obvious optimizations possible here.
        # The cp before the sed ensures we do not mess up
        # the config file's ownership and permissions.
        db_get mypackage/foo
        FOO="$RET"
        db_get mypackage/bar
        BAR="$RET"
        cp -a -f $CONFIGFILE $CONFIGFILE.tmp

        # If the admin deleted or commented some variables but then set
        # them via debconf, (re-)add them to the conffile.
        test -z "$FOO" || grep -Eq '^ *FOO=' $CONFIGFILE || \
            echo "FOO=" >> $CONFIGFILE
        test -z "$BAR" || grep -Eq '^ *BAR=' $CONFIGFILE || \
            echo "BAR=" >> $CONFIGFILE

        sed -e "s/^ *FOO=.*/FOO=\"$FOO\"/" \
            -e "s/^ *BAR=.*/BAR=\"$BAR\"/" \
            < $CONFIGFILE > $CONFIGFILE.tmp
        mv -f $CONFIGFILE.tmp $CONFIGFILE

       Consider  how these two scripts handle all the cases. On fresh installs
       the questions are asked by the config script, and  a  new  config  file
       generated  by  the  postinst.  On upgrades and reconfigures, the config
       file is read in, and the values in it are used to change the values  in
       the  debconf  database, so the admin's manual changes are not lost. The
       questions are asked again (and may or may not be displayed).  Then  the
       postinst  substitutes the values back into the config file, leaving the
       rest of it unchanged.

   Letting the user back up
       Few things are more frustrating when using a system like  debconf  than
       being  asked  a  question,  and answering it, then moving on to another
       screen with a new question on it, and realizing that hey,  you  made  a
       mistake,  with  that  last question, and you want to go back to it, and
       discovering that you can't.

       Since debconf is driven by your config script, it can't jump back to  a
       previous  question  on  its own but with a little help from you, it can
       accomplish this feat. The first step is to make your config script  let
       debconf know it is capable of handling the user pressing a back button.
       You use the CAPB command to do this, passing backup as a parameter.

       Then after each GO command, you must test to see if the user  asked  to
       back  up  (debconf  returns  a  code of 30), and if so jump back to the
       previous question.

       There are several ways to write the control structures of your  program
       so it can jump back to previous questions when necessary. You can write
       goto-laden spaghetti code. Or you can create several functions and  use
       recursion.  But  perhaps the cleanest and easiest way is to construct a
       state machine. Here is a skeleton of a state machine that you can  fill
       out and expand.

        #!/bin/sh
        set -e
        . /usr/share/debconf/confmodule
        db_capb backup

        STATE=1
        while true; do
            case "$STATE" in
            1)
                 # Two unrelated questions.
                 db_input medium my/question || true
                 db_input medium my/other_question || true
            ;;
            2)
                 # Only ask this question if the
                 # first question was answered in
                 # the affirmative.
                 db_get my/question
                 if [ "$RET" = "true" ]; then
                      db_input medium my/dep_question || true
                 fi
            ;;
            *)
                 # The default case catches when $STATE is greater than the
                 # last implemented state, and breaks out of the loop. This
                 # requires that states be numbered consecutively from 1
                 # with no gaps, as the default case will also be entered
                 # if there is a break in the numbering
                 break # exits the enclosing "while" loop
            ;;
            esac

            if db_go; then
                 STATE=$(($STATE + 1))
            else
                 STATE=$(($STATE - 1))
            fi
        done

        if [ $STATE -eq 0 ]; then
            # The user has asked to back up from the first
            # question. This case is problematical. Regular
            # dpkg and apt package installation isn't capable
            # of backing up questions between packages as this
            # is written, so this will exit leaving the package
            # unconfigured - probably the best way to handle
            # the situation.
            exit 10
        fi

       Note  that  if  all  your  config  script  does  is ask a few unrelated
       questions, then there is no need for the state machine. Just  ask  them
       all,  and  GO;  debconf  will  do  its  best to present them all in one
       screen, and the user won't need to back up.

   Preventing infinite loops
       One gotcha with debconf comes up if you have  a  loop  in  your  config
       script.  Suppose you're asking for input and validating it, and looping
       if it's not valid:

        ok=''
        do while [ ! "$ok" ];
            db_input low foo/bar || true
            db_go || true
            db_get foo/bar
            if [ "$RET" ]; then
                 ok=1
            fi
        done

       This looks ok at first glance. But consider what happens if  the  value
       of  foo/bar  is  ""  when  this loop is entered, and the user has their
       priority set high, or is using a non-interactive frontend, and so  they
       are  not really asked for input. The value of foo/bar is not changed by
       the db_input, and so it fails the test and loops. And loops ...

       One fix for this is to make sure that before the loop is  entered,  the
       value  of  foo/bar  is  set to something that will pass the test in the
       loop. So for example if the default value of foo/bar is "1",  then  you
       could RESET foo/bar just before entering the loop.

       Another  fix is to check the return code of the INPUT command. If it is
       30 then the user is not being shown the question you  asked  them,  and
       you should break out of the loop.

   Choosing among related packages
       Sometimes  a  set of related packages can be installed, and you want to
       prompt the user which of the set should be used by default. Examples of
       such sets are window managers, or ispell dictionary files.

       While  it  would  be  possible  for  each  package in the set to simply
       prompt, "Should this package be default?",  this  leads  to  a  lot  of
       repetitive  questions  if  several  of the packages are installed. It's
       possible with debconf to present a list of all the packages in the  set
       and allow the user to choose between them. Here's how.

       Make  all the packages in the set use a shared template. Something like
       this:

        Template: shared/window-manager
        Type: select
        Choices: ${choices}
        Description: Select the default window manager.
         Select the window manager that will be started by
         default when X starts.

       Each package should include a copy of  the  template.  Then  it  should
       include some code like this in its config script:

        db_metaget shared/window-manager owners
        OWNERS=$RET
        db_metaget shared/window-manager choices
        CHOICES=$RET

        if [ "$OWNERS" != "$CHOICES" ]; then
            db_subst shared/window-manager choices $OWNERS
            db_fset shared/window-manager seen false
        fi

        db_input medium shared/window-manager || true
        db_go || true

       A  bit  of an explanation is called for. By the time your config script
       runs, debconf has already read in all the templates  for  the  packages
       that  are  being installed. Since the set of packages share a question,
       debconf  records  that  fact  in  the  owners  field.  By   a   strange
       coincidence,  the format of the owners field is the same as that of the
       choices field (a comma and space delimited list of values).

       The METAGET command can be used to get the list of owners and the  list
       of  choices.  If  they  are  different,  then  a  new  package has been
       installed. So use the SUBST command to change the list of choices to be
       the same as the list of owners, and ask the question.

       When  a package is removed, you probably want to see if that package is
       the currently selected choice, and if so, prompt the user to  select  a
       different package to replace it.

       This  can  be  accomplished  by adding something like this to the prerm
       scripts of all related packages (replacing <package> with  the  package
       name):

        if [ -e /usr/share/debconf/confmodule ]; then
            . /usr/share/debconf/confmodule
            # I no longer claim this question.
            db_unregister shared/window-manager

            # See if the shared question still exists.
            if db_get shared/window-manager; then
                 db_metaget shared/window-manager owners
                 db_subst shared/window-manager choices $RET
                 db_metaget shared/window-manager value
                 if [ "<package>" = "$RET" ] ; then
                      db_fset shared/window-manager seen false
                      db_input high shared/window-manager || true
                      db_go || true
                 fi

                 # Now do whatever the postinst script did
                 # to update the window manager symlink.
            fi
        fi

HACKS

       Debconf  is  currently  not  fully  integrated into dpkg (but I want to
       change this in the future), and  so  some  messy  hacks  are  currently
       called for.

       The  worst  of these involves getting the config script to run. The way
       that works now is the config script will be run  when  the  package  is
       pre-configured.  Then,  when  the  postinst  script  runs, it starts up
       debconf again. Debconf notices it is being used by the postinst script,
       and  so  it  goes off and runs the config script. This can only work if
       your postinst  loads  up  one  of  the  debconf  libraries  though,  so
       postinsts  always have to take care to do that. We hope to address this
       later by adding explicit support to dpkg for  debconf.  The  debconf(1)
       program is a step in this direction.

       A  related  hack  is  getting  debconf  running  when  a config script,
       postinst, or other program that uses it  starts  up.  After  all,  they
       expect  to  be  able  to  talk  to  debconf right away. The way this is
       accomplished for now is that when such a script loads a debconf library
       (like   /usr/share/debconf/confmodule),  and  debconf  is  not  already
       running, it is started up, and a new copy of the script  is  re-execed.
       The  only noticeable result is that you need to put the line that loads
       a debconf library at the very top of the script, or weird  things  will
       happen.  We  hope  to  address  this  later  by changing how debconf is
       invoked, and turning it into something more like a transient daemon.

       It's rather hackish how debconf figures out  what  templates  files  to
       load,  and  when  it loads them. When the config, preinst, and postinst
       scripts invoke debconf, it will  automatically  figure  out  where  the
       templates  file  is,  and load it. Standalone programs that use debconf
       will   cause   debconf    to    look    for    templates    files    in
       /usr/share/debconf/templates/progname.templates.  And if a postrm wants
       to use debconf at purge time, the templates won't be  available  unless
       debconf  had  a chance to load them in its postinst. This is messy, but
       rather unavoidable. In the future some of these programs may be able to
       use debconf-loadtemplate by hand though.

       /usr/share/debconf/confmodule's  historic behavior of playing with file
       descriptors and setting up a fd #3 that talks to debconf, can cause all
       sorts  of  trouble when a postinst runs a daemon, since the daemon ends
       up talking to debconf, and debconf can't figure  out  when  the  script
       terminates.  The  STOP  command can work around this. In the future, we
       are considering making debconf communication happen over  a  socket  or
       some other mechanism than stdio.

       Debconf  sets DEBCONF_RECONFIGURE=1 before running postinst scripts, so
       a postinst script that needs to avoid  some  expensive  operation  when
       reconfigured  can  look  at  that  variable. This is a hack because the
       right thing would be to pass $1 = "reconfigure", but doing  so  without
       breaking all the postinsts that use debconf is difficult. The migration
       plan away from this hack is to encourage people to write postinsts that
       accept  "reconfigure",  and  once  they  all  do,  begin  passing  that
       parameter.

SEE ALSO

       debconf(7) is the debconf user's guide.

       The debconf specification in debian policy is the canonical  definition
       of       the       debconf       protocol.       /usr/share/doc/debian-
       policy/debconf_specification.txt.gz

       debconf.conf(5) has much useful information, including some info  about
       the backend database.

AUTHOR

       Joey Hess <joeyh@debian.org>

                                                              DEBCONF-DEVEL(7)