man/dpkg-maintscript-helper.pod

   1 # dpkg manual page - dpkg-maintscript-helper(1)
   2 #
   3 # Copyright © 2010-2012 Raphaël Hertzog <hertzog@debian.org>
   4 # Copyright © 2011-2015 Guillem Jover <guillem@debian.org>
   5 #
   6 # This is free software; you can redistribute it and/or modify
   7 # it under the terms of the GNU General Public License as published by
   8 # the Free Software Foundation; either version 2 of the License, or
   9 # (at your option) any later version.
  10 #
  11 # This is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 # GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License
  17 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  18
  19 =encoding utf8
  20
  21 =head1 NAME
  22
  23 dpkg-maintscript-helper - works around known dpkg limitations in maintainer scripts
  24
  25 =head1 SYNOPSIS
  26
  27 B<dpkg-maintscript-helper>
  28 I<command> [I<parameter>...] B<--> I<maint-script-parameter>...
  29
  30 =head1 COMMANDS AND PARAMETERS
  31
  32 =over
  33
  34 =item B<supports> I<command>
  35
  36 =item B<rm_conffile> I<conffile> [I<prior-version> [I<package>]]
  37
  38 =item B<mv_conffile> I<old-conffile> I<new-conffile> [I<prior-version> [I<package>]]
  39
  40 =item B<symlink_to_dir> I<pathname> I<old-target> [I<prior-version> [I<package>]]
  41
  42 =item B<dir_to_symlink> I<pathname> I<new-target> [I<prior-version> [I<package>]]
  43
  44 =back
  45
  46 =head1 DESCRIPTION
  47
  48 This program is designed to be run within maintainer scripts to achieve
  49 some tasks that B<dpkg> can't (yet) handle natively either because of
  50 design decisions or due to current limitations.
  51
  52 Many of those tasks require coordinated actions from several maintainer
  53 scripts (B<preinst>, B<postinst>, B<prerm>, B<postrm>). To
  54 avoid mistakes the same call simply needs to be put in all scripts and the
  55 program will automatically adapt its behavior based on the environment
  56 variable B<DPKG_MAINTSCRIPT_NAME> and on the maintainer scripts arguments
  57 that you have to forward after a double hyphen.
  58
  59 =head1 COMMON PARAMETERS
  60
  61 =over
  62
  63 =item I<prior-version>
  64
  65 Defines the latest version of the package whose upgrade should trigger the
  66 operation. It is important to calculate I<prior-version> correctly so
  67 that the operations are correctly performed even if the user rebuilt the
  68 package with a local version. If I<prior-version> is empty or omitted,
  69 then the operation is tried on every upgrade (note: it's safer to give
  70 the version and have the operation tried only once).
  71
  72 If the conffile has not been shipped for several versions, and you are
  73 now modifying the maintainer scripts to clean up the obsolete file,
  74 I<prior-version> should be based on the version of the package that
  75 you are now preparing, not the first version of the package that lacked
  76 the conffile. This applies to all other actions in the same way.
  77
  78 For example, for a conffile removed in version B<2.0-1> of a package,
  79 I<prior-version> should be set to B<2.0-1~>. This will cause the
  80 conffile to be removed even if the user rebuilt the previous version
  81 B<1.0-1> as B<1.0-1local1>. Or a package switching a path from
  82 a symlink (shipped in version B<1.0-1>) to a directory (shipped in
  83 version B<2.0-1>), but only performing the actual switch in the
  84 maintainer scripts in version B<3.0-1>, should set I<prior-version>
  85 to B<3.0-1~>.
  86
  87 =item I<package>
  88
  89 The package name owning the pathname(s).
  90 When the package is “Multi-Arch: same” this parameter
  91 must include the architecture qualifier, otherwise it should B<not>
  92 usually include the architecture qualifier (as it would disallow
  93 cross-grades, or switching from being architecture specific to
  94 architecture B<all> or vice versa).
  95 If the parameter is empty or omitted, the B<DPKG_MAINTSCRIPT_PACKAGE>
  96 and B<DPKG_MAINTSCRIPT_ARCH> environment variables (as set by B<dpkg>
  97 when running the maintainer scripts) will be used to generate an
  98 arch-qualified package name.
  99
 100 =item B<-->
 101
 102 All the parameters of the maintainer scripts have to be forwarded to the
 103 program after B<-->.
 104
 105 =back
 106
 107 =head1 CONFFILE RELATED TASKS
 108
 109 When upgrading a package, B<dpkg> will not automatically remove a conffile
 110 (a configuration file for which B<dpkg> should preserve user changes) if
 111 it is not present in the newer version. There are two principal reasons for
 112 this; the first is that the conffile could've been dropped by accident and
 113 the next version could restore it, users wouldn't want their changes
 114 thrown away. The second is to allow packages to transition files from a
 115 dpkg-maintained conffile to a file maintained by the package's maintainer
 116 scripts, usually with a tool like debconf or ucf.
 117
 118 This means that if a package is intended to rename or remove a conffile,
 119 it must explicitly do so and B<dpkg-maintscript-helper> can be used
 120 to implement graceful deletion and moving of conffiles within maintainer
 121 scripts.
 122
 123 =head2 Removing a conffile
 124
 125 B<Note>: This can be replaced in most cases by the C<remove-on-upgrade>
 126 flag in F<DEBIAN/conffiles> (since dpkg 1.20.6), see L<deb-conffiles(5)>.
 127
 128 If a conffile is completely removed, it should be removed from disk,
 129 unless the user has modified it. If there are local modifications, they
 130 should be preserved. If the package upgrades aborts, the newly obsolete
 131 conffile should not disappear.
 132
 133 All of this is implemented by putting the following shell snippet in the
 134 B<preinst>, B<postinst> and B<postrm> maintainer scripts:
 135
 136 =over
 137
 138 Z<>
 139  dpkg-maintscript-helper rm_conffile \
 140     I<conffile> I<prior-version> I<package> -- "$@"
 141
 142 =back
 143
 144 I<conffile> is the filename of the conffile to remove.
 145
 146 Current implementation: in the B<preinst>, it checks if the conffile
 147 was modified and renames it either to I<conffile>B<.dpkg-remove> (if not
 148 modified) or to I<conffile>B<.dpkg-backup> (if modified). In the
 149 B<postinst>, the latter file is renamed to I<conffile>B<.dpkg-bak>
 150 and kept for reference as it contains user modifications but the former will
 151 be removed. If the package upgrade aborts, the B<postrm> reinstalls the
 152 original conffile. During purge, the B<postrm> will also delete the
 153 B<.dpkg-bak> file kept up to now.
 154
 155 =head2 Renaming a conffile
 156
 157 If a conffile is moved from one location to another, you need to make sure
 158 you move across any changes the user has made. This may seem a simple
 159 change to the B<preinst> script at first, however that will result in
 160 the user being prompted by B<dpkg> to approve the conffile edits even
 161 though they are not responsible of them.
 162
 163 Graceful renaming can be implemented by putting the following shell
 164 snippet in the B<preinst>, B<postinst> and B<postrm> maintainer
 165 scripts:
 166
 167 =over
 168
 169 Z<>
 170  dpkg-maintscript-helper mv_conffile \
 171     I<old-conffile> I<new-conffile> I<prior-version> I<package> -- "$@"
 172
 173 =back
 174
 175 I<old-conffile> and I<new-conffile> are the old and new name of the
 176 conffile to rename.
 177
 178 Current implementation: the B<preinst> checks if the conffile has been
 179 modified, if yes it's left on place otherwise it's renamed to
 180 I<old-conffile>B<.dpkg-remove>. On configuration, the B<postinst>
 181 removes I<old-conffile>B<.dpkg-remove> and renames I<old-conffile>
 182 to I<new-conffile> if I<old-conffile> is still available. On
 183 abort-upgrade/abort-install, the B<postrm> renames
 184 I<old-conffile>B<.dpkg-remove> back to I<old-conffile> if required.
 185
 186 =head1 SYMLINK AND DIRECTORY SWITCHES
 187
 188 When upgrading a package, B<dpkg> will not automatically switch a symlink
 189 to a directory or vice-versa. Downgrades are not supported and the path
 190 will be left as is.
 191
 192 B<Note>: The symlinks and directories created during these switches need to
 193 be shipped in the new packages, or B<dpkg> will not be able to remove them
 194 on purge.
 195
 196 =head2 Switching a symlink to directory
 197
 198 If a symlink is switched to a real directory, you need to make sure
 199 before unpacking that the symlink is removed. This may seem a simple
 200 change to the B<preinst> script at first, however that will result
 201 in some problems in case of admin local customization of the symlink
 202 or when downgrading the package.
 203
 204 Graceful renaming can be implemented by putting the following shell
 205 snippet in the B<preinst>, B<postinst> and B<postrm> maintainer
 206 scripts:
 207
 208 =over
 209
 210 Z<>
 211  dpkg-maintscript-helper symlink_to_dir \
 212     I<pathname> I<old-target> I<prior-version> I<package> -- "$@"
 213
 214 =back
 215
 216 I<pathname> is the absolute name of the old symlink (the path will be a
 217 directory at the end of the installation) and I<old-target> is
 218 the target name of the former symlink at I<pathname>. It can either be
 219 absolute or relative to the directory containing I<pathname>.
 220
 221 Current implementation: the B<preinst> checks if the symlink exists
 222 and points to I<old-target>, if not then it's left in place, otherwise
 223 it's renamed to I<pathname>B<.dpkg-backup>. On configuration,
 224 the B<postinst> removes I<pathname>B<.dpkg-backup> if
 225 I<pathname>B<.dpkg-backup> is still a symlink. On
 226 abort-upgrade/abort-install, the B<postrm> renames
 227 I<pathname>B<.dpkg-backup> back to I<pathname> if required.
 228
 229 =head2 Switching a directory to symlink
 230
 231 If a real directory is switched to a symlink, you need to make sure
 232 before unpacking that the directory is removed. This may seem a simple
 233 change to the B<preinst> script at first, however that will result
 234 in some problems in case the directory contains conffiles, pathnames
 235 owned by other packages, locally created pathnames, or when downgrading
 236 the package.
 237
 238 Graceful switching can be implemented by putting the following shell
 239 snippet in the B<preinst>, B<postinst> and B<postrm> maintainer
 240 scripts:
 241
 242 =over
 243
 244 Z<>
 245  dpkg-maintscript-helper dir_to_symlink \
 246     I<pathname> I<new-target> I<prior-version> I<package> -- "$@"
 247
 248 =back
 249
 250 I<pathname> is the absolute name of the old directory (the path
 251 will be a symlink at the end of the installation) and I<new-target> is
 252 the target of the new symlink at I<pathname>. It can either be absolute
 253 or relative to the directory containing I<pathname>.
 254
 255 Current implementation: the B<preinst> checks if the directory
 256 exists, does not contain conffiles, pathnames owned by other packages,
 257 or locally created pathnames, if not then it's left in place, otherwise
 258 it's renamed to I<pathname>B<.dpkg-backup>, and an empty staging
 259 directory named I<pathname> is created, marked with a file so that
 260 dpkg can track it. On configuration, the B<postinst> finishes the
 261 switch if I<pathname>B<.dpkg-backup> is still a directory and
 262 I<pathname> is the staging directory; it removes the staging directory
 263 mark file, moves the newly created files inside the staging directory
 264 to the symlink target I<new-target>/, replaces the now empty staging
 265 directory I<pathname> with a symlink to I<new-target>, and
 266 removes I<pathname>B<.dpkg-backup>. On
 267 abort-upgrade/abort-install, the B<postrm> renames
 268 I<pathname>B<.dpkg-backup> back to I<pathname> if required.
 269
 270 =head1 INTEGRATION IN PACKAGES
 271
 272 When using a packaging helper, please check if it has native
 273 B<dpkg-maintscript-helper> integration, which might make your life
 274 easier. See for example B<dh_installdeb>(1).
 275
 276 Given that B<dpkg-maintscript-helper> is used in the B<preinst>,
 277 using it unconditionally requires a pre-dependency to ensure that the
 278 required version of B<dpkg> has been unpacked before. The required version
 279 depends on the command used, for B<rm_conffile> and B<mv_conffile>
 280 it is 1.15.7.2, for B<symlink_to_dir> and B<dir_to_symlink>
 281 it is 1.17.14:
 282
 283 =over
 284
 285  Pre-Depends: dpkg (>= 1.17.14)
 286
 287 =back
 288
 289 But in many cases the operation done by the program is not critical for
 290 the package, and instead of using a pre-dependency we can call the
 291 program only if we know that the required command is supported by
 292 the currently installed B<dpkg>:
 293
 294 =over
 295
 296 Z<>
 297  if dpkg-maintscript-helper supports I<command>; then
 298     dpkg-maintscript-helper I<command> ...
 299  fi
 300
 301 =back
 302
 303 The command B<supports> will return 0 on success, 1 otherwise. The
 304 B<supports> command will check if the environment variables as set
 305 by dpkg and required by the script are present, and will consider it a
 306 failure in case the environment is not sufficient.
 307
 308 =head1 ENVIRONMENT
 309
 310 =over
 311
 312 =item B<DPKG_ROOT>
 313
 314 If set, it will be used as the filesystem root directory.
 315
 316 =item B<DPKG_ADMINDIR>
 317
 318 If set, it will be used as the B<dpkg> data directory.
 319
 320 =item B<DPKG_COLORS>
 321
 322 Sets the color mode (since dpkg 1.19.1).
 323 The currently accepted values are: B<auto> (default), B<always> and
 324 B<never>.
 325
 326 =back
 327
 328 =head1 SEE ALSO
 329
 330 B<dh_installdeb>(1).