kernel-install

From ArchWiki

kernel-install(8) is a script used to automatically move kernels and their respective initramfs images to the boot partition (usually mounted at /boot or /efi). It uses a script system which can extend its functionality. It also creates boot entries for systemd-boot for the installed kernel and initramfs.

Installation

kernel-install is part of and packaged with systemd. The systemd-ukify optional dependency is also needed for unified kernel images unless a different UKI generator is specified (with the uki_generator option).

Configuration

For all the details of possible configurations see kernel-install(8).

Here are the most important configurations that you can set in /etc/kernel/install.conf

layout

The installation layout that will be followed by kernel-install. For details also see the Standard Boot Loader Specification.

Possible values are:

value meaning
bls Traditional split kernel and initrd images
uki Standard Boot Loader Specification type 2 layout, a.k.a. unified kernel images under the /efi/EFI/Linux, /boot/EFI/Linux, or /boot/efi/EFI/Linux

initrd_generator

The initrd generator to use to generate the initramfs images. i.e.: mkinitcpio, dracut etc.

uki_generator

In case the layout is set to uki who should perform the UKI image generation. It could be either ukify which will merge a standalone initramfs image and a kernel image into a UKI image or it could be the initrd generator itself, if it can generate UKI images directly, like mkinitcpio.

Usage

The kernel-install script is not an initramfs generator itself, but uses another program, such as mkinitcpio or dracut to generate an initramfs. In order to use an initramfs, an initramfs generator must be installed.

Adding kernels

One can install a kernel from /usr/lib/modules as follows:

# kernel-install add A.B.C-name /usr/lib/modules/A.B.C-name/vmlinuz

Removing kernels

To remove a kernel, use the remove subcommand:

# kernel-install remove A.B.C-name

UKI generator

For generating UKI images, kernel-install needs a initrd_generator and an uki_generator.

If uki_generator is not specified it will default to ukify. Since 2024-01-15, mkinitcpio no longer creates .efi images in all cases, forcing users to either install the separate systemd-ukify package or change the default image generator.

Direct UKI image generation by the initrd generator

Some initramfs generators are actually capable of generating a UKI image directly, e.g. mkinitcpio. To use mkinitcpio to generate an UKI image directly specify the uki_generator to mkinitcpio:

# echo uki_generator=mkinitcpio >> /etc/kernel/install.conf

In this case systemd-ukify is not needed at all.

Plugins

kernel-install has the concept of plugins, scripts or other programs for kernel-install(8) to run when it installs, upgrades, or removes a kernel (and initrd for bls). For instance, sbctl contains kernel-install plugin scripts that can automatically sign new UKIs for Secure Boot, e.g. /usr/lib/kernel/install.d/91-sbctl.install.

The system administrator can write their own kernel-install plugins; place them in /etc/kernel/install.d/ (which will override files in /usr/lib/kernel/install.d/). The administrator can also disable a system plugin by overriding its basename in the local system directory, i.e.:

# ln -sf /dev/null /etc/kernel/install.d/91-sbctl.install

Tips and tricks

Pacman hook

For a pacman hook triggering on update of a kernel package to install that kernel automatically, pacman-hook-kernel-installAUR can be installed.

A similar, conflicting functionality is already performed by the mkinitcpio package's pacman hooks. If you want to switch to kernel-install, you will need to manually mask the pacman hooks of mkinitcpio:

# ln -s /dev/null /etc/pacman.d/hooks/60-mkinitcpio-remove.hook
# ln -s /dev/null /etc/pacman.d/hooks/90-mkinitcpio-install.hook

Unified kernel images

See Unified kernel image#kernel-install

Troubleshooting

"... is missing .efi suffix."

Due to the way mkinitcpio worked in the past, mkinitcpio was always generating a UKI image when the kernel-install layout was set to uki, even when there was no value set for uki_generator. This is because that configuration option didn't have a default value of ukify when kernel-install support for mkinitcpio was added.

This is no longer the case. This can result in error messages like: "... is missing .efi suffix.", in case the value of uki_generator is not set and systemd-ukify is not installed.

To fix this either install systemd-ukify or set uki_generator to mkinitcpio.

See also