345 lines
14 KiB
HTML
345 lines
14 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of dpkg-maintscript-helper</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>dpkg-maintscript-helper</H1>
|
|
Section: dpkg suite (1)<BR>Updated: 2020-03-23<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
dpkg-maintscript-helper - works around known dpkg limitations in maintainer scripts
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>dpkg-maintscript-helper</B>
|
|
|
|
<I>command</I> [<I>parameter</I>...] <B>--</B> <I>maint-script-parameter</I>...
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>COMMANDS AND PARAMETERS</H2>
|
|
|
|
<P>
|
|
|
|
<B>supports</B> <I>command</I>
|
|
<P>
|
|
|
|
<B>rm_conffile</B> <I>conffile</I> [<I>prior-version</I> [<I>package</I>]]
|
|
<P>
|
|
|
|
<B>mv_conffile</B> <I>old-conffile</I> <I>new-conffile</I> [<I>prior-version</I> [<I>package</I>]]
|
|
<P>
|
|
|
|
<B>symlink_to_dir</B> <I>pathname</I> <I>old-target</I> [<I>prior-version</I> [<I>package</I>]]
|
|
<P>
|
|
|
|
<B>dir_to_symlink</B> <I>pathname</I> <I>new-target</I> [<I>prior-version</I> [<I>package</I>]]
|
|
<A NAME="lbAE"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<P>
|
|
|
|
This program is designed to be run within maintainer scripts to achieve
|
|
some tasks that <B>dpkg</B> can't (yet) handle natively either because of
|
|
design decisions or due to current limitations.
|
|
<P>
|
|
|
|
Many of those tasks require coordinated actions from several maintainer
|
|
scripts (<B>preinst</B>, <B>postinst</B>, <B>prerm</B>, <B>postrm</B>). 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</B> and on the maintainer scripts arguments
|
|
that you have to forward after a double hyphen.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>COMMON PARAMETERS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="1"><I>prior-version</I>
|
|
|
|
<DD>
|
|
Defines the latest version of the package whose upgrade should trigger the
|
|
operation. It is important to calculate <I>prior-version</I> correctly so
|
|
that the operations are correctly performed even if the user rebuilt the
|
|
package with a local version. If <I>prior-version</I> 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).
|
|
<P>
|
|
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</I> 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.
|
|
<P>
|
|
For example, for a conffile removed in version <B>2.0-1</B> of a package,
|
|
<I>prior-version</I> should be set to <B>2.0-1~</B>. This will cause the
|
|
conffile to be removed even if the user rebuilt the previous version
|
|
<B>1.0-1</B> as <B>1.0-1local1</B>. Or a package switching a path from
|
|
a symlink (shipped in version <B>1.0-1</B>) to a directory (shipped in
|
|
version <B>2.0-1</B>), but only performing the actual switch in the
|
|
maintainer scripts in version <B>3.0-1</B>, should set <I>prior-version</I>
|
|
to <B>3.0-1~</B>.
|
|
<DT id="2"><I>package</I>
|
|
|
|
<DD>
|
|
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</B>
|
|
usually include the architecture qualifier (as it would disallow
|
|
cross-grades, or switching from being architecture specific to
|
|
architecture <B>all</B> or vice versa).
|
|
If the parameter is empty or omitted, the <B>DPKG_MAINTSCRIPT_PACKAGE</B>
|
|
and <B>DPKG_MAINTSCRIPT_ARCH</B> environment variables (as set by <B>dpkg</B>
|
|
when running the maintainer scripts) will be used to generate an
|
|
arch-qualified package name.
|
|
<DT id="3"><B>--</B>
|
|
|
|
<DD>
|
|
All the parameters of the maintainer scripts have to be forwarded to the
|
|
program after <B>--</B>.
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>CONFFILE RELATED TASKS</H2>
|
|
|
|
<P>
|
|
|
|
When upgrading a package, <B>dpkg</B> will not automatically remove a conffile
|
|
(a configuration file for which <B>dpkg</B> 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.
|
|
<P>
|
|
|
|
This means that if a package is intended to rename or remove a conffile,
|
|
it must explicitly do so and <B>dpkg-maintscript-helper</B> can be used
|
|
to implement graceful deletion and moving of conffiles within maintainer
|
|
scripts.
|
|
<A NAME="lbAH"> </A>
|
|
<H3>Removing a conffile</H3>
|
|
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
All of this is implemented by putting the following shell snippet in the
|
|
<B>preinst</B>, <B>postinst</B> and <B>postrm</B> maintainer scripts:
|
|
<P>
|
|
|
|
<BR> dpkg-maintscript-helper rm_conffile \
|
|
<BR> <I>conffile</I> <I>prior-version</I> <I>package</I> -- "$@"
|
|
<P>
|
|
|
|
<I>conffile</I> is the filename of the conffile to remove.
|
|
<P>
|
|
|
|
Current implementation: in the <B>preinst</B>, it checks if the conffile
|
|
was modified and renames it either to <I>conffile</I><B>.dpkg-remove</B> (if not
|
|
modified) or to <I>conffile</I><B>.dpkg-backup</B> (if modified). In the
|
|
<B>postinst</B>, the latter file is renamed to <I>conffile</I><B>.dpkg-bak</B>
|
|
and kept for reference as it contains user modifications but the former will
|
|
be removed. If the package upgrade aborts, the <B>postrm</B> reinstalls the
|
|
original conffile. During purge, the <B>postrm</B> will also delete the
|
|
<B>.dpkg-bak</B> file kept up to now.
|
|
<A NAME="lbAI"> </A>
|
|
<H3>Renaming a conffile</H3>
|
|
|
|
<P>
|
|
|
|
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</B> script at first, however that will result in
|
|
the user being prompted by <B>dpkg</B> to approve the conffile edits even
|
|
though they are not responsible of them.
|
|
<P>
|
|
|
|
Graceful renaming can be implemented by putting the following shell
|
|
snippet in the <B>preinst</B>, <B>postinst</B> and <B>postrm</B> maintainer
|
|
scripts:
|
|
<P>
|
|
|
|
<BR> dpkg-maintscript-helper mv_conffile \
|
|
<BR> <I>old-conffile</I> <I>new-conffile</I> <I>prior-version</I> <I>package</I> -- "$@"
|
|
<P>
|
|
|
|
<I>old-conffile</I> and <I>new-conffile</I> are the old and new name of the
|
|
conffile to rename.
|
|
<P>
|
|
|
|
Current implementation: the <B>preinst</B> checks if the conffile has been
|
|
modified, if yes it's left on place otherwise it's renamed to
|
|
<I>old-conffile</I><B>.dpkg-remove</B>. On configuration, the <B>postinst</B>
|
|
removes <I>old-conffile</I><B>.dpkg-remove</B> and renames <I>old-conffile</I>
|
|
to <I>new-conffile</I> if <I>old-conffile</I> is still available. On
|
|
abort-upgrade/abort-install, the <B>postrm</B> renames
|
|
<I>old-conffile</I><B>.dpkg-remove</B> back to <I>old-conffile</I> if required.
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>SYMLINK AND DIRECTORY SWITCHES</H2>
|
|
|
|
When upgrading a package, <B>dpkg</B> will not automatically switch a symlink
|
|
to a directory or vice-versa. Downgrades are not supported and the path
|
|
will be left as is.
|
|
<A NAME="lbAK"> </A>
|
|
<H3>Switching a symlink to directory</H3>
|
|
|
|
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</B> script at first, however that will result
|
|
in some problems in case of admin local customization of the symlink
|
|
or when downgrading the package.
|
|
<P>
|
|
|
|
Graceful renaming can be implemented by putting the following shell
|
|
snippet in the <B>preinst</B>, <B>postinst</B> and <B>postrm</B> maintainer
|
|
scripts:
|
|
<P>
|
|
|
|
<BR> dpkg-maintscript-helper symlink_to_dir \
|
|
<BR> <I>pathname</I> <I>old-target</I> <I>prior-version</I> <I>package</I> -- "$@"
|
|
<P>
|
|
|
|
<I>pathname</I> is the absolute name of the old symlink (the path will be a
|
|
directory at the end of the installation) and <I>old-target</I> is
|
|
the target name of the former symlink at <I>pathname</I>. It can either be
|
|
absolute or relative to the directory containing <I>pathname</I>.
|
|
<P>
|
|
|
|
Current implementation: the <B>preinst</B> checks if the symlink exists
|
|
and points to <I>old-target</I>, if not then it's left in place, otherwise
|
|
it's renamed to <I>pathname</I><B>.dpkg-backup</B>. On configuration,
|
|
the <B>postinst</B> removes <I>pathname</I><B>.dpkg-backup</B> if
|
|
<I>pathname</I><B>.dpkg-backup</B> is still a symlink. On
|
|
abort-upgrade/abort-install, the <B>postrm</B> renames
|
|
<I>pathname</I><B>.dpkg-backup</B> back to <I>pathname</I> if required.
|
|
<A NAME="lbAL"> </A>
|
|
<H3>Switching a directory to symlink</H3>
|
|
|
|
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</B> 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.
|
|
<P>
|
|
|
|
Graceful switching can be implemented by putting the following shell
|
|
snippet in the <B>preinst</B>, <B>postinst</B> and <B>postrm</B> maintainer
|
|
scripts:
|
|
<P>
|
|
|
|
<BR> dpkg-maintscript-helper dir_to_symlink \
|
|
<BR> <I>pathname</I> <I>new-target</I> <I>prior-version</I> <I>package</I> -- "$@"
|
|
<P>
|
|
|
|
<I>pathname</I> is the absolute name of the old directory (the path
|
|
will be a symlink at the end of the installation) and <I>new-target</I> is
|
|
the target of the new symlink at <I>pathname</I>. It can either be absolute
|
|
or relative to the directory containing <I>pathname</I>.
|
|
<P>
|
|
|
|
Current implementation: the <B>preinst</B> 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</I><B>.dpkg-backup</B>, and an empty staging
|
|
directory named <I>pathname</I> is created, marked with a file so that
|
|
dpkg can track it. On configuration, the <B>postinst</B> finishes the
|
|
switch if <I>pathname</I><B>.dpkg-backup</B> is still a directory and
|
|
<I>pathname</I> 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</I>/, replaces the now empty staging
|
|
directory <I>pathname</I> with a symlink to <I>new-target</I>, and
|
|
removes <I>pathname</I><B>.dpkg-backup</B>. On
|
|
abort-upgrade/abort-install, the <B>postrm</B> renames
|
|
<I>pathname</I><B>.dpkg-backup</B> back to <I>pathname</I> if required.
|
|
<A NAME="lbAM"> </A>
|
|
<H2>INTEGRATION IN PACKAGES</H2>
|
|
|
|
<P>
|
|
|
|
When using a packaging helper, please check if it has native
|
|
<B>dpkg-maintscript-helper</B> integration, which might make your life
|
|
easier. See for example <B><A HREF="/cgi-bin/man/man2html?1+dh_installdeb">dh_installdeb</A></B>(1).
|
|
<P>
|
|
|
|
Given that <B>dpkg-maintscript-helper</B> is used in the <B>preinst</B>,
|
|
using it unconditionally requires a pre-dependency to ensure that the
|
|
required version of <B>dpkg</B> has been unpacked before. The required version
|
|
depends on the command used, for <B>rm_conffile</B> and <B>mv_conffile</B>
|
|
it is 1.15.7.2, for <B>symlink_to_dir</B> and <B>dir_to_symlink</B>
|
|
it is 1.17.14:
|
|
<P>
|
|
|
|
<BR> <B>Pre-Depends:</B> dpkg (>= 1.17.14)
|
|
<P>
|
|
|
|
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</B>:
|
|
<P>
|
|
|
|
<BR> if dpkg-maintscript-helper supports <I>command</I>; then
|
|
<BR> dpkg-maintscript-helper <I>command</I> ...
|
|
<BR> fi
|
|
<P>
|
|
|
|
The command <B>supports</B> will return 0 on success, 1 otherwise. The
|
|
<B>supports</B> 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.
|
|
<A NAME="lbAN"> </A>
|
|
<H2>ENVIRONMENT</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="4"><B>DPKG_COLORS</B>
|
|
|
|
<DD>
|
|
Sets the color mode (since dpkg 1.19.1).
|
|
The currently accepted values are: <B>auto</B> (default), <B>always</B> and
|
|
<B>never</B>.
|
|
</DL>
|
|
<A NAME="lbAO"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+dh_installdeb">dh_installdeb</A></B>(1).
|
|
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="5"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="6"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="7"><A HREF="#lbAD">COMMANDS AND PARAMETERS</A><DD>
|
|
<DT id="8"><A HREF="#lbAE">DESCRIPTION</A><DD>
|
|
<DT id="9"><A HREF="#lbAF">COMMON PARAMETERS</A><DD>
|
|
<DT id="10"><A HREF="#lbAG">CONFFILE RELATED TASKS</A><DD>
|
|
<DL>
|
|
<DT id="11"><A HREF="#lbAH">Removing a conffile</A><DD>
|
|
<DT id="12"><A HREF="#lbAI">Renaming a conffile</A><DD>
|
|
</DL>
|
|
<DT id="13"><A HREF="#lbAJ">SYMLINK AND DIRECTORY SWITCHES</A><DD>
|
|
<DL>
|
|
<DT id="14"><A HREF="#lbAK">Switching a symlink to directory</A><DD>
|
|
<DT id="15"><A HREF="#lbAL">Switching a directory to symlink</A><DD>
|
|
</DL>
|
|
<DT id="16"><A HREF="#lbAM">INTEGRATION IN PACKAGES</A><DD>
|
|
<DT id="17"><A HREF="#lbAN">ENVIRONMENT</A><DD>
|
|
<DT id="18"><A HREF="#lbAO">SEE ALSO</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:11 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|