1<?xml version='1.0'?>
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-or-later -->
5
6<refentry id="kernel-install" conditional='ENABLE_KERNEL_INSTALL'
7          xmlns:xi="http://www.w3.org/2001/XInclude">
8
9  <refentryinfo>
10    <title>kernel-install</title>
11    <productname>systemd</productname>
12  </refentryinfo>
13
14  <refmeta>
15    <refentrytitle>kernel-install</refentrytitle>
16    <manvolnum>8</manvolnum>
17  </refmeta>
18
19  <refnamediv>
20    <refname>kernel-install</refname>
21    <refpurpose>Add and remove kernel and initramfs images to and from /boot</refpurpose>
22  </refnamediv>
23
24  <refsynopsisdiv>
25    <cmdsynopsis>
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>
32    </cmdsynopsis>
33  </refsynopsisdiv>
34
35  <refsect1>
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.
40    </para>
41
42    <para><command>kernel-install</command> will run the executable files ("plugins") located in the
43    directory <filename>/usr/lib/kernel/install.d/</filename> and the local administration directory
44    <filename>/etc/kernel/install.d/</filename>.  All files are collectively sorted and executed in lexical
45    order, regardless of the directory in which they live. However, files with identical filenames replace
46    each other.  Files in <filename>/etc/kernel/install.d/</filename> take precedence over files with the
47    same name in <filename>/usr/lib/kernel/install.d/</filename>. This can be used to override a
48    system-supplied executables with a local file if needed; a symbolic link in
49    <filename>/etc/kernel/install.d/</filename> with the same name as an executable in
50    <filename>/usr/lib/kernel/install.d/</filename>, pointing to <filename>/dev/null</filename>, disables the
51    executable entirely. Executables must have the extension <literal>.install</literal>; other extensions
52    are ignored.</para>
53
54    <para>An executable placed in these directories should return <constant>0</constant> on success. It may
55    also return <constant>77</constant> to cause the whole operation to terminate (executables later in
56    lexical order will be skipped).</para>
57  </refsect1>
58
59  <refsect1>
60    <title>Commands</title>
61    <para>The following commands are understood:</para>
62    <variablelist>
63      <varlistentry>
64        <term><command>add <replaceable>KERNEL-VERSION</replaceable> <replaceable>KERNEL-IMAGE</replaceable> [<replaceable>INITRD-FILE</replaceable> ...]</command></term>
65        <listitem>
66          <para>This command expects a kernel version string and a path to a kernel image file as
67          arguments. Optionally, one or more initial RAM disk images may be specified as well (note that
68          plugins might generate additional ones). <command>kernel-install</command> calls the executable
69          files from <filename>/usr/lib/kernel/install.d/*.install</filename> and
70          <filename>/etc/kernel/install.d/*.install</filename> (i.e. the plugins) with the following
71          arguments:</para>
72
73          <programlisting>add <replaceable>KERNEL-VERSION</replaceable> <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> <replaceable>KERNEL-IMAGE</replaceable> [<replaceable>INITRD-FILE</replaceable> ...]</programlisting>
74
75          <para>The third argument directly refers to the path where to place kernel images, initial RAM disk
76          images and other resources for <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot
77          Loader Specification</ulink> Type #1 entries (the "entry directory"). If other boot loader schemes
78          are used the parameter may be ignored. The <replaceable>ENTRY-TOKEN</replaceable> string is
79          typically the machine ID and is supposed to identify the local installation on the system. For
80          details see below.</para>
81
82          <para>Two default plugins execute the following operations in this case:</para>
83
84          <itemizedlist>
85            <listitem><para><command>kernel-install</command> creates
86            <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable></filename>,
87            if enabled (see <varname>$KERNEL_INSTALL_LAYOUT</varname>).</para></listitem>
88
89            <listitem><para><filename>50-depmod.install</filename> runs
90            <citerefentry project='man-pages'><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry> for the
91            <replaceable>KERNEL-VERSION</replaceable>.</para></listitem>
92
93            <listitem><para><filename>90-loaderentry.install</filename> copies
94            <replaceable>KERNEL-IMAGE</replaceable> to
95            <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/linux</filename>.
96            If <replaceable>INITRD-FILE</replaceable>s are provided, it also copies them to
97            <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL_VERSION</replaceable>/<replaceable>INITRD-FILE</replaceable></filename>.
98            It also creates a boot loader entry according to the <ulink
99            url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> (Type #1) in
100            <filename>$BOOT/loader/entries/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.
101            The title of the entry is the <replaceable>PRETTY_NAME</replaceable> parameter specified in
102            <filename>/etc/os-release</filename> or <filename>/usr/lib/os-release</filename> (if the former
103            is missing), or "Linux <replaceable>KERNEL-VERSION</replaceable>", if unset.</para>
104
105            <para>If <varname>$KERNEL_INSTALL_LAYOUT</varname> is not "bls", this plugin does nothing.</para></listitem>
106          </itemizedlist>
107        </listitem>
108      </varlistentry>
109      <varlistentry>
110        <term><command>remove <replaceable>KERNEL-VERSION</replaceable></command></term>
111        <listitem>
112          <para>This command expects a kernel version string as single argument. This calls executables from
113          <filename>/usr/lib/kernel/install.d/*.install</filename> and
114          <filename>/etc/kernel/install.d/*.install</filename> with the following arguments:
115          </para>
116
117          <programlisting>remove <replaceable>KERNEL-VERSION</replaceable> <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename></programlisting>
118
119          <para>Afterwards, <command>kernel-install</command> removes the entry directory
120          <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
121          and its contents, if it exists.</para>
122
123          <para>Two default plugins execute the following operations in this case:</para>
124
125          <itemizedlist>
126            <listitem><para><filename>50-depmod.install</filename> removes the files generated by <command>depmod</command> for this kernel again.</para></listitem>
127
128            <listitem><para><filename>90-loaderentry.install</filename> removes the file
129            <filename>$BOOT/loader/entries/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.</para></listitem>
130          </itemizedlist>
131        </listitem>
132      </varlistentry>
133      <varlistentry>
134        <term><command>inspect</command></term>
135        <listitem>
136          <para>Shows the various paths and parameters configured or auto-detected. In particular shows the
137          values of the various <varname>$KERNEL_INSTALL_*</varname> environment variables listed
138          below.</para>
139        </listitem>
140      </varlistentry>
141
142    </variablelist>
143  </refsect1>
144
145  <refsect1>
146    <title>The <varname>$BOOT</varname> partition</title>
147    <para>The partition where the kernels and <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot
148    Loader Specification</ulink> snippets are located is called <varname>$BOOT</varname>.
149    <command>kernel-install</command> determines the location of this partition by checking
150    <filename>/efi/</filename>, <filename>/boot/</filename>, and <filename>/boot/efi/</filename> in turn. The
151    first location where <filename>$BOOT/loader/entries/</filename> or
152    <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/</filename> exists is used.</para>
153  </refsect1>
154
155  <refsect1>
156    <title>Options</title>
157    <para>The following options are understood:</para>
158
159    <variablelist>
160      <varlistentry>
161        <term><option>-v</option></term>
162        <term><option>--verbose</option></term>
163        <listitem>
164          <para>Output additional information about operations being performed.</para>
165        </listitem>
166      </varlistentry>
167
168      <xi:include href="standard-options.xml" xpointer="help" />
169      <xi:include href="standard-options.xml" xpointer="version" />
170    </variablelist>
171  </refsect1>
172
173  <refsect1>
174    <title>Environment variables</title>
175
176    <para>If <option>--verbose</option> is used, <varname>$KERNEL_INSTALL_VERBOSE=1</varname> will be set for
177    the plugins. They may output additional logs in this case.</para>
178
179    <para>If <varname>$MACHINE_ID</varname> is set and not empty when <command>kernel-install</command> is
180    invoked, it will be used as <replaceable>MACHINE-ID</replaceable>, overriding any automatic detection
181    attempts.  The value must be a valid machine ID (32 hexadecimal characters).</para>
182
183    <para><varname>$KERNEL_INSTALL_MACHINE_ID</varname> is set for the plugins to the desired
184    <replaceable>MACHINE-ID</replaceable> to use. It's always a 128bit ID, and typically the ID from
185    <filename>/etc/machine-id</filename> or the one passed in via <varname>$MACHINE_ID</varname>. (If no
186    machine ID was specified via these methods it might be generated randomly by
187    <command>kernel-install</command>, in which case it only applies to this invocation.)</para>
188
189    <para><varname>$KERNEL_INSTALL_ENTRY_TOKEN</varname> is set for the plugins to the desired entry "token"
190    to use. It's an identifier that shall be used to identify the local installation, and is often the
191    machine ID, i.e. same as <varname>$KERNEL_INSTALL_MACHINE_ID</varname>, but might also be a different
192    type of identifier, for example a fixed string or the <varname>ID=</varname>,
193    <varname>IMAGE_ID=</varname> values from <filename>/etc/os-release</filename>. The string passed here
194    will be used to name Boot Loader Specification entries, or the directories the kernel image and initial
195    RAM disk images are placed into. Note that while oftentimes
196    <varname>$KERNEL_INSTALL_ENTRY_TOKEN</varname> and <varname>$KERNEL_INSTALL_MACHINE_ID</varname> are set
197    to the same value, the latter is guaranteed to be a valid 32 character ID in lowercase hexadecimals while
198    the former can be any short string. The entry token to use is read from
199    <filename>/etc/kernel/entry-token</filename>, if it exists. Otherwise a few possible candidates below the
200    <varname>$BOOT</varname> are searched for Boot Loader Specification Type 1 entry directories, and if
201    found the entry token is derived from that. If that is not successful the machine ID is used as
202    fallback.</para>
203
204    <para><varname>$KERNEL_INSTALL_BOOT_ROOT</varname> is set for the plugins to the absolute path of the
205    root directory (mount point, usually) of the hierarchy where boot loader entries, kernel images, and
206    associated resources should be placed. This usually is the path where the XBOOTLDR partition or the ESP
207    (EFI System Partition) are mounted, and also conceptually referred to as <varname>$BOOT</varname>. Can be
208    overridden by setting <varname>$BOOT_ROOT</varname>.</para>
209
210    <para><varname>$KERNEL_INSTALL_LAYOUT=bls|other|...</varname> is set for the plugins to specify the
211    installation layout.  Defaults to <option>bls</option> if
212    <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable></filename> exists, or <option>other</option>
213    otherwise.  Additional layout names may be defined by convention. If a plugin uses a special layout, it's
214    encouraged to declare its own layout name and configure <varname>layout=</varname> in
215    <filename>install.conf</filename> upon initial installation. The following values are currently
216    understood:</para>
217
218    <variablelist>
219      <varlistentry>
220        <term>bls</term>
221        <listitem>
222          <para>Standard <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader
223          Specification</ulink> Type #1 layout, compatible with
224          <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>:
225          entries in
226          <filename>$BOOT/loader/entries/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>[+<replaceable>TRIES</replaceable>].conf</filename>,
227          kernel and initrds under
228          <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename></para>
229          <para>Implemented by <filename>90-loaderentry.install</filename>.</para>
230        </listitem>
231      </varlistentry>
232      <varlistentry>
233        <term>other</term>
234        <listitem>
235          <para>Some other layout not understood natively by <command>kernel-install</command>.</para>
236        </listitem>
237      </varlistentry>
238    </variablelist>
239
240    <para><varname>$KERNEL_INSTALL_INITRD_GENERATOR</varname> is set for plugins to select the initrd
241    generator. This may be configured as <varname>initrd_generator=</varname> in
242    <filename>install.conf</filename>. See below.</para>
243
244    <para><varname>$KERNEL_INSTALL_STAGING_AREA</varname> is set for plugins to a path to a directory.
245    Plugins may drop files in that directory, and they will be installed as part of the loader entry, based
246    on the file name and extension.</para>
247  </refsect1>
248
249  <refsect1>
250    <title>Exit status</title>
251    <para>If every executable returns 0 or 77, 0 is returned, and a non-zero failure code otherwise.</para>
252  </refsect1>
253
254  <refsect1>
255    <title>Files</title>
256    <variablelist>
257      <varlistentry>
258        <term>
259          <filename>/usr/lib/kernel/install.d/*.install</filename>
260          <filename>/etc/kernel/install.d/*.install</filename>
261        </term>
262          <listitem>
263            <para>Drop-in files which are executed by kernel-install.</para>
264          </listitem>
265      </varlistentry>
266      <varlistentry>
267        <term>
268          <filename>/usr/lib/kernel/cmdline</filename>
269          <filename>/etc/kernel/cmdline</filename>
270          <filename>/proc/cmdline</filename>
271        </term>
272          <listitem>
273            <para>Read by <filename>90-loaderentry.install</filename>. The content of the file
274            <filename>/etc/kernel/cmdline</filename> specifies the kernel command line to use.  If that file does not
275            exist, <filename>/usr/lib/kernel/cmdline</filename> is used.  If that also does not exist,
276            <filename>/proc/cmdline</filename> is used.</para>
277          </listitem>
278      </varlistentry>
279      <varlistentry>
280        <term>
281          <filename>/etc/kernel/tries</filename>
282        </term>
283          <listitem>
284            <para>Read by <filename>90-loaderentry.install</filename>. If this file exists a numeric value is read from
285            it and the naming of the generated entry file is slightly altered to include it as
286            <filename>$BOOT/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>+<replaceable>TRIES</replaceable>.conf</filename>. This
287            is useful for boot loaders such as
288            <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> which
289            implement boot attempt counting with a counter embedded in the entry file name.</para>
290          </listitem>
291      </varlistentry>
292      <varlistentry>
293        <term>
294          <filename>/etc/kernel/entry-token</filename>
295        </term>
296          <listitem>
297            <para>If this file exists it is read and used as "entry token" for this system, i.e. is used for
298            naming Boot Loader Specification entries, see
299            <varname>$KERNEL_INSTALL_ENTRY_TOKEN</varname> above for details.</para>
300          </listitem>
301      </varlistentry>
302      <varlistentry>
303        <term>
304          <filename>/etc/machine-id</filename>
305        </term>
306          <listitem>
307            <para>The content of this file specifies the machine identification
308            <replaceable>MACHINE-ID</replaceable>.</para>
309          </listitem>
310      </varlistentry>
311      <varlistentry>
312        <term>
313          <filename>/etc/os-release</filename>
314          <filename>/usr/lib/os-release</filename>
315        </term>
316        <listitem>
317            <para>Read by <filename>90-loaderentry.install</filename>.
318            If available, <varname>PRETTY_NAME=</varname> is read from these files and used as the title of the boot menu entry.
319            Otherwise, <literal>Linux <replaceable>KERNEL-VERSION</replaceable></literal> will be used.</para>
320          </listitem>
321      </varlistentry>
322      <varlistentry>
323        <term>
324          <filename>/usr/lib/kernel/install.conf</filename>
325          <filename>/etc/kernel/install.conf</filename>
326        </term>
327          <listitem>
328            <para>Configuration options for <command>kernel-install</command>, as a series of
329            <varname>KEY=</varname><replaceable>VALUE</replaceable> assignments, compatible with shell
330            syntax.  This currently supports two keys: <varname>layout=</varname> and
331            <varname>initrd_generator=</varname>, for details see the Environment variables section above.</para>
332          </listitem>
333      </varlistentry>
334    </variablelist>
335  </refsect1>
336
337  <refsect1>
338    <title>See Also</title>
339    <para>
340      <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
341      <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
342      <citerefentry project='man-pages'><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
343      <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
344      <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>
345    </para>
346  </refsect1>
347
348</refentry>
349