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