Chapter 8. Package maintainer scripts and hooks

Table of Contents

8.1. Kernel hooks
8.2. Kernel hooks required for boot loaders
8.3. Initramfs hooks
8.4. Kernel hooks required for initramfs builders
8.5. Optimising boot loader updates
8.6. Deprecated features
8.7. Initial configuration by the installer

The following policy applies to Debian GNU/Linux. Some parts may be applicable to kernels other than Linux, but this policy does not set any requirements for them.

8.1. Kernel hooks

The maintainer scripts in Linux kernel packages must use run-parts to invoke hook scripts in the corresponding subdirectory of /etc/kernel, e.g. the postinst script must invoke scripts in /etc/kernel/postinst.d.

The arguments given to all kernel hook scripts are the kernel ABI version (the string that uname -r reports) and, optionally, the absolute path to the kernel image. If the second argument is missing then the path is either /boot/vmlinuz-version or /boot/vmlinux-version, according to architecture convention. The environment variable DEB_MAINT_PARAMS will contain the arguments given to the kernel maintainer script, possibly single-quoted. In a shell script, this variable can be parsed using:

eval set -- "$DEB_MAINT_PARAMS"

Kernel hook scripts may be run under debconf. In this case they must not use stdin and stdout, and should send all output to stderr (fd 2). A shell script can ensure that it does this using:

exec </dev/null >&2

8.2. Kernel hooks required for boot loaders

Packages for boot loaders that need to be updated whenever the files they load are modified (i.e. those that store a block list) must install hook scripts in /etc/kernel/postinst.d and /etc/kernel/postrm.d.

Since these boot loaders should be updated as the last step during installation/upgrade and removal, hook scripts for boot loaders must be named using the prefix zz- and no other packages may use this prefix or one that sorts later by the rules used by run-parts. A postrm hook script should warn but exit with code 0 if the boot loader configuration file still refers to the kernel image that has been removed.

These boot loader packages must be installable on the filesystem in a disabled state where they will not write to the boot sector or other special storage. While a boot loader is disabled, any kernel hooks it includes must do nothing except (optionally) printing a warning that the boot loader is disabled, and must exit successfully.

Packages for boot loaders that can provide a menu of kernel versions should install kernel hook scripts in order to update that menu.

8.3. Initramfs hooks

Packages for boot loaders that need to be updated whenever the files they load are modified must also install hook scripts in /etc/initramfs/post-update.d. Initramfs builders must call these scripts using run-parts after they create, update or delete an initramfs. The arguments given to these hook scripts are the kernel ABI version and the absolute path to the initramfs image.

While a boot loader is disabled, any initramfs hook it includes must do nothing except (optionally) printing a warning that the boot loader is disabled, and must exit successfully.

8.4. Kernel hooks required for initramfs builders

Initramfs builders must install hook scripts in /etc/kernel/postinst.d and /etc/kernel/postrm.d, to create/update and delete the corresponding initramfs images. The postinst hook script must complete its work before returning.

8.5. Optimising boot loader updates

During a kernel package installation, upgrade or removal, various boot loader hooks may be invoked (in this order):

  1. A postinst_hook or postrm_hook command set by the user or the installer in /etc/kernel-img.conf

  2. A hook script in /etc/initramfs/post-update.d

  3. A hook script in /etc/kernel/postinst.d or .../postrm.d

To avoid unnecessary updates, the hooks invoked at steps 1 and 2 may check whether $DPKG_MAINTSCRIPT_PACKAGE begins with linux-image- and do nothing in this case.

8.6. Deprecated features

Kernel packages must not invoke boot loaders or initramfs builders except via hooks. If /etc/kernel-img.conf contains do_bootloader = yes or equivalent, maintainer scripts that previously acted on this must warn that they are ignoring it. linux-base must also warn on upgrade that the default has changed.

8.7. Initial configuration by the installer

The installer must not define do_bootloader, postinst_hook or postrm_hook in /etc/kernel-img.conf.