mirror of
https://salsa.debian.org/kernel-team/kernel-handbook.git
synced 2026-01-11 19:58:20 +00:00
3018ac6f3a
Instead of just <screen> and <literal>, use these elements as appropriate:
<command>
<computeroutput>
<envar>
<filename>
<lineannotation>
<literallayout>
<package>,
<prompt>
<symbol>
<userinput>
Also use <email> for the single email address.
147 lines
5.7 KiB
XML
147 lines
5.7 KiB
XML
<?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 </dev/null >&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>
|
|
|