# Package maintainer scripts and hooks

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.

## 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

## 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.

## 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.

## 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.

## 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.

## 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.

## Initial configuration by the installer

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