.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "DH_CME_UPGRADE 1p" .TH DH_CME_UPGRADE 1p "2020-07-18" "perl v5.30.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" dh_cme_upgrade \- add cme based configuration merge .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& dh_cme_upgrade [ debhelper options ] [ \-p pkg ] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBdh_cme_upgrade is experimental\fR .PP 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. .PP Configuration information used by cme for upgrade are specified in a configuration file (see below) .PP Configuration information is specified in a configuration model. It must be provided by another package like \&\f(CW\*(C`libconfig\-model\-lcdproc\-perl\*(C'\fR .SH "REQUIREMENTS" .IX Header "REQUIREMENTS" For this program to work, package maintainer must make sure that: .IP "\(bu" 4 \&\f(CW\*(C`*.postinst\*(C'\fR, \f(CW\*(C`*.postrm\*(C'\fR and \f(CW\*(C`*.config\*(C'\fR have a \f(CW\*(C`#DEBHELPER#\*(C'\fR line (if these files exist) .IP "\(bu" 4 \&\f(CW\*(C`control\*(C'\fR file has a dependency on \f(CW\*(C`${misc:Depends}\*(C'\fR .IP "\(bu" 4 Configuration files upgraded by \f(CW\*(C`cme\*(C'\fR must not be conffiles. Any default configuration file provided by upstream must not be installed directly in \f(CW\*(C`/etc\*(C'\fR. They should be installed in \f(CW\*(C`/usr/share/doc/\*(C'\fR for reference. \f(CW\*(C`cme\*(C'\fR will create a default configuration file during package installation. .SH "OPTIONS" .IX Header "OPTIONS" This program accepts all debhelper options, including the \f(CW\*(C`\-p\*(C'\fR option to specify which package(s) to act on. .SH "Usage" .IX Header "Usage" \&\f(CW\*(C`dh_cme_upgrade\*(C'\fR is designed be called in the rules file via the dh command: .PP .Vb 2 \& %: \& dh \-\-with cme_upgrade .Ve .PP No options can be passed to \f(CW\*(C`dh_cme_upgrade\*(C'\fR. Its configuration must be specified in \f(CW\*(C`debian/*.config_model\*(C'\fR file. This file contains several lines, each in the form of \*(L"key: value\*(R". .PP Here are the possible keys: .IP "cme-app-name" 4 .IX Item "cme-app-name" Specifies the application or model name (X la \f(CW\*(C`Config::Model\*(C'\fR) that will be used to perform the upgrade. (mandatory) .IP "cme-model-package" 4 .IX Item "cme-model-package" Specifies the debian package that provide the model specified by \&\f(CW\*(C`cme\-app\-name\*(C'\fR. (mandatory) .IP "cme-model-version" 4 .IX Item "cme-model-version" Specifies the minimal version of the package that provides the model. (optional) .IP "cme-command" 4 .IX Item "cme-command" Specify the command passed to cme. Defaults to \f(CW\*(C`migrate\*(C'\fR. Another useful value is \f(CW\*(C`fix\*(C'\fR which will migrate and fix the configuration file. .IP "cme-options" 4 .IX Item "cme-options" Specify a list of options or command that will be passed verbatim to cme during upgrade. (optional) .IP "cme-purge" 4 .IX Item "cme-purge" Specify the configuration files or directory to be removed when purging the package. E.g \&\f(CW\*(C`/etc/LCDd.conf*\*(C'\fR or \f(CW\*(C`/etc/java/\*(C'\fR. 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. .IP "cme-conf-target" 4 .IX Item "cme-conf-target" Specifies where the target configuration files is expected. Defaults to \&\f(CW\*(C`/etc\*(C'\fR. 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 \f(CW\*(C`/usr/share/doc/package_name\*(C'\fR) and where to copy it (in \&\f(CW\*(C`/cme\-conf\-target\*(C'\fR). .PP Alternatively, since cme/1.030\-1 you can just build depend on \&\fBdh-sequence-cme-upgrade\fR and omit the \f(CW\*(C`\-\-with cme_upgrade\*(C'\fR part. .SH "Examples" .IX Header "Examples" Here's a possible configuration for openssh server: .PP .Vb 4 \& $ cat debian/openssh\-server.config\-model \& cme\-app\-name: sshd \& cme\-model\-package: lib\-config\-model\-openssh\-perl \& cme\-model\-version: 1.206 .Ve .PP For lcdproc: .PP .Vb 7 \& $ 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* .Ve .PP For Popcon: .PP .Vb 3 \& $ cat debian/popcon.config\-model \& cme\-app\-name: popcon \& cme\-model\-package: libconfig\-model\-perl .Ve .SH "debian files setup" .IX Header "debian files setup" \&\f(CW\*(C`dh_cme_upgrade\*(C'\fR will work only if: .IP "\(bu" 4 \&\f(CW\*(C`control\*(C'\fR file contains a \f(CW\*(C`${misc:Depends}\*(C'\fR variable in \f(CW\*(C`Depends\*(C'\fR line .IP "\(bu" 4 If present, \f(CW\*(C`postinst\*(C'\fR script contains a \f(CW\*(C`#DEBHELPER#\*(C'\fR line to insert generated postinst snippet .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" This program will \fBexit\fR\|(0) if \f(CW\*(C`DH_NO_ACT\*(C'\fR is set or if \f(CW\*(C`DEB_BUILD_OPTIONS\*(C'\fR contains \f(CW\*(C`noconfigmodel\*(C'\fR. .SH "SEE ALSO" .IX Header "SEE ALSO" debhelper .PP This program is an addendum to debhelper (part of libconfig-model-perl). .SH "AUTHOR" .IX Header "AUTHOR" Dominique Dumont