policy/ch-maintainerscripts.rst

   1 Package maintainer scripts and installation procedure
   2 =====================================================
   3
   4 .. _s6.1:
   5
   6 Introduction to package maintainer scripts
   7 ------------------------------------------
   8
   9 It is possible to supply scripts as part of a package which the package
  10 management system will run for you when your package is installed,
  11 upgraded or removed.
  12
  13 These scripts are the control information files ``preinst``,
  14 ``postinst``, ``prerm`` and ``postrm``. They must be proper executable
  15 files; if they are scripts (which is recommended), they must start with
  16 the usual ``#!`` convention. They should be readable and executable by
  17 anyone, and must not be world-writable.
  18
  19 The package management system looks at the exit status from these
  20 scripts. It is important that they exit with a non-zero status if there
  21 is an error, so that the package management system can stop its
  22 processing. For shell scripts this means that you *almost always* need
  23 to use ``set -e`` (this is usually true when writing shell scripts, in fact).
  24 It is also important, of course, that they exit with a zero status if
  25 everything went well.
  26
  27 Additionally, packages interacting with users using ``debconf`` in the
  28 ``postinst`` script should install a ``config`` script as a control
  29 information file. See :ref:`s-maintscriptprompt` for
  30 details.
  31
  32 When a package is upgraded a combination of the scripts from the old and
  33 new packages is called during the upgrade procedure. If your scripts are
  34 going to be at all complicated you need to be aware of this, and may
  35 need to check the arguments to your scripts.
  36
  37 Broadly speaking the ``preinst`` is called before (a particular version
  38 of) a package is unpacked, and the ``postinst`` afterwards; the
  39 ``prerm`` before (a version of) a package is removed and the ``postrm``
  40 afterwards.
  41
  42 Programs called from maintainer scripts should not normally have a path
  43 prepended to them. Before installation is started, the package
  44 management system checks to see if the programs ``ldconfig``,
  45 ``start-stop-daemon``, and ``update-rc.d`` can be found via the ``PATH``
  46 environment variable. Those programs, and any other program that one
  47 would expect to be in the ``PATH``, should thus be invoked without an
  48 absolute pathname. Maintainer scripts should also not reset the
  49 ``PATH``, though they might choose to modify it by prepending or
  50 appending package-specific directories. These considerations really
  51 apply to all shell scripts.
  52
  53 .. _s-idempotency:
  54
  55 Maintainer scripts idempotency
  56 ------------------------------
  57
  58 It is necessary for the error recovery procedures that the scripts be
  59 idempotent. This means that if it is run successfully, and then it is
  60 called again, it doesn't bomb out or cause any harm, but just ensures
  61 that everything is the way it ought to be. If the first call failed, or
  62 aborted half way through for some reason, the second call should merely
  63 do the things that were left undone the first time, if any, and exit
  64 with a success status if everything is OK.  [#]_
  65
  66 .. _s-controllingterminal:
  67
  68 Controlling terminal for maintainer scripts
  69 -------------------------------------------
  70
  71 Maintainer scripts are not guaranteed to run with a controlling terminal
  72 and may not be able to interact with the user. They must be able to fall
  73 back to noninteractive behavior if no controlling terminal is available.
  74 Maintainer scripts that prompt via a program conforming to the Debian
  75 Configuration Management Specification (see
  76 :ref:`s-maintscriptprompt`) may assume that program will
  77 handle falling back to noninteractive behavior.
  78
  79 For high-priority prompts without a reasonable default answer,
  80 maintainer scripts may abort if there is no controlling terminal.
  81 However, this situation should be avoided if at all possible, since it
  82 prevents automated or unattended installs. In most cases, users will
  83 consider this to be a bug in the package.
  84
  85 .. _s-exitstatus:
  86
  87 Exit status
  88 -----------
  89
  90 Each script must return a zero exit status for success, or a nonzero one
  91 for failure, since the package management system looks for the exit
  92 status of these scripts and determines what action to take next based on
  93 that datum.
  94
  95 .. _s-mscriptsinstact:
  96
  97 Summary of ways maintainer scripts are called
  98 ---------------------------------------------
  99
 100 What follows is a summary of all the ways in which maintainer scripts
 101 may be called along with what facilities those scripts may rely on being
 102 available at that time. Script names preceded by new- are the scripts
 103 from the new version of a package being installed, upgraded to, or
 104 downgraded to. Script names preceded by old- are the scripts from the
 105 old version of a package that is being upgraded from or downgraded from.
 106
 107 The ``preinst`` script may be called in the following ways:
 108
 109 | ``new-preinst`` install
 110 | ``new-preinst`` install *old-version*
 111 | ``new-preinst`` upgrade *old-version*
 112
 113     The package will not yet be unpacked, so the ``preinst`` script
 114     cannot rely on any files included in its package. Only essential
 115     packages and pre-dependencies (``Pre-Depends``) may be assumed to be
 116     available. Pre-dependencies will have been configured at least once,
 117     but at the time the ``preinst`` is called they may only be in an
 118     "Unpacked" or "Half-Configured" state if a previous version of the
 119     pre-dependency was completely configured and has not been removed
 120     since then.
 121
 122 ``old-preinst`` abort-upgrade *new-version*
 123     Called during error handling of an upgrade that failed after
 124     unpacking the new package because the ``postrm upgrade`` action failed. The unpacked files may be
 125     partly from the new version or partly missing, so the script cannot
 126     rely on files included in the package. Package dependencies may not
 127     be available. Pre-dependencies will be at least "Unpacked" following
 128     the same rules as above, except they may be only "Half-Installed" if
 129     an upgrade of the pre-dependency failed.  [#]_
 130
 131 The ``postinst`` script may be called in the following ways:
 132
 133 ``postinst`` configure *most-recently-configured-version*
 134     The files contained in the package will be unpacked. All package
 135     dependencies will at least be "Unpacked". If there are no circular
 136     dependencies involved, all package dependencies will be configured.
 137     For behavior in the case of circular dependencies, see the
 138     discussion in :ref:`s-binarydeps`.
 139
 140 | ``old-postinst`` abort-upgrade *new-version*
 141 | ``conflictor's-postinst`` abort-remove in-favour *package* *new-version*
 142 | ``postinst`` abort-remove
 143 | ``deconfigured's-postinst`` abort-deconfigure in-favour *failed-install-package* *version* [ removing conflicting-package version ]
 144
 145     The files contained in the package will be unpacked. All package
 146     dependencies will at least be "Half-Installed" and will have
 147     previously been configured and not removed. However, dependencies
 148     may not be configured or even fully unpacked in some error
 149     situations.  [#]_ The ``postinst`` should still attempt any actions
 150     for which its dependencies are required, since they will normally be
 151     available, but consider the correct error handling approach if those
 152     actions fail. Aborting the ``postinst`` action if commands or
 153     facilities from the package dependencies are not available is often
 154     the best approach.
 155
 156 The ``prerm`` script may be called in the following ways:
 157
 158 | ``prerm`` remove
 159 | ``old-prerm`` upgrade *new-version*
 160 | ``conflictor's-prerm`` remove in-favour package *new-version*
 161 | ``deconfigured's-prerm`` deconfigure in-favour *package-being-installed* *version* [removing conflicting-package version]
 162
 163     The package whose ``prerm`` is being called will be at least
 164     "Half-Installed". All package dependencies will at least be
 165     "Half-Installed" and will have previously been configured and not
 166     removed. If there was no error, all dependencies will at least be
 167     "Unpacked", but these actions may be called in various error states
 168     where dependencies are only "Half-Installed" due to a partial
 169     upgrade.
 170
 171 ``new-prerm`` failed-upgrade *old-version*
 172     Called during error handling when ``prerm upgrade`` fails. The new package will not yet be
 173     unpacked, and all the same constraints as for ``preinst upgrade``
 174     apply.
 175
 176 The ``postrm`` script may be called in the following ways:
 177
 178 | ``postrm`` remove
 179 | ``postrm`` purge
 180 | ``old-postrm`` upgrade *new-version*
 181 | ``disappearer's-postrm`` disappear overwriter *overwriter-version*
 182
 183     The ``postrm`` script is called after the package's files have been
 184     removed or replaced. The package whose ``postrm`` is being called
 185     may have previously been deconfigured and only be "Unpacked", at
 186     which point subsequent package changes do not consider its
 187     dependencies. Therefore, all ``postrm`` actions may only rely on
 188     essential packages and must gracefully skip any actions that require
 189     the package's dependencies if those dependencies are unavailable.
 190     [#]_
 191
 192 ``new-postrm`` failed-upgrade *old-version*
 193     Called when the old ``postrm upgrade`` action fails. The new package
 194     will be unpacked, but only essential packages and pre-dependencies
 195     can be relied on. Pre-dependencies will either be configured or will
 196     be "Unpacked" or "Half-Configured" but previously had been
 197     configured and was never removed.
 198
 199 | ``new-postrm`` abort-install
 200 | ``new-postrm`` abort-install *old-version*
 201 | ``new-postrm`` abort-upgrade *old-version*
 202
 203     Called before unpacking the new package as part of the error
 204     handling of ``preinst`` failures. May assume the same state as
 205     ``preinst`` can assume.
 206
 207 .. _s-unpackphase:
 208
 209 Details of unpack phase of installation or upgrade
 210 --------------------------------------------------
 211
 212 The procedure on installation/upgrade/overwrite/disappear (i.e., when
 213 running ``dpkg --unpack``, or the unpack stage of ``dpkg --install``) is
 214 as follows.  [#]_ In each case, if a major error occurs (unless listed
 215 below) the actions are, in general, run backwards - this means that the
 216 maintainer scripts are run with different arguments in reverse order.
 217 These are the "error unwind" calls listed below.
 218
 219 1.  Notify the currently installed package:
 220
 221     a. If a version of the package is already "Installed", call
 222
 223        .. parsed-literal::
 224
 225            old-prerm upgrade *new-version*
 226
 227     b. If the script runs but exits with a non-zero exit status,
 228        ``dpkg`` will attempt:
 229
 230        .. parsed-literal::
 231
 232            new-prerm failed-upgrade *old-version*
 233
 234        If this works, the upgrade continues. If this does not work, the
 235        error unwind:
 236
 237        .. parsed-literal::
 238
 239            *old-postinst* abort-upgrade *new-version*
 240
 241        If this works, then the *old-version* is "Installed", if not, the
 242        old version is in a "Half-Configured" state.
 243
 244 2.  If a "conflicting" package is being removed at the same time, or if
 245     any package will be broken (due to ``Breaks``):
 246
 247     a. If ``--auto-deconfigure`` is specified, call, for each package to
 248        be deconfigured due to ``Breaks``:
 249
 250        .. parsed-literal::
 251
 252             *deconfigured's-prerm* deconfigure \\
 253                 in-favour *package-being-installed* *version*
 254
 255        Error unwind:
 256
 257        .. parsed-literal::
 258
 259            *deconfigured's-postinst* abort-deconfigure \\
 260                in-favour *package-being-installed-but-failed* *version*
 261
 262        The deconfigured packages are marked as requiring configuration,
 263        so that if ``--install`` is used they will be configured again if
 264        possible.
 265
 266     b. If any packages depended on a conflicting package being removed
 267        and ``--auto-deconfigure`` is specified, call, for each such
 268        package:
 269
 270        .. parsed-literal::
 271
 272             *deconfigured's-prerm* deconfigure \\
 273                in-favour *package-being-installed* *version* \\
 274                removing *conflicting-package* *version*
 275
 276        Error unwind:
 277
 278        .. parsed-literal::
 279
 280            *deconfigured's-postinst* abort-deconfigure \\
 281                in-favour *package-being-installed-but-failed* *version* \\
 282                removing *conflicting-package* *version*
 283
 284        The deconfigured packages are marked as requiring configuration,
 285        so that if ``--install`` is used they will be configured again if
 286        possible.
 287
 288     c. To prepare for removal of each conflicting package, call:
 289
 290        .. parsed-literal::
 291
 292            *conflictor's-prerm* remove \\
 293                in-favour *package* *new-version*
 294
 295        Error unwind:
 296
 297        .. parsed-literal::
 298
 299            *conflictor's-postinst* abort-remove \\
 300                in-favour *package* *new-version*
 301
 302 3.  Run the ``preinst`` of the new package:
 303
 304     a. If the package is being upgraded, call:
 305
 306        .. parsed-literal::
 307
 308            *new-preinst* upgrade *old-version*
 309
 310        If this fails, we call:
 311
 312        .. parsed-literal::
 313
 314            *new-postrm* abort-upgrade *old-version*
 315
 316        i.  If that works, then
 317
 318            .. parsed-literal::
 319
 320                *old-postinst* abort-upgrade *new-version*
 321
 322            is called. If this works, then the old version is in an
 323            "Installed" state, or else it is left in an "Unpacked" state.
 324
 325        ii. If it fails, then the old version is left in an
 326            "Half-Installed" state.
 327
 328     b. Otherwise, if the package had some configuration files from a
 329        previous version installed (i.e., it is in the "Config-Files"
 330        state):
 331
 332        .. parsed-literal::
 333
 334            *new-preinst* install *old-version*
 335
 336        Error unwind:
 337
 338        .. parsed-literal::
 339
 340            *new-postrm* abort-install *old-version*
 341
 342        If this fails, the package is left in a "Half-Installed" state,
 343        which requires a reinstall. If it works, the packages is left in
 344        a "Config-Files" state.
 345
 346     c. Otherwise (i.e., the package was completely purged):
 347
 348        .. parsed-literal::
 349
 350            *new-preinst* install
 351
 352        Error unwind:
 353
 354        .. parsed-literal::
 355
 356            *new-postrm* abort-install
 357
 358        If the error-unwind fails, the package is in a "Half-Installed"
 359        phase, and requires a reinstall. If the error unwind works, the
 360        package is in the "Not-Installed" state.
 361
 362 4.  The new package's files are unpacked, overwriting any that may be on
 363     the system already, for example any from the old version of the same
 364     package or from another package. Backups of the old files are kept
 365     temporarily, and if anything goes wrong the package management
 366     system will attempt to put them back as part of the error unwind.
 367
 368     It is an error for a package to contain files which are on the
 369     system in another package, unless ``Replaces`` is used (see
 370     :ref:`s-replaces`).
 371
 372     It is a more serious error for a package to contain a plain file or
 373     other kind of non-directory where another package has a directory
 374     (again, unless ``Replaces`` is used). This error can be overridden
 375     if desired using ``--force-overwrite-dir``, but this is not
 376     advisable.
 377
 378     Packages which overwrite each other's files produce behavior which,
 379     though deterministic, is hard for the system administrator to
 380     understand. It can easily lead to "missing" programs if, for
 381     example, a package is unpacked which overwrites a file from another
 382     package, and is then removed again.  [#]_
 383
 384     A directory will never be replaced by a symbolic link to a directory
 385     or vice versa; instead, the existing state (symlink or not) will be
 386     left alone and ``dpkg`` will follow the symlink if there is one.
 387
 388 5.  If the package is being upgraded:
 389
 390     a. Call:
 391
 392        .. parsed-literal::
 393
 394            *old-postrm* upgrade *new-version*
 395
 396     b. If this fails, ``dpkg`` will attempt:
 397
 398        .. parsed-literal::
 399
 400            *new-postrm* failed-upgrade *old-version*
 401
 402        If this works, installation continues. If not, Error unwind:
 403
 404        .. parsed-literal::
 405
 406            *old-preinst* abort-upgrade *new-version*
 407
 408        If this fails, the old version is left in a "Half-Installed"
 409        state. If it works, dpkg now calls:
 410
 411        .. parsed-literal::
 412
 413            *new-postrm* abort-upgrade *old-version*
 414
 415        If this fails, the old version is left in a "Half-Installed"
 416        state. If it works, dpkg now calls:
 417
 418        .. parsed-literal::
 419
 420            *old-postinst* abort-upgrade *new-version*
 421
 422        If this fails, the old version is in an "Unpacked" state.
 423
 424     This is the point of no return. If ``dpkg`` gets this far, it won't
 425     back off past this point if an error occurs. This will leave the
 426     package in a fairly bad state, which will require a successful
 427     re-installation to clear up, but it's when ``dpkg`` starts doing
 428     things that are irreversible.
 429
 430 6.  Any files which were in the old version of the package but not in
 431     the new are removed.
 432
 433 7.  The new file list replaces the old.
 434
 435 8.  The new maintainer scripts replace the old.
 436
 437 9.  Any packages all of whose files have been overwritten during the
 438     installation, and which aren't required for dependencies, are
 439     considered to have been removed. For each such package
 440
 441     a. ``dpkg`` calls:
 442
 443        .. parsed-literal::
 444
 445            *disappearer's-postrm* disappear \\
 446                *overwriter* *overwriter-version*
 447
 448     b. The package's maintainer scripts are removed.
 449
 450     c. It is noted in the status database as being in a sane state,
 451        namely "Not-Installed" (any conffiles it may have are ignored,
 452        rather than being removed by ``dpkg``). Note that disappearing
 453        packages do not have their prerm called, because ``dpkg`` doesn't
 454        know in advance that the package is going to vanish.
 455
 456 10. Any files in the package we're unpacking that are also listed in the
 457     file lists of other packages are removed from those lists. (This
 458     will lobotomize the file list of the "conflicting" package if there
 459     is one.)
 460
 461 11. The backup files made during installation, above, are deleted.
 462
 463 12. The new package's status is now sane, and recorded as "Unpacked".
 464
 465     Here is another point of no return: if the conflicting package's
 466     removal fails we do not unwind the rest of the installation. The
 467     conflicting package is left in a half-removed limbo.
 468
 469 13. If there was a conflicting package we go and do the removal actions
 470     (described below), starting with the removal of the conflicting
 471     package's files (any that are also in the package being unpacked
 472     have already been removed from the conflicting package's file list,
 473     and so do not get removed now).
 474
 475 .. _s-configdetails:
 476
 477 Details of configuration
 478 ------------------------
 479
 480 When we configure a package (this happens with ``dpkg --install`` and ``dpkg --configure``), we first update any
 481 ``conffile``\ s and then call:
 482
 483 .. parsed-literal::
 484
 485     *postinst* configure *most-recently-configured-version*
 486
 487 No attempt is made to unwind after errors during configuration. If the
 488 configuration fails, the package is in a "Half-Configured" state, and an
 489 error message is generated.
 490
 491 If there is no most recently configured version ``dpkg`` will pass a
 492 null argument.  [#]_
 493
 494 .. _s-removedetails:
 495
 496 Details of removal and/or configuration purging
 497 -----------------------------------------------
 498
 499 1. .. parsed-literal::
 500
 501        *prerm* remove
 502
 503    If prerm fails during replacement due to conflict
 504
 505    .. parsed-literal::
 506
 507        *conflictor's-postinst* abort-remove \\
 508            in-favour *package* *new-version*
 509
 510    Or else we call:
 511
 512    .. parsed-literal::
 513
 514        *postinst* abort-remove
 515
 516    If this fails, the package is in a "Half-Configured" state, or else
 517    it remains "Installed".
 518
 519 2. The package's files are removed (except ``conffile``\ s).
 520
 521 3. .. parsed-literal::
 522
 523        *postrm* remove
 524
 525    If it fails, there's no error unwind, and the package is in an
 526    "Half-Installed" state.
 527
 528 4. All the maintainer scripts except the ``postrm`` are removed.
 529
 530    If we aren't purging the package we stop here. Note that packages
 531    which have no ``postrm`` and no ``conffile``\ s are automatically
 532    purged when removed, as there is no difference except for the
 533    ``dpkg`` status.
 534
 535 5. The ``conffile``\ s and any backup files (``~``-files, ``#*#`` files,
 536    ``%``-files, ``.dpkg-{old,new,tmp}``, etc.) are removed.
 537
 538 6. .. parsed-literal::
 539
 540        *postrm* purge
 541
 542    If this fails, the package remains in a "Config-Files" state.
 543
 544 7. The package's file list is removed.
 545
 546 .. [#]
 547    This is so that if an error occurs, the user interrupts ``dpkg`` or
 548    some other unforeseen circumstance happens you don't leave the user
 549    with a badly-broken package when ``dpkg`` attempts to repeat the
 550    action.
 551
 552 .. [#]
 553    This can happen if the new version of the package no longer
 554    pre-depends on a package that had been partially upgraded.
 555
 556 .. [#]
 557    For example, suppose packages foo and bar are "Installed" with foo
 558    depending on bar. If an upgrade of bar were started and then aborted,
 559    and then an attempt to remove foo failed because its ``prerm`` script
 560    failed, foo's ``postinst abort-remove`` would be called with bar only
 561    "Half-Installed".
 562
 563 .. [#]
 564    This is often done by checking whether the command or facility the
 565    ``postrm`` intends to call is available before calling it. For
 566    example:
 567
 568    ::
 569
 570        if [ "$1" = pur.. [#] && [ -e /usr/share/debconf/confmodule ]; then
 571            . /usr/share/debconf/confmodule db_purge
 572        fi
 573
 574    in ``postrm`` purges the ``debconf`` configuration for the package if
 575    debconf is installed.
 576
 577 .. [#]
 578    See :doc:`ap-flowcharts` for flowcharts illustrating
 579    the processes described here.
 580
 581 .. [#]
 582    Part of the problem is due to what is arguably a bug in ``dpkg``.
 583
 584 .. [#]
 585    Historical note: Truly ancient (pre-1997) versions of ``dpkg`` passed
 586    ``<unknown>`` (including the angle brackets) in this case. Even older
 587    ones did not pass a second argument at all, under any circumstance.
 588    Note that upgrades using such an old dpkg version are unlikely to
 589    work for other reasons, even if this old argument behavior is handled
 590    by your postinst script.
 591