Installkernel

From Gentoo Wiki
Jump to:navigation Jump to:search
Resources
Other languages:

Installkernel is a collection of scripts to automatically install new kernels and update bootloader configuration.

The package sys-kernel/installkernel provides two different paths of managing kernel installation. The first is the traditional installkernel originating from Debian, the second is systemd's kernel-install.

The systemd USE flag changes which one is used by default, this default can be overridden with the SYSTEMD_KERNEL_INSTALL environment variable.

Debian's installkernel

To select this installation method, disable the systemd USE flag or set SYSTEMD_KERNEL_INSTALL=0 in the environment. The additional USE flags on sys-kernel/installkernel should be used to control the installation of additional automation plugins as shown in the overview below.

USE flags for sys-kernel/installkernel Gentoo fork of installkernel script from debianutils

dracut Generate an initramfs or UKI on each kernel installation
efistub EXPERIMENTAL: Update UEFI configuration on each kernel installation
grub Re-generate grub.cfg on each kernel installation, used grub.cfg is overridable with GRUB_CFG env var
refind Install a Gentoo icon for rEFInd alongside the (unified) kernel image, used icon is overridable with REFIND_ICON env var
systemd Use systemd's kernel-install to install kernels, overridable with SYSTEMD_KERNEL_INSTALL env var
systemd-boot Use systemd-boot's native layout by default
ugrd Generate an initramfs using UGRD on each kernel installation
uki Install UKIs to ESP/EFI/Linux for EFI stub booting and/or bootloaders with support for auto-discovering UKIs
ukify Build an UKI with systemd's ukify on each kernel installation

FILE /etc/portage/package.use/installkernel
sys-kernel/installkernel -systemd
root #emerge --ask sys-kernel/installkernel
FILE /etc/env.d/99no-systemd-kernel-install
SYSTEMD_KERNEL_INSTALL=0
root #env-update
Note
Since the traditional installkernel installs the initramfs and/or Unified Kernel Image (UKI) at the same place as the kernel image, these files may be left-over when switching from a configuration with initramfs and/or Unified Kernel Image to one without. In this situation these files may have to be cleaned up manually to ensure they are not picked up and installed by installkernel.

Customization

Custom plugins to, for example, generate initramfs or Unified Kernel Image (UKI) may be installed into /etc/kernel/preinst.d. An initramfs plugin should install a file named initrd at the same location as the kernel image. And an UKI plugin should install a file named uki.efi at the same location as the kernel image.

Additionally, custom plugins to, for example, update the bootloader configuration may be installed in /etc/kernel/postinst.d.

Systemd's kernel-install

To select this installation method, enable the systemd USE flag or set SYSTEMD_KERNEL_INSTALL=1 in the environment. The additional USE flags on sys-kernel/installkernel control the default configuration of kernel-install as described below.

FILE /etc/portage/package.use/installkernel
sys-kernel/installkernel systemd
root #emerge --ask sys-kernel/installkernel
FILE /etc/env.d/99systemd-kernel-install
SYSTEMD_KERNEL_INSTALL=1
root #env-update

Configuration

Configuration of kernel-install is done in /etc/kernel/install.conf and /usr/lib/kernel/install.conf, where the former takes precedence over the latter. Three configuration options can be set:

FILE /etc/kernel/install.conf
layout=
initrd_generator=
uki_generator=

The USE flags on sys-kernel/installkernel that provide additional automation plugins for Debian's installkernel also control the default install.conf configuration file for systemd's kernel-install. Of course the configuration may also be changed manually.

layout

Upstream systemd supports the Boot Loader Specification type 1 (layout=bls) and type 2 (layout=uki) layout. The type 1 layout is used by systemd-boot, the type 2 layout is intended to be used for Unified Kernel Images and is supported by GRUB, systemd-boot and refind, though installkernel currently does not provide a plugin to update refind's configuration.

Gentoo also supports a more traditional layout intended for use with GRUB (layout=grub), which is very similar (but not identical) to the layout used by Debian's installkernel as described above. This layout may also be used in other cases where a more basic and traditional layout is desired. To use GRUB in combination with Unified Kernel Images, use the uki layout instead.

initrd_generator

This setting controls which plugin should be used to generate the initramfs. Currently the only package that installs such a plugin is Dracut from sys-kernel/dracut. This setting is exposed to the plugins as ${KERNEL_INSTALL_INITRD_GENERATOR}.

uki_generator

This setting controls which plugin should be used to generate the Unified Kernel Image. Currently two packages provide such a plugin: sys-kernel/dracut and systemd (via the ukify flag on sys-apps/systemd and sys-apps/systemd-utils). This setting is exposed to the plugins as ${KERNEL_INSTALL_UKI_GENERATOR}

Customization

Custom plugins to, for example, generate initramfs or UKI, or update the bootloader configuration, may be installed into /etc/kernel/install.d. An initramfs plugin should install a file named initrd on the ${KERNEL_INSTALL_STAGING_AREA}. And an UKI plugin should install a file named uki.efi on the ${KERNEL_INSTALL_STAGING_AREA}. All plugin files must have the .install suffix. Plugins in /etc/kernel/install.d override default plugins in /usr/lib/kernel/install.d with the same name.

See also