kernel-install.xml 8.02 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
This file is part of systemd.

Copyright 2013 Harald Hoyer

systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.

systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="kernel-install">

  <refentryinfo>
    <title>kernel-install</title>
    <productname>systemd</productname>

    <authorgroup>
      <author>
        <contrib>Developer</contrib>
        <firstname>Harald</firstname>
        <surname>Hoyer</surname>
        <email>harald@redhat.com</email>
      </author>
    </authorgroup>
  </refentryinfo>

  <refmeta>
    <refentrytitle>kernel-install</refentrytitle>
    <manvolnum>8</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>kernel-install</refname>
    <refpurpose>Add and remove kernel and initramfs images to and from /boot</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>kernel-install</command>
      <arg choice="plain">COMMAND</arg>
      <arg choice="plain"><replaceable>KERNEL-VERSION</replaceable></arg>
      <arg choice="opt"><replaceable>KERNEL-IMAGE</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>
      <command>kernel-install</command> is used to install and remove kernel and
      initramfs images to and from <filename>/boot</filename>.
    </para>

    <para><command>kernel-install</command> will execute the files
    located in the directory <filename>/usr/lib/kernel/install.d/</filename>
    and the local administration directory <filename>/etc/kernel/install.d/</filename>.
    All files are collectively sorted and executed in lexical order, regardless of the directory in
70
    which they live. However, files with identical filenames replace each other.
71 72 73 74 75
    Files in <filename>/etc/kernel/install.d/</filename> take precedence over files with the same name
    in <filename>/usr/lib/kernel/install.d/</filename>. This can be used to override a system-supplied
    executables with a local file if needed; a symbolic link in <filename>/etc/kernel/install.d/</filename>
    with the same name as an executable in <filename>/usr/lib/kernel/install.d/</filename>,
    pointing to /dev/null, disables the executable entirely. Executables must have the
76
    extension <literal>.install</literal>; other extensions are ignored.</para>
77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92

  </refsect1>

  <refsect1>
    <title>Commands</title>
    <para>The following commands are understood:</para>
    <variablelist>
      <varlistentry>
        <term><command>add <replaceable>KERNEL-VERSION</replaceable> <replaceable>KERNEL-IMAGE</replaceable></command></term>
        <listitem>
          <para><command>kernel-install</command> creates the directory
          <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
          and calls every executable
          <filename>/usr/lib/kernel/install.d/*.install</filename> and
          <filename>/etc/kernel/install.d/*.install</filename> with
          the arguments
93
          <programlisting>add <replaceable>KERNEL-VERSION</replaceable> <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename></programlisting>
94 95 96 97
          </para>

          <para>The kernel-install plugin <filename>50-depmod.install</filename> runs depmod for the <replaceable>KERNEL-VERSION</replaceable>.</para>

98 99
          <para>The kernel-install plugin
          <filename>90-loaderentry.install</filename> copies
100 101
          <replaceable>KERNEL-IMAGE</replaceable> to
          <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/linux</filename>.
102 103
          It also creates a boot loader entry according to the boot
          loader specification in
104
          <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.
105 106 107 108 109 110 111
          The title of the entry is the
          <replaceable>PRETTY_NAME</replaceable> parameter specified
          in <filename>/etc/os-release</filename> or
          <filename>/usr/lib/os-release</filename> (if the former is
          missing), or "Linux
          <replaceable>KERNEL-VERSION</replaceable>", if unset.  If
          the file <filename>initrd</filename> is found next to the
112 113 114 115 116 117 118
          <filename>linux</filename> file, the initrd will be added to
          the configuration.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><command>remove <replaceable>KERNEL-VERSION</replaceable></command></term>
        <listitem>
119
          <para>Calls every executable <filename>/usr/lib/kernel/install.d/*.install</filename>
120
          and <filename>/etc/kernel/install.d/*.install</filename> with the arguments
121
          <programlisting>remove <replaceable>KERNEL-VERSION</replaceable> <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename></programlisting>
122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149
          </para>

          <para><command>kernel-install</command> removes the entire directory
          <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> afterwards.</para>

          <para>The kernel-install plugin <filename>90-loaderentry.install</filename> removes the file
          <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.</para>
        </listitem>
      </varlistentry>

    </variablelist>

  </refsect1>

  <refsect1>
    <title>Exit status</title>
    <para>If every executable returns with 0, 0 is returned, a non-zero failure code otherwise.</para>
  </refsect1>

  <refsect1>
    <title>Files</title>
    <variablelist>
      <varlistentry>
        <term>
          <filename>/usr/lib/kernel/install.d/*.install</filename>
          <filename>/etc/kernel/install.d/*.install</filename>
        </term>
          <listitem>
150
            <para>Drop-in files which are executed by kernel-install.</para>
151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173
          </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <filename>/etc/kernel/cmdline</filename>
          <filename>/proc/cmdline</filename>
        </term>
          <listitem>
            <para>The content of the file <filename>/etc/kernel/cmdline</filename> specifies the kernel command line to use.
            If that file does not exist, <filename>/proc/cmdline</filename> is used.</para>
          </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <filename>/etc/machine-id</filename>
        </term>
          <listitem>
            <para>The content of the file specifies the machine identification <replaceable>MACHINE-ID</replaceable>.</para>
          </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <filename>/etc/os-release</filename>
174
          <filename>/usr/lib/os-release</filename>
175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192
        </term>
          <listitem>
            <para>The content of the file specifies the operating system title <replaceable>PRETTY_NAME</replaceable>.</para>
          </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
      <ulink url="http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec">Boot loader specification</ulink>
    </para>
  </refsect1>

</refentry>