Introduction

This is a guide to using debconf with your packages, aimed at a Debian developer.

So, what is debconf? To save you reading the specification (which is in Debian policy if you're interested), debconf is a backend database, with a frontend that talks to it and presents an interface to the user. There can be many different types of frontends, from plain text to a web frontend. The frontend also talks to a special config script in the control section of a debian package, and it can talk to postinst scripts and other scripts as well, all using a special protocol. These scripts tell the frontend what values they need from the database, and the frontend asks the user questions to get those values if they aren't set.

Debconf should be used whenever your package needs to output something to the user, or ask a question. I'll assume you already have a package that does this and you want to convert it to use debconf.

Getting started

First, your package must depend on debconf (or pre-depend on it if it uses debconf in its preinst[1]). This is necessary since debconf isn't essential.

The first thing to do is look at your postinst, plus any program your postinst calls (like a "packageconfig" program), plus your preinst, and even your prerm and postrm. Take note of all output they can generate and all input they prompt the user for. All this output and input must be eliminated for your package to use debconf. (Output to stderr can be left as is.)

For example, a hypothetical package "foo" has the following postinst:

#!/bin/sh -e
echo -n "Do you like debian? [yn] "
read like
case "$like" in
n*|N*)
    echo "Poor misguided one. Why are you installing this package, then?"
    /etc/init.d/subliminal_messages start "I like debian."
;;
esac
     

It's clear that it asks a question and sometimes outputs a message. In this tutorial, we will make it use use debconf to do both.

The Templates file

Start writing a debian/templates file. Each time you find a piece of output or a question, add it to the file as a new template. The format of this file is simple and quite similar to a Debian control file:

Template: packagename/something
Type: [select,multiselect,string,boolean,note,text,password]
Default: [an optional default value]
Description: Blah blah blah?
 Blah blah blah. Blah blah. Blah blah blah. Blah blah? Blah
 blah blah blah. Blah blah blah. Blah blah.
 .
 Blah blah blah. Blah blah. Blah blah blah. Blah blah. Blah blah blah.
 blah.

Template: ....
....
     

Note that the Description field has two parts, a short description and a long description. Please note, that some frontends do not always display the long description, often only showing it if the user asks for additional help. So the short description should be entirely standalone.

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 long 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.

Following along in our example, we create a templates file with two templates in it:

Template: foo/like_debian
Type: boolean
Description: Do you like Debian?
 We'd like to know if you like the Debian GNU/Linux system.

Template: foo/why_debian_is_great
Type: note
Description: Poor misguided one. Why are you installing this package?
 Debian is great. As you continue using Debian, we hope you will
 discover the error in your ways.

     

     debconf-getlang it templates > templates.it
   

     debconf-getlang --stats templates templates.it
   

     debconf-getlang it templates templates.it > new.it
   

The Config Script

Next, decide what order the questions should be asked and the messages to the user should be displayed, figure out what tests you'll make before asking the questions and displaying the messages, and start writing a debian/config file to ask and display them.

• shell script

  You can source /usr/share/debconf/confmodule, which will make a number of shell functions available to you. Each shell function corresponds to a command in the protocol (lowercased, and with "db_" prefixed to its name). You pass parameters to it and get a result back in the $RET variable.

  Note: Some commands also return a number exitcode, to indicate failure and other unusual occurances, so you need to trap that to prevent set -e shell scripts from dying.

  For details, see confmodule.3 and the debconf protocol specification in Debian policy.
  
  

• perl

  You can use the Debconf::Client::ConfModule perl module, which makes a number of functions available to you. Each function corresponds to a command in the protocol -- you pass parameters into it and it returns the result. For details, see the Debconf::Client::ConfModule (3pm) man page, and the debconf protocol specification in Debian policy.

• other

  You'll have to communicate with the frontend directly via standard input and standard output. This isn't hard; read the protocol specification for details (the specification is in Debian policy).

A list and description of all the commands you can use to talk to the frontend is in the Commands appendix. The most common commands you will use in the config script are "input", "go", and "get". Briefly, "input priority question" asks the frontend to make sure it has asked the user a question, specifying how important it is the user be asked. The question names normally correspond to the names of the templates in the template files. "go" tells the frontend to display all accumulated input commands to the user. And "get question" asks the frontend to return to you the answer to a question.

Some other notes about config scripts: Just like other maintainer scripts, config scripts must be idempotent. The config script is passed 2 parameters. The first is either "configure" or "reconfigure". The latter occurs only if a package is being reconfigured by dpkg-reconfig. The second parameter is the last version of the package that was configured. [5].

Continuing the example, we need a config script to display the first question, and if the user says they do not like debian, it should display the message about that.

#!/bin/sh -e

# Source debconf library.
. /usr/share/debconf/confmodule

