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><command>kernel-install</command> creates the directory
  67           <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
  68           and calls executables from
  69           <filename>/usr/lib/kernel/install.d/*.install</filename> and
  70           <filename>/etc/kernel/install.d/*.install</filename> with
  71           the arguments
  72           <programlisting>add <replaceable>KERNEL-VERSION</replaceable> \
  73     <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> <replaceable>KERNEL-IMAGE</replaceable></programlisting>
  74           </para>
  75
  76           <para>The kernel-install plugin <filename>50-depmod.install</filename> runs depmod for the <replaceable>KERNEL-VERSION</replaceable>.</para>
  77
  78           <para>The kernel-install plugin
  79           <filename>90-loaderentry.install</filename> copies
  80           <replaceable>KERNEL-IMAGE</replaceable> to
  81           <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/linux</filename>.
  82           It also creates a boot loader entry according to the boot
  83           loader specification in
  84           <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.
  85           The title of the entry is the
  86           <replaceable>PRETTY_NAME</replaceable> parameter specified
  87           in <filename>/etc/os-release</filename> or
  88           <filename>/usr/lib/os-release</filename> (if the former is
  89           missing), or "Linux
  90           <replaceable>KERNEL-VERSION</replaceable>", if unset.  If
  91           the file <filename>initrd</filename> is found next to the
  92           <filename>linux</filename> file, the initrd will be added to
  93           the configuration.</para>
  94         </listitem>
  95       </varlistentry>
  96       <varlistentry>
  97         <term><command>remove <replaceable>KERNEL-VERSION</replaceable></command></term>
  98         <listitem>
  99           <para>Calls executables from <filename>/usr/lib/kernel/install.d/*.install</filename>
 100           and <filename>/etc/kernel/install.d/*.install</filename> with the arguments
 101           <programlisting>remove <replaceable>KERNEL-VERSION</replaceable> <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename></programlisting>
 102           </para>
 103
 104           <para><command>kernel-install</command> removes the entire directory
 105           <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> afterwards.</para>
 106
 107           <para>The kernel-install plugin <filename>90-loaderentry.install</filename> removes the file
 108           <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.</para>
 109         </listitem>
 110       </varlistentry>
 111
 112     </variablelist>
 113
 114   </refsect1>
 115
 116   <refsect1>
 117     <title>Exit status</title>
 118     <para>If every executable returns 0 or 77, 0 is returned, and a non-zero failure code otherwise.</para>
 119   </refsect1>
 120
 121   <refsect1>
 122     <title>Files</title>
 123     <variablelist>
 124       <varlistentry>
 125         <term>
 126           <filename>/usr/lib/kernel/install.d/*.install</filename>
 127           <filename>/etc/kernel/install.d/*.install</filename>
 128         </term>
 129           <listitem>
 130             <para>Drop-in files which are executed by kernel-install.</para>
 131           </listitem>
 132       </varlistentry>
 133       <varlistentry>
 134         <term>
 135           <filename>/etc/kernel/cmdline</filename>
 136           <filename>/proc/cmdline</filename>
 137         </term>
 138           <listitem>
 139             <para>The content of the file <filename>/etc/kernel/cmdline</filename> specifies the kernel command line to use.
 140             If that file does not exist, <filename>/proc/cmdline</filename> is used.</para>
 141           </listitem>
 142       </varlistentry>
 143       <varlistentry>
 144         <term>
 145           <filename>/etc/machine-id</filename>
 146         </term>
 147           <listitem>
 148             <para>The content of the file specifies the machine identification <replaceable>MACHINE-ID</replaceable>.</para>
 149           </listitem>
 150       </varlistentry>
 151       <varlistentry>
 152         <term>
 153           <filename>/etc/os-release</filename>
 154           <filename>/usr/lib/os-release</filename>
 155         </term>
 156           <listitem>
 157             <para>The content of the file specifies the operating system title <replaceable>PRETTY_NAME</replaceable>.</para>
 158           </listitem>
 159       </varlistentry>
 160     </variablelist>
 161   </refsect1>
 162
 163   <refsect1>
 164     <title>See Also</title>
 165     <para>
 166       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 167       <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 168       <ulink url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader Specification</ulink>
 169     </para>
 170   </refsect1>
 171
 172 </refentry>