Provided by: debconf-doc_1.5.79ubuntu1_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  (separated  by  spaces).  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)