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+ -->
   5
   6 <refentry id="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 execute the files
  43     located in the directory <filename>/usr/lib/kernel/install.d/</filename>
  44     and the local administration directory <filename>/etc/kernel/install.d/</filename>.
  45     All files are collectively sorted and executed in lexical order, regardless of the directory in
  46     which they live. However, files with identical filenames replace each other.
  47     Files in <filename>/etc/kernel/install.d/</filename> take precedence over files with the same name
  48     in <filename>/usr/lib/kernel/install.d/</filename>. This can be used to override a system-supplied
  49     executables with a local file if needed; a symbolic link in <filename>/etc/kernel/install.d/</filename>
  50     with the same name as an executable in <filename>/usr/lib/kernel/install.d/</filename>,
  51     pointing to <filename>/dev/null</filename>, disables the executable entirely. Executables must have the
  52     extension <literal>.install</literal>; other extensions are ignored.</para>
  53
  54     <para>An executable should return <constant>0</constant> on success. It may also
  55     return <constant>77</constant> to cause the whole operation to terminate
  56     (executables later in lexical order will be skipped).</para>
  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. <command>kernel-install</command> calls the executables from
  68           <filename>/usr/lib/kernel/install.d/*.install</filename> and
  69           <filename>/etc/kernel/install.d/*.install</filename> with the following arguments:
  70
  71           <programlisting>add <replaceable>KERNEL-VERSION</replaceable> <filename>$BOOT/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> <replaceable>KERNEL-IMAGE</replaceable> [<replaceable>INITRD-FILE</replaceable> ...]</programlisting>
  72           </para>
  73
  74           <para>Three default plugins execute the following operations in this case:</para>
  75
  76           <itemizedlist>
  77             <listitem><para><filename>00-entry-directory.install</filename> creates the directory
  78             <filename>$BOOT/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
  79             if <filename>$BOOT/<replaceable>MACHINE-ID</replaceable>/</filename> already exists.
  80             </para></listitem>
  81
  82             <listitem><para><filename>50-depmod.install</filename> runs
  83             <citerefentry><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry> for the
  84             <replaceable>KERNEL-VERSION</replaceable>.</para></listitem>
  85
  86             <listitem><para><filename>90-loaderentry.install</filename> copies <replaceable>KERNEL-IMAGE</replaceable>
  87             to
  88             <filename>$BOOT/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/linux</filename>.
  89             If an <replaceable>INITRD-FILE</replaceable> is provided, it also copies <replaceable>INITRD-FILE</replaceable>
  90             to
  91             <filename>$BOOT/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL_VERSION</replaceable>/<replaceable>INITRD-FILE</replaceable></filename>.
  92             It also creates a boot loader entry according to the <ulink
  93             url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> in
  94             <filename>$BOOT/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.
  95             The title of the entry is the <replaceable>PRETTY_NAME</replaceable> parameter specified in
  96             <filename>/etc/os-release</filename> or <filename>/usr/lib/os-release</filename> (if the former is
  97             missing), or "Linux <replaceable>KERNEL-VERSION</replaceable>", if unset.</para>
  98
  99             <para>If the entry directory
 100             <filename>$BOOT/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
 101             does not exist, this plugin does nothing.</para></listitem>
 102           </itemizedlist>
 103         </listitem>
 104       </varlistentry>
 105       <varlistentry>
 106         <term><command>remove <replaceable>KERNEL-VERSION</replaceable></command></term>
 107         <listitem>
 108           <para>This command expects a kernel version string as single argument. This calls executables from
 109           <filename>/usr/lib/kernel/install.d/*.install</filename> and
 110           <filename>/etc/kernel/install.d/*.install</filename> with the following arguments:
 111
 112           <programlisting>remove <replaceable>KERNEL-VERSION</replaceable> <filename>$BOOT/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename></programlisting>
 113           </para>
 114
 115           <para>Afterwards, <command>kernel-install</command> removes the directory
 116           <filename>$BOOT/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
 117           and its contents.</para>
 118
 119           <para>Two default plugins execute the following operations in this case:</para>
 120
 121           <itemizedlist>
 122
 123             <listitem><para><filename>50-depmod.install</filename> removes the files generated by <command>depmod</command> for this kernel again.</para></listitem>
 124
 125             <listitem><para><filename>90-loaderentry.install</filename> removes the file
 126             <filename>$BOOT/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.</para></listitem>
 127           </itemizedlist>
 128
 129         </listitem>
 130       </varlistentry>
 131
 132     </variablelist>
 133   </refsect1>
 134
 135   <refsect1>
 136     <title>The <varname>$BOOT</varname> partition</title>
 137     <para>The partition where the kernels and <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot
 138     Loader Specification</ulink> snippets are located is called <varname>$BOOT</varname>.
 139     <command>kernel-install</command> determines the location of this partition by checking
 140     <filename>/efi/</filename>, <filename>/boot/</filename>, and <filename>/boot/efi</filename>
 141     in turn. The first location where <filename>$BOOT/loader/entries/</filename> or
 142     <filename>$BOOT/$MACHINE_ID/</filename> exists is used.</para>
 143   </refsect1>
 144
 145   <refsect1>
 146     <title>Options</title>
 147     <para>The following options are understood:</para>
 148
 149     <variablelist>
 150       <varlistentry>
 151         <term><option>-v</option></term>
 152         <term><option>--verbose</option></term>
 153         <listitem>
 154           <para>Output additional information about operations being performed.</para>
 155         </listitem>
 156       </varlistentry>
 157
 158       <xi:include href="standard-options.xml" xpointer="help" />
 159     </variablelist>
 160   </refsect1>
 161
 162   <refsect1>
 163     <title>Environment variables</title>
 164     <para>If <option>--verbose</option> is used, <varname>$KERNEL_INSTALL_VERBOSE=1</varname> will be set for
 165     the plugins. They may output additional logs in this case.</para>
 166   </refsect1>
 167
 168   <refsect1>
 169     <title>Exit status</title>
 170     <para>If every executable returns 0 or 77, 0 is returned, and a non-zero failure code otherwise.</para>
 171   </refsect1>
 172
 173   <refsect1>
 174     <title>Files</title>
 175     <variablelist>
 176       <varlistentry>
 177         <term>
 178           <filename>/usr/lib/kernel/install.d/*.install</filename>
 179           <filename>/etc/kernel/install.d/*.install</filename>
 180         </term>
 181           <listitem>
 182             <para>Drop-in files which are executed by kernel-install.</para>
 183           </listitem>
 184       </varlistentry>
 185       <varlistentry>
 186         <term>
 187           <filename>/etc/kernel/cmdline</filename>
 188           <filename>/proc/cmdline</filename>
 189         </term>
 190           <listitem>
 191             <para>Read by <filename>90-loaderentry.install</filename>. The content of the file
 192             <filename>/etc/kernel/cmdline</filename> specifies the kernel command line to use.  If that file does not
 193             exist, <filename>/proc/cmdline</filename> is used.</para>
 194           </listitem>
 195       </varlistentry>
 196       <varlistentry>
 197         <term>
 198           <filename>/etc/kernel/tries</filename>
 199         </term>
 200           <listitem>
 201             <para>Read by <filename>90-loaderentry.install</filename>. If this file exists a numeric value is read from
 202             it and the naming of the generated entry file is slightly altered to include it as
 203             <filename>$BOOT/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>+<replaceable>TRIES</replaceable>.conf</filename>. This
 204             is useful for boot loaders such as
 205             <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> which
 206             implement boot attempt counting with a counter embedded in the entry file name.</para>
 207           </listitem>
 208       </varlistentry>
 209       <varlistentry>
 210         <term>
 211           <filename>/etc/machine-id</filename>
 212         </term>
 213           <listitem>
 214             <para>The content of the file specifies the machine identification <replaceable>MACHINE-ID</replaceable>.</para>
 215           </listitem>
 216       </varlistentry>
 217       <varlistentry>
 218         <term>
 219           <filename>/etc/os-release</filename>
 220           <filename>/usr/lib/os-release</filename>
 221         </term>
 222           <listitem>
 223             <para>The content of the file specifies the operating system title <replaceable>PRETTY_NAME</replaceable>.</para>
 224           </listitem>
 225       </varlistentry>
 226     </variablelist>
 227   </refsect1>
 228
 229   <refsect1>
 230     <title>See Also</title>
 231     <para>
 232       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 233       <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 234       <citerefentry><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 235       <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 236       <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>
 237     </para>
 238   </refsect1>
 239
 240 </refentry>