Debian Codegraph @

upstream/debian-trixie/man8/kernel-install.8

raw
1 '\" t
2 .TH "KERNEL\-INSTALL" "8" "" "systemd 257.13" "kernel-install"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 kernel-install \- Add and remove kernel and initrd images to and from the boot partition
24 .SH "SYNOPSIS"
25 .HP \w'\fBkernel\-install\fR\ 'u
26 \fBkernel\-install\fR [OPTIONS...] add \fIKERNEL\-VERSION\fR \fIKERNEL\-IMAGE\fR [\fIINITRD\-FILE\fR...]
27 .HP \w'\fBkernel\-install\fR\ 'u
28 \fBkernel\-install\fR [OPTIONS...] add\-all
29 .HP \w'\fBkernel\-install\fR\ 'u
30 \fBkernel\-install\fR [OPTIONS...] remove \fIKERNEL\-VERSION\fR
31 .HP \w'\fBkernel\-install\fR\ 'u
32 \fBkernel\-install\fR [OPTIONS...] inspect [\fIKERNEL\-VERSION\fR] [\fIKERNEL\-IMAGE\fR] [\fIINITRD\-FILE\fR...]
33 .HP \w'\fBkernel\-install\fR\ 'u
34 \fBkernel\-install\fR [OPTIONS...] list
35 .SH "DESCRIPTION"
36 .PP
37 \fBkernel\-install\fR
38 is used to install and remove kernel and initrd images
39 \&\s-2\u[1]\d\s+2
40 to and from the boot partition, referred to as
41 \fI$BOOT\fR
42 here\&. It will usually be one of
43 /boot/,
44 /efi/, or
45 /boot/efi/, see below\&.
46 .PP
47 \fBkernel\-install\fR
48 will run the executable files ("plugins") located in the directory
49 /usr/lib/kernel/install\&.d/
50 and the local administration directory
51 /etc/kernel/install\&.d/\&. 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
52 /etc/kernel/install\&.d/
53 take precedence over files with the same name in
54 /usr/lib/kernel/install\&.d/\&. This can be used to override a system\-supplied executables with a local file if needed; a symbolic link in
55 /etc/kernel/install\&.d/
56 with the same name as an executable in
57 /usr/lib/kernel/install\&.d/, pointing to
58 /dev/null, disables the executable entirely\&. Executables must have the extension
59 "\&.install"; other extensions are ignored\&.
60 .PP
61 An executable placed in these directories should return
62 \fB0\fR
63 on success\&. It may also return
64 \fB77\fR
65 to cause the whole operation to terminate (executables later in lexical order will be skipped)\&.
66 .SH "COMMANDS"
67 .PP
68 The following commands are understood:
69 .PP
70 \fBadd [[[\fR\fB\fIKERNEL\-VERSION\fR\fR\fB] \fR\fB\fIKERNEL\-IMAGE\fR\fR\fB] [\fR\fB\fIINITRD\-FILE\fR\fR\fB \&.\&.\&.]]\fR
71 .RS 4
72 This command takes a kernel version string and a path to a kernel image file as arguments\&. If the former is omitted, specified as an empty string or as "\-" it defaults to the current kernel version, i\&.e\&. the same string
73 \fBuname \-r\fR
74 returns\&. If the latter is omitted, specified as an empty string or as "\-" defaults to
75 /usr/lib/modules/\fIKERNEL_VERSION\fR/vmlinuz\&. Optionally, one or more initrd images may be specified as well (note that plugins might generate additional ones)\&.
76 .sp
77 The executable files from
78 /usr/lib/kernel/install\&.d/*\&.install
79 and
80 /etc/kernel/install\&.d/*\&.install
81 (i\&.e\&. the plugins) are called with the following arguments:
82 .sp
83 .if n \{\
84 .RS 4
85 .\}
86 .nf
87 add \fIKERNEL\-VERSION\fR $BOOT/\fIENTRY\-TOKEN\fR/\fIKERNEL\-VERSION\fR/ \fIKERNEL\-IMAGE\fR \e
88 [\fIINITRD\-FILE\fR \&.\&.\&.]
89 .fi
90 .if n \{\
91 .RE
92 .\}
93 .sp
94 The third argument directly refers to the path where to place kernel images, initrd images and other resources for
95 \m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2
96 Type #1 entries (the "entry directory")\&. If other boot loader schemes are used the parameter may be ignored\&.
97 .sp
98 The
99 \fIENTRY\-TOKEN\fR
100 string is typically the machine ID and is supposed to identify the local installation on the system\&. For details see below\&.
101 .sp
102 Two default plugins execute the following operations in this case:
103 .sp
104 .RS 4
105 .ie n \{\
106 \h'-04'\(bu\h'+03'\c
107 .\}
108 .el \{\
109 .sp -1
110 .IP \(bu 2.3
111 .\}
112 \fBkernel\-install\fR
113 creates
114 $BOOT/\fIENTRY\-TOKEN\fR/\fIKERNEL\-VERSION\fR, if enabled (see
115 \fI$KERNEL_INSTALL_LAYOUT\fR)\&.
116 .RE
117 .sp
118 .RS 4
119 .ie n \{\
120 \h'-04'\(bu\h'+03'\c
121 .\}
122 .el \{\
123 .sp -1
124 .IP \(bu 2.3
125 .\}
126 50\-depmod\&.install
127 runs
128 \fBdepmod\fR(8)
129 for the
130 \fIKERNEL\-VERSION\fR\&.
131 .RE
132 .sp
133 .RS 4
134 .ie n \{\
135 \h'-04'\(bu\h'+03'\c
136 .\}
137 .el \{\
138 .sp -1
139 .IP \(bu 2.3
140 .\}
141 90\-loaderentry\&.install
142 copies
143 \fIKERNEL\-IMAGE\fR
144 to
145 $BOOT/\fIENTRY\-TOKEN\fR/\fIKERNEL\-VERSION\fR/linux\&. If
146 \fIINITRD\-FILE\fRs are provided, it also copies them to
147 $BOOT/\fIENTRY\-TOKEN\fR/\fIKERNEL_VERSION\fR/\fIINITRD\-FILE\fR\&. This can also be used to prepend microcode before the actual initrd\&. It also creates a boot loader entry according to the
148 \m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2
149 (Type #1) in
150 $BOOT/loader/entries/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR\&.conf\&. The title of the entry is the
151 \fIPRETTY_NAME\fR
152 parameter specified in
153 /etc/os\-release
154 or
155 /usr/lib/os\-release
156 (if the former is missing), or "Linux
157 \fIKERNEL\-VERSION\fR", if unset\&.
158 .sp
159 If
160 \fI$KERNEL_INSTALL_LAYOUT\fR
161 is not "bls", this plugin does nothing\&.
162 .RE
163 .sp
164 .RS 4
165 .ie n \{\
166 \h'-04'\(bu\h'+03'\c
167 .\}
168 .el \{\
169 .sp -1
170 .IP \(bu 2.3
171 .\}
172 90\-uki\-copy\&.install
173 copies a file
174 uki\&.efi
175 from
176 \fI$KERNEL_INSTALL_STAGING_AREA\fR
177 or if it does not exist the
178 \fIKERNEL\-IMAGE\fR
179 argument, only if it has a
180 "\&.efi"
181 extension, to
182 $BOOT/EFI/Linux/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR\&.efi\&.
183 .sp
184 If
185 \fI$KERNEL_INSTALL_LAYOUT\fR
186 is not "uki", this plugin does nothing\&.
187 .RE
188 .sp
189 Added in version 198\&.
190 .RE
191 .PP
192 \fBadd\-all\fR
193 .RS 4
194 This is the same as
195 \fBadd\fR
196 (see above), but invokes the operation iteratively for every installed kernel in
197 /usr/lib/modules/\&. This operation is only supported on systems where the kernel image is installed in
198 /usr/lib/modules/\fIKERNEL\-VERSION\fR/vmlinuz\&.
199 .sp
200 Added in version 255\&.
201 .RE
202 .PP
203 \fBremove \fR\fB\fIKERNEL\-VERSION\fR\fR
204 .RS 4
205 This command expects a kernel version string as single argument\&.
206 .sp
207 The executable files from
208 /usr/lib/kernel/install\&.d/*\&.install
209 and
210 /etc/kernel/install\&.d/*\&.install
211 (i\&.e\&. the plugins) are called with the following arguments:
212 .sp
213 .if n \{\
214 .RS 4
215 .\}
216 .nf
217 remove \fIKERNEL\-VERSION\fR $BOOT/\fIENTRY\-TOKEN\fR/\fIKERNEL\-VERSION\fR/
218 .fi
219 .if n \{\
220 .RE
221 .\}
222 .sp
223 Afterwards,
224 \fBkernel\-install\fR
225 removes the entry directory
226 $BOOT/\fIENTRY\-TOKEN\fR/\fIKERNEL\-VERSION\fR/
227 and its contents, if it exists\&.
228 .sp
229 Two default plugins execute the following operations in this case:
230 .sp
231 .RS 4
232 .ie n \{\
233 \h'-04'\(bu\h'+03'\c
234 .\}
235 .el \{\
236 .sp -1
237 .IP \(bu 2.3
238 .\}
239 50\-depmod\&.install
240 removes the files generated by
241 \fBdepmod\fR
242 for this kernel again\&.
243 .RE
244 .sp
245 .RS 4
246 .ie n \{\
247 \h'-04'\(bu\h'+03'\c
248 .\}
249 .el \{\
250 .sp -1
251 .IP \(bu 2.3
252 .\}
253 90\-loaderentry\&.install
254 removes the file
255 $BOOT/loader/entries/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR\&.conf\&.
256 .RE
257 .sp
258 .RS 4
259 .ie n \{\
260 \h'-04'\(bu\h'+03'\c
261 .\}
262 .el \{\
263 .sp -1
264 .IP \(bu 2.3
265 .\}
266 90\-uki\-copy\&.install
267 removes the file
268 $BOOT/EFI/Linux/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR\&.efi\&.
269 .RE
270 .sp
271 Added in version 198\&.
272 .RE
273 .PP
274 \fBinspect [[[\fR\fB\fIKERNEL\-VERSION\fR\fR\fB] \fR\fB\fIKERNEL\-IMAGE\fR\fR\fB] [\fR\fB\fIINITRD\-FILE\fR\fR\fB \&.\&.\&.]]\fR
275 .RS 4
276 Takes the same parameters as
277 \fBadd\fR\&.
278 .sp
279 Shows the various paths and parameters configured or auto\-detected\&. In particular shows the values of the various
280 \fI$KERNEL_INSTALL_*\fR
281 environment variables listed below, as they would be passed to plugins\&. The
282 \fB\-\-json\fR
283 option can be used to get the output of this verb as a JSON object\&.
284 .sp
285 Added in version 251\&.
286 .RE
287 .PP
288 \fBlist\fR
289 .RS 4
290 Shows the various installed kernels\&. This enumerates the subdirectories of
291 /usr/lib/modules/, and shows whether a kernel image is installed there\&.
292 .sp
293 Added in version 255\&.
294 .RE
295 .SH "COMPATIBILITY WITH THE KERNEL BUILD SYSTEM"
296 .HP \w'\fBinstallkernel\fR\ 'u
297 \fBinstallkernel\fR [OPTIONS...] VERSION VMLINUZ [MAP] [INSTALLATION\-DIR]
298 .PP
299 When invoked as
300 \fBinstallkernel\fR, this program accepts arguments as specified by the kernel build system\*(Aqs
301 \fBmake install\fR
302 command\&. The
303 \fIVERSION\fR
304 and
305 \fIVMLINUZ\fR
306 parameters specify the kernel version and the kernel binary\&. The other two parameters (\fIMAP\fR
307 and
308 \fIINSTALLATION\-DIR\fR) are currently ignored\&.
309 .SH "THE \FI$BOOT\FR PARTITION"
310 .PP
311 The partition where the kernels and
312 \m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2
313 snippets are located is called
314 \fI$BOOT\fR\&.
315 \fBkernel\-install\fR
316 determines the location of this partition by checking
317 /efi/,
318 /boot/, and
319 /boot/efi/
320 in turn\&. The first location where
321 $BOOT/loader/entries/
322 or
323 $BOOT/\fIENTRY\-TOKEN\fR/
324 exists is used\&.
325 .SH "OPTIONS"
326 .PP
327 The following options are understood:
328 .PP
329 \fB\-\-esp\-path=\fR
330 .RS 4
331 Path to the EFI System Partition (ESP)\&. If not specified,
332 /efi/,
333 /boot/, and
334 /boot/efi/
335 are checked in turn\&. It is recommended to mount the ESP to
336 /efi/, if possible\&.
337 .RE
338 .PP
339 \fB\-\-boot\-path=\fR
340 .RS 4
341 Path to the Extended Boot Loader partition, as defined in the
342 \m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2\&. If not specified,
343 /boot/
344 is checked\&. It is recommended to mount the Extended Boot Loader partition to
345 /boot/, if possible\&.
346 .RE
347 .PP
348 \fB\-\-make\-entry\-directory=yes|no|auto\fR
349 .RS 4
350 Controls creation and deletion of the
351 \m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2
352 Type #1 entry directory on the file system containing resources such as kernel and initrd images during
353 \fBadd\fR
354 and
355 \fBremove\fR, respectively\&. The directory is named after the entry token, and is placed immediately below the boot root directory\&. When
356 "auto", the directory is created or removed only when the install layout is
357 "bls"\&. Defaults to
358 "auto"\&.
359 .sp
360 Added in version 254\&.
361 .RE
362 .PP
363 \fB\-\-entry\-token=\fR
364 .RS 4
365 Controls how to name and identify boot loader entries for this kernel installation or deletion\&. Takes one of
366 "auto",
367 "machine\-id",
368 "os\-id",
369 "os\-image\-id", or an arbitrary string prefixed by
370 "literal:"
371 as argument\&.
372 .sp
373 If set to
374 \fBmachine\-id\fR
375 the entries are named after the machine ID of the running system (e\&.g\&.
376 "b0e793a9baf14b5fa13ecbe84ff637ac")\&. See
377 \fBmachine-id\fR(5)
378 for details about the machine ID concept and file\&.
379 .sp
380 If set to
381 \fBos\-id\fR
382 the entries are named after the OS ID of the running system, i\&.e\&. the
383 \fIID=\fR
384 field of
385 \fBos-release\fR(5)
386 (e\&.g\&.
387 "fedora")\&. Similarly, if set to
388 \fBos\-image\-id\fR
389 the entries are named after the OS image ID of the running system, i\&.e\&. the
390 \fIIMAGE_ID=\fR
391 field of
392 os\-release
393 (e\&.g\&.
394 "vendorx\-cashier\-system")\&.
395 .sp
396 If set to
397 \fBauto\fR
398 (the default), the
399 /etc/kernel/entry\-token
400 (or
401 $KERNEL_INSTALL_CONF_ROOT/entry\-token) file will be read if it exists, and the stored value used\&. Otherwise, if the local machine ID is initialized, it is used\&. Otherwise,
402 \fIIMAGE_ID=\fR
403 from
404 os\-release
405 will be used, if set\&. Otherwise,
406 \fIID=\fR
407 from
408 os\-release
409 will be used, if set\&. Otherwise, a randomly generated machine ID is used\&.
410 .sp
411 Using the machine ID for naming the entries is generally preferable, however there are cases where using the other identifiers is a good option\&. Specifically: if the identification data that the machine ID entails shall not be stored on the (unencrypted)
412 \fI$BOOT_ROOT\fR
413 partition, or if the ID shall be generated on first boot and is not known when the entries are prepared\&. Note that using the machine ID has the benefit that multiple parallel installations of the same OS can coexist on the same medium, and they can update their boot loader entries independently\&. When using another identifier (such as the OS ID or the OS image ID), parallel installations of the same OS would try to use the same entry name\&. To support parallel installations, the installer must use a different entry token when adding a second installation\&.
414 .sp
415 Added in version 254\&.
416 .RE
417 .PP
418 \fB\-v\fR, \fB\-\-verbose\fR
419 .RS 4
420 Output additional information about operations being performed\&.
421 .sp
422 Added in version 242\&.
423 .RE
424 .PP
425 \fB\-\-root=\fR\fB\fIroot\fR\fR
426 .RS 4
427 Takes a directory path as an argument\&. All paths will be prefixed with the given alternate
428 \fIroot\fR
429 path, including config search paths\&. This is useful to operate on a system image mounted to the specified directory instead of the host system itself\&.
430 .sp
431 Added in version 255\&.
432 .RE
433 .PP
434 \fB\-\-image=\fR\fB\fIimage\fR\fR
435 .RS 4
436 Takes a path to a disk image file or block device node\&. If specified, all operations are applied to the file system in the indicated disk image\&. This option is similar to
437 \fB\-\-root=\fR, but operates on file systems stored in disk images or block devices\&. The disk image should either contain just a file system or a set of file systems within a GPT partition table, following the
438 \m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[3]\d\s+2\&. For further information on supported disk images, see
439 \fBsystemd-nspawn\fR(1)\*(Aqs switch of the same name\&.
440 .sp
441 Added in version 255\&.
442 .RE
443 .PP
444 \fB\-h\fR, \fB\-\-help\fR
445 .RS 4
446 Print a short help text and exit\&.
447 .RE
448 .PP
449 \fB\-\-version\fR
450 .RS 4
451 Print a short version string and exit\&.
452 .RE
453 .PP
454 \fB\-\-no\-pager\fR
455 .RS 4
456 Do not pipe output into a pager\&.
457 .RE
458 .PP
459 \fB\-\-json=\fR\fB\fIMODE\fR\fR
460 .RS 4
461 Shows output formatted as JSON\&. Expects one of
462 "short"
463 (for the shortest possible output without any redundant whitespace or line breaks),
464 "pretty"
465 (for a pretty version of the same, with indentation and line breaks) or
466 "off"
467 (to turn off JSON output, the default)\&.
468 .RE
469 .PP
470 \fB\-\-image\-policy=\fR\fB\fIpolicy\fR\fR
471 .RS 4
472 Takes an image policy string as argument, as per
473 \fBsystemd.image-policy\fR(7)\&. The policy is enforced when operating on the disk image specified via
474 \fB\-\-image=\fR, see above\&. If not specified, defaults to the
475 "*"
476 policy, i\&.e\&. all recognized file systems in the image are used\&.
477 .RE
478 .PP
479 \fB\-\-no\-legend\fR
480 .RS 4
481 Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
482 .RE
483 .SH "ENVIRONMENT VARIABLES"
484 .SS "Environment variables exported for plugins"
485 .PP
486 If
487 \fB\-\-verbose\fR
488 is used,
489 \fI$KERNEL_INSTALL_VERBOSE=1\fR
490 will be exported for plugins\&. They may output additional logs in this case\&.
491 .PP
492 \fI$KERNEL_INSTALL_IMAGE_TYPE=uki|pe|unknown\fR
493 is set for the plugins to specify the type of the kernel image\&.
494 .PP
495 uki
496 .RS 4
497 Unified kernel image\&.
498 .sp
499 Added in version 254\&.
500 .RE
501 .PP
502 pe
503 .RS 4
504 PE binary\&.
505 .sp
506 Added in version 254\&.
507 .RE
508 .PP
509 unknown
510 .RS 4
511 Unknown type\&.
512 .sp
513 Added in version 254\&.
514 .RE
515 .PP
516 \fI$KERNEL_INSTALL_MACHINE_ID\fR
517 is set for the plugins to the desired machine\-id to use\&. It\*(Aqs always a 128\-bit ID\&. Normally it is read from
518 /etc/machine\-id, but it can also be overridden via
519 \fI$MACHINE_ID\fR
520 (see below)\&. If not specified via these methods, a fallback value will generated by
521 \fBkernel\-install\fR
522 and used only for a single invocation\&.
523 .PP
524 \fI$KERNEL_INSTALL_ENTRY_TOKEN\fR
525 is set for the plugins to the desired entry "token" to use\&. It\*(Aqs an identifier that shall be used to identify the local installation, and is often the machine ID, i\&.e\&. same as
526 \fI$KERNEL_INSTALL_MACHINE_ID\fR, but might also be a different type of identifier, for example a fixed string or the
527 \fIID=\fR,
528 \fIIMAGE_ID=\fR
529 values from
530 /etc/os\-release\&. The string passed here will be used to name Boot Loader Specification entries, or the directories the kernel image and initial RAM disk images are placed into\&.
531 .PP
532 Note that while
533 \fI$KERNEL_INSTALL_ENTRY_TOKEN\fR
534 and
535 \fI$KERNEL_INSTALL_MACHINE_ID\fR
536 are often set to the same value, the latter is guaranteed to be a valid 32 character ID in lowercase hexadecimals while the former can be any short string\&. The entry token to use is read from
537 /etc/kernel/entry\-token, if it exists\&. Otherwise, a few possible candidates below
538 \fI$BOOT\fR
539 are checked for Boot Loader Specification Type 1 entry directories, and if found the entry token is derived from that\&. If that is not successful,
540 \fI$KERNEL_INSTALL_MACHINE_ID\fR
541 is used as fallback\&.
542 .PP
543 \fI$KERNEL_INSTALL_BOOT_ROOT\fR
544 is set for the plugins to the absolute path of the root directory (mount point, usually) of the hierarchy where boot loader entries, kernel images, and associated resources should be placed\&. This usually is the path where the XBOOTLDR partition or the ESP (EFI System Partition) are mounted, and also conceptually referred to as
545 \fI$BOOT\fR\&. Can be overridden by setting
546 \fI$BOOT_ROOT\fR
547 (see below)\&.
548 .PP
549 \fI$KERNEL_INSTALL_LAYOUT=auto|bls|uki|other|\&.\&.\&.\fR
550 is set for the plugins to specify the installation layout\&. Additional layout names may be defined by convention\&. If a plugin uses a special layout, it is encouraged to declare its own layout name and configure
551 \fIlayout=\fR
552 in
553 install\&.conf
554 upon initial installation\&. The following values are currently understood:
555 .PP
556 bls
557 .RS 4
558 Standard
559 \m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2
560 Type #1 layout, compatible with
561 \fBsystemd-boot\fR(7): entries in
562 $BOOT/loader/entries/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR[+\fITRIES\fR]\&.conf, kernel and initrds under
563 $BOOT/\fIENTRY\-TOKEN\fR/\fIKERNEL\-VERSION\fR/
564 .sp
565 Implemented by
566 90\-loaderentry\&.install\&.
567 .sp
568 Added in version 250\&.
569 .RE
570 .PP
571 uki
572 .RS 4
573 Standard
574 \m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2
575 Type #2 layout, compatible with
576 \fBsystemd-boot\fR(7): unified kernel images under
577 $BOOT/EFI/Linux
578 as
579 $BOOT/EFI/Linux/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR[+\fITRIES\fR]\&.efi\&.
580 .sp
581 Implemented by
582 90\-uki\-copy\&.install\&.
583 .sp
584 Added in version 253\&.
585 .RE
586 .PP
587 other
588 .RS 4
589 Some other layout not understood natively by
590 \fBkernel\-install\fR\&.
591 .sp
592 Added in version 250\&.
593 .RE
594 .PP
595 auto
596 .RS 4
597 Pick the layout automatically\&. If the kernel is a UKI set layout to
598 \fBuki\fR\&. If not default to
599 \fBbls\fR
600 if
601 $BOOT/loader/entries\&.srel
602 with content
603 "type1"
604 or
605 $BOOT/\fIENTRY\-TOKEN\fR
606 exists, or
607 \fBother\fR
608 otherwise\&.
609 .sp
610 Leaving layout blank has the same effect\&. This is the default\&.
611 .sp
612 Added in version 254\&.
613 .RE
614 .PP
615 \fI$KERNEL_INSTALL_INITRD_GENERATOR\fR
616 and
617 \fI$KERNEL_INSTALL_UKI_GENERATOR\fR
618 are set for plugins to select the initrd and/or UKI generator\&. This may be configured as
619 \fIinitrd_generator=\fR
620 and
621 \fIuki_generator=\fR
622 in
623 install\&.conf, see below\&.
624 .PP
625 \fI$KERNEL_INSTALL_STAGING_AREA\fR
626 is set for plugins to a path to a directory\&. Plugins may drop files in that directory, and they will be installed as part of the loader entry, based on the file name and extension: Files named
627 initrd*
628 will be installed as
629 \fIINITRD\-FILE\fRs, and files named
630 microcode*
631 will be prepended before
632 \fIINITRD\-FILE\fRs\&.
633 .SS "Environment variables understood by kernel\-install"
634 .PP
635 \fI$KERNEL_INSTALL_CONF_ROOT\fR
636 can be set to override the location of the configuration files read by
637 \fBkernel\-install\fR\&. When set,
638 install\&.conf,
639 entry\-token, and other files will be read from this directory only\&. Note that this path is relative to the host, and in particular
640 \fIsymlinks in this directory are resolved relative to the host\fR, even if
641 \fB\-\-root=\fR\fB\fIroot\fR\fR
642 is used\&. This means that it is generally
643 \fInot\fR
644 correct to use this variable to specify a directory underneath
645 \fIroot\fR
646 if symlinks are used there\&.
647 .PP
648 \fI$KERNEL_INSTALL_PLUGINS\fR
649 can be set to override the list of plugins executed by
650 \fBkernel\-install\fR\&. The argument is a whitespace\-separated list of paths\&.
651 "KERNEL_INSTALL_PLUGINS=:"
652 may be used to prevent any plugins from running\&.
653 .PP
654 \fI$MACHINE_ID\fR
655 can be set for
656 \fBkernel\-install\fR
657 to override
658 \fI$KERNEL_INSTALL_MACHINE_ID\fR, the machine ID\&.
659 .PP
660 \fI$BOOT_ROOT\fR
661 can be set for
662 \fBkernel\-install\fR
663 to override
664 \fI$KERNEL_INSTALL_BOOT_ROOT\fR, the installation location for boot entries\&.
665 .PP
666 The last two variables may also be set in
667 install\&.conf\&. Variables set in the environment take precedence over the values specified in the config file\&.
668 .SH "EXIT STATUS"
669 .PP
670 If every executable returns 0 or 77, 0 is returned, and a non\-zero failure code otherwise\&.
671 .SH "FILES"
672 .PP
673 /etc/kernel/install\&.d/*\&.install, /usr/lib/kernel/install\&.d/*\&.install
674 .RS 4
675 Drop\-in files which are executed by
676 \fBkernel\-install\fR\&.
677 .sp
678 Added in version 198\&.
679 .RE
680 .PP
681 /etc/kernel/cmdline, /usr/lib/kernel/cmdline, /proc/cmdline
682 .RS 4
683 Specifies the kernel command line to use\&. The first of the files that is found will be used\&. When running in a container,
684 /proc/cmdline
685 is ignored\&.
686 \fI$KERNEL_INSTALL_CONF_ROOT\fR
687 may be used to override the search path; see below for details\&.
688 .sp
689 Added in version 198\&.
690 .RE
691 .PP
692 /etc/kernel/devicetree, /usr/lib/kernel/devicetree
693 .RS 4
694 Specifies the partial path to the file containing the device tree blob to install with the kernel and use at boot\&. The first of the files that is found will be used\&.
695 \fI$KERNEL_INSTALL_CONF_ROOT\fR
696 may be used to override the search path; see below for details\&.
697 .sp
698 The
699 devicetree
700 file contains a path, and this path specifies a location relative to the kernel install tree\&. A set of locations is checked, including in particular
701 /usr/lib/modules/\fIKERNEL_VERSION\fR/dtb/, which is the recommended location to place the dtb files under\&. For example, with
702 "broadcom/bcm2711\-rpi\-4\-b\&.dtb"
703 in the
704 devicetree
705 file, the device tree blob for the Raspberry Pi 4 Model B would be installed, and the actual file would be
706 /usr/lib/modules/\fIKERNEL_VERSION\fR/dtb/broadcom/bcm2711\-rpi\-4\-b\&.dtb\&.
707 .sp
708 Added in version 255\&.
709 .RE
710 .PP
711 /etc/kernel/tries
712 .RS 4
713 Read by
714 90\-loaderentry\&.install
715 and
716 90\-uki\-copy\&.install\&. If this file exists, a numeric value is read from it and the naming of the generated entry file or UKI is altered to include it as
717 $BOOT/loader/entries/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR+\fITRIES\fR\&.conf
718 or
719 $BOOT/EFI/Linux/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR+\fITRIES\fR\&.efi, respectively\&. This is useful for boot loaders such as
720 \fBsystemd-boot\fR(7)
721 which implement boot attempt counting with a counter embedded in the entry file name\&.
722 \fI$KERNEL_INSTALL_CONF_ROOT\fR
723 may be used to override the search path; see below for details\&.
724 .sp
725 Added in version 240\&.
726 .RE
727 .PP
728 /etc/kernel/entry\-token
729 .RS 4
730 If this file exists it is read and used as "entry token" for this system, i\&.e\&. is used for naming Boot Loader Specification entries\&. See
731 \fI$KERNEL_INSTALL_ENTRY_TOKEN\fR
732 above for details\&.
733 \fI$KERNEL_INSTALL_CONF_ROOT\fR
734 may be used to override the search path; see below for details\&.
735 .sp
736 Added in version 251\&.
737 .RE
738 .PP
739 /etc/machine\-id
740 .RS 4
741 The content of this file specifies the machine identification
742 \fIMACHINE\-ID\fR\&.
743 .sp
744 Added in version 198\&.
745 .RE
746 .PP
747 /etc/os\-release, /usr/lib/os\-release
748 .RS 4
749 Read by
750 90\-loaderentry\&.install\&. If available,
751 \fIPRETTY_NAME=\fR
752 is read from these files and used as the title of the boot menu entry\&. Otherwise,
753 "Linux \fIKERNEL\-VERSION\fR"
754 will be used\&.
755 .sp
756 Added in version 198\&.
757 .RE
758 .PP
759 /etc/kernel/install\&.conf, /run/kernel/install\&.conf, /usr/local/lib/kernel/install\&.conf, /usr/lib/kernel/install\&.conf, /etc/kernel/install\&.conf\&.d/*\&.conf, /run/kernel/install\&.conf\&.d/*\&.conf, /usr/local/lib/kernel/install\&.conf\&.d/*\&.conf, /usr/lib/kernel/install\&.conf\&.d/*\&.conf
760 .RS 4
761 Configuration file with options for
762 \fBkernel\-install\fR, as a series of
763 \fIKEY=\fR\fIVALUE\fR
764 assignments, compatible with shell syntax, following the same rules as described in
765 \fBos-release\fR(5)\&. The first of the files that is found will be used\&.
766 \fI$KERNEL_INSTALL_CONF_ROOT\fR
767 may be used to override the search path; see below for details\&. Drop\-in files may also be used to extend the configuration with overrides, see
768 \fBsystemd.unit\fR(5)\&.
769 .sp
770 Currently, the following keys are supported:
771 \fIMACHINE_ID=\fR,
772 \fIBOOT_ROOT=\fR,
773 \fIlayout=\fR,
774 \fIinitrd_generator=\fR,
775 \fIuki_generator=\fR\&. See the Environment variables section above for details\&.
776 .sp
777 Added in version 250\&.
778 .RE
779 .PP
780 /etc/kernel/uki\&.conf
781 .RS 4
782 Ini\-style configuration file for
783 \fBukify\fR(1)
784 which is only effective when
785 \fI$KERNEL_INSTALL_LAYOUT\fR
786 or
787 \fIlayout=\fR
788 in
789 install\&.conf
790 is set to
791 \fBuki\fR
792 and
793 \fI$KERNEL_INSTALL_UKI_GENERATOR\fR
794 or
795 \fIuki_generator=\fR
796 in
797 install\&.conf
798 is set to
799 \fBukify\fR, or is unset\&.
800 \fI$KERNEL_INSTALL_CONF_ROOT\fR
801 may be used to override the search path; see below for details\&.
802 .sp
803 Added in version 255\&.
804 .RE
805 .PP
806 /usr/lib/modules/\fIKERNEL\-VERSION/\fR
807 .RS 4
808 Location for installed kernel modules and other kernel related resources\&. For each locally installed kernel a directory named after the kernel version (\fBuname \-r\fR) is kept\&.
809 .sp
810 Added in version 255\&.
811 .RE
812 .PP
813 /usr/lib/modules/\fIKERNEL\-VERSION/vmlinuz\fR
814 .RS 4
815 Location for installed kernel images\&. This is the recommended location for OS package managers to install kernel images into (as applicable), from which
816 \fBkernel\-install add\fR
817 then copies it into the final boot partition\&.
818 .sp
819 Added in version 255\&.
820 .RE
821 .PP
822 For various cases listed above, if the
823 \fI$KERNEL_INSTALL_CONF_ROOT\fR
824 environment variable is set, it will override the search path\&. The files will be loaded
825 \fIonly\fR
826 from the directory specified by the environment variable\&. When the variable is not set, the listed paths are tried in turn, and the first file that exists is used\&.
827 .SH "SEE ALSO"
828 .PP
829 \fBmachine-id\fR(5), \fBos-release\fR(5), \fBdepmod\fR(8), \fBsystemd-boot\fR(7), \fBukify\fR(1), \m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2
830 .SH "NOTES"
831 .IP " 1." 4
832 Nowadays actually CPIO archives used as an "initramfs", rather than "initrd". See
833 \fBbootup\fR(7)
834 for an explanation.
835 .IP " 2." 4
836 Boot Loader Specification
837 .RS 4
838 \%https://uapi-group.org/specifications/specs/boot_loader_specification
839 .RE
840 .IP " 3." 4
841 Discoverable Partitions Specification
842 .RS 4
843 \%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
844 .RE