Translation(s): none

This page contains a proposal for a way to handle upgrades where a user's data and the package maintainer data are merged with minimal interaction with user. The package approx will be used as an example.

Configuration upgrade by package


Automatic configuration merge is provided with lcdproc >= 0.5.6


For a casual user (like you mother-in-law or your neighbor), the questions asked during package upgrades can be intimidating. Casual users barely know that some files exist outside of their home directory and are completely lost when looking at the /etc directory. Unfortunately, during package upgrade, user is faced with cryptic questions whether to keep his configuration, use the maintainers configuration or look at a diff. The casual user will seldom know what to do in this case.

This situation can be made worse if user's configuration was edited with a tool (e.g. cups configuration is edited through a web browser): the user has no knowledge of the syntax of the configuration file.

This proposal aims to provide a way for Debian package to minimize the number of questions raised to the user when upgrading packages. If questions are necessary, an interface will be provided to the user. Hopefully, manual editing of configuration files will not be necessary.

Upgrades with cme and Config::Model

cme and Config-Model provide a framework for editing and validating the content of any configuration file or data. With a configuration model (expressed in a data structure), Config-Model provides a user interface and a tool to validate configuration.

A typical configuration model contains the following specifications :

This notion of default value versus built-in default value is important to distinguish:

  1. the values that were customized by the user (or sysadmin)
  2. the value that are recommended by the package maintainer (and specified as default in the model)

  3. the value that are provided upstream (specified as upstream_default)

When creating a model just for upgrades, a model does not need to feature:

During a package upgrade we want to:

So the idea is:

The same principles can be applied to downgrade with some limitations (see below for more details)

Apply configuration upgrade using an existing model: lcdproc example

This is a real use case implemented for lcdproc

Current lcdproc situation

Up to version 0.5.5, lcdproc is shipped with several configuration files, including /etc/LCDd.conf. This file is modified upstream at every lcdproc release to bring configuration for new lcdproc drivers. On the other hand, this file is always customized to suit the specific hardware of the user's system. So upgrading a package will *always* lead to a conflict during upgrade. User will always be required to choose whether to use current version or upstream version.

libconfig-model-lcdproc-perl provides a configuration model for lcdproc. This blog explains how this model is generated from upstream LCDd.conf. But this is off topic for this page.

What will change for user

When lcdproc is upgraded to the new version featuring automatic upgrade, the following changes will be visible: * lcdproc will depend on libconfig-model-lcdproc-perl * user will be asked *once* by debconf whether to use automatic configuration upgrades or not. * no further question will be asked (no ucf style questions).

Note: the automatic upgrade currently applies only to LCDd.conf. The other configuration files of lcdproc are handled the usual way.

lcdproc package changes for automatic upgrades

lcdproc package was changed the following way:

This file contains the following lines:

For more information, see dh_cme_upgrade man page.

If you want to apply config-model based upgrades to your favorite package

lcdproc did start from an existing configuration model. Let's see what is required to create a minimal configuration model so that your package can also feature automatic configuration upgrade.

You will have to:

Well, that was the theory. Let's experiment with Approx configuration file and work out the details.

Approx example

configuration analysis

From approx.conf(5) man page, we find that approx has a very simple configuration. Approx will need one configuration class that will have:

The syntax of approx.conf is fairly simple but there's no Perl module available to read and write it. A dedicated parser/writer will be required. I.e. a Perl class that will inherit Well, you can cheat and look at the source of the actual Approx backend.

Upgrade scenario

For the sake of the example, let's assume that offline parameter was named nointernet in previous versions of Approx. This is of course not true. Apologies to Eric Cooper for such a ludicrous idea.

So the upgrade model must feature:

Approx configuration model

To create the Approx configuration model, you can use the GUI provided by libconfig-model-itself-perl.

In a empty directory, run config-edit-model -model Approx and fill the fields as required.

You will have to:

In the end you will get :

  'name' => 'Approx',
  => [
      nointernet => { type => 'leaf', value_type => 'boolean', status => 'deprecated' },
      offline    => { type => 'leaf', value_type => 'boolean', 
                      migrate_from => {
                                        variables => { old => '- nointernet' } ,
                                        formula => '$old', 
      'distributions', { type => 'hash', index_type => 'string' ,
                         cargo => { value_type => 'uniline', type => 'leaf',},
  'accept' => [
      '.*'  => { type => 'leaf', value_type => 'uniline',                      },
] ;

You can view the actual model on Approx model on github. This model is more complex as all parameters and help text are provided.

/!\ Any Debian specific requirement (e.g. default value) will have to be implemented in the model and not in the template configuration file provided to the user (e.g. not in /etc/approx/approx.conf)

Configuraion upgrade during package upgrade

This can use modification similar to the lcdproc example shown above.

cme commands to manage configuration upgrade

For reference, cme can also be used outside of package script to manually migrate a configuration file. These commands are not specific to Debian and can be applied to other distros or OS.

Let's start with a simple approx.conf file:

$max_wait       12

In most cases, simply running cme migrate will be enough to upgrade a configuration files. Even if the configuration model is changed from package version N to version N+1, the upgrade will work most to the time. cme will exit on error if some data to upgrade are not recognized.

   cme migrate approx

cme will:

After upgrade, approx.conf has:

# This file was written by Config::Model with Approx model
# You may modify the content of this file. Configuration
# modification will be preserved. 

$max_wait   12


If you want to keep a backup of the old configuration file, you can run cme migrate approx -backup. The old configuration will be in approx.conf.old

Working with Debconf

Warning: just a bunch of ideas, no working implementation

Main ideas:

Fortunately, the semantic of Config::Model value_type mostly matches debconf's type:


CategoryDeveloper CategoryPackaging