]>
Commit | Line | Data |
---|---|---|
514094f9 | 1 | <?xml version='1.0'?> |
3a54a157 ZJS |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> | |
db9ecf05 | 4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
81516adc | 5 | |
9858e6d2 | 6 | <refentry id="kernel-install" conditional='ENABLE_KERNEL_INSTALL' |
7054308a | 7 | xmlns:xi="http://www.w3.org/2001/XInclude"> |
81516adc HH |
8 | |
9 | <refentryinfo> | |
10 | <title>kernel-install</title> | |
11 | <productname>systemd</productname> | |
81516adc HH |
12 | </refentryinfo> |
13 | ||
14 | <refmeta> | |
15 | <refentrytitle>kernel-install</refentrytitle> | |
16 | <manvolnum>8</manvolnum> | |
17 | </refmeta> | |
18 | ||
19 | <refnamediv> | |
20 | <refname>kernel-install</refname> | |
21 | <refpurpose>Add and remove kernel and initramfs images to and from /boot</refpurpose> | |
22 | </refnamediv> | |
23 | ||
24 | <refsynopsisdiv> | |
25 | <cmdsynopsis> | |
845c5324 ZJS |
26 | <command>kernel-install</command> |
27 | <arg choice="plain">COMMAND</arg> | |
7054308a | 28 | <arg choice="opt" rep="repeat">OPTIONS</arg> |
845c5324 | 29 | <arg choice="plain"><replaceable>KERNEL-VERSION</replaceable></arg> |
04ca4d19 | 30 | <arg choice="plain"><replaceable>KERNEL-IMAGE</replaceable></arg> |
0912c0b8 | 31 | <arg choice="opt" rep="repeat"><replaceable>INITRD-FILE</replaceable></arg> |
81516adc HH |
32 | </cmdsynopsis> |
33 | </refsynopsisdiv> | |
34 | ||
35 | <refsect1> | |
36 | <title>Description</title> | |
694fe6da ZJS |
37 | <para><command>kernel-install</command> is used to install and remove kernel and initramfs images to and |
38 | from the boot loader partition, referred to as <varname>$BOOT</varname> here. It will usually be one of | |
e9dd6984 | 39 | <filename>/boot/</filename>, <filename>/efi/</filename>, or <filename>/boot/efi/</filename>, see below. |
81516adc HH |
40 | </para> |
41 | ||
fe81e346 LP |
42 | <para><command>kernel-install</command> will run the executable files ("plugins") located in the |
43 | directory <filename>/usr/lib/kernel/install.d/</filename> and the local administration directory | |
44 | <filename>/etc/kernel/install.d/</filename>. All files are collectively sorted and executed in lexical | |
45 | order, regardless of the directory in which they live. However, files with identical filenames replace | |
46 | each other. Files in <filename>/etc/kernel/install.d/</filename> take precedence over files with the | |
47 | same name in <filename>/usr/lib/kernel/install.d/</filename>. This can be used to override a | |
48 | system-supplied executables with a local file if needed; a symbolic link in | |
49 | <filename>/etc/kernel/install.d/</filename> with the same name as an executable in | |
50 | <filename>/usr/lib/kernel/install.d/</filename>, pointing to <filename>/dev/null</filename>, disables the | |
51 | executable entirely. Executables must have the extension <literal>.install</literal>; other extensions | |
52 | are ignored.</para> | |
53 | ||
54 | <para>An executable placed in these directories should return <constant>0</constant> on success. It may | |
55 | also return <constant>77</constant> to cause the whole operation to terminate (executables later in | |
56 | lexical order will be skipped).</para> | |
81516adc HH |
57 | </refsect1> |
58 | ||
59 | <refsect1> | |
60 | <title>Commands</title> | |
61 | <para>The following commands are understood:</para> | |
62 | <variablelist> | |
63 | <varlistentry> | |
0912c0b8 | 64 | <term><command>add <replaceable>KERNEL-VERSION</replaceable> <replaceable>KERNEL-IMAGE</replaceable> [<replaceable>INITRD-FILE</replaceable> ...]</command></term> |
81516adc | 65 | <listitem> |
4b2d80bb | 66 | <para>This command expects a kernel version string and a path to a kernel image file as |
fe81e346 LP |
67 | arguments. Optionally, one or more initial RAM disk images may be specified as well (note that |
68 | plugins might generate additional ones). <command>kernel-install</command> calls the executable | |
69 | files from <filename>/usr/lib/kernel/install.d/*.install</filename> and | |
70 | <filename>/etc/kernel/install.d/*.install</filename> (i.e. the plugins) with the following | |
71 | arguments:</para> | |
4b2d80bb | 72 | |
fe81e346 LP |
73 | <programlisting>add <replaceable>KERNEL-VERSION</replaceable> <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> <replaceable>KERNEL-IMAGE</replaceable> [<replaceable>INITRD-FILE</replaceable> ...]</programlisting> |
74 | ||
75 | <para>The third argument directly refers to the path where to place kernel images, initial RAM disk | |
76 | images and other resources for <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot | |
77 | Loader Specification</ulink> Type #1 entries (the "entry directory"). If other boot loader schemes | |
78 | are used the parameter may be ignored. The <replaceable>ENTRY-TOKEN</replaceable> string is | |
79 | typically the machine ID and is supposed to identify the local installation on the system. For | |
80 | details see below.</para> | |
845c5324 | 81 | |
641e2124 | 82 | <para>Two default plugins execute the following operations in this case:</para> |
4b2d80bb LP |
83 | |
84 | <itemizedlist> | |
641e2124 | 85 | <listitem><para><command>kernel-install</command> creates |
fe81e346 LP |
86 | <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable></filename>, |
87 | if enabled (see <varname>$KERNEL_INSTALL_LAYOUT</varname>).</para></listitem> | |
4b2d80bb LP |
88 | |
89 | <listitem><para><filename>50-depmod.install</filename> runs | |
b7a47345 | 90 | <citerefentry project='man-pages'><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry> for the |
4b2d80bb LP |
91 | <replaceable>KERNEL-VERSION</replaceable>.</para></listitem> |
92 | ||
fe81e346 LP |
93 | <listitem><para><filename>90-loaderentry.install</filename> copies |
94 | <replaceable>KERNEL-IMAGE</replaceable> to | |
95 | <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/linux</filename>. | |
641e2124 | 96 | If <replaceable>INITRD-FILE</replaceable>s are provided, it also copies them to |
fe81e346 | 97 | <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL_VERSION</replaceable>/<replaceable>INITRD-FILE</replaceable></filename>. |
4b2d80bb | 98 | It also creates a boot loader entry according to the <ulink |
fe81e346 LP |
99 | url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> (Type #1) in |
100 | <filename>$BOOT/loader/entries/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>. | |
4b2d80bb | 101 | The title of the entry is the <replaceable>PRETTY_NAME</replaceable> parameter specified in |
fe81e346 LP |
102 | <filename>/etc/os-release</filename> or <filename>/usr/lib/os-release</filename> (if the former |
103 | is missing), or "Linux <replaceable>KERNEL-VERSION</replaceable>", if unset.</para> | |
cf73f650 | 104 | |
fe81e346 | 105 | <para>If <varname>$KERNEL_INSTALL_LAYOUT</varname> is not "bls", this plugin does nothing.</para></listitem> |
4b2d80bb | 106 | </itemizedlist> |
81516adc HH |
107 | </listitem> |
108 | </varlistentry> | |
109 | <varlistentry> | |
8f51399e | 110 | <term><command>remove <replaceable>KERNEL-VERSION</replaceable></command></term> |
845c5324 | 111 | <listitem> |
4b2d80bb LP |
112 | <para>This command expects a kernel version string as single argument. This calls executables from |
113 | <filename>/usr/lib/kernel/install.d/*.install</filename> and | |
114 | <filename>/etc/kernel/install.d/*.install</filename> with the following arguments: | |
845c5324 ZJS |
115 | </para> |
116 | ||
fe81e346 LP |
117 | <programlisting>remove <replaceable>KERNEL-VERSION</replaceable> <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename></programlisting> |
118 | ||
119 | <para>Afterwards, <command>kernel-install</command> removes the entry directory | |
120 | <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> | |
121 | and its contents, if it exists.</para> | |
4b2d80bb LP |
122 | |
123 | <para>Two default plugins execute the following operations in this case:</para> | |
124 | ||
125 | <itemizedlist> | |
4b2d80bb LP |
126 | <listitem><para><filename>50-depmod.install</filename> removes the files generated by <command>depmod</command> for this kernel again.</para></listitem> |
127 | ||
128 | <listitem><para><filename>90-loaderentry.install</filename> removes the file | |
fe81e346 | 129 | <filename>$BOOT/loader/entries/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.</para></listitem> |
641e2124 | 130 | </itemizedlist> |
81516adc HH |
131 | </listitem> |
132 | </varlistentry> | |
fe81e346 LP |
133 | <varlistentry> |
134 | <term><command>inspect</command></term> | |
135 | <listitem> | |
136 | <para>Shows the various paths and parameters configured or auto-detected. In particular shows the | |
137 | values of the various <varname>$KERNEL_INSTALL_*</varname> environment variables listed | |
138 | below.</para> | |
139 | </listitem> | |
140 | </varlistentry> | |
81516adc HH |
141 | |
142 | </variablelist> | |
694fe6da | 143 | </refsect1> |
81516adc | 144 | |
694fe6da ZJS |
145 | <refsect1> |
146 | <title>The <varname>$BOOT</varname> partition</title> | |
147 | <para>The partition where the kernels and <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot | |
148 | Loader Specification</ulink> snippets are located is called <varname>$BOOT</varname>. | |
149 | <command>kernel-install</command> determines the location of this partition by checking | |
fe81e346 LP |
150 | <filename>/efi/</filename>, <filename>/boot/</filename>, and <filename>/boot/efi/</filename> in turn. The |
151 | first location where <filename>$BOOT/loader/entries/</filename> or | |
152 | <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/</filename> exists is used.</para> | |
81516adc HH |
153 | </refsect1> |
154 | ||
7054308a ZJS |
155 | <refsect1> |
156 | <title>Options</title> | |
157 | <para>The following options are understood:</para> | |
158 | ||
159 | <variablelist> | |
160 | <varlistentry> | |
161 | <term><option>-v</option></term> | |
162 | <term><option>--verbose</option></term> | |
163 | <listitem> | |
164 | <para>Output additional information about operations being performed.</para> | |
165 | </listitem> | |
166 | </varlistentry> | |
167 | ||
168 | <xi:include href="standard-options.xml" xpointer="help" /> | |
99d8cbce | 169 | <xi:include href="standard-options.xml" xpointer="version" /> |
7054308a ZJS |
170 | </variablelist> |
171 | </refsect1> | |
172 | ||
173 | <refsect1> | |
174 | <title>Environment variables</title> | |
dcd9d196 | 175 | |
7054308a ZJS |
176 | <para>If <option>--verbose</option> is used, <varname>$KERNEL_INSTALL_VERBOSE=1</varname> will be set for |
177 | the plugins. They may output additional logs in this case.</para> | |
dcd9d196 | 178 | |
fe81e346 LP |
179 | <para>If <varname>$MACHINE_ID</varname> is set and not empty when <command>kernel-install</command> is |
180 | invoked, it will be used as <replaceable>MACHINE-ID</replaceable>, overriding any automatic detection | |
181 | attempts. The value must be a valid machine ID (32 hexadecimal characters).</para> | |
182 | ||
183 | <para><varname>$KERNEL_INSTALL_MACHINE_ID</varname> is set for the plugins to the desired | |
184 | <replaceable>MACHINE-ID</replaceable> to use. It's always a 128bit ID, and typically the ID from | |
185 | <filename>/etc/machine-id</filename> or the one passed in via <varname>$MACHINE_ID</varname>. (If no | |
186 | machine ID was specified via these methods it might be generated randomly by | |
187 | <command>kernel-install</command>, in which case it only applies to this invocation.)</para> | |
188 | ||
189 | <para><varname>$KERNEL_INSTALL_ENTRY_TOKEN</varname> is set for the plugins to the desired entry "token" | |
190 | to use. It's an identifier that shall be used to identify the local installation, and is often the | |
191 | machine ID, i.e. same as <varname>$KERNEL_INSTALL_MACHINE_ID</varname>, but might also be a different | |
192 | type of identifier, for example a fixed string or the <varname>ID=</varname>, | |
193 | <varname>IMAGE_ID=</varname> values from <filename>/etc/os-release</filename>. The string passed here | |
194 | will be used to name Boot Loader Specification entries, or the directories the kernel image and initial | |
195 | RAM disk images are placed into. Note that while oftentimes | |
196 | <varname>$KERNEL_INSTALL_ENTRY_TOKEN</varname> and <varname>$KERNEL_INSTALL_MACHINE_ID</varname> are set | |
197 | to the same value, the latter is guaranteed to be a valid 32 character ID in lowercase hexadecimals while | |
198 | the former can be any short string. The entry token to use is read from | |
199 | <filename>/etc/kernel/entry-token</filename>, if it exists. Otherwise a few possible candidates below the | |
200 | <varname>$BOOT</varname> are searched for Boot Loader Specification Type 1 entry directories, and if | |
201 | found the entry token is derived from that. If that is not successful the machine ID is used as | |
202 | fallback.</para> | |
203 | ||
204 | <para><varname>$KERNEL_INSTALL_BOOT_ROOT</varname> is set for the plugins to the absolute path of the | |
205 | root directory (mount point, usually) of the hierarchy where boot loader entries, kernel images, and | |
206 | associated resources should be placed. This usually is the path where the XBOOTLDR partition or the ESP | |
207 | (EFI System Partition) are mounted, and also conceptually referred to as <varname>$BOOT</varname>. Can be | |
208 | overridden by setting <varname>$BOOT_ROOT</varname>.</para> | |
209 | ||
210 | <para><varname>$KERNEL_INSTALL_LAYOUT=bls|other|...</varname> is set for the plugins to specify the | |
211 | installation layout. Defaults to <option>bls</option> if | |
212 | <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable></filename> exists, or <option>other</option> | |
213 | otherwise. Additional layout names may be defined by convention. If a plugin uses a special layout, it's | |
214 | encouraged to declare its own layout name and configure <varname>layout=</varname> in | |
215 | <filename>install.conf</filename> upon initial installation. The following values are currently | |
216 | understood:</para> | |
367165a4 | 217 | |
641e2124 | 218 | <variablelist> |
219 | <varlistentry> | |
220 | <term>bls</term> | |
221 | <listitem> | |
fe81e346 LP |
222 | <para>Standard <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader |
223 | Specification</ulink> Type #1 layout, compatible with | |
224 | <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>: | |
225 | entries in | |
226 | <filename>$BOOT/loader/entries/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>[+<replaceable>TRIES</replaceable>].conf</filename>, | |
227 | kernel and initrds under | |
228 | <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename></para> | |
229 | <para>Implemented by <filename>90-loaderentry.install</filename>.</para> | |
641e2124 | 230 | </listitem> |
231 | </varlistentry> | |
232 | <varlistentry> | |
233 | <term>other</term> | |
234 | <listitem> | |
235 | <para>Some other layout not understood natively by <command>kernel-install</command>.</para> | |
236 | </listitem> | |
237 | </varlistentry> | |
238 | </variablelist> | |
fe81e346 LP |
239 | |
240 | <para><varname>$KERNEL_INSTALL_INITRD_GENERATOR</varname> is set for plugins to select the initrd | |
354a2441 LP |
241 | generator. This may be configured as <varname>initrd_generator=</varname> in |
242 | <filename>install.conf</filename>. See below.</para> | |
fe81e346 LP |
243 | |
244 | <para><varname>$KERNEL_INSTALL_STAGING_AREA</varname> is set for plugins to a path to a directory. | |
245 | Plugins may drop files in that directory, and they will be installed as part of the loader entry, based | |
246 | on the file name and extension.</para> | |
7054308a ZJS |
247 | </refsect1> |
248 | ||
81516adc HH |
249 | <refsect1> |
250 | <title>Exit status</title> | |
c4c50112 | 251 | <para>If every executable returns 0 or 77, 0 is returned, and a non-zero failure code otherwise.</para> |
81516adc HH |
252 | </refsect1> |
253 | ||
254 | <refsect1> | |
255 | <title>Files</title> | |
256 | <variablelist> | |
257 | <varlistentry> | |
258 | <term> | |
259 | <filename>/usr/lib/kernel/install.d/*.install</filename> | |
260 | <filename>/etc/kernel/install.d/*.install</filename> | |
261 | </term> | |
262 | <listitem> | |
409dee2e | 263 | <para>Drop-in files which are executed by kernel-install.</para> |
81516adc HH |
264 | </listitem> |
265 | </varlistentry> | |
2d0614d3 HH |
266 | <varlistentry> |
267 | <term> | |
595fd662 | 268 | <filename>/usr/lib/kernel/cmdline</filename> |
2d0614d3 HH |
269 | <filename>/etc/kernel/cmdline</filename> |
270 | <filename>/proc/cmdline</filename> | |
271 | </term> | |
272 | <listitem> | |
4b2d80bb LP |
273 | <para>Read by <filename>90-loaderentry.install</filename>. The content of the file |
274 | <filename>/etc/kernel/cmdline</filename> specifies the kernel command line to use. If that file does not | |
595fd662 | 275 | exist, <filename>/usr/lib/kernel/cmdline</filename> is used. If that also does not exist, |
276 | <filename>/proc/cmdline</filename> is used.</para> | |
4b2d80bb LP |
277 | </listitem> |
278 | </varlistentry> | |
279 | <varlistentry> | |
280 | <term> | |
281 | <filename>/etc/kernel/tries</filename> | |
282 | </term> | |
283 | <listitem> | |
284 | <para>Read by <filename>90-loaderentry.install</filename>. If this file exists a numeric value is read from | |
285 | it and the naming of the generated entry file is slightly altered to include it as | |
694fe6da | 286 | <filename>$BOOT/loader/entries/<replaceable>MACHINE-ID</replaceable>-<replaceable>KERNEL-VERSION</replaceable>+<replaceable>TRIES</replaceable>.conf</filename>. This |
4b2d80bb LP |
287 | is useful for boot loaders such as |
288 | <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> which | |
289 | implement boot attempt counting with a counter embedded in the entry file name.</para> | |
2d0614d3 HH |
290 | </listitem> |
291 | </varlistentry> | |
292 | <varlistentry> | |
293 | <term> | |
fe81e346 | 294 | <filename>/etc/kernel/entry-token</filename> |
2d0614d3 HH |
295 | </term> |
296 | <listitem> | |
fe81e346 LP |
297 | <para>If this file exists it is read and used as "entry token" for this system, i.e. is used for |
298 | naming Boot Loader Specification entries, see | |
299 | <varname>$KERNEL_INSTALL_ENTRY_TOKEN</varname> above for details.</para> | |
2d0614d3 HH |
300 | </listitem> |
301 | </varlistentry> | |
357376d0 DDM |
302 | <varlistentry> |
303 | <term> | |
fe81e346 | 304 | <filename>/etc/machine-id</filename> |
357376d0 DDM |
305 | </term> |
306 | <listitem> | |
fe81e346 LP |
307 | <para>The content of this file specifies the machine identification |
308 | <replaceable>MACHINE-ID</replaceable>.</para> | |
357376d0 DDM |
309 | </listitem> |
310 | </varlistentry> | |
2d0614d3 HH |
311 | <varlistentry> |
312 | <term> | |
313 | <filename>/etc/os-release</filename> | |
5ae4d543 | 314 | <filename>/usr/lib/os-release</filename> |
2d0614d3 | 315 | </term> |
fe81e346 | 316 | <listitem> |
22a81fe4 | 317 | <para>Read by <filename>90-loaderentry.install</filename>. |
fe81e346 | 318 | If available, <varname>PRETTY_NAME=</varname> is read from these files and used as the title of the boot menu entry. |
22a81fe4 | 319 | Otherwise, <literal>Linux <replaceable>KERNEL-VERSION</replaceable></literal> will be used.</para> |
2d0614d3 HH |
320 | </listitem> |
321 | </varlistentry> | |
641e2124 | 322 | <varlistentry> |
323 | <term> | |
324 | <filename>/usr/lib/kernel/install.conf</filename> | |
325 | <filename>/etc/kernel/install.conf</filename> | |
326 | </term> | |
327 | <listitem> | |
354a2441 LP |
328 | <para>Configuration options for <command>kernel-install</command>, as a series of |
329 | <varname>KEY=</varname><replaceable>VALUE</replaceable> assignments, compatible with shell | |
330 | syntax. This currently supports two keys: <varname>layout=</varname> and | |
331 | <varname>initrd_generator=</varname>, for details see the Environment variables section above.</para> | |
641e2124 | 332 | </listitem> |
333 | </varlistentry> | |
81516adc HH |
334 | </variablelist> |
335 | </refsect1> | |
336 | ||
337 | <refsect1> | |
338 | <title>See Also</title> | |
339 | <para> | |
2d0614d3 HH |
340 | <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
341 | <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>, | |
b7a47345 | 342 | <citerefentry project='man-pages'><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
4b2d80bb | 343 | <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, |
a0848495 | 344 | <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> |
81516adc HH |
345 | </para> |
346 | </refsect1> | |
347 | ||
348 | </refentry> |