man/kernel-install.xml

   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 initrd images to and from the boot partition</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <cmdsynopsis>
  26       <command>kernel-install</command>
  27       <arg choice="opt" rep="repeat">OPTIONS</arg>
  28       <arg choice="plain">add</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     <cmdsynopsis>
  34       <command>kernel-install</command>
  35       <arg choice="opt" rep="repeat">OPTIONS</arg>
  36       <arg choice="plain">remove</arg>
  37       <arg choice="plain"><replaceable>KERNEL-VERSION</replaceable></arg>
  38     </cmdsynopsis>
  39     <cmdsynopsis>
  40       <command>kernel-install</command>
  41       <arg choice="opt" rep="repeat">OPTIONS</arg>
  42       <arg choice="plain">inspect</arg>
  43       <arg choice="opt"><replaceable>KERNEL-VERSION</replaceable></arg>
  44       <arg choice="opt"><replaceable>KERNEL-IMAGE</replaceable></arg>
  45       <arg choice="opt" rep="repeat"><replaceable>INITRD-FILE</replaceable></arg>
  46     </cmdsynopsis>
  47     <cmdsynopsis>
  48       <command>kernel-install</command>
  49       <arg choice="opt" rep="repeat">OPTIONS</arg>
  50       <arg choice="plain">list</arg>
  51     </cmdsynopsis>
  52   </refsynopsisdiv>
  53
  54   <refsect1>
  55     <title>Description</title>
  56     <para><command>kernel-install</command> is used to install and remove kernel and initrd images
  57     <footnote>
  58       <para>Nowadays actually CPIO archives used as an "initramfs", rather than "initrd". See
  59       <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry> for an
  60       explanation.</para>
  61     </footnote>
  62     to and from the boot partition, referred to as <varname>$BOOT</varname> here. It will usually be one of
  63     <filename>/boot/</filename>, <filename>/efi/</filename>, or <filename>/boot/efi/</filename>, see below.
  64     </para>
  65
  66     <para><command>kernel-install</command> will run the executable files ("plugins") located in the
  67     directory <filename>/usr/lib/kernel/install.d/</filename> and the local administration directory
  68     <filename>/etc/kernel/install.d/</filename>.  All files are collectively sorted and executed in lexical
  69     order, regardless of the directory in which they live. However, files with identical filenames replace
  70     each other.  Files in <filename>/etc/kernel/install.d/</filename> take precedence over files with the
  71     same name in <filename>/usr/lib/kernel/install.d/</filename>. This can be used to override a
  72     system-supplied executables with a local file if needed; a symbolic link in
  73     <filename>/etc/kernel/install.d/</filename> with the same name as an executable in
  74     <filename>/usr/lib/kernel/install.d/</filename>, pointing to <filename>/dev/null</filename>, disables the
  75     executable entirely. Executables must have the extension <literal>.install</literal>; other extensions
  76     are ignored.</para>
  77
  78     <para>An executable placed in these directories should return <constant>0</constant> on success. It may
  79     also return <constant>77</constant> to cause the whole operation to terminate (executables later in
  80     lexical order will be skipped).</para>
  81   </refsect1>
  82
  83   <refsect1>
  84     <title>Commands</title>
  85     <para>The following commands are understood:</para>
  86     <variablelist>
  87       <varlistentry>
  88         <term>
  89           <command>add [[[<replaceable>KERNEL-VERSION</replaceable>] <replaceable>KERNEL-IMAGE</replaceable>] [<replaceable>INITRD-FILE</replaceable> ...]]</command>
  90         </term>
  91
  92         <listitem>
  93           <para>This command takes a kernel version string and a path to a kernel image file as arguments. If
  94           the former is omitted, specified as an empty string or as "-" it defaults to the current kernel
  95           version, i.e. the same string <command>uname -r</command> returns. If the latter is omitted,
  96           specified as an empty string or as "-" defaults to
  97           <filename>/usr/lib/modules/<replaceable>KERNEL_VERSION</replaceable>/vmlinuz</filename>. Optionally,
  98           one or more initrd images may be specified as well (note that plugins might generate additional
  99           ones).</para>
 100
 101           <para>The executable files from <filename>/usr/lib/kernel/install.d/*.install</filename> and
 102           <filename>/etc/kernel/install.d/*.install</filename> (i.e. the plugins) are called with the
 103           following arguments:</para>
 104
 105           <programlisting>add <replaceable>KERNEL-VERSION</replaceable> <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> <replaceable>KERNEL-IMAGE</replaceable> \
 106           [<replaceable>INITRD-FILE</replaceable> ...]</programlisting>
 107
 108           <para>The third argument directly refers to the path where to place kernel images, initrd
 109           images and other resources for
 110           <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot
 111           Loader Specification</ulink> Type #1 entries (the "entry directory"). If other boot loader schemes
 112           are used the parameter may be ignored.</para>
 113
 114           <para>The <replaceable>ENTRY-TOKEN</replaceable> string is typically the machine ID and is supposed
 115           to identify the local installation on the system. For details see below.</para>
 116
 117           <para>Two default plugins execute the following operations in this case:</para>
 118
 119           <itemizedlist>
 120             <listitem><para><command>kernel-install</command> creates
 121             <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable></filename>,
 122             if enabled (see <varname>$KERNEL_INSTALL_LAYOUT</varname>).</para></listitem>
 123
 124             <listitem><para><filename>50-depmod.install</filename> runs
 125             <citerefentry project='man-pages'><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry> for the
 126             <replaceable>KERNEL-VERSION</replaceable>.</para></listitem>
 127
 128             <listitem><para><filename>90-loaderentry.install</filename> copies
 129             <replaceable>KERNEL-IMAGE</replaceable> to
 130             <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/linux</filename>.
 131             If <replaceable>INITRD-FILE</replaceable>s are provided, it also copies them to
 132             <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL_VERSION</replaceable>/<replaceable>INITRD-FILE</replaceable></filename>.
 133             This can also be used to prepend microcode before the actual initrd. It also creates a boot loader entry according to the <ulink
 134             url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> (Type #1) in
 135             <filename>$BOOT/loader/entries/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.
 136             The title of the entry is the <replaceable>PRETTY_NAME</replaceable> parameter specified in
 137             <filename>/etc/os-release</filename> or <filename>/usr/lib/os-release</filename> (if the former
 138             is missing), or "Linux <replaceable>KERNEL-VERSION</replaceable>", if unset.</para>
 139
 140             <para>If <varname>$KERNEL_INSTALL_LAYOUT</varname> is not "bls", this plugin does nothing.</para></listitem>
 141
 142             <listitem><para><filename>90-uki-copy.install</filename> copies a file
 143             <filename>uki.efi</filename> from <varname>$KERNEL_INSTALL_STAGING_AREA</varname> or if it does
 144             not exist the <replaceable>KERNEL-IMAGE</replaceable> argument, only if it has a
 145             <literal>.efi</literal> extension, to
 146             <filename>$BOOT/EFI/Linux/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.efi</filename>.</para>
 147
 148             <para>If <varname>$KERNEL_INSTALL_LAYOUT</varname> is not "uki", this plugin does nothing.</para></listitem>
 149           </itemizedlist>
 150
 151             <xi:include href="version-info.xml" xpointer="v198"/>
 152         </listitem>
 153       </varlistentry>
 154       <varlistentry>
 155         <term>
 156           <command>add-all</command>
 157         </term>
 158
 159         <listitem>
 160           <para>This is the same as <command>add</command> (see above), but invokes the operation iteratively
 161           for every installed kernel in <filename>/usr/lib/modules/</filename>. This operation is only
 162           supported on systems where the kernel image is installed in
 163           <filename>/usr/lib/modules/<replaceable>KERNEL-VERSION</replaceable>/vmlinuz</filename>.</para>
 164
 165           <xi:include href="version-info.xml" xpointer="v255"/>
 166         </listitem>
 167       </varlistentry>
 168       <varlistentry>
 169         <term><command>remove <replaceable>KERNEL-VERSION</replaceable></command></term>
 170         <listitem>
 171           <para>This command expects a kernel version string as single argument.</para>
 172
 173           <para>The executable files from <filename>/usr/lib/kernel/install.d/*.install</filename> and
 174           <filename>/etc/kernel/install.d/*.install</filename> (i.e. the plugins) are called with the
 175           following arguments:</para>
 176
 177           <programlisting>remove <replaceable>KERNEL-VERSION</replaceable> <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename></programlisting>
 178
 179           <para>Afterwards, <command>kernel-install</command> removes the entry directory
 180           <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
 181           and its contents, if it exists.</para>
 182
 183           <para>Two default plugins execute the following operations in this case:</para>
 184
 185           <itemizedlist>
 186             <listitem><para><filename>50-depmod.install</filename> removes the files generated by
 187             <command>depmod</command> for this kernel again.</para></listitem>
 188
 189             <listitem><para><filename>90-loaderentry.install</filename> removes the file
 190             <filename>$BOOT/loader/entries/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.
 191             </para></listitem>
 192
 193             <listitem><para><filename>90-uki-copy.install</filename> removes the file
 194             <filename>$BOOT/EFI/Linux/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.efi</filename>.
 195             </para></listitem>
 196           </itemizedlist>
 197
 198             <xi:include href="version-info.xml" xpointer="v198"/>
 199         </listitem>
 200       </varlistentry>
 201       <varlistentry>
 202         <term>
 203           <command>inspect [[[<replaceable>KERNEL-VERSION</replaceable>] <replaceable>KERNEL-IMAGE</replaceable>] [<replaceable>INITRD-FILE</replaceable> ...]]</command>
 204         </term>
 205         <listitem>
 206           <para>Takes the same parameters as <command>add</command>.</para>
 207
 208           <para>Shows the various paths and parameters configured or auto-detected. In particular shows the
 209           values of the various <varname>$KERNEL_INSTALL_*</varname> environment variables listed below, as
 210           they would be passed to plugins. The <option>--json</option> option can be used to get the output
 211           of this verb as a JSON object.</para>
 212
 213           <xi:include href="version-info.xml" xpointer="v251"/>
 214         </listitem>
 215       </varlistentry>
 216       <varlistentry>
 217         <term><command>list</command></term>
 218         <listitem>
 219           <para>Shows the various installed kernels. This enumerates the subdirectories of
 220           <filename>/usr/lib/modules/</filename>, and shows whether a kernel image is installed there.</para>
 221
 222           <xi:include href="version-info.xml" xpointer="v255"/>
 223         </listitem>
 224       </varlistentry>
 225     </variablelist>
 226   </refsect1>
 227
 228   <refsect1>
 229     <title>Compatibility with the kernel build system</title>
 230
 231     <cmdsynopsis>
 232       <command>installkernel</command>
 233       <arg choice="opt" rep="repeat">OPTIONS</arg>
 234       <arg choice="plain">VERSION</arg>
 235       <arg choice="plain">VMLINUZ</arg>
 236       <arg choice="opt">MAP</arg>
 237       <arg choice="opt">INSTALLATION-DIR</arg>
 238     </cmdsynopsis>
 239
 240     <para>When invoked as <command>installkernel</command>, this program accepts arguments as specified by
 241     the kernel build system's <command>make install</command> command. The <parameter>VERSION</parameter> and
 242     <parameter>VMLINUZ</parameter> parameters specify the kernel version and the kernel binary. The other two
 243     parameters (<parameter>MAP</parameter> and <parameter>INSTALLATION-DIR</parameter>) are currently
 244     ignored.
 245     </para>
 246   </refsect1>
 247
 248   <refsect1>
 249     <title>The <varname>$BOOT</varname> partition</title>
 250
 251     <para>The partition where the kernels and <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot
 252     Loader Specification</ulink> snippets are located is called <varname>$BOOT</varname>.
 253     <command>kernel-install</command> determines the location of this partition by checking
 254     <filename>/efi/</filename>, <filename>/boot/</filename>, and <filename>/boot/efi/</filename> in turn. The
 255     first location where <filename>$BOOT/loader/entries/</filename> or
 256     <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/</filename> exists is used.</para>
 257   </refsect1>
 258
 259   <refsect1>
 260     <title>Options</title>
 261     <para>The following options are understood:</para>
 262
 263     <variablelist>
 264       <xi:include href="standard-options.xml" xpointer="esp-path"/>
 265       <xi:include href="standard-options.xml" xpointer="boot-path"/>
 266
 267       <varlistentry>
 268         <term><option>--make-entry-directory=yes|no|auto</option></term>
 269         <listitem>
 270           <para>Controls creation and deletion of the
 271           <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink>
 272           Type #1 entry directory on the file system containing resources such as kernel and initrd images
 273           during <option>add</option> and <option>remove</option>, respectively. The directory is named after
 274           the entry token, and is placed immediately below the boot root directory. When
 275           <literal>auto</literal>, the directory is created or removed only when the install layout is
 276           <literal>bls</literal>. Defaults to <literal>auto</literal>.</para>
 277
 278           <xi:include href="version-info.xml" xpointer="v254"/>
 279         </listitem>
 280       </varlistentry>
 281
 282       <varlistentry>
 283         <term><option>--entry-token=</option></term>
 284
 285         <listitem>
 286           <para>Controls how to name and identify boot loader entries for this kernel installation or
 287           deletion. Takes one of <literal>auto</literal>, <literal>machine-id</literal>,
 288           <literal>os-id</literal>, <literal>os-image-id</literal>, or an arbitrary string prefixed by
 289           <literal>literal:</literal> as argument.</para>
 290
 291           <para>If set to <option>machine-id</option> the entries are named after the machine ID of the
 292           running system (e.g. <literal>b0e793a9baf14b5fa13ecbe84ff637ac</literal>). See
 293           <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 294           details about the machine ID concept and file.</para>
 295
 296           <para>If set to <option>os-id</option> the entries are named after the OS ID of the running system,
 297           i.e. the <varname>ID=</varname> field of
 298           <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 299           (e.g. <literal>fedora</literal>). Similarly, if set to <option>os-image-id</option> the entries are
 300           named after the OS image ID of the running system, i.e. the <varname>IMAGE_ID=</varname> field of
 301           <filename>os-release</filename> (e.g. <literal>vendorx-cashier-system</literal>).</para>
 302
 303           <para>If set to <option>auto</option> (the default), the
 304           <filename>/etc/kernel/entry-token</filename> (or
 305           <filename>$KERNEL_INSTALL_CONF_ROOT/entry-token</filename>) file will be read if it exists, and the
 306           stored value used. Otherwise if the local machine ID is initialized it is used. Otherwise
 307           <varname>IMAGE_ID=</varname> from <filename>os-release</filename> will be used, if set. Otherwise,
 308           <varname>ID=</varname> from <filename>os-release</filename> will be used, if set. Otherwise a
 309           randomly generated machine ID is used.</para>
 310
 311           <para>Using the machine ID for naming the entries is generally preferable, however there are cases
 312           where using the other identifiers is a good option. Specifically: if the identification data that
 313           the machine ID entails shall not be stored on the (unencrypted) <varname>$BOOT_ROOT</varname>
 314           partition, or if the ID shall be generated on first boot and is not known when the entries are
 315           prepared. Note that using the machine ID has the benefit that multiple parallel installations of
 316           the same OS can coexist on the same medium, and they can update their boot loader entries
 317           independently. When using another identifier (such as the OS ID or the OS image ID), parallel
 318           installations of the same OS would try to use the same entry name. To support parallel
 319           installations, the installer must use a different entry token when adding a second installation.
 320           </para>
 321
 322           <xi:include href="version-info.xml" xpointer="v254"/>
 323         </listitem>
 324       </varlistentry>
 325
 326       <varlistentry>
 327         <term><option>-v</option></term>
 328         <term><option>--verbose</option></term>
 329         <listitem>
 330           <para>Output additional information about operations being performed.</para>
 331
 332         <xi:include href="version-info.xml" xpointer="v242"/>
 333         </listitem>
 334       </varlistentry>
 335
 336       <varlistentry>
 337         <term><option>--root=<replaceable>root</replaceable></option></term>
 338
 339         <listitem><para>Takes a directory path as an argument. All paths will be prefixed with the given
 340         alternate <replaceable>root</replaceable> path, including config search paths. This is useful to
 341         operate on a system image mounted to the specified directory instead of the host system
 342         itself.</para>
 343
 344         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 345       </varlistentry>
 346
 347       <varlistentry>
 348         <term><option>--image=<replaceable>image</replaceable></option></term>
 349
 350         <listitem><para>Takes a path to a disk image file or block device node. If specified, all operations
 351         are applied to the file system in the indicated disk image. This option is similar to
 352         <option>--root=</option>, but operates on file systems stored in disk images or block devices. The
 353         disk image should either contain just a file system or a set of file systems within a GPT partition
 354         table, following the <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
 355         Specification</ulink>. For further information on supported disk images, see
 356         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 357         switch of the same name.</para>
 358
 359         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 360       </varlistentry>
 361
 362       <xi:include href="standard-options.xml" xpointer="help" />
 363       <xi:include href="standard-options.xml" xpointer="version" />
 364       <xi:include href="standard-options.xml" xpointer="no-pager"/>
 365       <xi:include href="standard-options.xml" xpointer="json" />
 366       <xi:include href="standard-options.xml" xpointer="image-policy-open" />
 367       <xi:include href="standard-options.xml" xpointer="no-legend"/>
 368     </variablelist>
 369   </refsect1>
 370
 371   <refsect1>
 372     <title>Environment variables</title>
 373
 374     <refsect2>
 375       <title>Environment variables exported for plugins</title>
 376
 377       <para>If <option>--verbose</option> is used, <varname>$KERNEL_INSTALL_VERBOSE=1</varname> will be
 378       exported for plugins. They may output additional logs in this case.</para>
 379
 380       <para><varname>$KERNEL_INSTALL_IMAGE_TYPE=uki|pe|unknown</varname> is set for the plugins to specify the
 381       type of the kernel image.</para>
 382
 383       <variablelist>
 384         <varlistentry>
 385           <term>uki</term>
 386           <listitem>
 387             <para>Unified kernel image.</para>
 388
 389             <xi:include href="version-info.xml" xpointer="v254"/>
 390           </listitem>
 391         </varlistentry>
 392         <varlistentry>
 393           <term>pe</term>
 394           <listitem>
 395             <para>PE binary.</para>
 396
 397             <xi:include href="version-info.xml" xpointer="v254"/>
 398           </listitem>
 399         </varlistentry>
 400         <varlistentry>
 401           <term>unknown</term>
 402           <listitem>
 403             <para>Unknown type.</para>
 404
 405             <xi:include href="version-info.xml" xpointer="v254"/>
 406           </listitem>
 407         </varlistentry>
 408       </variablelist>
 409
 410       <para><varname>$KERNEL_INSTALL_MACHINE_ID</varname> is set for the plugins to the desired machine-id to
 411       use. It's always a 128-bit ID. Normally it's read from <filename>/etc/machine-id</filename>, but it can
 412       also be overridden via <varname>$MACHINE_ID</varname> (see below). If not specified via these methods,
 413       a fallback value will generated by <command>kernel-install</command> and used only for a single
 414       invocation.</para>
 415
 416       <para><varname>$KERNEL_INSTALL_ENTRY_TOKEN</varname> is set for the plugins to the desired entry
 417       "token" to use. It's an identifier that shall be used to identify the local installation, and is often
 418       the machine ID, i.e. same as <varname>$KERNEL_INSTALL_MACHINE_ID</varname>, but might also be a
 419       different type of identifier, for example a fixed string or the <varname>ID=</varname>,
 420       <varname>IMAGE_ID=</varname> values from <filename>/etc/os-release</filename>. The string passed here
 421       will be used to name Boot Loader Specification entries, or the directories the kernel image and initial
 422       RAM disk images are placed into.</para>
 423
 424       <para>Note that while <varname>$KERNEL_INSTALL_ENTRY_TOKEN</varname> and
 425       <varname>$KERNEL_INSTALL_MACHINE_ID</varname> are often set to the same value, the latter is guaranteed
 426       to be a valid 32 character ID in lowercase hexadecimals while the former can be any short string. The
 427       entry token to use is read from <filename>/etc/kernel/entry-token</filename>, if it exists. Otherwise a
 428       few possible candidates below <varname>$BOOT</varname> are checked for Boot Loader Specification Type 1
 429       entry directories, and if found the entry token is derived from that. If that is not successful,
 430       <varname>$KERNEL_INSTALL_MACHINE_ID</varname> is used as fallback.</para>
 431
 432       <para><varname>$KERNEL_INSTALL_BOOT_ROOT</varname> is set for the plugins to the absolute path of the
 433       root directory (mount point, usually) of the hierarchy where boot loader entries, kernel images, and
 434       associated resources should be placed. This usually is the path where the XBOOTLDR partition or the ESP
 435       (EFI System Partition) are mounted, and also conceptually referred to as <varname>$BOOT</varname>. Can
 436       be overridden by setting <varname>$BOOT_ROOT</varname> (see below).</para>
 437
 438       <para><varname>$KERNEL_INSTALL_LAYOUT=auto|bls|uki|other|...</varname> is set for the plugins to specify the
 439       installation layout. Additional layout names may be defined by convention. If a plugin uses a special layout,
 440       it's encouraged to declare its own layout name and configure <varname>layout=</varname> in
 441       <filename>install.conf</filename> upon initial installation. The following values are currently
 442       understood:</para>
 443
 444       <variablelist>
 445         <varlistentry>
 446           <term>bls</term>
 447           <listitem>
 448             <para>Standard <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader
 449             Specification</ulink> Type #1 layout, compatible with
 450             <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>:
 451             entries in
 452             <filename>$BOOT/loader/entries/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>[+<replaceable>TRIES</replaceable>].conf</filename>,
 453             kernel and initrds under
 454             <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename></para>
 455             <para>Implemented by <filename>90-loaderentry.install</filename>.</para>
 456
 457             <xi:include href="version-info.xml" xpointer="v250"/>
 458           </listitem>
 459         </varlistentry>
 460         <varlistentry>
 461           <term>uki</term>
 462           <listitem>
 463             <para>Standard <ulink
 464             url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader
 465             Specification</ulink> Type #2 layout, compatible with
 466             <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>:
 467             unified kernel images under <filename>$BOOT/EFI/Linux</filename> as
 468             <filename>$BOOT/EFI/Linux/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>[+<replaceable>TRIES</replaceable>].efi</filename>.</para>
 469             <para>Implemented by <filename>90-uki-copy.install</filename>.</para>
 470
 471             <xi:include href="version-info.xml" xpointer="v253"/>
 472           </listitem>
 473         </varlistentry>
 474         <varlistentry>
 475           <term>other</term>
 476           <listitem>
 477             <para>Some other layout not understood natively by <command>kernel-install</command>.</para>
 478
 479           <xi:include href="version-info.xml" xpointer="v250"/>
 480           </listitem>
 481         </varlistentry>
 482         <varlistentry>
 483           <term>auto</term>
 484           <listitem>
 485             <para>Pick the layout automatically. If the kernel is a UKI set layout to
 486             <option>uki</option>. If not default to <option>bls</option> if
 487             <filename>$BOOT/loader/entries.srel</filename> with content <literal>type1</literal> or
 488             <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable></filename> exists, or
 489             <option>other</option> otherwise.</para>
 490             <para>Leaving layout blank has the same effect. This is the default.</para>
 491
 492             <xi:include href="version-info.xml" xpointer="v254"/>
 493           </listitem>
 494         </varlistentry>
 495       </variablelist>
 496
 497       <para><varname>$KERNEL_INSTALL_INITRD_GENERATOR</varname> and <varname>$KERNEL_INSTALL_UKI_GENERATOR</varname>
 498       are set for plugins to select the initrd and/or UKI generator. This may be configured as
 499       <varname>initrd_generator=</varname> and <varname>uki_generator=</varname> in <filename>install.conf</filename>, see below.</para>
 500
 501       <para><varname>$KERNEL_INSTALL_STAGING_AREA</varname> is set for plugins to a path to a directory.
 502       Plugins may drop files in that directory, and they will be installed as part of the loader entry, based
 503       on the file name and extension: Files named <filename>initrd*</filename> will be installed as <replaceable>INITRD-FILE</replaceable>s,
 504       and files named <filename>microcode*</filename> will be prepended before <replaceable>INITRD-FILE</replaceable>s.</para>
 505
 506     </refsect2>
 507
 508     <refsect2>
 509       <title>Environment variables understood by <command>kernel-install</command></title>
 510
 511       <para><varname>$KERNEL_INSTALL_CONF_ROOT</varname> can be set to override the location of the
 512       configuration files read by <command>kernel-install</command>. When set,
 513       <filename>install.conf</filename>, <filename>entry-token</filename>, and other files will be
 514       read from this directory.</para>
 515
 516       <para><varname>$KERNEL_INSTALL_PLUGINS</varname> can be set to override the list of plugins executed by
 517       <command>kernel-install</command>. The argument is a whitespace-separated list of paths.
 518       <literal>KERNEL_INSTALL_PLUGINS=:</literal> may be used to prevent any plugins from running.
 519       </para>
 520
 521       <para><varname>$MACHINE_ID</varname> can be set for <command>kernel-install</command> to override
 522       <varname>$KERNEL_INSTALL_MACHINE_ID</varname>, the machine ID.</para>
 523
 524       <para><varname>$BOOT_ROOT</varname> can be set for <command>kernel-install</command> to override
 525       <varname>$KERNEL_INSTALL_BOOT_ROOT</varname>, the installation location for boot entries.</para>
 526
 527       <para>The last two variables may also be set in <filename>install.conf</filename>. Variables set in the
 528       environment take precedence over the values specified in the config file.</para>
 529     </refsect2>
 530   </refsect1>
 531
 532   <refsect1>
 533     <title>Exit status</title>
 534     <para>If every executable returns 0 or 77, 0 is returned, and a non-zero failure code otherwise.</para>
 535   </refsect1>
 536
 537   <refsect1>
 538     <title>Files</title>
 539     <variablelist>
 540       <varlistentry>
 541         <term><filename>/etc/kernel/install.d/*.install</filename></term>
 542         <term><filename>/usr/lib/kernel/install.d/*.install</filename></term>
 543         <listitem>
 544           <para>Drop-in files which are executed by <command>kernel-install</command>.</para>
 545
 546           <xi:include href="version-info.xml" xpointer="v198"/>
 547         </listitem>
 548       </varlistentry>
 549
 550       <varlistentry>
 551         <term><filename>/etc/kernel/cmdline</filename></term>
 552         <term><filename>/usr/lib/kernel/cmdline</filename></term>
 553         <term><filename>/proc/cmdline</filename></term>
 554         <listitem>
 555           <para>Specifies the kernel command line to use. The first of the files that is found will be used.
 556           <varname>$KERNEL_INSTALL_CONF_ROOT</varname> may be used to override the search path; see below for
 557           details.</para>
 558
 559           <xi:include href="version-info.xml" xpointer="v198"/>
 560         </listitem>
 561       </varlistentry>
 562
 563       <varlistentry>
 564         <term><filename>/etc/kernel/devicetree</filename></term>
 565         <term><filename>/usr/lib/kernel/devicetree</filename></term>
 566         <listitem>
 567           <para>Specifies the partial path to the file containing the device tree blob to install with the
 568           kernel and use at boot. The first of the files that is found will be used.
 569           <varname>$KERNEL_INSTALL_CONF_ROOT</varname> may be used to override the search path; see below for
 570           details.</para>
 571
 572           <para>The <filename>devicetree</filename> file contains a path, and this path specifies a location
 573           relative to the kernel install tree. A set of locations is checked, including in particular
 574           <filename>/usr/lib/modules/<replaceable>KERNEL_VERSION</replaceable>/dtb/</filename>, which is the
 575           recommended location to place the dtb files under. For example, with
 576           <literal>broadcom/bcm2711-rpi-4-b.dtb</literal> in the <filename>devicetree</filename> file, the
 577           device tree blob for the Raspberry Pi 4 Model B would be installed, and the actual file would be
 578           <filename index='false'>/usr/lib/modules/<replaceable>KERNEL_VERSION</replaceable>/dtb/broadcom/bcm2711-rpi-4-b.dtb</filename>.
 579           </para>
 580
 581           <xi:include href="version-info.xml" xpointer="v255"/>
 582         </listitem>
 583       </varlistentry>
 584
 585       <varlistentry>
 586         <term><filename>/etc/kernel/tries</filename></term>
 587         <listitem>
 588           <para>Read by <filename>90-loaderentry.install</filename> and
 589           <filename>90-uki-copy.install</filename>. If this file exists, a numeric value is read from it and
 590           the naming of the generated entry file or UKI is altered to include it as
 591           <filename>$BOOT/loader/entries/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>+<replaceable>TRIES</replaceable>.conf</filename>
 592           or
 593           <filename>$BOOT/EFI/Linux/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>+<replaceable>TRIES</replaceable>.efi</filename>,
 594           respectively. This is useful for boot loaders such as
 595           <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 596           which implement boot attempt counting with a counter embedded in the entry file name.
 597           <varname>$KERNEL_INSTALL_CONF_ROOT</varname> may be used to override the search path; see below for
 598           details.</para>
 599
 600           <xi:include href="version-info.xml" xpointer="v240"/>
 601         </listitem>
 602       </varlistentry>
 603
 604       <varlistentry>
 605         <term><filename>/etc/kernel/entry-token</filename></term>
 606         <listitem>
 607           <para>If this file exists it is read and used as "entry token" for this system, i.e. is used for
 608           naming Boot Loader Specification entries. See <varname>$KERNEL_INSTALL_ENTRY_TOKEN</varname> above
 609           for details. <varname>$KERNEL_INSTALL_CONF_ROOT</varname> may be used to override the search path; see
 610           below for details.</para>
 611
 612           <xi:include href="version-info.xml" xpointer="v251"/>
 613         </listitem>
 614       </varlistentry>
 615
 616       <varlistentry>
 617         <term>
 618           <filename>/etc/machine-id</filename>
 619         </term>
 620           <listitem>
 621             <para>The content of this file specifies the machine identification
 622             <replaceable>MACHINE-ID</replaceable>.</para>
 623
 624             <xi:include href="version-info.xml" xpointer="v198"/>
 625           </listitem>
 626       </varlistentry>
 627
 628       <varlistentry>
 629         <term><filename>/etc/os-release</filename></term>
 630         <term><filename>/usr/lib/os-release</filename></term>
 631         <listitem>
 632             <para>Read by <filename>90-loaderentry.install</filename>. If available,
 633             <varname>PRETTY_NAME=</varname> is read from these files and used as the title of the boot menu
 634             entry. Otherwise, <literal>Linux <replaceable>KERNEL-VERSION</replaceable></literal> will be
 635             used.</para>
 636
 637             <xi:include href="version-info.xml" xpointer="v198"/>
 638           </listitem>
 639       </varlistentry>
 640       <varlistentry>
 641         <term><filename>/etc/kernel/install.conf</filename></term>
 642         <term><filename>/usr/lib/kernel/install.conf</filename></term>
 643         <listitem>
 644           <para>Configuration file with options for <command>kernel-install</command>, as a series of
 645           <varname>KEY=</varname><replaceable>VALUE</replaceable> assignments, compatible with shell syntax,
 646           following the same rules as described in
 647           <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
 648           first of the files that is found will be used. <varname>$KERNEL_INSTALL_CONF_ROOT</varname> may be
 649           used to override the search path; see below for details.</para>
 650
 651           <para>Currently, the following keys are supported:
 652           <varname>MACHINE_ID=</varname>,
 653           <varname>BOOT_ROOT=</varname>,
 654           <varname>layout=</varname>,
 655           <varname>initrd_generator=</varname>,
 656           <varname>uki_generator=</varname>.
 657           See the Environment variables section above for details.</para>
 658
 659           <xi:include href="version-info.xml" xpointer="v250"/>
 660         </listitem>
 661       </varlistentry>
 662       <varlistentry>
 663         <term><filename>/etc/kernel/uki.conf</filename></term>
 664         <listitem>
 665           <para>Ini-style configuration file for
 666           <citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry> which is
 667           only effective when <varname>$KERNEL_INSTALL_LAYOUT</varname> or <varname>layout=</varname> in
 668           <filename>install.conf</filename> is set to <option>uki</option> and
 669           <varname>$KERNEL_INSTALL_UKI_GENERATOR</varname> or <varname>uki_generator=</varname> in
 670           <filename>install.conf</filename> is set to <option>ukify</option>, or is unset.
 671           <varname>$KERNEL_INSTALL_CONF_ROOT</varname> may be used to override the search path; see below for
 672           details.</para>
 673
 674           <xi:include href="version-info.xml" xpointer="v255"/>
 675         </listitem>
 676       </varlistentry>
 677
 678       <varlistentry>
 679         <term><filename>/usr/lib/modules/<replaceable>KERNEL-VERSION/</replaceable></filename></term>
 680
 681         <listitem>
 682           <para>Location for installed kernel modules and other kernel related resources. For each locally
 683           installed kernel a directory named after the kernel version (<command>uname -r</command>) is
 684           kept.</para>
 685
 686           <xi:include href="version-info.xml" xpointer="v255"/>
 687         </listitem>
 688       </varlistentry>
 689
 690       <varlistentry>
 691         <term><filename>/usr/lib/modules/<replaceable>KERNEL-VERSION/vmlinuz</replaceable></filename></term>
 692
 693         <listitem>
 694           <para>Location for installed kernel images. This is the recommended location for OS package
 695           managers to install kernel images into (as applicable), from which <command>kernel-install
 696           add</command> then copies it into the final boot partition.</para>
 697
 698           <xi:include href="version-info.xml" xpointer="v255"/>
 699         </listitem>
 700       </varlistentry>
 701
 702     </variablelist>
 703
 704     <para>For various cases listed above, if the <varname>$KERNEL_INSTALL_CONF_ROOT</varname> environment
 705     variable is set, it will override the search path. The files will be loaded <emphasis>only</emphasis>
 706     from the directory specified by the environment variable. When the variable is not set, the listed paths
 707     are tried in turn, and the first file that exists is used.</para>
 708   </refsect1>
 709
 710   <refsect1>
 711     <title>See Also</title>
 712     <para>
 713       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 714       <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 715       <citerefentry project='man-pages'><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 716       <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 717       <citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 718       <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink>
 719     </para>
 720   </refsect1>
 721
 722 </refentry>