man/kernel-install.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="kernel-install">
  10
  11   <refentryinfo>
  12     <title>kernel-install</title>
  13     <productname>systemd</productname>
  14   </refentryinfo>
  15
  16   <refmeta>
  17     <refentrytitle>kernel-install</refentrytitle>
  18     <manvolnum>8</manvolnum>
  19   </refmeta>
  20
  21   <refnamediv>
  22     <refname>kernel-install</refname>
  23     <refpurpose>Add and remove kernel and initramfs images to and from /boot</refpurpose>
  24   </refnamediv>
  25
  26   <refsynopsisdiv>
  27     <cmdsynopsis>
  28       <command>kernel-install</command>
  29       <arg choice="plain">COMMAND</arg>
  30       <arg choice="plain"><replaceable>KERNEL-VERSION</replaceable></arg>
  31       <arg choice="plain"><replaceable>KERNEL-IMAGE</replaceable></arg>
  32       <arg choice="opt"><replaceable>INITRD-FILE</replaceable></arg>
  33     </cmdsynopsis>
  34   </refsynopsisdiv>
  35
  36   <refsect1>
  37     <title>Description</title>
  38     <para>
  39       <command>kernel-install</command> is used to install and remove kernel and
  40       initramfs images to and from <filename>/boot</filename>.
  41     </para>
  42
  43     <para><command>kernel-install</command> will execute the files
  44     located in the directory <filename>/usr/lib/kernel/install.d/</filename>
  45     and the local administration directory <filename>/etc/kernel/install.d/</filename>.
  46     All files are collectively sorted and executed in lexical order, regardless of the directory in
  47     which they live. However, files with identical filenames replace each other.
  48     Files in <filename>/etc/kernel/install.d/</filename> take precedence over files with the same name
  49     in <filename>/usr/lib/kernel/install.d/</filename>. This can be used to override a system-supplied
  50     executables with a local file if needed; a symbolic link in <filename>/etc/kernel/install.d/</filename>
  51     with the same name as an executable in <filename>/usr/lib/kernel/install.d/</filename>,
  52     pointing to <filename>/dev/null</filename>, disables the executable entirely. Executables must have the
  53     extension <literal>.install</literal>; other extensions are ignored.</para>
  54
  55     <para>An executable should return <constant>0</constant> on success. It may also
  56     return <constant>77</constant> to cause the whole operation to terminate
  57     (executables later in lexical order will be skipped).</para>
  58   </refsect1>
  59
  60   <refsect1>
  61     <title>Commands</title>
  62     <para>The following commands are understood:</para>
  63     <variablelist>
  64       <varlistentry>
  65         <term><command>add <replaceable>KERNEL-VERSION</replaceable> <replaceable>KERNEL-IMAGE</replaceable> [<replaceable>INITRD-FILE</replaceable>]</command></term>
  66         <listitem>
  67           <para>This command expects a kernel version string and a path to a kernel image file as
  68           arguments. <command>kernel-install</command> creates the directory
  69           <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
  70           and calls the executables from <filename>/usr/lib/kernel/install.d/*.install</filename> and
  71           <filename>/etc/kernel/install.d/*.install</filename> with the following arguments:
  72
  73           <programlisting>add <replaceable>KERNEL-VERSION</replaceable> <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> <replaceable>KERNEL-IMAGE</replaceable> <replaceable>INITRD-FILE</replaceable></programlisting>
  74           </para>
  75
  76           <para>Two default plugins execute the following operations in this case:</para>
  77
  78           <itemizedlist>
  79
  80             <listitem><para><filename>50-depmod.install</filename> runs
  81             <citerefentry><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry> for the
  82             <replaceable>KERNEL-VERSION</replaceable>.</para></listitem>
  83
  84             <listitem><para><filename>90-loaderentry.install</filename> copies <replaceable>KERNEL-IMAGE</replaceable>
  85             to
  86             <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/linux</filename>.
  87             If <replaceable>INITRD-FILE</replaceable> is provided, it also copies <replaceable>INITRD-FILE</replaceable>
  88             to
  89             <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL_VERSION</replaceable>/initrd</filename>.
  90             It also creates a boot loader entry according to the <ulink
  91             url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> in
  92             <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.
  93             The title of the entry is the <replaceable>PRETTY_NAME</replaceable> parameter specified in
  94             <filename>/etc/os-release</filename> or <filename>/usr/lib/os-release</filename> (if the former is
  95             missing), or "Linux <replaceable>KERNEL-VERSION</replaceable>", if unset.</para></listitem>
  96           </itemizedlist>
  97         </listitem>
  98       </varlistentry>
  99       <varlistentry>
 100         <term><command>remove <replaceable>KERNEL-VERSION</replaceable></command></term>
 101         <listitem>
 102           <para>This command expects a kernel version string as single argument. This calls executables from
 103           <filename>/usr/lib/kernel/install.d/*.install</filename> and
 104           <filename>/etc/kernel/install.d/*.install</filename> with the following arguments:
 105
 106           <programlisting>remove <replaceable>KERNEL-VERSION</replaceable> <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename></programlisting>
 107           </para>
 108
 109           <para>Afterwards, <command>kernel-install</command> removes the directory
 110           <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
 111           and its contents.</para>
 112
 113           <para>Two default plugins execute the following operations in this case:</para>
 114
 115           <itemizedlist>
 116
 117             <listitem><para><filename>50-depmod.install</filename> removes the files generated by <command>depmod</command> for this kernel again.</para></listitem>
 118
 119             <listitem><para><filename>90-loaderentry.install</filename> removes the file
 120             <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.</para></listitem>
 121           </itemizedlist>
 122
 123         </listitem>
 124       </varlistentry>
 125
 126     </variablelist>
 127
 128   </refsect1>
 129
 130   <refsect1>
 131     <title>Exit status</title>
 132     <para>If every executable returns 0 or 77, 0 is returned, and a non-zero failure code otherwise.</para>
 133   </refsect1>
 134
 135   <refsect1>
 136     <title>Files</title>
 137     <variablelist>
 138       <varlistentry>
 139         <term>
 140           <filename>/usr/lib/kernel/install.d/*.install</filename>
 141           <filename>/etc/kernel/install.d/*.install</filename>
 142         </term>
 143           <listitem>
 144             <para>Drop-in files which are executed by kernel-install.</para>
 145           </listitem>
 146       </varlistentry>
 147       <varlistentry>
 148         <term>
 149           <filename>/etc/kernel/cmdline</filename>
 150           <filename>/proc/cmdline</filename>
 151         </term>
 152           <listitem>
 153             <para>Read by <filename>90-loaderentry.install</filename>. The content of the file
 154             <filename>/etc/kernel/cmdline</filename> specifies the kernel command line to use.  If that file does not
 155             exist, <filename>/proc/cmdline</filename> is used.</para>
 156           </listitem>
 157       </varlistentry>
 158       <varlistentry>
 159         <term>
 160           <filename>/etc/kernel/tries</filename>
 161         </term>
 162           <listitem>
 163             <para>Read by <filename>90-loaderentry.install</filename>. If this file exists a numeric value is read from
 164             it and the naming of the generated entry file is slightly altered to include it as
 165             <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>+<replaceable>TRIES</replaceable>.conf</filename>. This
 166             is useful for boot loaders such as
 167             <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> which
 168             implement boot attempt counting with a counter embedded in the entry file name.</para>
 169           </listitem>
 170       </varlistentry>
 171       <varlistentry>
 172         <term>
 173           <filename>/etc/machine-id</filename>
 174         </term>
 175           <listitem>
 176             <para>The content of the file specifies the machine identification <replaceable>MACHINE-ID</replaceable>.</para>
 177           </listitem>
 178       </varlistentry>
 179       <varlistentry>
 180         <term>
 181           <filename>/etc/os-release</filename>
 182           <filename>/usr/lib/os-release</filename>
 183         </term>
 184           <listitem>
 185             <para>The content of the file specifies the operating system title <replaceable>PRETTY_NAME</replaceable>.</para>
 186           </listitem>
 187       </varlistentry>
 188     </variablelist>
 189   </refsect1>
 190
 191   <refsect1>
 192     <title>See Also</title>
 193     <para>
 194       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 195       <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 196       <citerefentry><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 197       <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 198       <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>
 199     </para>
 200   </refsect1>
 201
 202 </refentry>