NAME
po-debconf – introduction

DESCRIPTION
The goal of “debconf” was to make package configuration user-friendly.  In order to achieve this, it is important to ensure that users will get the question in their
own language.  Translators need a framework to easily work on translations without having to track down package development; “po-debconf” was designed to be able to
work with standard “gettext” tools when translating debconf templates files.

ADDING I18N SUPPORT TO DEBCONF TEMPLATES FILES
If you are adding debconf support to your package, you have written a templates file containing English text.  To add proper i18n support into your package, you need
to:

- Create debian/po/POTFILES.in
This file contains the list of master templates.  It typically contains a single line

[type: gettext/rfc822deb] templates

Paths are relative to the parent directory.

- Prepend an underscore before translatable fields
Normally “Description”, “Choices” and sometimes “Default” fields can be translated.

- Run debconf-updatepo
This will create the debian/po/templates.pot file that translators will translate into their language.

- Add a build dependency on “po-debconf” in debian/control

UPDATE TEMPLATES
In order to help translators, PO files in your package should always be up-to-date, otherwise they may lose their time with unused strings.  For that, simply call
the following command without arguments:

$ debconf-updatepo

You should run this command every time you change templates in English, but also when you receive new or updated translations, because translators may have worked on
an obsolete PO file.

If you rename, add or remove some templates files, remember also to edit debian/po/POTFILES.in accordingly, otherwise English strings are missing from PO files and
will be displayed to users even if PO files are fully translated.

The debconf-updatepo program is idempotent, it modifies PO files only if their content has been updated.  Thus the best solution to provide up-to-date PO files in
your source package is to call this command from the “clean” target of the debian/rules file.
Please note that you need to run debconf-updatepo even if you use dh_installdebconf.  The latter calls po2debconf which used to call debconf-updatepo if outdated
files were detected, but this is no more the case because it was not a good solution for at least two reasons:

1. po2debconf relied on timestamps to detect outdated files, and may be abused when using “pbuilder” or if an outdated translation has been stored on disk after tem‐
plates have been modified

2. dh_installdebconf is called long after “.diff.gz” file has been generated

MERGE TRANSLATIONS AND ORIGINAL
You have to make sure that when your package is compiled, translations will get into the built package. You can do that manually, or automatically using the
dh_installdebconf script (make sure to have a versionned build dependency against “debhelper (>= 4.1.16)”).

To do that manually, you’ll have to merge the templates and the translations at compile time (and to have a build depend against “po-debconf”) like this:

$ po2debconf debian/templates > debian/tmp/DEBIAN/templates

BE CAREFUL: the two files called templates are not the same at all.  The first one contains only the English text, and mark some fields to be translated while the
second contains all languages.  That is to say that you CANNOT keep only the merged templates, or you won’t be able to deal with translations as people submit them
to you.

NEW MASTER TEMPLATES
The new templates file source format is almost identical to one of distributed templates files, but translatable fields are prepended with an underscore.  Example:

Template: debconf/frontend
Type: select
_Choices: Dialog, Readline, Gnome, Editor, Noninteractive
Default: Dialog
_Description: Interface to use for configuring packages:
Packages that use debconf for configuration share a common look and
feel.  You can select the type of user interface they use.
.
The dialog frontend is a full-screen, character based interface,
while the readline frontend uses a more traditional plain text
interface, and the gnome frontend is a modern X interface.  The
editor frontend lets you configure things using your favorite text
editor. The noninteractive frontend never asks you any questions.

SPLITTING CHOICES LIST
Since “po-debconf” 0.6.0, localized fields may contain two leading underscores.  In this case, field value is supposed to be a comma separated list of values, which
are put in separate msgids.  Thus if the previous example did contain

__Choices: Dialog, Readline, Gnome, Editor, Noninteractive

there would be 5 different msgids.  Note that spaces after commas are not significant.

Basically when a choices list never changes, “_Choices” is fine, but otherwise “__Choices” will ease translator’s life.

Unfortunately if you decide to switch between these two forms, all translations become fuzzy.  Here is an explanation to make this change without translation loss
(it requires “po-debconf” >= 1.0).  Suppose that we want to switch the previous example to “__Choices”.  You copy the templates file into a temporary file.

$ cp debian/templates debian/foo

Edit debian/foo and keep only “Template”, “Type” and “_Choices” fields, which are in this example

Template: debconf/frontend
Type: select
_Choices: Dialog, Readline, Gnome, Kde, Editor, Noninteractive

Run debconf-gettextize with “–merge” and “–choices” flags to build PO files as if “__Choices” was written, and merge these PO files to existing ones:

$ debconf-gettextize –merge –choices debian/foo

Eventually you have to remove foo and manually edit debian/templates to replace “_Choices” by “__Choices” before debconf-updatepo is run.

PUTTING COMMENTS FOR TRANSLATORS

