diff options
Diffstat (limited to '')
| -rw-r--r-- | man/dpkg-maintscript-helper.pod | 326 |
1 files changed, 326 insertions, 0 deletions
diff --git a/man/dpkg-maintscript-helper.pod b/man/dpkg-maintscript-helper.pod new file mode 100644 index 0000000..7e2953a --- /dev/null +++ b/man/dpkg-maintscript-helper.pod @@ -0,0 +1,326 @@ +# dpkg manual page - dpkg-maintscript-helper(1) +# +# Copyright © 2010-2012 Raphaël Hertzog <hertzog@debian.org> +# Copyright © 2011-2015 Guillem Jover <guillem@debian.org> +# +# This is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see <https://www.gnu.org/licenses/>. + +=encoding utf8 + +=head1 NAME + +dpkg-maintscript-helper - works around known dpkg limitations in maintainer scripts + +=head1 SYNOPSIS + +B<dpkg-maintscript-helper> +I<command> [I<parameter>...] B<--> I<maint-script-parameter>... + +=head1 COMMANDS AND PARAMETERS + +=over + +=item B<supports> I<command> + +=item B<rm_conffile> I<conffile> [I<prior-version> [I<package>]] + +=item B<mv_conffile> I<old-conffile> I<new-conffile> [I<prior-version> [I<package>]] + +=item B<symlink_to_dir> I<pathname> I<old-target> [I<prior-version> [I<package>]] + +=item B<dir_to_symlink> I<pathname> I<new-target> [I<prior-version> [I<package>]] + +=back + +=head1 DESCRIPTION + +This program is designed to be run within maintainer scripts to achieve +some tasks that B<dpkg> can't (yet) handle natively either because of +design decisions or due to current limitations. + +Many of those tasks require coordinated actions from several maintainer +scripts (B<preinst>, B<postinst>, B<prerm>, B<postrm>). To +avoid mistakes the same call simply needs to be put in all scripts and the +program will automatically adapt its behaviour based on the environment +variable B<DPKG_MAINTSCRIPT_NAME> and on the maintainer scripts arguments +that you have to forward after a double hyphen. + +=head1 COMMON PARAMETERS + +=over + +=item I<prior-version> + +Defines the latest version of the package whose upgrade should trigger the +operation. It is important to calculate I<prior-version> correctly so +that the operations are correctly performed even if the user rebuilt the +package with a local version. If I<prior-version> is empty or omitted, +then the operation is tried on every upgrade (note: it's safer to give +the version and have the operation tried only once). + +If the conffile has not been shipped for several versions, and you are +now modifying the maintainer scripts to clean up the obsolete file, +I<prior-version> should be based on the version of the package that +you are now preparing, not the first version of the package that lacked +the conffile. This applies to all other actions in the same way. + +For example, for a conffile removed in version B<2.0-1> of a package, +I<prior-version> should be set to B<2.0-1~>. This will cause the +conffile to be removed even if the user rebuilt the previous version +B<1.0-1> as B<1.0-1local1>. Or a package switching a path from +a symlink (shipped in version B<1.0-1>) to a directory (shipped in +version B<2.0-1>), but only performing the actual switch in the +maintainer scripts in version B<3.0-1>, should set I<prior-version> +to B<3.0-1~>. + +=item I<package> + +The package name owning the pathname(s). +When the package is “Multi-Arch: same” this parameter +must include the architecture qualifier, otherwise it should B<not> +usually include the architecture qualifier (as it would disallow +cross-grades, or switching from being architecture specific to +architecture B<all> or vice versa). +If the parameter is empty or omitted, the B<DPKG_MAINTSCRIPT_PACKAGE> +and B<DPKG_MAINTSCRIPT_ARCH> environment variables (as set by B<dpkg> +when running the maintainer scripts) will be used to generate an +arch-qualified package name. + +=item B<--> + +All the parameters of the maintainer scripts have to be forwarded to the +program after B<-->. + +=back + +=head1 CONFFILE RELATED TASKS + +When upgrading a package, B<dpkg> will not automatically remove a conffile +(a configuration file for which B<dpkg> should preserve user changes) if +it is not present in the newer version. There are two principal reasons for +this; the first is that the conffile could've been dropped by accident and +the next version could restore it, users wouldn't want their changes +thrown away. The second is to allow packages to transition files from a +dpkg-maintained conffile to a file maintained by the package's maintainer +scripts, usually with a tool like debconf or ucf. + +This means that if a package is intended to rename or remove a conffile, +it must explicitly do so and B<dpkg-maintscript-helper> can be used +to implement graceful deletion and moving of conffiles within maintainer +scripts. + +=head2 Removing a conffile + +Note: This can be replaced in most cases by the C<remove-on-upgrade> +flag in F<DEBIAN/conffiles> (since dpkg 1.20.6), see L<deb-conffiles(5)>. + +If a conffile is completely removed, it should be removed from disk, +unless the user has modified it. If there are local modifications, they +should be preserved. If the package upgrades aborts, the newly obsolete +conffile should not disappear. + +All of this is implemented by putting the following shell snippet in the +B<preinst>, B<postinst> and B<postrm> maintainer scripts: + +=over + +Z<> + dpkg-maintscript-helper rm_conffile \ + I<conffile> I<prior-version> I<package> -- "$@" + +=back + +I<conffile> is the filename of the conffile to remove. + +Current implementation: in the B<preinst>, it checks if the conffile +was modified and renames it either to I<conffile>B<.dpkg-remove> (if not +modified) or to I<conffile>B<.dpkg-backup> (if modified). In the +B<postinst>, the latter file is renamed to I<conffile>B<.dpkg-bak> +and kept for reference as it contains user modifications but the former will +be removed. If the package upgrade aborts, the B<postrm> reinstalls the +original conffile. During purge, the B<postrm> will also delete the +B<.dpkg-bak> file kept up to now. + +=head2 Renaming a conffile + +If a conffile is moved from one location to another, you need to make sure +you move across any changes the user has made. This may seem a simple +change to the B<preinst> script at first, however that will result in +the user being prompted by B<dpkg> to approve the conffile edits even +though they are not responsible of them. + +Graceful renaming can be implemented by putting the following shell +snippet in the B<preinst>, B<postinst> and B<postrm> maintainer +scripts: + +=over + +Z<> + dpkg-maintscript-helper mv_conffile \ + I<old-conffile> I<new-conffile> I<prior-version> I<package> -- "$@" + +=back + +I<old-conffile> and I<new-conffile> are the old and new name of the +conffile to rename. + +Current implementation: the B<preinst> checks if the conffile has been +modified, if yes it's left on place otherwise it's renamed to +I<old-conffile>B<.dpkg-remove>. On configuration, the B<postinst> +removes I<old-conffile>B<.dpkg-remove> and renames I<old-conffile> +to I<new-conffile> if I<old-conffile> is still available. On +abort-upgrade/abort-install, the B<postrm> renames +I<old-conffile>B<.dpkg-remove> back to I<old-conffile> if required. + +=head1 SYMLINK AND DIRECTORY SWITCHES + +When upgrading a package, B<dpkg> will not automatically switch a symlink +to a directory or vice-versa. Downgrades are not supported and the path +will be left as is. + +=head2 Switching a symlink to directory + +If a symlink is switched to a real directory, you need to make sure +before unpacking that the symlink is removed. This may seem a simple +change to the B<preinst> script at first, however that will result +in some problems in case of admin local customization of the symlink +or when downgrading the package. + +Graceful renaming can be implemented by putting the following shell +snippet in the B<preinst>, B<postinst> and B<postrm> maintainer +scripts: + +=over + +Z<> + dpkg-maintscript-helper symlink_to_dir \ + I<pathname> I<old-target> I<prior-version> I<package> -- "$@" + +=back + +I<pathname> is the absolute name of the old symlink (the path will be a +directory at the end of the installation) and I<old-target> is +the target name of the former symlink at I<pathname>. It can either be +absolute or relative to the directory containing I<pathname>. + +Current implementation: the B<preinst> checks if the symlink exists +and points to I<old-target>, if not then it's left in place, otherwise +it's renamed to I<pathname>B<.dpkg-backup>. On configuration, +the B<postinst> removes I<pathname>B<.dpkg-backup> if +I<pathname>B<.dpkg-backup> is still a symlink. On +abort-upgrade/abort-install, the B<postrm> renames +I<pathname>B<.dpkg-backup> back to I<pathname> if required. + +=head2 Switching a directory to symlink + +If a real directory is switched to a symlink, you need to make sure +before unpacking that the directory is removed. This may seem a simple +change to the B<preinst> script at first, however that will result +in some problems in case the directory contains conffiles, pathnames +owned by other packages, locally created pathnames, or when downgrading +the package. + +Graceful switching can be implemented by putting the following shell +snippet in the B<preinst>, B<postinst> and B<postrm> maintainer +scripts: + +=over + +Z<> + dpkg-maintscript-helper dir_to_symlink \ + I<pathname> I<new-target> I<prior-version> I<package> -- "$@" + +=back + +I<pathname> is the absolute name of the old directory (the path +will be a symlink at the end of the installation) and I<new-target> is +the target of the new symlink at I<pathname>. It can either be absolute +or relative to the directory containing I<pathname>. + +Current implementation: the B<preinst> checks if the directory +exists, does not contain conffiles, pathnames owned by other packages, +or locally created pathnames, if not then it's left in place, otherwise +it's renamed to I<pathname>B<.dpkg-backup>, and an empty staging +directory named I<pathname> is created, marked with a file so that +dpkg can track it. On configuration, the B<postinst> finishes the +switch if I<pathname>B<.dpkg-backup> is still a directory and +I<pathname> is the staging directory; it removes the staging directory +mark file, moves the newly created files inside the staging directory +to the symlink target I<new-target>/, replaces the now empty staging +directory I<pathname> with a symlink to I<new-target>, and +removes I<pathname>B<.dpkg-backup>. On +abort-upgrade/abort-install, the B<postrm> renames +I<pathname>B<.dpkg-backup> back to I<pathname> if required. + +=head1 INTEGRATION IN PACKAGES + +When using a packaging helper, please check if it has native +B<dpkg-maintscript-helper> integration, which might make your life +easier. See for example B<dh_installdeb>(1). + +Given that B<dpkg-maintscript-helper> is used in the B<preinst>, +using it unconditionally requires a pre-dependency to ensure that the +required version of B<dpkg> has been unpacked before. The required version +depends on the command used, for B<rm_conffile> and B<mv_conffile> +it is 1.15.7.2, for B<symlink_to_dir> and B<dir_to_symlink> +it is 1.17.14: + +=over + + Pre-Depends: dpkg (>= 1.17.14) + +=back + +But in many cases the operation done by the program is not critical for +the package, and instead of using a pre-dependency we can call the +program only if we know that the required command is supported by +the currently installed B<dpkg>: + +=over + +Z<> + if dpkg-maintscript-helper supports I<command>; then + dpkg-maintscript-helper I<command> ... + fi + +=back + +The command B<supports> will return 0 on success, 1 otherwise. The +B<supports> command will check if the environment variables as set +by dpkg and required by the script are present, and will consider it a +failure in case the environment is not sufficient. + +=head1 ENVIRONMENT + +=over + +=item B<DPKG_ROOT> + +If set, it will be used as the filesystem root directory. + +=item B<DPKG_ADMINDIR> + +If set, it will be used as the B<dpkg> data directory. + +=item B<DPKG_COLORS> + +Sets the color mode (since dpkg 1.19.1). +The currently accepted values are: B<auto> (default), B<always> and +B<never>. + +=back + +=head1 SEE ALSO + +B<dh_installdeb>(1). |