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

  Three default plugins execute the following operations in this case:

  - `00-entry-directory.install` creates the directory `$BOOT/MACHINE-ID/KERNEL-VERSION/` if `$BOOT/MACHINE-ID/` already exists.

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

  - `90-loaderentry.install` copies KERNEL-IMAGE to `$BOOT/MACHINE-ID/KERNEL-VERSION/linux`. If an INITRD-FILE is provided, it also copies INITRD-FILE 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 the entry directory `$BOOT/MACHINE-ID/KERNEL-VERSION/` does not exist, 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`.

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

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

`/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, `/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 the file specifies the machine identification MACHINE-ID.

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

  The content of the file specifies the operating system title PRETTY_NAME.

## See Also

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