DOKK / manpages / debian 10 / cme / dh_cme_upgrade.1p.en
DH_CME_UPGRADE(1p) User Contributed Perl Documentation DH_CME_UPGRADE(1p)

dh_cme_upgrade - add cme based configuration merge

 dh_cme_upgrade [ debhelper options ] [ -p pkg ]

dh_cme_upgrade is experimental

dh_cme_upgrade is a debhelper that will modify the package script to merge configuration on package upgrade. This merge is based on cme from Config::Model and will merge user's customisations with maintainer's configuration updates. This provides another way to preserve users modifications during upgrades.

Configuration information used by cme for upgrade are specified in a configuration file (see below)

Configuration information is specified in a configuration model. It must be provided by another package like "libconfig-model-lcdproc-perl"

For this program to work, package maintainer must make sure that:

  • "*.postinst", "*.postrm" and "*.config" have a "#DEBHELPER#" line (if these files exist)
  • "control" file has a dependency on "${misc:Depends}"
  • Configuration files upgraded by "cme" must not be conffiles. Any default configuration file provided by upstream must not be installed directly in "/etc". They should be installed in "/usr/share/doc/" for reference. "cme" will create a default configuration file during package installation.

This program accepts all debhelper options, including the "-p" option to specify which package(s) to act on.

"dh_cme_upgrade" is designed be called in the rules file via the dh command:

 %:
   dh --with cme_upgrade

No options can be passed to "dh_cme_upgrade". Its configuration must be specified in "debian/*.config_model" file. This file contains several lines, each in the form of "key: value".

Here are the possible keys:

Specifies the application or model name (X la "Config::Model") that will be used to perform the upgrade. (mandatory)
Specifies the debian package that provide the model specified by "cme-app-name". (mandatory)
Specifies the minimal version of the package that provides the model. (optional)
Specify the command passed to cme. Defaults to "migrate". Another useful value is "fix" which will migrate and fix the configuration file.
Specify a list of options or command that will be passed verbatim to cme during upgrade. (optional)
Specify the configuration files or directory to be removed when purging the package. E.g "/etc/LCDd.conf*" or "/etc/java/". Several files or directory can be purged by using a shell glob. If this option is empty, configuration files handled by cme will be left as-is after a purge.
Specifies where the target configuration files is expected. Defaults to "/etc". This parameter is used to create a message to inform user who don't want automatic upgrade where to find the original configuration file (in "/usr/share/doc/package_name") and where to copy it (in "/cme-conf-target").

Here's a possible configuration for openssh server:

 $ cat debian/openssh-server.config-model
 cme-app-name: sshd
 cme-model-package: lib-config-model-openssh-perl
 cme-model-version: 1.206

For lcdproc:

 $ cat debian/lcdproc.config-model
 cme-app-name: lcdproc
 cme-package: libconfig-model-lcdproc-perl
 cme-model-version: 2.040
 # required to upgrade LCDd.conf from upstream configuration
 cme-options: -force
 cme-purge: /etc/LCDd.conf*

For Popcon:

 $ cat debian/popcon.config-model
 cme-app-name: popcon
 cme-model-package: libconfig-model-perl

"dh_cme_upgrade" will work only if:

  • "control" file contains a "${misc:Depends}" variable in "Depends" line
  • If present, "postinst" script contains a "#DEBHELPER#" line to insert generated postinst snippet

This program will exit(0) if "DH_NO_ACT" is set or if "DEB_BUILD_OPTIONS" contains "noconfigmodel".

debhelper

This program is an addendum to debhelper (part of libconfig-model-perl).

Dominique Dumont <dod@debian.org>

2018-08-28 perl v5.26.2