# Do you like debian?
db_input medium foo/like_debian || true
db_go

# Check their answer.
db_get foo/like_debian
if [ "$RET" = "false" ]; then
    # Poor misguided one..
    db_input high foo/why_debian_is_great || true
    db_go
fi

     

Modifying Existing Maintainer Scripts

Once you have a templates file and a config script, it's time to move on to using the data your config script collects in other maintainer scripts of your package, like your postinst. Just like the config script, the postinst and other maintainer scripts can use the confmodule or Debconf::Client::ConfModule libraries, or they can speak directly to the frontend on standard output.

Anything your maintainer scripts output to standard output is passed into the frontend as a command, so you need to remove all extraneous noise, like the starting and stopping of daemons, etc.

The only command postinsts normally use to communicate with the frontend is "get" [6]. Typically, the config script prompts the user for input, and the postinst then pulls that input out of the database via the get command.

In the example, before debconf, the package's postinst did this:

#!/bin/sh -e
echo -n "Do you like debian? [yn] "
read like
case "$like" in
n*|N*)
    echo "Poor misguided one. Why are you installing this package, then?"
    /etc/init.d/subliminal_messages start "I like debian."
;;
esac
     

Our config script already handles most of this. After debconf, the postinst becomes:

#!/bin/sh -e

# Source debconf library.
. /usr/share/debconf/confmodule

db_get foo/like_debian
if [ "$RET" = "false" ]; then
    /etc/init.d/subliminal_messages start "I like debian."
fi
     

There is one other alteration you need to make to the postrm script. When your package is purged, it should get rid of all the questions and templates it was using in the database. Accomplishing this is simple; use the "purge" command (make sure you don't fail if debconf has already been removed, though):

if [ "$1" = "purge" -a -e /usr/share/debconf/confmodule ]; then
    # Source debconf library.
    . /usr/share/debconf/confmodule
    # Remove my changes to the db.
    db_purge
fi
     

Finishing Up

Now you have a config script and a templates file. Install both into debian/tmp/DEBIAN/. Make sure to make the config script executable. [7]

Your package now uses debconf!

Testing

Before you go build your package, you probably want to test the config script you wrote. This is possible to do, without installing the package -- just run your config script. There is a problem though: the config script relies on your templates being loaded before it is run. When a package that uses debconf is installed, that is handled automatically. Luckily, in most cases it is also handled automatically when you run the config script by hand. Debconf uses two simple rules to try to figure out the templates file associated with the config script, and if it finds one, it loads it.

First, if there is a file with a name that is ".templates" appended to the name of the config script that is being run, debconf assumes that is the templates file.

If that fails, debconf looks to see if the config script that is being ran has a filename ending in "config". If so, and if there exists a file with the same name, except the "config" is instead "templates", debconf assumes that is the templates file.

Troubleshooting

A few things can commonly go wrong when you convert something over to debconf:

• Your postinst uses debconf and starts a daemon that doesn't close all inherited file descriptors (all such daemons are buggy, really). This makes debconf hang, because the debconf frontend waits for the daemon to close the fd's before continuing. Note that if you use confmodule, the program probably needs to close fd's 0, 1, 2, and 3.

  To fix:

  • Redirect fd's to /dev/null before running the daemon

  • Or fix the daemon.

  • Or call the "stop" command at the end of your postinst, to let the frontend know you're done.

  
  
  

• Something weird is happening, and you don't understand what's going on.

  Try setting DEBCONF_DEBUG to 'developer' in the environment. This makes debconf output debugging information, including the commands your scripts send to it and its responses. See the User's Manual for more information on the DEBCONF_DEBUG environment variable.

Advanced Topics

Now I'll move on to some more complicated areas of debconf.

#!/bin/sh -e

# Source debconf library.
. /usr/share/debconf/confmodule
db_version 2.0

# This conf script is capable of backing up
db_capb backup

STATE=1 
while [ "$STATE" != 0 -a "$STATE" != 3 ]; do
    case "$STATE" in
    1)
        # Do you like debian?
        db_input medium foo/like_debian || true
    ;;
    
    2)
        # Check to see if they like debian.
        db_get foo/like_debian
        if [ "$RET" = "false" ]; then
            # Poor misguided one..
            db_input high foo/why_debian_is_great || true
        fi
    ;;
    esac

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

   

ok=''
do while [ ! "$ok" ];
    db_input low foo/bar || true
    db_go || true

    db_get foo/bar
    if [ "$RET" ]; then
        ok=1
    fi
done
   

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.
   

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
   

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-manage seen false
            db_input critical shared/window-manager || true
            db_go || true
        fi

        # Now do whatever the postinst script did tp upsate
        # the window manager symlink or whatever.
    fi
fi