man/kernel-install.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   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   This file is part of systemd.
   9
  10   Copyright 2013 Harald Hoyer
  11
  12   systemd is free software; you can redistribute it and/or modify it
  13   under the terms of the GNU Lesser General Public License as published by
  14   the Free Software Foundation; either version 2.1 of the License, or
  15   (at your option) any later version.
  16
  17   systemd is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  24 -->
  25
  26 <refentry id="kernel-install">
  27
  28   <refentryinfo>
  29     <title>kernel-install</title>
  30     <productname>systemd</productname>
  31
  32     <authorgroup>
  33       <author>
  34         <contrib>Developer</contrib>
  35         <firstname>Harald</firstname>
  36         <surname>Hoyer</surname>
  37         <email>harald@redhat.com</email>
  38       </author>
  39     </authorgroup>
  40   </refentryinfo>
  41
  42   <refmeta>
  43     <refentrytitle>kernel-install</refentrytitle>
  44     <manvolnum>8</manvolnum>
  45   </refmeta>
  46
  47   <refnamediv>
  48     <refname>kernel-install</refname>
  49     <refpurpose>Add and remove kernel and initramfs images to and from /boot</refpurpose>
  50   </refnamediv>
  51
  52   <refsynopsisdiv>
  53     <cmdsynopsis>
  54       <command>kernel-install</command>
  55       <arg choice="plain">COMMAND</arg>
  56       <arg choice="plain"><replaceable>KERNEL-VERSION</replaceable></arg>
  57       <arg choice="opt"><replaceable>KERNEL-IMAGE</replaceable></arg>
  58     </cmdsynopsis>
  59   </refsynopsisdiv>
  60
  61   <refsect1>
  62     <title>Description</title>
  63     <para>
  64       <command>kernel-install</command> is used to install and remove kernel and
  65       initramfs images to and from <filename>/boot</filename>.
  66     </para>
  67
  68     <para><command>kernel-install</command> will execute the files
  69     located in the directory <filename>/usr/lib/kernel/install.d/</filename>
  70     and the local administration directory <filename>/etc/kernel/install.d/</filename>.
  71     All files are collectively sorted and executed in lexical order, regardless of the directory in
  72     which they live. However, files with identical filenames replace each other.
  73     Files in <filename>/etc/kernel/install.d/</filename> take precedence over files with the same name
  74     in <filename>/usr/lib/kernel/install.d/</filename>. This can be used to override a system-supplied
  75     executables with a local file if needed; a symbolic link in <filename>/etc/kernel/install.d/</filename>
  76     with the same name as an executable in <filename>/usr/lib/kernel/install.d/</filename>,
  77     pointing to <filename>/dev/null</filename>, disables the executable entirely. Executables must have the
  78     extension <literal>.install</literal>; other extensions are ignored.</para>
  79
  80     <para>An executable should return <constant>0</constant> on success. It may also
  81     return <constant>77</constant> to cause the whole operation to terminate
  82     (executables later in lexical order will be skipped).</para>
  83   </refsect1>
  84
  85   <refsect1>
  86     <title>Commands</title>
  87     <para>The following commands are understood:</para>
  88     <variablelist>
  89       <varlistentry>
  90         <term><command>add <replaceable>KERNEL-VERSION</replaceable> <replaceable>KERNEL-IMAGE</replaceable></command></term>
  91         <listitem>
  92           <para><command>kernel-install</command> creates the directory
  93           <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
  94           and calls executables from
  95           <filename>/usr/lib/kernel/install.d/*.install</filename> and
  96           <filename>/etc/kernel/install.d/*.install</filename> with
  97           the arguments
  98           <programlisting>add <replaceable>KERNEL-VERSION</replaceable> \
  99     <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> <replaceable>KERNEL-IMAGE</replaceable></programlisting>
 100           </para>
 101
 102           <para>The kernel-install plugin <filename>50-depmod.install</filename> runs depmod for the <replaceable>KERNEL-VERSION</replaceable>.</para>
 103
 104           <para>The kernel-install plugin
 105           <filename>90-loaderentry.install</filename> copies
 106           <replaceable>KERNEL-IMAGE</replaceable> to
 107           <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/linux</filename>.
 108           It also creates a boot loader entry according to the boot
 109           loader specification in
 110           <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.
 111           The title of the entry is the
 112           <replaceable>PRETTY_NAME</replaceable> parameter specified
 113           in <filename>/etc/os-release</filename> or
 114           <filename>/usr/lib/os-release</filename> (if the former is
 115           missing), or "Linux
 116           <replaceable>KERNEL-VERSION</replaceable>", if unset.  If
 117           the file <filename>initrd</filename> is found next to the
 118           <filename>linux</filename> file, the initrd will be added to
 119           the configuration.</para>
 120         </listitem>
 121       </varlistentry>
 122       <varlistentry>
 123         <term><command>remove <replaceable>KERNEL-VERSION</replaceable></command></term>
 124         <listitem>
 125           <para>Calls executables from <filename>/usr/lib/kernel/install.d/*.install</filename>
 126           and <filename>/etc/kernel/install.d/*.install</filename> with the arguments
 127           <programlisting>remove <replaceable>KERNEL-VERSION</replaceable> <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename></programlisting>
 128           </para>
 129
 130           <para><command>kernel-install</command> removes the entire directory
 131           <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> afterwards.</para>
 132
 133           <para>The kernel-install plugin <filename>90-loaderentry.install</filename> removes the file
 134           <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.</para>
 135         </listitem>
 136       </varlistentry>
 137
 138     </variablelist>
 139
 140   </refsect1>
 141
 142   <refsect1>
 143     <title>Exit status</title>
 144     <para>If every executable returns 0 or 77, 0 is returned, and a non-zero failure code otherwise.</para>
 145   </refsect1>
 146
 147   <refsect1>
 148     <title>Files</title>
 149     <variablelist>
 150       <varlistentry>
 151         <term>
 152           <filename>/usr/lib/kernel/install.d/*.install</filename>
 153           <filename>/etc/kernel/install.d/*.install</filename>
 154         </term>
 155           <listitem>
 156             <para>Drop-in files which are executed by kernel-install.</para>
 157           </listitem>
 158       </varlistentry>
 159       <varlistentry>
 160         <term>
 161           <filename>/etc/kernel/cmdline</filename>
 162           <filename>/proc/cmdline</filename>
 163         </term>
 164           <listitem>
 165             <para>The content of the file <filename>/etc/kernel/cmdline</filename> specifies the kernel command line to use.
 166             If that file does not exist, <filename>/proc/cmdline</filename> is used.</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       <ulink url="https://www.freedesktop.org/wiki/Specifications/BootLoaderSpec">Boot loader specification</ulink>
 195     </para>
 196   </refsect1>
 197
 198 </refentry>