kernel-install

systemd
kernel-install 8
kernel-install Add and remove kernel and initramfs images to and from /boot
`kernel-install` COMMAND OPTIONS KERNEL-VERSION KERNEL-IMAGE INITRD-FILE

## Description

`kernel-install` is used to install and remove kernel and initramfs images to and from the boot loader partition, referred to as `$BOOT` here. It will usually be one of `/boot/`, `/efi/`, or `/boot/efi/`, see below.

`kernel-install` will execute the files located in the directory `/usr/lib/kernel/install.d/` and the local administration directory `/etc/kernel/install.d/`. All files are collectively sorted and executed in lexical order, regardless of the directory in which they live. However, files with identical filenames replace each other. Files in `/etc/kernel/install.d/` take precedence over files with the same name in `/usr/lib/kernel/install.d/`. This can be used to override a system-supplied executables with a local file if needed; a symbolic link in `/etc/kernel/install.d/` with the same name as an executable in `/usr/lib/kernel/install.d/`, pointing to `/dev/null`, disables the executable entirely. Executables must have the extension `.install`; other extensions are ignored.

An executable should return `0` on success. It may also return `77` to cause the whole operation to terminate (executables later in lexical order will be skipped).

## Commands

The following commands are understood:

`add KERNEL-VERSION KERNEL-IMAGE [INITRD-FILE ...]`

  This command expects a kernel version string and a path to a kernel image file as arguments. `kernel-install` calls the executables from `/usr/lib/kernel/install.d/*.install` and `/etc/kernel/install.d/*.install` with the following arguments:

      add KERNEL-VERSION $BOOT/MACHINE-ID/KERNEL-VERSION/ KERNEL-IMAGE [INITRD-FILE ...]

  Two default plugins execute the following operations in this case:

  - `kernel-install` creates `$BOOT/MACHINE-ID/KERNEL-VERSION`, if enabled (see `$KERNEL_INSTALL_LAYOUT=`).

  - `50-depmod.install` runs depmod 8 for the KERNEL-VERSION.

  - `90-loaderentry.install` copies KERNEL-IMAGE to `$BOOT/MACHINE-ID/KERNEL-VERSION/linux`. If INITRD-FILEs are provided, it also copies them to `$BOOT/MACHINE-ID/KERNEL_VERSION/INITRD-FILE`. It also creates a boot loader entry according to the Boot Loader Specification in `$BOOT/loader/entries/MACHINE-ID-KERNEL-VERSION.conf`. The title of the entry is the PRETTY_NAME parameter specified in `/etc/os-release` or `/usr/lib/os-release` (if the former is missing), or "Linux KERNEL-VERSION", if unset.

    If `$KERNEL_INSTALL_LAYOUT=` is not "bls", this plugin does nothing.

`remove KERNEL-VERSION`

  This command expects a kernel version string as single argument. This calls executables from `/usr/lib/kernel/install.d/*.install` and `/etc/kernel/install.d/*.install` with the following arguments:

      remove KERNEL-VERSION $BOOT/MACHINE-ID/KERNEL-VERSION/

  Afterwards, `kernel-install` removes the directory `$BOOT/MACHINE-ID/KERNEL-VERSION/` and its contents.

  Two default plugins execute the following operations in this case:

  - `50-depmod.install` removes the files generated by `depmod` for this kernel again.

  - `90-loaderentry.install` removes the file `$BOOT/loader/entries/MACHINE-ID-KERNEL-VERSION.conf`.

  - `kernel-install` removes `$BOOT/MACHINE-ID/KERNEL-VERSION`, if enabled (see `$KERNEL_INSTALL_LAYOUT=`).

## The `$BOOT` partition

The partition where the kernels and Boot Loader Specification snippets are located is called `$BOOT`. `kernel-install` determines the location of this partition by checking `/efi/`, `/boot/`, and `/boot/efi/` in turn. The first location where `$BOOT/loader/entries/` or `$BOOT/$MACHINE_ID/` exists is used.

## Options

The following options are understood:

`-v`
`--verbose`

  Output additional information about operations being performed.

## Environment variables

If `--verbose` is used, `$KERNEL_INSTALL_VERBOSE=1` will be set for the plugins. They may output additional logs in this case.

If `MACHINE_ID=` is set and not empty, it will be used as MACHINE-ID, overriding any automatic detection attempts. The value must be a valid machine ID (32 hexadecimal characters).

`KERNEL_INSTALL_MACHINE_ID=` is set for the plugins to the desired MACHINE-ID – either 32 hexadecimal characters or the special value `Default`.

`KERNEL_INSTALL_BOOT_ROOT=` is set for the plugins to the root directory (mount point, usually) of the hierarchy where boot-loader entries, kernel images, and associated resources should be placed. Can be overridden by setting `BOOT_ROOT=`.

`KERNEL_INSTALL_LAYOUT=bls|other|...` specifies the installation layout. Defaults to `bls` if `$BOOT/MACHINE-ID` exists, or `other` otherwise. Additional layout names may be defined by convention. If a plugin uses a special layout, it's encouraged to declare its own layout name and configure `layout=` in `install.conf` upon initial installation.

bls

  Standard Boot Loader Specification layout, compatible with systemd-boot 7: entries in `$BOOT/loader/entries/MACHINE-ID-KERNEL-VERSION[+TRIES].conf`, kernel and initrds under `$BOOT/MACHINE-ID/KERNEL-VERSION/`

  Provided by `90-loaderentry.install`.

other

  Some other layout not understood natively by `kernel-install`.

## Exit status

If every executable returns 0 or 77, 0 is returned, and a non-zero failure code otherwise.

## Files

`/usr/lib/kernel/install.d/*.install` `/etc/kernel/install.d/*.install`

  Drop-in files which are executed by kernel-install.

`/usr/lib/kernel/cmdline` `/etc/kernel/cmdline` `/proc/cmdline`

  Read by `90-loaderentry.install`. The content of the file `/etc/kernel/cmdline` specifies the kernel command line to use. If that file does not exist, `/usr/lib/kernel/cmdline` is used. If that also does not exist, `/proc/cmdline` is used.

`/etc/kernel/tries`

  Read by `90-loaderentry.install`. If this file exists a numeric value is read from it and the naming of the generated entry file is slightly altered to include it as `$BOOT/loader/entries/MACHINE-ID-KERNEL-VERSION+TRIES.conf`. This is useful for boot loaders such as systemd-boot 7 which implement boot attempt counting with a counter embedded in the entry file name.

`/etc/machine-id`

  The content of this file specifies the machine identification MACHINE-ID. If `/etc/machine-id` cannot be read or is temporary (backed by a file on `tmpfs`), `kernel-install` will use `Default` instead.

`/etc/machine-info`

  If this file contains the `KERNEL_INSTALL_MACHINE_ID` variable, `kernel-install` will use it as MACHINE-ID instead of the contents of `/etc/machine-id`. If the variable is not found in `/etc/machine-info`, `kernel-install` will try to save the machine ID it uses to install to `$BOOT` to this file.

`/etc/os-release` `/usr/lib/os-release`

  Read by `90-loaderentry.install`. If available, `PRETTY_NAME` is read from these files and used as the title of the boot menu entry. Otherwise, `Linux KERNEL-VERSION` will be used.

`/usr/lib/kernel/install.conf` `/etc/kernel/install.conf`

  Configuration options for `kernel-install`, as a series of `KEY=`VALUE assignments, compatible with shell syntax. See the Environment variables section for supported keys.

## See Also

machine-id 5, os-release 5, depmod 8, systemd-boot 7, Boot Loader Specification