Chapter 8. Package maintainer scripts and hooks
Prev |  | Next

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

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

Prev |  | Next
Chapter 7. Managing the initial ramfs (initramfs) archive | Home | Chapter 9. Reporting and handling bugs