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
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
<?xml version='1.0'?>
<!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+
-->
<refentry id="kernel-install">
<refentryinfo>
<title>kernel-install</title>
<productname>systemd</productname>
</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>This command expects a kernel version string and a path to a kernel image file as
arguments. <command>kernel-install</command> creates the directory
<filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
and calls the executables from <filename>/usr/lib/kernel/install.d/*.install</filename> and
<filename>/etc/kernel/install.d/*.install</filename> with the following 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>Two default plugins execute the following operations in this case:</para>
<itemizedlist>
<listitem><para><filename>50-depmod.install</filename> runs
<citerefentry><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry> for the
<replaceable>KERNEL-VERSION</replaceable>.</para></listitem>
<listitem><para><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 <ulink
url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> 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 kernel image file, the initrd will be added to the
configuration.</para></listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><command>remove <replaceable>KERNEL-VERSION</replaceable></command></term>
<listitem>
<para>This command expects a kernel version string as single argument. This calls executables from
<filename>/usr/lib/kernel/install.d/*.install</filename> and
<filename>/etc/kernel/install.d/*.install</filename> with the following arguments:
<programlisting>remove <replaceable>KERNEL-VERSION</replaceable> <filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename></programlisting>
</para>
<para>Afterwards, <command>kernel-install</command> removes the directory
<filename>/boot/<replaceable>MACHINE-ID</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
and its contents.</para>
<para>Two default plugins execute the following operations in this case:</para>
<itemizedlist>
<listitem><para><filename>50-depmod.install</filename> removes the files generated by <command>depmod</command> for this kernel again.</para></listitem>
<listitem><para><filename>90-loaderentry.install</filename> removes the file
<filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.</para></listitem>
</itemizedlist>
</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>Read by <filename>90-loaderentry.install</filename>. 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/kernel/tries</filename>
</term>
<listitem>
<para>Read by <filename>90-loaderentry.install</filename>. If this file exists a numeric value is read from
it and the naming of the generated entry file is slightly altered to include it as
<filename>/boot/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>+<replaceable>TRIES</replaceable>.conf</filename>. This
is useful for boot loaders such as
<citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> which
implement boot attempt counting with a counter embedded in the entry file name.</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>,
<citerefentry><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>
</para>
</refsect1>
</refentry>
|
