<?xml version='1.0' encoding='utf-8'?>
<!-- -*- DocBook -*- -->
<chapter id="ch-update-hooks">
<?dbhtml filename="ch-update-hooks.html" ?>
<title>Package maintainer scripts and hooks</title>
<para>
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.
</para>
<section id="s-kernel-hooks"><title>Kernel hooks</title>
<para>
The maintainer scripts in Linux kernel packages must use
<command>run-parts</command> to invoke hook scripts in the corresponding
subdirectory of <filename>/etc/kernel</filename>, e.g.  the
<literal>postinst</literal> script must invoke scripts in
<filename>/etc/kernel/postinst.d</filename>.
</para>
<para>
The arguments given to all kernel hook scripts are the kernel ABI version (the
string that <command>uname -r</command> reports) and, optionally, the absolute
path to the kernel image.  If the second argument is missing then the path is
either <filename>/boot/vmlinuz-<replaceable>version</replaceable></filename> or
<filename>/boot/vmlinux-<replaceable>version</replaceable></filename>, according to
architecture convention.  The environment variable
<envar>DEB_MAINT_PARAMS</envar> will contain the arguments given to the
kernel maintainer script, possibly single-quoted.  In a shell script, this
variable can be parsed using:
</para>
<literallayout class="monospaced">eval set -- "$DEB_MAINT_PARAMS"
</literallayout>
<para>
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:
</para>
<literallayout class="monospaced">exec &lt;/dev/null >&amp;2
</literallayout>
</section>

<section id="s-kernel-hooks-loader"><title>Kernel hooks required for boot loaders</title>
<para>
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
<filename>/etc/kernel/postinst.d</filename> and
<filename>/etc/kernel/postrm.d</filename>.
</para>
<para>
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 <literal>zz-</literal> and no other packages may use this
prefix or one that sorts later by the rules used by
<command>run-parts</command>.  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.
</para>
<para>
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.
</para>
<para>
Packages for boot loaders that can provide a menu of kernel versions should
install kernel hook scripts in order to update that menu.
</para>
</section>

<section id="s-initramfs-hooks"><title>Initramfs hooks</title>
<para>
Packages for boot loaders that need to be updated whenever the files they load
are modified must also install hook scripts in
<filename>/etc/initramfs/post-update.d</filename>.  Initramfs builders must call
these scripts using <command>run-parts</command> 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.
</para>
<para>
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.
</para>
</section>

<section id="s-kernel-hooks-initramfs"><title>Kernel hooks required for initramfs builders</title>
<para>
Initramfs builders must install hook scripts in
<filename>/etc/kernel/postinst.d</filename> and
<filename>/etc/kernel/postrm.d</filename>, to create/update and delete the
corresponding initramfs images.  The postinst hook script must complete its
work before returning.
</para>
</section>

<section id="s-loader-optimisation"><title>Optimising boot loader updates</title>
<para>
During a kernel package installation, upgrade or removal, various boot loader
hooks may be invoked (in this order):
</para>
<orderedlist numeration="arabic">
<listitem>
<para>
A <literal>postinst_hook</literal> or <literal>postrm_hook</literal> command
set by the user or the installer in <filename>/etc/kernel-img.conf</filename>
</para>
</listitem>
<listitem>
<para>
A hook script in <filename>/etc/initramfs/post-update.d</filename>
</para>
</listitem>
<listitem>
<para>
A hook script in <filename>/etc/kernel/postinst.d</filename> or
...<filename>/postrm.d</filename>
</para>
</listitem>
</orderedlist>
<para>
To avoid unnecessary updates, the hooks invoked at steps 1 and 2 may check
whether <envar>$DPKG_MAINTSCRIPT_PACKAGE</envar> begins with
<literal>linux-image-</literal> and do nothing in this case.
</para>
</section>

<section id="s-deprecation"><title>Deprecated features</title>
<para>
Kernel packages must not invoke boot loaders or initramfs builders
except via hooks.  If <filename>/etc/kernel-img.conf</filename> contains
<literal>do_bootloader = yes</literal> or equivalent, maintainer
scripts that previously acted on this must warn that they are ignoring
it.  <package>linux-base</package> must also warn on upgrade that the
default has changed.
</para>
</section>

<section id="s-init-config"><title>Initial configuration by the installer</title>
<para>
The installer must not define <literal>do_bootloader</literal>,
<literal>postinst_hook</literal> or <literal>postrm_hook</literal> in
<filename>/etc/kernel-img.conf</filename>.
</para>
</section>

</chapter>