[DRAFT] Policy for Linux kernel, initramfs, boot loader update process

[Stephen Powell]

I took the liberty of adding debian-boot and debian-s390 to the CC
list on this e-mail, since it affects the Debian installer and
the s390-tools package, which contains the zipl boot loader, which
has a design very similar to that of lilo. If this results in some people
getting more than one copy of this e-mail, please accept my apologies; but
I figured it was better to err on the side of caution in this case.
I also added Joachim Wiedorn, the new lilo upstream maintainer (who
also happens to be the Debian package maintainer for backup2l).

I propose the following policy for squeeze and later releases. This
affects all Linux kernel, initramfs builder and boot loader packages,
and the installer.
I regret that this is happening so late in the release cycle, but
currently a kernel update can easily leave the system unbootable and
this does need to be addressed before release and I want to do so in a
way that is reasonably clean and maintainable.
---
1. 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, which
will be called on installation/upgrade and removal of kernel packages,
respectively.
The arguments given to all kernel hook scripts are the kernel ABI
version (the string that uname -r reports) and the absolute path to the
kernel image.

Currently, hook scripts invoked by a stock kernel maintainer script
or a maintainer script from a kernel image package created by make-kpkg
pass these exact same arguments. But a maintainer script for a kernel
image package created by "make deb-pkg" passes only the first argument.
Existing hook scripts rely on that difference to determine whether or
not to take action. For example, the initramfs hook script provided by
the initramfs-tools package tests the number of arguments and exits
without doing anything if more than one argument is supplied. In other
words, this hook script is designed to create the initial RAM file system
for a kernel image created by "make deb-pkg", and only for a kernel
image created by "make deb-pkg". It does nothing otherwise. Are you
proposing to change this behavior?

The environment variable DEB_MAINT_PARAMS will contain
the arguments given to the kernel maintainer script, single-quoted.

Is this environment variable provided by the maintainer scripts
that come with kernel image packages created by "make deb-pkg"?
(I honestly don't know. I've never used "make deb-pkg".)

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.
2. Packages for boot loaders that need to be updated whenever the files
they load are modified must also install hook scripts in
/etc/mkinitramfs/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.
3. Initramfs builders must complete their work before returning from the
kernel postinst hook script. [initramfs-tools currently uses a trigger
to defer this because it can also be invoked twice, but this means it
also has to know how to update specific boot loaders.]
4. During a kernel package installation, upgrade or removal, various
a. A postinst_hook or postrm_hook command set by the user or the
installer in /etc/kernel-img.conf
b. A hook script in /etc/mkinitramfs/post-update.d
c. A hook script in /etc/kernel/postinst.d or .../postrm.d
To avoid unnecessary updates, the hooks invoked at step a and b may
check whether $DPKG_MAINTSCRIPT_PACKAGE begins with 'linux-image-' and
do nothing in this case. [Is this sensible or is it too 'clever'?]
5. Kernel and initramfs builder packages must not invoke boot loaders
except via hooks. If /etc/kernel-img.conf contains an explicit
'do_bootloader = yes', kernel package maintainer scripts should warn
that this is now ignored.

At the risk of flogging a dead horse, I would prefer to see
"do_bootloader = yes" supported until Squeeze+1, both by the
kernel maintainer scripts and by "update-initramfs -u", particularly
since we are so close to a freeze. But if
you're going to drop support for it in Squeeze, then yes,
a warning message is necessary. Both the kernel maintainer scripts
*and* "update-initramfs -u" *must* issue a warning message if they
find "do_bootloader = yes" specified in /etc/kernel-img.conf.
In fact, since the default value is "yes", they should issue
the warning message unless do_bootloader is *explicitly* set
to no.

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

