summaryrefslogtreecommitdiff
path: root/man/kernel-install.xml
blob: 78d1a866f606efeb3464fda01125896d4adfd63a (plain)
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
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  SPDX-License-Identifier: LGPL-2.1+

  Copyright 2013 Harald Hoyer
-->

<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
    which they live. However, files with identical filenames replace each other.
    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 <filename>/dev/null</filename>, disables the executable entirely. Executables must have the
    extension <literal>.install</literal>; other extensions are ignored.</para>

    <para>An executable should return <constant>0</constant> on success. It may also
    return <constant>77</constant> to cause the whole operation to terminate
    (executables later in lexical order will be skipped).</para>
  </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 executables from
          <filename>/usr/lib/kernel/install.d/*.install</filename> and
          <filename>/etc/kernel/install.d/*.install</filename> with
          the arguments
          <programlisting>add <replaceable>KERNEL-VERSION</replaceable> \
    <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> <replaceable>KERNEL-IMAGE</replaceable></programlisting>
          </para>

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

          <para>The kernel-install plugin
          <filename>90-loaderentry.install</filename> copies
          <replaceable>KERNEL-IMAGE</replaceable> to
          <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/linux</filename>.
          It also creates a boot loader entry according to the boot
          loader specification in
          <filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.
          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
          <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>
          <para>Calls executables from <filename>/usr/lib/kernel/install.d/*.install</filename>
          and <filename>/etc/kernel/install.d/*.install</filename> with the arguments
          <programlisting>remove <replaceable>KERNEL-VERSION</replaceable> <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename></programlisting>
          </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 0 or 77, 0 is returned, and 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>
            <para>Drop-in files which are executed by kernel-install.</para>
          </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>
          <filename>/usr/lib/os-release</filename>
        </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="https://www.freedesktop.org/wiki/Specifications/BootLoaderSpec">Boot loader specification</ulink>
    </para>
  </refsect1>

</refentry>