“Dpkg” maintainers decided that by convention lines beginning with a number sign (”#”) are comments in debian/control files, and “po-debconf” follows this rule.
Since “po-debconf” 0.8.0, such comments are written into PO files, and can then contain valuable informations for translators.  Incidentally all previous “po-deb‐
conf” versions ignore lines which do not contain a colon, thus if your comments does not contain any colon, there is no need to add a versioned build dependency
against “po-debconf”.  Here is an example:

Template: debconf/button-yes
Type: text
# Translators, this text will appear on a button, so KEEP IT SHORT
_Description: Yes

Special comments have been introduced in “po-debconf” 1.0 to deal with strings which are composed of several items (as with Choices field) or paragraphs (like
Description).  With these directives, developers have a better control over what is exposed to translators.  They are in the form “#flag:directive”; directives are
detailed below.
translate:spec, translate!:spec
Mark only some items as translatable; spec is a comma separated list of numbers, it specifies which strings will be printed into PO files.  Ranges can also be
defined via a minus sign (for instance “2-6″), and a star (”*”) means all strings.  For instance, with

Template: partman-basicfilesystems/fat_mountpoint
Type: select
#flag:translate:3,4
__Choices: /dos, /windows, Enter manually, Do not mount it
_Description: Mount point for this partition:

“Enter manually” and “Do not mount it” will appear in PO files but not “/dos” and “/windows”.  When an exclamation mark follows the translate keyword, spec speci‐
fies which strings will be discarded from PO files, all other strings are printed.  Previous example is similar to

Template: partman-basicfilesystems/fat_mountpoint
Type: select
#flag:translate!:1,2
__Choices: /dos, /windows, Enter manually, Do not mount it
_Description: Mount point for this partition:

The same keyword can also be applied to the Description field to make sure that some strings are not translated.

Template: partman-crypto/options_missing
Type: error
#flag:translate!:3
_Description: Required encryption options missing
The encryption options for ${DEVICE} are incomplete. Please
return to the partition menu and select all required options.
.
${ITEMS}

But this is hazardous because context may be dropped from PO files, please add comments in this case so that translators are not confused.

comment:spec, comment!:spec
The comment just below this directive applies to the strings specified by spec, which is defined above.  By default, a comment written before a translatable field
is printed along with all strings belonging to this field.  (Note: with “po-debconf” < 1.0, the comment was written only with the first string)

Template: arcboot-installer/prom-variables
Type: note
# Translators, the 4th string of this description has been dropped
# from PO files.  It contains shell commands and should not be
# translated.
#flag:comment:3
# “Stop for Maintenance” should be left in English
#flag:translate!:4
_Description: Setting PROM variables for Arcboot
If this is the first Linux installation on this machine, or if the
hard drives have been repartitioned, some variables need to be set
in the PROM before the system is able to boot normally.
.
At the end of this installation stage, the system will reboot.
After this, enter the command monitor from the “Stop for
Maintenance” option, and enter the following commands:
.
setenv OSLoader arcboot
setenv OSLoadFilename Linux
.
You will only need to do this once.  Afterwards, enter the “boot”
command or reboot the system to proceed to the next stage of the
installation.

The example above has a comment without “#flag:comment” directive, an implicit “#flag:comment:*” is added.  This comment appears with all strings, but the one
about Stop for Maintenance is printed only before the relevant string.

partial
This keyword tells po2debconf to keep translated strings even if all strings have not been translated.  Please use with caution, this keyword has been introduced
for very specific purposes.

GIVING NOTICES TO TRANSLATORS BEFORE UPLOADING

Usually translators notice on the status web pages (see below) that translations are outdated, and send patches which will be included in future uploads.  But devel‐
opers are encouraged to send outdated files to translators before an upload, for instance one week in advance.  A dedicated tool, podebconf-report-po, has been
written for this purpose.  Do not hesitate to abuse it!

CAVEATS
· “Debconf” 1.2.0 recognizes fields in the form Name-lang.encoding, e.g.  “Description-de.ISO-8859-1″ or “Choices-ru.KOI8-R”.  By default po2debconf writes templates
files in that new format.  Older “debconf” will ignore these fields, and English text is displayed.  See po2debconf(1) to know how to change encoding and output
format.

· A given English string may have only one unique translation in a given language.  It is impossible to give two different translations, depending on the context.
To solve this issue, you have to add special markups to the different occurrences of a given string to make them different.  (These markers will only be visible to
translators, and they will be removed from the string before being displayed to user)

Such markers must be added to the end of the strings to translate, they must start with “[ " (a left bracket followed by a space) and end with "]” (right bracket),
and may contain any character but brackets or new lines. For example “[ blahblah]” is a valid marker while “[ bla[bla]bla]” isn’t. For Perl regexp addicts, the
markers are recognized (and removed) using this rule:

$msg =~ s/\[\s[^\[\]]*\]$//s;

· Spacing is not handled exactly the same way by “po-debconf” and “debconf-utils”; with the latter, paragraphs are reformatted when updating and merging transla‐
tions, so “debconf-utils” is very smart and spaces are not considered as being part of strings when determining fuzzy entries.  (ie, the ones needing translator’s
attention because the original changed)

On the other hand “po-debconf” relies on “gettext” to detect fuzzy entries, and it does not treat spaces as special characters.  Thus superfluous spaces must be
removed at end of lines in master templates files, or they will appear in PO and POT files.

For the same reason, debconf-gettextize can mark fuzzy text because of mismatch with space characters, and translators have to manually unfuzzy such strings.  This
only happens once when converting templates to “po-debconf” format, unless you randomly change spaces in master templates files, which will be painful for transla‐
tors.

· Normally the Default: field must not be translated when template type is Select or Multiselect. Under rare circumstances (e.g. when selecting the default language
for an application) localized values may be meaningful.

The localized value must not be translated, but chosen from the English values listed in the Choices field.  The best way to achieve this goal is to insert a com‐
ment in your templates file which will be copied into PO files.

Template: geneweb/lang
Type: select
__Choices: Danish (da), Dutch (nl), English (en), Esperanto (eo)
#  You must NOT translate this string, but you can change its value.
#  The comment between brackets is used to distinguish this msgid
#  from the one in the Choices list; you do not have to worry about
#  them, and have to simply choose a msgstr among the English values
#  listed in the Choices field above, e.g. msgstr “Dutch (nl)”
_Default: English (en)[ default language]
_Description: Geneweb default language
The default value also apears in the Choices field, and both have different translations: the former is an untranslated value chosen among Choices values, whereas
the latter is a normal translation.  As “gettext” cannot hae two different translations for the same msgid, both msgids must be different by using bracketed com‐
ments as described in a previous subsection.

Prior to “po-debconf” 0.8.0, such comments were not available and maintainers had to replace the _Default: field by _DefaultChoice: in order to highlight such
fields in PO files:

#. DefaultChoice
msgid “”
“English[ default: do not translate bracketed material, put your "
"own language here but UNTRANSLATED.  If it is not in the list, "
"put English (without bracketed material)]”
msgstr “”
“Swedish”

Plain comments in templates files are less error prone and are encouraged.

STATUS WEB PAGES
Statistics for “po-debconf” translations are available at <http://www.debian.org/intl/l10n/po-debconf/> (or from mirrors); they are automatically updated when new
packages are uploaded.  Only packages shipping debian/po/templates.pot and debian/po/POTFILES.in files are considered, so you should make sure your source package do
provide them.

Translators can grab PO and POT files from there, but they must always get in touch with the previous translator (her mail address can be found in the PO file)
and/or their fellow translators on debian-l10n-<language>@lists.debian.org (if such a list does exist) to make sure that noone is currently working on the same
translation, and read current bugreports against the package they are going to translate to see if a translation has already been reported.

After translating these files, they should submit their work to the maintainer as bug report of severity minor with the patch tag.

SEE ALSO
debconf-gettextize(1), debconf-updatepo(1), dh_installdebconf(1), podebconf-report-po(1).  po2debconf(1).

AUTHORS
Martin Quinson <Martin.Quinson@ens-lyon.fr>
Denis Barbier <barbier@linuxfr.org>

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 itemsis 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 chose 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, and even mailing the note to them in some cases. It’s best to use these only for warning about very serious problems.
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.
title
This datatype is used for titles, to be set with the SETTITLE command.

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 displays 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 genrally free form and unspecified, so you should generally ignore it, and should certianly 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.
TITLE string
This sets the title debconf displays to the user. You rarely need to use this commands since debconf can automatically generate a title based on your package’s name.
SETTITLE question
This sets the title to the short description of the template for the specified question. The template should be of type title. The advantage this has over the TITLE command is that it allows for titles to be stored in the same place as the rest of the debconf questions, and allows them to be translated.
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 question 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, and 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 explicitely 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 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 the 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. 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(3) 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 removed, 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 sources /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, stand alone 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 of 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 supsesceded by the po-debconf 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 README file. 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-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 PROGRAMING 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

a 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=’ || echo “FOO=” >> $CONFIGFILE
test -z “$BAR” || grep -Eq ‘^ *BAR=’ || 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" = "false" ]; 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 1 ]; 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
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 [ "
" = "$RET" ] ; then

db_fset shared/window-manage 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/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 variable.
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

Index

NAME
DESCRIPTION
THE CONFIG SCRIPT
THE TEMPLATES FILE
QUESTIONS
SHARED TEMPLATES
THE DEBCONF PROTOCOL
LIBRARIES
THE POSTINST SCRIPT
OTHER SCRIPTS
LOCALIZATION
PUTTING IT ALL TOGETHER
DEBUGGING
ADVANCED PROGRAMING WITH DEBCONF

Config file handling
Letting the user back up
Preventing infinite loops
Choosing among related packages

HACKS
SEE ALSO
AUTHOR

This document was created by man2html, using the manual pages.
Time: 12:23:17 GMT, February 12, 2009