'\" t
.TH "KERNEL\-INSTALL" "8" "" "systemd 247" "kernel-install"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
kernel-install \- Add and remove kernel and initramfs images to and from /boot
.SH "SYNOPSIS"
.HP \w'\fBkernel\-install\fR\ 'u
\fBkernel\-install\fR COMMAND [OPTIONS...] \fIKERNEL\-VERSION\fR \fIKERNEL\-IMAGE\fR [\fIINITRD\-FILE\fR...]
.SH "DESCRIPTION"
.PP
\fBkernel\-install\fR
is used to install and remove kernel and initramfs images to and from the boot loader partition, referred to as
\fI$BOOT\fR
here\&. It will usually be one of
/boot/,
/efi/, or
/boot/efi/, see below\&.
.PP
\fBkernel\-install\fR
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\&.
.PP
An executable should return
\fB0\fR
on success\&. It may also return
\fB77\fR
to cause the whole operation to terminate (executables later in lexical order will be skipped)\&.
.SH "COMMANDS"
.PP
The following commands are understood:
.PP
\fBadd \fR\fB\fIKERNEL\-VERSION\fR\fR\fB \fR\fB\fIKERNEL\-IMAGE\fR\fR\fB [\fR\fB\fIINITRD\-FILE\fR\fR\fB \&.\&.\&.]\fR
.RS 4
This command expects a kernel version string and a path to a kernel image file as arguments\&.
\fBkernel\-install\fR
calls the executables from
/usr/lib/kernel/install\&.d/*\&.install
and
/etc/kernel/install\&.d/*\&.install
with the following arguments:
.sp
.if n \{\
.RS 4
.\}
.nf
add \fIKERNEL\-VERSION\fR $BOOT/\fIMACHINE\-ID\fR/\fIKERNEL\-VERSION\fR/ \fIKERNEL\-IMAGE\fR [\fIINITRD\-FILE\fR \&.\&.\&.]
.fi
.if n \{\
.RE
.\}
.sp
Three default plugins execute the following operations in this case:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
00\-entry\-directory\&.install
creates the directory
$BOOT/\fIMACHINE\-ID\fR/\fIKERNEL\-VERSION\fR/
if
$BOOT/\fIMACHINE\-ID\fR/
already exists\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
50\-depmod\&.install
runs
\fBdepmod\fR(8)
for the
\fIKERNEL\-VERSION\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
90\-loaderentry\&.install
copies
\fIKERNEL\-IMAGE\fR
to
$BOOT/\fIMACHINE\-ID\fR/\fIKERNEL\-VERSION\fR/linux\&. If an
\fIINITRD\-FILE\fR
is provided, it also copies
\fIINITRD\-FILE\fR
to
$BOOT/\fIMACHINE\-ID\fR/\fIKERNEL_VERSION\fR/\fIINITRD\-FILE\fR\&. It also creates a boot loader entry according to the
\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2
in
$BOOT/loader/entries/\fIMACHINE\-ID\fR\-\fIKERNEL\-VERSION\fR\&.conf\&. The title of the entry is the
\fIPRETTY_NAME\fR
parameter specified in
/etc/os\-release
or
/usr/lib/os\-release
(if the former is missing), or "Linux
\fIKERNEL\-VERSION\fR", if unset\&.
.sp
If the entry directory
$BOOT/\fIMACHINE\-ID\fR/\fIKERNEL\-VERSION\fR/
does not exist, this plugin does nothing\&.
.RE
.RE
.PP
\fBremove \fR\fB\fIKERNEL\-VERSION\fR\fR
.RS 4
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:
.sp
.if n \{\
.RS 4
.\}
.nf
remove \fIKERNEL\-VERSION\fR $BOOT/\fIMACHINE\-ID\fR/\fIKERNEL\-VERSION\fR/
.fi
.if n \{\
.RE
.\}
.sp
Afterwards,
\fBkernel\-install\fR
removes the directory
$BOOT/\fIMACHINE\-ID\fR/\fIKERNEL\-VERSION\fR/
and its contents\&.
.sp
Two default plugins execute the following operations in this case:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
50\-depmod\&.install
removes the files generated by
\fBdepmod\fR
for this kernel again\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
90\-loaderentry\&.install
removes the file
$BOOT/loader/entries/\fIMACHINE\-ID\fR\-\fIKERNEL\-VERSION\fR\&.conf\&.
.RE
.RE
.SH "THE \FI$BOOT\FR PARTITION"
.PP
The partition where the kernels and
\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2
snippets are located is called
\fI$BOOT\fR\&.
\fBkernel\-install\fR
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\&.
.SH "OPTIONS"
.PP
The following options are understood:
.PP
\fB\-v\fR, \fB\-\-verbose\fR
.RS 4
Output additional information about operations being performed\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.SH "ENVIRONMENT VARIABLES"
.PP
If
\fB\-\-verbose\fR
is used,
\fI$KERNEL_INSTALL_VERBOSE=1\fR
will be set for the plugins\&. They may output additional logs in this case\&.
.SH "EXIT STATUS"
.PP
If every executable returns 0 or 77, 0 is returned, and a non\-zero failure code otherwise\&.
.SH "FILES"
.PP
/usr/lib/kernel/install\&.d/*\&.install /etc/kernel/install\&.d/*\&.install
.RS 4
Drop\-in files which are executed by kernel\-install\&.
.RE
.PP
/etc/kernel/cmdline /proc/cmdline
.RS 4
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\&.
.RE
.PP
/etc/kernel/tries
.RS 4
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/\fIMACHINE\-ID\fR\-\fIKERNEL\-VERSION\fR+\fITRIES\fR\&.conf\&. This is useful for boot loaders such as
\fBsystemd-boot\fR(7)
which implement boot attempt counting with a counter embedded in the entry file name\&.
.RE
.PP
/etc/machine\-id
.RS 4
The content of this file specifies the machine identification
\fIMACHINE\-ID\fR\&. If it cannot read
/etc/machine\-id, kernel\-install will use "Linux" as the machine ID instead\&.
.RE
.PP
/etc/os\-release /usr/lib/os\-release
.RS 4
The content of the file specifies the operating system title
\fIPRETTY_NAME\fR\&.
.RE
.SH "SEE ALSO"
.PP
\fBmachine-id\fR(5),
\fBos-release\fR(5),
\fBdepmod\fR(8),
\fBsystemd-boot\fR(7),
\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2
.SH "NOTES"
.IP " 1." 4
Boot Loader Specification
.RS 4
\%https://systemd.io/BOOT_LOADER_SPECIFICATION
.RE