kernel-install
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.