2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
6 <refentry id=
"kernel-install"
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <title>kernel-install
</title>
11 <productname>systemd
</productname>
15 <refentrytitle>kernel-install
</refentrytitle>
16 <manvolnum>8</manvolnum>
20 <refname>kernel-install
</refname>
21 <refpurpose>Add and remove kernel and initramfs images to and from /boot
</refpurpose>
26 <command>kernel-install
</command>
27 <arg choice=
"plain">COMMAND
</arg>
28 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
29 <arg choice=
"plain"><replaceable>KERNEL-VERSION
</replaceable></arg>
30 <arg choice=
"plain"><replaceable>KERNEL-IMAGE
</replaceable></arg>
31 <arg choice=
"opt" rep=
"repeat"><replaceable>INITRD-FILE
</replaceable></arg>
36 <title>Description
</title>
37 <para><command>kernel-install
</command> is used to install and remove kernel and initramfs images to and
38 from the boot loader partition, referred to as
<varname>$BOOT
</varname> here. It will usually be one of
39 <filename>/boot
</filename>,
<filename>/efi
</filename>, or
<filename>/boot/efi
</filename>, see below.
42 <para><command>kernel-install
</command> will execute the files
43 located in the directory
<filename>/usr/lib/kernel/install.d/
</filename>
44 and the local administration directory
<filename>/etc/kernel/install.d/
</filename>.
45 All files are collectively sorted and executed in lexical order, regardless of the directory in
46 which they live. However, files with identical filenames replace each other.
47 Files in
<filename>/etc/kernel/install.d/
</filename> take precedence over files with the same name
48 in
<filename>/usr/lib/kernel/install.d/
</filename>. This can be used to override a system-supplied
49 executables with a local file if needed; a symbolic link in
<filename>/etc/kernel/install.d/
</filename>
50 with the same name as an executable in
<filename>/usr/lib/kernel/install.d/
</filename>,
51 pointing to
<filename>/dev/null
</filename>, disables the executable entirely. Executables must have the
52 extension
<literal>.install
</literal>; other extensions are ignored.
</para>
54 <para>An executable should return
<constant>0</constant> on success. It may also
55 return
<constant>77</constant> to cause the whole operation to terminate
56 (executables later in lexical order will be skipped).
</para>
60 <title>Commands
</title>
61 <para>The following commands are understood:
</para>
64 <term><command>add
<replaceable>KERNEL-VERSION
</replaceable> <replaceable>KERNEL-IMAGE
</replaceable> [
<replaceable>INITRD-FILE
</replaceable> ...]
</command></term>
66 <para>This command expects a kernel version string and a path to a kernel image file as
67 arguments.
<command>kernel-install
</command> calls the executables from
68 <filename>/usr/lib/kernel/install.d/*.install
</filename> and
69 <filename>/etc/kernel/install.d/*.install
</filename> with the following arguments:
71 <programlisting>add
<replaceable>KERNEL-VERSION
</replaceable> <filename>$BOOT/
<replaceable>MACHINE-ID
</replaceable>/
<replaceable>KERNEL-VERSION
</replaceable>/
</filename> <replaceable>KERNEL-IMAGE
</replaceable> [
<replaceable>INITRD-FILE
</replaceable> ...]
</programlisting>
74 <para>Three default plugins execute the following operations in this case:
</para>
77 <listitem><para><filename>00-entry-directory.install
</filename> creates the directory
78 <filename>$BOOT/
<replaceable>MACHINE-ID
</replaceable>/
<replaceable>KERNEL-VERSION
</replaceable>/
</filename>
79 if
<filename>$BOOT/
<replaceable>MACHINE-ID
</replaceable>/
</filename> already exists.
82 <listitem><para><filename>50-depmod.install
</filename> runs
83 <citerefentry><refentrytitle>depmod
</refentrytitle><manvolnum>8</manvolnum></citerefentry> for the
84 <replaceable>KERNEL-VERSION
</replaceable>.
</para></listitem>
86 <listitem><para><filename>90-loaderentry.install
</filename> copies
<replaceable>KERNEL-IMAGE
</replaceable>
88 <filename>$BOOT/
<replaceable>MACHINE-ID
</replaceable>/
<replaceable>KERNEL-VERSION
</replaceable>/linux
</filename>.
89 If an
<replaceable>INITRD-FILE
</replaceable> is provided, it also copies
<replaceable>INITRD-FILE
</replaceable>
91 <filename>$BOOT/
<replaceable>MACHINE-ID
</replaceable>/
<replaceable>KERNEL_VERSION
</replaceable>/
<replaceable>INITRD-FILE
</replaceable></filename>.
92 It also creates a boot loader entry according to the
<ulink
93 url=
"https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification
</ulink> in
94 <filename>$BOOT/loader/entries/
<replaceable>MACHINE-ID
</replaceable>-
<replaceable>KERNEL-VERSION
</replaceable>.conf
</filename>.
95 The title of the entry is the
<replaceable>PRETTY_NAME
</replaceable> parameter specified in
96 <filename>/etc/os-release
</filename> or
<filename>/usr/lib/os-release
</filename> (if the former is
97 missing), or
"Linux <replaceable>KERNEL-VERSION</replaceable>", if unset.
</para>
99 <para>If the entry directory
100 <filename>$BOOT/
<replaceable>MACHINE-ID
</replaceable>/
<replaceable>KERNEL-VERSION
</replaceable>/
</filename>
101 does not exist, this plugin does nothing.
</para></listitem>
106 <term><command>remove
<replaceable>KERNEL-VERSION
</replaceable></command></term>
108 <para>This command expects a kernel version string as single argument. This calls executables from
109 <filename>/usr/lib/kernel/install.d/*.install
</filename> and
110 <filename>/etc/kernel/install.d/*.install
</filename> with the following arguments:
112 <programlisting>remove
<replaceable>KERNEL-VERSION
</replaceable> <filename>$BOOT/
<replaceable>MACHINE-ID
</replaceable>/
<replaceable>KERNEL-VERSION
</replaceable>/
</filename></programlisting>
115 <para>Afterwards,
<command>kernel-install
</command> removes the directory
116 <filename>$BOOT/
<replaceable>MACHINE-ID
</replaceable>/
<replaceable>KERNEL-VERSION
</replaceable>/
</filename>
117 and its contents.
</para>
119 <para>Two default plugins execute the following operations in this case:
</para>
123 <listitem><para><filename>50-depmod.install
</filename> removes the files generated by
<command>depmod
</command> for this kernel again.
</para></listitem>
125 <listitem><para><filename>90-loaderentry.install
</filename> removes the file
126 <filename>$BOOT/loader/entries/
<replaceable>MACHINE-ID
</replaceable>-
<replaceable>KERNEL-VERSION
</replaceable>.conf
</filename>.
</para></listitem>
136 <title>The
<varname>$BOOT
</varname> partition
</title>
137 <para>The partition where the kernels and
<ulink url=
"https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot
138 Loader Specification
</ulink> snippets are located is called
<varname>$BOOT
</varname>.
139 <command>kernel-install
</command> determines the location of this partition by checking
140 <filename>/efi/
</filename>,
<filename>/boot/
</filename>, and
<filename>/boot/efi
</filename>
141 in turn. The first location where
<filename>$BOOT/loader/entries/
</filename> or
142 <filename>$BOOT/$MACHINE_ID/
</filename> exists is used.
</para>
146 <title>Options
</title>
147 <para>The following options are understood:
</para>
151 <term><option>-v
</option></term>
152 <term><option>--verbose
</option></term>
154 <para>Output additional information about operations being performed.
</para>
158 <xi:include href=
"standard-options.xml" xpointer=
"help" />
163 <title>Environment variables
</title>
164 <para>If
<option>--verbose
</option> is used,
<varname>$KERNEL_INSTALL_VERBOSE=
1</varname> will be set for
165 the plugins. They may output additional logs in this case.
</para>
169 <title>Exit status
</title>
170 <para>If every executable returns
0 or
77,
0 is returned, and a non-zero failure code otherwise.
</para>
178 <filename>/usr/lib/kernel/install.d/*.install
</filename>
179 <filename>/etc/kernel/install.d/*.install
</filename>
182 <para>Drop-in files which are executed by kernel-install.
</para>
187 <filename>/etc/kernel/cmdline
</filename>
188 <filename>/proc/cmdline
</filename>
191 <para>Read by
<filename>90-loaderentry.install
</filename>. The content of the file
192 <filename>/etc/kernel/cmdline
</filename> specifies the kernel command line to use. If that file does not
193 exist,
<filename>/proc/cmdline
</filename> is used.
</para>
198 <filename>/etc/kernel/tries
</filename>
201 <para>Read by
<filename>90-loaderentry.install
</filename>. If this file exists a numeric value is read from
202 it and the naming of the generated entry file is slightly altered to include it as
203 <filename>$BOOT/loader/entries/
<replaceable>MACHINE-ID
</replaceable>-
<replaceable>KERNEL-VERSION
</replaceable>+
<replaceable>TRIES
</replaceable>.conf
</filename>. This
204 is useful for boot loaders such as
205 <citerefentry><refentrytitle>systemd-boot
</refentrytitle><manvolnum>7</manvolnum></citerefentry> which
206 implement boot attempt counting with a counter embedded in the entry file name.
</para>
211 <filename>/etc/machine-id
</filename>
214 <para>The content of the file specifies the machine identification
<replaceable>MACHINE-ID
</replaceable>.
</para>
219 <filename>/etc/os-release
</filename>
220 <filename>/usr/lib/os-release
</filename>
223 <para>The content of the file specifies the operating system title
<replaceable>PRETTY_NAME
</replaceable>.
</para>
230 <title>See Also
</title>
232 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
233 <citerefentry><refentrytitle>os-release
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
234 <citerefentry><refentrytitle>depmod
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
235 <citerefentry><refentrytitle>systemd-boot
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
236 <ulink url=
"https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification
</ulink>