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