Doesn't this conflict with point 4 (a)?
--
.''`. Stephen Powell
: :' :
`. `'`
`-

[maximilian attems]

Post by Stephen Powell

---
1. 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, which
will be called on installation/upgrade and removal of kernel packages,
respectively.
The arguments given to all kernel hook scripts are the kernel ABI
version (the string that uname -r reports) and the absolute path to the
kernel image.

Currently, hook scripts invoked by a stock kernel maintainer script
or a maintainer script from a kernel image package created by make-kpkg
pass these exact same arguments.

no.

Post by Stephen Powell
But a maintainer script for a kernel
image package created by "make deb-pkg" passes only the first argument.

no.

Post by Stephen Powell
Existing hook scripts rely on that difference to determine whether or
not to take action. For example, the initramfs hook script provided by
the initramfs-tools package tests the number of arguments and exits
without doing anything if more than one argument is supplied. In other
words, this hook script is designed to create the initial RAM file system
for a kernel image created by "make deb-pkg", and only for a kernel
image created by "make deb-pkg". It does nothing otherwise. Are you
proposing to change this behavior?

please get your facts right before spamming the world.

kthxbye.

[Stephen Powell]

Post by maximilian attems

The arguments given to all kernel hook scripts are the kernel ABI
version (the string that uname -r reports) and the absolute path to the
kernel image.
Currently, hook scripts invoked by a stock kernel maintainer script
or a maintainer script from a kernel image package created by make-kpkg
pass these exact same arguments.

no.

-----

debian3:~# dpkg-reconfigure linux-image-2.6.32-custom5b-s390x
Running depmod.
Examining /etc/kernel/postinst.d.
run-parts: executing /etc/kernel/postinst.d/S30initramfs 2.6.32-custom5b-s390x /boot/vmlinuz-2.6.32-custom5b-s390x
^ ^
+-- 1st argument +-- 2nd argument

-----
-----

***@testdebian:~# dpkg-reconfigure linux-image-2.6.32-3-686
Running depmod.
Running update-initramfs: Generating /boot/initrd.img-2.6.32-3-686
Examining /etc/kernel/postinst.d.
run-parts: executing /etc/kernel/postinst.d/S30initramfs 2.6.32-3-686 /boot/vmlinuz-2.6.32-3-686
^ ^
| +-- 2nd argument
+-- 1st argument

-----

Q.E.D.

Post by maximilian attems

But a maintainer script for a kernel
image package created by "make deb-pkg" passes only the first argument.

no.

The actual text of /etc/kernel/postinst.d/initramfs-tools:

-----

#!/bin/sh

version="$1"
bootopt=""

# passing the kernel version is required
[ -z "${version}" ] && exit 0

# kernel-package passes an extra arg
if [ -n "$2" ]; then
if [ -n "${KERNEL_PACKAGE_VERSION}" ]; then
bootdir=$(dirname "$2")
bootopt="-b ${bootdir}"
else
# official Debian linux-images take care themself
exit 0
fi
fi

# avoid running multiple times
if [ -n "$DEB_MAINT_PARAMS" ]; then
eval set -- "$DEB_MAINT_PARAMS"
if [ -z "$1" ] || [ "$1" != "configure" ]; then
exit 0
fi
fi

# we're good - create initramfs. update runs do_bootloader
update-initramfs -c -t -k "${version}" ${bootopt}

-----

I admit that I have never personally used "make deb-pkg", but
clearly the source code speaks for itself. This hook script is
expecting only one argument when invoked by "make deb-pkg".

Q.E.D.

Post by maximilian attems

Existing hook scripts rely on that difference to determine whether or
not to take action. For example, the initramfs hook script provided by
the initramfs-tools package tests the number of arguments and exits
without doing anything if more than one argument is supplied. In other
words, this hook script is designed to create the initial RAM file system
for a kernel image created by "make deb-pkg", and only for a kernel
image created by "make deb-pkg". It does nothing otherwise. Are you
proposing to change this behavior?

please get your facts right before spamming the world.

OK, you're partly right on this one. Execution tracing shows that it
does nothing when invoked by a stock kernel maintainer script but
does create an initial RAM file system when invoked by a maintainer
script from a kernel image package created by make-kpkg. (By the way,
since this script is running under debconf, output from update-initramfs
should be redirected to standard error via ">&2".) I don't remember the
kernel-package logic being present in this script the last time I looked
at it.

(1) As far as I am able to determine, my original statements are correct,
with the exception of the correction made in the above paragraph.
If you can prove me wrong, please do so.
(2) This was not spam. Spam is unsolicited advertising.
This was a response to an RFC, to which I was explicitly
included as an adressee.
(3) All the addressees of my e-mail were legitimate stake-holders
in this process. This is not "the world".
--
.''`. Stephen Powell
: :' :
`. `'`
`-

[Ben Hutchings]

On Mon, 2010-06-28 at 18:45 +0200, maximilian attems wrote:
[...]

Post by maximilian attems
please get your facts right before spamming the world.

Max, this is rude and unjustified.

Ben.

[Ben Hutchings]

Please reply to debian-kernel only.
[...]

Post by Stephen Powell

The environment variable DEB_MAINT_PARAMS will contain
the arguments given to the kernel maintainer script, single-quoted.

Is this environment variable provided by the maintainer scripts
that come with kernel image packages created by "make deb-pkg"?
(I honestly don't know. I've never used "make deb-pkg".)

It has done since 2.6.31, though without single-quotes. I'll note that
they may or may not be quoted, and recommend how to use this variable.

[...]

Post by Stephen Powell

5. Kernel and initramfs builder packages must not invoke boot loaders
except via hooks. If /etc/kernel-img.conf contains an explicit
'do_bootloader = yes', kernel package maintainer scripts should warn
that this is now ignored.

At the risk of flogging a dead horse, I would prefer to see
"do_bootloader = yes" supported until Squeeze+1, both by the
kernel maintainer scripts and by "update-initramfs -u", particularly
since we are so close to a freeze.

The release team has stated we are not close to a freeze. So we have a
little time to sort this out.

Post by Stephen Powell
But if
you're going to drop support for it in Squeeze, then yes,
a warning message is necessary. Both the kernel maintainer scripts
*and* "update-initramfs -u" *must* issue a warning message if they
find "do_bootloader = yes" specified in /etc/kernel-img.conf.
In fact, since the default value is "yes", they should issue
the warning message unless do_bootloader is *explicitly* set
to no.

I can put a one-time warning into linux-base. But the default for
squeeze must be 'no'. It should not be necessary to create
/etc/kernel-img.conf at all in squeeze.

Post by Stephen Powell

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

Doesn't this conflict with point 4 (a)?

Not at all. This means postinst_hook and postrm_hook are now strictly
for use by the user.

Ben.

[Ben Hutchings]

I think this incorporates all the comments and corrections for the
previous version. Please send follow-ups to debian-kernel, and
subscribe to it if you haven't already done so.

Ben.

---
0. 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 '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).
[Alternately we should change linux-2.6 and kernel-package to do the
necessary redirection. Is there any legitimate reason for a hook script
to interact with debconf?]

1. 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, which
will be called on installation/upgrade and removal of kernel packages,
respectively.

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.

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

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

3. Initramfs builders must complete their work before returning from the
kernel postinst hook script. [initramfs-tools currently uses a trigger
to defer this because it can also be invoked twice, but this means it
also has to know how to update specific boot loaders. This new
requirement will allow boot loader packages to avoid unnecessary
updates, as described in the following section.]

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

a. A postinst_hook or postrm_hook command set by the user or the
installer in /etc/kernel-img.conf
b. A hook script in /etc/initramfs/post-update.d
c. A hook script in /etc/kernel/postinst.d or .../postrm.d

To avoid unnecessary updates, the hooks invoked at step a and b may
check whether $DPKG_MAINTSCRIPT_PACKAGE begins with 'linux-image-' and
do nothing in this case.

5. Kernel packages must not invoke boot loaders 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. In squeeze+1, this prohibition extends to initramfs builder
packages.

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