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="opt"><replaceable>KERNEL-IMAGE</replaceable></arg>
  32     </cmdsynopsis>
  33   </refsynopsisdiv>
  34
  35   <refsect1>
  36     <title>Description</title>
  37     <para>
  38       <command>kernel-install</command> is used to install and remove kernel and
  39       initramfs images to and from <filename>/boot</filename>.
  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></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> creates the directory
  68           <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
  69           and calls the executables from <filename>/usr/lib/kernel/install.d/*.install</filename> and
  70           <filename>/etc/kernel/install.d/*.install</filename> with the following arguments:
  71
  72           <programlisting>add <replaceable>KERNEL-VERSION</replaceable> <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> <replaceable>KERNEL-IMAGE</replaceable></programlisting>
  73           </para>
  74
  75           <para>Two default plugins execute the following operations in this case:</para>
  76
  77           <itemizedlist>
  78
  79             <listitem><para><filename>50-depmod.install</filename> runs
  80             <citerefentry><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry> for the
  81             <replaceable>KERNEL-VERSION</replaceable>.</para></listitem>
  82
  83             <listitem><para><filename>90-loaderentry.install</filename> copies <replaceable>KERNEL-IMAGE</replaceable>
  84             to
  85             <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/linux</filename>.
  86             It also creates a boot loader entry according to the <ulink
  87             url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> in
  88             <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.
  89             The title of the entry is the <replaceable>PRETTY_NAME</replaceable> parameter specified in
  90             <filename>/etc/os-release</filename> or <filename>/usr/lib/os-release</filename> (if the former is
  91             missing), or "Linux <replaceable>KERNEL-VERSION</replaceable>", if unset.  If the file
  92             <filename>initrd</filename> is found next to the kernel image file, the initrd will be added to the
  93             configuration.</para></listitem>
  94           </itemizedlist>
  95         </listitem>
  96       </varlistentry>
  97       <varlistentry>
  98         <term><command>remove <replaceable>KERNEL-VERSION</replaceable></command></term>
  99         <listitem>
 100           <para>This command expects a kernel version string as single argument. This calls executables from
 101           <filename>/usr/lib/kernel/install.d/*.install</filename> and
 102           <filename>/etc/kernel/install.d/*.install</filename> with the following arguments:
 103
 104           <programlisting>remove <replaceable>KERNEL-VERSION</replaceable> <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename></programlisting>
 105           </para>
 106
 107           <para>Afterwards, <command>kernel-install</command> removes the directory
 108           <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
 109           and its contents.</para>
 110
 111           <para>Two default plugins execute the following operations in this case:</para>
 112
 113           <itemizedlist>
 114
 115             <listitem><para><filename>50-depmod.install</filename> removes the files generated by <command>depmod</command> for this kernel again.</para></listitem>
 116
 117             <listitem><para><filename>90-loaderentry.install</filename> removes the file
 118             <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.</para></listitem>
 119           </itemizedlist>
 120
 121         </listitem>
 122       </varlistentry>
 123
 124     </variablelist>
 125
 126   </refsect1>
 127
 128   <refsect1>
 129     <title>Exit status</title>
 130     <para>If every executable returns 0 or 77, 0 is returned, and a non-zero failure code otherwise.</para>
 131   </refsect1>
 132
 133   <refsect1>
 134     <title>Files</title>
 135     <variablelist>
 136       <varlistentry>
 137         <term>
 138           <filename>/usr/lib/kernel/install.d/*.install</filename>
 139           <filename>/etc/kernel/install.d/*.install</filename>
 140         </term>
 141           <listitem>
 142             <para>Drop-in files which are executed by kernel-install.</para>
 143           </listitem>
 144       </varlistentry>
 145       <varlistentry>
 146         <term>
 147           <filename>/etc/kernel/cmdline</filename>
 148           <filename>/proc/cmdline</filename>
 149         </term>
 150           <listitem>
 151             <para>Read by <filename>90-loaderentry.install</filename>. The content of the file
 152             <filename>/etc/kernel/cmdline</filename> specifies the kernel command line to use.  If that file does not
 153             exist, <filename>/proc/cmdline</filename> is used.</para>
 154           </listitem>
 155       </varlistentry>
 156       <varlistentry>
 157         <term>
 158           <filename>/etc/kernel/tries</filename>
 159         </term>
 160           <listitem>
 161             <para>Read by <filename>90-loaderentry.install</filename>. If this file exists a numeric value is read from
 162             it and the naming of the generated entry file is slightly altered to include it as
 163             <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>+<replaceable>TRIES</replaceable>.conf</filename>. This
 164             is useful for boot loaders such as
 165             <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> which
 166             implement boot attempt counting with a counter embedded in the entry file name.</para>
 167           </listitem>
 168       </varlistentry>
 169       <varlistentry>
 170         <term>
 171           <filename>/etc/machine-id</filename>
 172         </term>
 173           <listitem>
 174             <para>The content of the file specifies the machine identification <replaceable>MACHINE-ID</replaceable>.</para>
 175           </listitem>
 176       </varlistentry>
 177       <varlistentry>
 178         <term>
 179           <filename>/etc/os-release</filename>
 180           <filename>/usr/lib/os-release</filename>
 181         </term>
 182           <listitem>
 183             <para>The content of the file specifies the operating system title <replaceable>PRETTY_NAME</replaceable>.</para>
 184           </listitem>
 185       </varlistentry>
 186     </variablelist>
 187   </refsect1>
 188
 189   <refsect1>
 190     <title>See Also</title>
 191     <para>
 192       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 193       <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 194       <citerefentry><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 195       <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 196       <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>
 197     </para>
 198   </refsect1>
 199
 200 </refentry>