Debian Codegraph @

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

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