2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
9 <refentry id=
"kernel-install">
12 <title>kernel-install
</title>
13 <productname>systemd
</productname>
17 <refentrytitle>kernel-install
</refentrytitle>
18 <manvolnum>8</manvolnum>
22 <refname>kernel-install
</refname>
23 <refpurpose>Add and remove kernel and initramfs images to and from /boot
</refpurpose>
28 <command>kernel-install
</command>
29 <arg choice=
"plain">COMMAND
</arg>
30 <arg choice=
"plain"><replaceable>KERNEL-VERSION
</replaceable></arg>
31 <arg choice=
"plain"><replaceable>KERNEL-IMAGE
</replaceable></arg>
32 <arg choice=
"opt" rep=
"repeat"><replaceable>INITRD-FILE
</replaceable></arg>
37 <title>Description
</title>
39 <command>kernel-install
</command> is used to install and remove kernel and
40 initramfs images to and from
<filename>/boot
</filename>.
43 <para><command>kernel-install
</command> will execute the files
44 located in the directory
<filename>/usr/lib/kernel/install.d/
</filename>
45 and the local administration directory
<filename>/etc/kernel/install.d/
</filename>.
46 All files are collectively sorted and executed in lexical order, regardless of the directory in
47 which they live. However, files with identical filenames replace each other.
48 Files in
<filename>/etc/kernel/install.d/
</filename> take precedence over files with the same name
49 in
<filename>/usr/lib/kernel/install.d/
</filename>. This can be used to override a system-supplied
50 executables with a local file if needed; a symbolic link in
<filename>/etc/kernel/install.d/
</filename>
51 with the same name as an executable in
<filename>/usr/lib/kernel/install.d/
</filename>,
52 pointing to
<filename>/dev/null
</filename>, disables the executable entirely. Executables must have the
53 extension
<literal>.install
</literal>; other extensions are ignored.
</para>
55 <para>An executable should return
<constant>0</constant> on success. It may also
56 return
<constant>77</constant> to cause the whole operation to terminate
57 (executables later in lexical order will be skipped).
</para>
61 <title>Commands
</title>
62 <para>The following commands are understood:
</para>
65 <term><command>add
<replaceable>KERNEL-VERSION
</replaceable> <replaceable>KERNEL-IMAGE
</replaceable> [
<replaceable>INITRD-FILE
</replaceable> ...]
</command></term>
67 <para>This command expects a kernel version string and a path to a kernel image file as
68 arguments.
<command>kernel-install
</command> creates the directory
69 <filename>/boot/
<replaceable>MACHINE-ID
</replaceable>/
<replaceable>KERNEL-VERSION
</replaceable>/
</filename>
70 and calls the executables from
<filename>/usr/lib/kernel/install.d/*.install
</filename> and
71 <filename>/etc/kernel/install.d/*.install
</filename> with the following arguments:
73 <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>
76 <para>Two default plugins execute the following operations in this case:
</para>
80 <listitem><para><filename>50-depmod.install
</filename> runs
81 <citerefentry><refentrytitle>depmod
</refentrytitle><manvolnum>8</manvolnum></citerefentry> for the
82 <replaceable>KERNEL-VERSION
</replaceable>.
</para></listitem>
84 <listitem><para><filename>90-loaderentry.install
</filename> copies
<replaceable>KERNEL-IMAGE
</replaceable>
86 <filename>/boot/
<replaceable>MACHINE-ID
</replaceable>/
<replaceable>KERNEL-VERSION
</replaceable>/linux
</filename>.
87 If an
<replaceable>INITRD-FILE
</replaceable> is provided, it also copies
<replaceable>INITRD-FILE
</replaceable>
89 <filename>/boot/
<replaceable>MACHINE-ID
</replaceable>/
<replaceable>KERNEL_VERSION
</replaceable>/
<replaceable>INITRD-FILE
</replaceable></filename>.
90 It also creates a boot loader entry according to the
<ulink
91 url=
"https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification
</ulink> in
92 <filename>/boot/loader/entries/
<replaceable>MACHINE-ID
</replaceable>-
<replaceable>KERNEL-VERSION
</replaceable>.conf
</filename>.
93 The title of the entry is the
<replaceable>PRETTY_NAME
</replaceable> parameter specified in
94 <filename>/etc/os-release
</filename> or
<filename>/usr/lib/os-release
</filename> (if the former is
95 missing), or
"Linux <replaceable>KERNEL-VERSION</replaceable>", if unset.
</para></listitem>
100 <term><command>remove
<replaceable>KERNEL-VERSION
</replaceable></command></term>
102 <para>This command expects a kernel version string as single argument. This calls executables from
103 <filename>/usr/lib/kernel/install.d/*.install
</filename> and
104 <filename>/etc/kernel/install.d/*.install
</filename> with the following arguments:
106 <programlisting>remove
<replaceable>KERNEL-VERSION
</replaceable> <filename>/boot/
<replaceable>MACHINE-ID
</replaceable>/
<replaceable>KERNEL-VERSION
</replaceable>/
</filename></programlisting>
109 <para>Afterwards,
<command>kernel-install
</command> removes the directory
110 <filename>/boot/
<replaceable>MACHINE-ID
</replaceable>/
<replaceable>KERNEL-VERSION
</replaceable>/
</filename>
111 and its contents.
</para>
113 <para>Two default plugins execute the following operations in this case:
</para>
117 <listitem><para><filename>50-depmod.install
</filename> removes the files generated by
<command>depmod
</command> for this kernel again.
</para></listitem>
119 <listitem><para><filename>90-loaderentry.install
</filename> removes the file
120 <filename>/boot/loader/entries/
<replaceable>MACHINE-ID
</replaceable>-
<replaceable>KERNEL-VERSION
</replaceable>.conf
</filename>.
</para></listitem>
131 <title>Exit status
</title>
132 <para>If every executable returns
0 or
77,
0 is returned, and a non-zero failure code otherwise.
</para>
140 <filename>/usr/lib/kernel/install.d/*.install
</filename>
141 <filename>/etc/kernel/install.d/*.install
</filename>
144 <para>Drop-in files which are executed by kernel-install.
</para>
149 <filename>/etc/kernel/cmdline
</filename>
150 <filename>/proc/cmdline
</filename>
153 <para>Read by
<filename>90-loaderentry.install
</filename>. The content of the file
154 <filename>/etc/kernel/cmdline
</filename> specifies the kernel command line to use. If that file does not
155 exist,
<filename>/proc/cmdline
</filename> is used.
</para>
160 <filename>/etc/kernel/tries
</filename>
163 <para>Read by
<filename>90-loaderentry.install
</filename>. If this file exists a numeric value is read from
164 it and the naming of the generated entry file is slightly altered to include it as
165 <filename>/boot/loader/entries/
<replaceable>MACHINE-ID
</replaceable>-
<replaceable>KERNEL-VERSION
</replaceable>+
<replaceable>TRIES
</replaceable>.conf
</filename>. This
166 is useful for boot loaders such as
167 <citerefentry><refentrytitle>systemd-boot
</refentrytitle><manvolnum>7</manvolnum></citerefentry> which
168 implement boot attempt counting with a counter embedded in the entry file name.
</para>
173 <filename>/etc/machine-id
</filename>
176 <para>The content of the file specifies the machine identification
<replaceable>MACHINE-ID
</replaceable>.
</para>
181 <filename>/etc/os-release
</filename>
182 <filename>/usr/lib/os-release
</filename>
185 <para>The content of the file specifies the operating system title
<replaceable>PRETTY_NAME
</replaceable>.
</para>
192 <title>See Also
</title>
194 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
195 <citerefentry><refentrytitle>os-release
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
196 <citerefentry><refentrytitle>depmod
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
197 <citerefentry><refentrytitle>systemd-boot
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
198 <ulink url=
"https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification
</ulink>