1KERNEL-INSTALL(8) kernel-install KERNEL-INSTALL(8)
2
6 kernel-install - Add and remove kernel and initrd images to and from
7 /boot
8
10 kernel-install [OPTIONS...] add KERNEL-VERSION KERNEL-IMAGE
11 [INITRD-FILE...]
12 kernel-install [OPTIONS...] remove KERNEL-VERSION
14 kernel-install [OPTIONS...] inspect [KERNEL-IMAGE]
16
18 kernel-install is used to install and remove kernel and initrd images
19 [1] to and from the boot loader partition, referred to as $BOOT here.
20 It will usually be one of /boot/, /efi/, or /boot/efi/, see below.
21 kernel-install will run the executable files ("plugins") located in the
23 directory /usr/lib/kernel/install.d/ and the local administration
24 directory /etc/kernel/install.d/. All files are collectively sorted and
25 executed in lexical order, regardless of the directory in which they
26 live. However, files with identical filenames replace each other. Files
27 in /etc/kernel/install.d/ take precedence over files with the same name
28 in /usr/lib/kernel/install.d/. This can be used to override a
29 system-supplied executables with a local file if needed; a symbolic
30 link in /etc/kernel/install.d/ with the same name as an executable in
31 /usr/lib/kernel/install.d/, pointing to /dev/null, disables the
32 executable entirely. Executables must have the extension ".install";
33 other extensions are ignored.
34 An executable placed in these directories should return 0 on success.
36 It may also return 77 to cause the whole operation to terminate
37 (executables later in lexical order will be skipped).
38
40 The following commands are understood:
41 add KERNEL-VERSION KERNEL-IMAGE [INITRD-FILE ...]
43 This command expects a kernel version string and a path to a kernel
44 image file as arguments. Optionally, one or more initrd images may
45 be specified as well (note that plugins might generate additional
46 ones). kernel-install calls the executable files from
47 /usr/lib/kernel/install.d/*.install and
48 /etc/kernel/install.d/*.install (i.e. the plugins) with the
49 following arguments:
50 add KERNEL-VERSION $BOOT/ENTRY-TOKEN/KERNEL-VERSION/ KERNEL-IMAGE [INITRD-FILE ...]
52 The third argument directly refers to the path where to place
54 kernel images, initrd images and other resources for Boot Loader
55 Specification[2] Type #1 entries (the "entry directory"). If other
56 boot loader schemes are used the parameter may be ignored. The
57 ENTRY-TOKEN string is typically the machine ID and is supposed to
58 identify the local installation on the system. For details see
59 below.
60 Two default plugins execute the following operations in this case:
62 • kernel-install creates $BOOT/ENTRY-TOKEN/KERNEL-VERSION, if
64 enabled (see $KERNEL_INSTALL_LAYOUT).
65 • 50-depmod.install runs depmod(8) for the KERNEL-VERSION.
67 • 90-loaderentry.install copies KERNEL-IMAGE to
69 $BOOT/ENTRY-TOKEN/KERNEL-VERSION/linux. If INITRD-FILEs are
70 provided, it also copies them to
71 $BOOT/ENTRY-TOKEN/KERNEL_VERSION/INITRD-FILE. This can also be
72 used to prepend microcode before the actual initrd. It also
73 creates a boot loader entry according to the Boot Loader
74 Specification[2] (Type #1) in
75 $BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION.conf. The title
76 of the entry is the PRETTY_NAME parameter specified in
77 /etc/os-release or /usr/lib/os-release (if the former is
78 missing), or "Linux KERNEL-VERSION", if unset.
79 If $KERNEL_INSTALL_LAYOUT is not "bls", this plugin does
81 nothing.
82 • 90-uki-copy.install copies a file uki.efi from
84 $KERNEL_INSTALL_STAGING_AREA or if it does not exist the
85 KERNEL-IMAGE argument, only if it has a ".efi" extension, to
86 $BOOT/EFI/Linux/ENTRY-TOKEN-KERNEL-VERSION.efi.
87 If $KERNEL_INSTALL_LAYOUT is not "uki", this plugin does
89 nothing.
90 remove KERNEL-VERSION
92 This command expects a kernel version string as single argument.
93 This calls executables from /usr/lib/kernel/install.d/*.install and
94 /etc/kernel/install.d/*.install with the following arguments:
95 remove KERNEL-VERSION $BOOT/ENTRY-TOKEN/KERNEL-VERSION/
97 Afterwards, kernel-install removes the entry directory
99 $BOOT/ENTRY-TOKEN/KERNEL-VERSION/ and its contents, if it exists.
100 Two default plugins execute the following operations in this case:
102 • 50-depmod.install removes the files generated by depmod for
104 this kernel again.
105 • 90-loaderentry.install removes the file
107 $BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION.conf.
108 • 90-uki-copy.install removes the file
110 $BOOT/EFI/Linux/ENTRY-TOKEN-KERNEL-VERSION.efi.
111 inspect [KERNEL-IMAGE]
113 Shows the various paths and parameters configured or auto-detected.
114 In particular shows the values of the various $KERNEL_INSTALL_*
115 environment variables listed below.
116
118 installkernel [OPTIONS...] VERSION VMLINUZ [MAP] [INSTALLATION-DIR]
119 When invoked as installkernel, this program accepts arguments as
121 specified by the kernel build system's make install command. The
122 VERSION and VMLINUZ parameters specify the kernel version and the
123 kernel binary. The other two parameters (MAP and INSTALLATION-DIR) are
124 currently ignored.
125
127 The partition where the kernels and Boot Loader Specification[2]
128 snippets are located is called $BOOT. kernel-install determines the
129 location of this partition by checking /efi/, /boot/, and /boot/efi/ in
130 turn. The first location where $BOOT/loader/entries/ or
131 $BOOT/ENTRY-TOKEN/ exists is used.
132
134 The following options are understood:
135 --esp-path=
137 Path to the EFI System Partition (ESP). If not specified, /efi/,
138 /boot/, and /boot/efi/ are checked in turn. It is recommended to
139 mount the ESP to /efi/, if possible.
140 --boot-path=
142 Path to the Extended Boot Loader partition, as defined in the Boot
143 Loader Specification[2]. If not specified, /boot/ is checked. It is
144 recommended to mount the Extended Boot Loader partition to /boot/,
145 if possible.
146 --make-entry-directory=yes|no|auto
148 Controls creation and deletion of the Boot Loader Specification[2]
149 Type #1 entry directory on the file system containing resources
150 such as kernel and initrd images during add and remove,
151 respectively. The directory is named after the entry token, and is
152 placed immediately below the boot root directory. When "auto", the
153 directory is created or removed only when the install layout is
154 "bls". Defaults to "auto".
155 --entry-token=
157 Controls how to name and identify boot loader entries for this
158 kernel installation or deletion. Takes one of "auto", "machine-id",
159 "os-id", "os-image-id", or an arbitrary string prefixed by
160 "literal:" as argument.
161 If set to machine-id the entries are named after the machine ID of
163 the running system (e.g. "b0e793a9baf14b5fa13ecbe84ff637ac"). See
164 machine-id(5) for details about the machine ID concept and file.
165 If set to os-id the entries are named after the OS ID of the
167 running system, i.e. the ID= field of os-release(5) (e.g.
168 "fedora"). Similarly, if set to os-image-id the entries are named
169 after the OS image ID of the running system, i.e. the IMAGE_ID=
170 field of os-release (e.g. "vendorx-cashier-system").
171 If set to auto (the default), the /etc/kernel/entry-token (or
173 $KERNEL_INSTALL_CONF_ROOT/entry-token) file will be read if it
174 exists, and the stored value used. Otherwise if the local machine
175 ID is initialized it is used. Otherwise IMAGE_ID= from os-release
176 will be used, if set. Otherwise, ID= from os-release will be used,
177 if set. Otherwise a randomly generated machine ID is used.
178 Using the machine ID for naming the entries is generally
180 preferable, however there are cases where using the other
181 identifiers is a good option. Specifically: if the identification
182 data that the machine ID entails shall not be stored on the
183 (unencrypted) $BOOT_ROOT partition, or if the ID shall be generated
184 on first boot and is not known when the entries are prepared. Note
185 that using the machine ID has the benefit that multiple parallel
186 installations of the same OS can coexist on the same medium, and
187 they can update their boot loader entries independently. When using
188 another identifier (such as the OS ID or the OS image ID), parallel
189 installations of the same OS would try to use the same entry name.
190 To support parallel installations, the installer must use a
191 different entry token when adding a second installation.
192 -v, --verbose
194 Output additional information about operations being performed.
195 -h, --help
197 Print a short help text and exit.
198 --version
200 Print a short version string and exit.
201
203 Environment variables exported for plugins
204 If --verbose is used, $KERNEL_INSTALL_VERBOSE=1 will be exported for
205 plugins. They may output additional logs in this case.
206 $KERNEL_INSTALL_IMAGE_TYPE=uki|pe|unknown is set for the plugins to
208 specify the type of the kernel image.
209 uki
211 Unified kernel image.
212 pe
214 PE binary.
215 unknown
217 Unknown type.
218 $KERNEL_INSTALL_MACHINE_ID is set for the plugins to the desired
220 machine-id to use. It's always a 128-bit ID. Normally it's read from
221 /etc/machine-id, but it can also be overridden via $MACHINE_ID (see
222 below). If not specified via these methods, a fallback value will
223 generated by kernel-install and used only for a single invocation.
224 $KERNEL_INSTALL_ENTRY_TOKEN is set for the plugins to the desired entry
226 "token" to use. It's an identifier that shall be used to identify the
227 local installation, and is often the machine ID, i.e. same as
228 $KERNEL_INSTALL_MACHINE_ID, but might also be a different type of
229 identifier, for example a fixed string or the ID=, IMAGE_ID= values
230 from /etc/os-release. The string passed here will be used to name Boot
231 Loader Specification entries, or the directories the kernel image and
232 initial RAM disk images are placed into.
233 Note that while $KERNEL_INSTALL_ENTRY_TOKEN and
235 $KERNEL_INSTALL_MACHINE_ID are often set to the same value, the latter
236 is guaranteed to be a valid 32 character ID in lowercase hexadecimals
237 while the former can be any short string. The entry token to use is
238 read from /etc/kernel/entry-token, if it exists. Otherwise a few
239 possible candidates below $BOOT are checked for Boot Loader
240 Specification Type 1 entry directories, and if found the entry token is
241 derived from that. If that is not successful,
242 $KERNEL_INSTALL_MACHINE_ID is used as fallback.
243 $KERNEL_INSTALL_BOOT_ROOT is set for the plugins to the absolute path
245 of the root directory (mount point, usually) of the hierarchy where
246 boot loader entries, kernel images, and associated resources should be
247 placed. This usually is the path where the XBOOTLDR partition or the
248 ESP (EFI System Partition) are mounted, and also conceptually referred
249 to as $BOOT. Can be overridden by setting $BOOT_ROOT (see below).
250 $KERNEL_INSTALL_LAYOUT=auto|bls|uki|other|... is set for the plugins
252 to specify the installation layout. Additional layout names may be
253 defined by convention. If a plugin uses a special layout, it's
254 encouraged to declare its own layout name and configure layout= in
255 install.conf upon initial installation. The following values are
256 currently understood:
257 bls
259 Standard Boot Loader Specification[2] Type #1 layout, compatible
260 with systemd-boot(7): entries in
261 $BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION[+TRIES].conf,
262 kernel and initrds under $BOOT/ENTRY-TOKEN/KERNEL-VERSION/
263 Implemented by 90-loaderentry.install.
265 uki
267 Standard Boot Loader Specification[2] Type #2 layout, compatible
268 with systemd-boot(7): unified kernel images under $BOOT/EFI/Linux
269 as $BOOT/EFI/Linux/ENTRY-TOKEN-KERNEL-VERSION[+TRIES].efi.
270 Implemented by 90-uki-copy.install.
272 other
274 Some other layout not understood natively by kernel-install.
275 auto
277 Pick the layout automatically. If the kernel is a UKI set layout to
278 uki. If not default to bls if $BOOT/loader/entries.srel with
279 content "type1" or $BOOT/ENTRY-TOKEN exists, or other otherwise.
280 Leaving layout blank has the same effect. This is the default.
282 $KERNEL_INSTALL_INITRD_GENERATOR and $KERNEL_INSTALL_UKI_GENERATOR are
284 set for plugins to select the initrd and/or UKI generator. This may be
285 configured as initrd_generator= and uki_generator= in install.conf, see
286 below.
287 $KERNEL_INSTALL_STAGING_AREA is set for plugins to a path to a
289 directory. Plugins may drop files in that directory, and they will be
290 installed as part of the loader entry, based on the file name and
291 extension: Files named initrd* will be installed as INITRD-FILEs, and
292 files named microcode* will be prepended before INITRD-FILEs.
293 Environment variables understood by kernel-install
295 $KERNEL_INSTALL_CONF_ROOT can be set to override the location of the
296 configuration files read by kernel-install. When set, install.conf,
297 entry-token, and other files will be read from this directory.
298 $KERNEL_INSTALL_PLUGINS can be set to override the list of plugins
300 executed by kernel-install. The argument is a whitespace-separated list
301 of paths. "KERNEL_INSTALL_PLUGINS=:" may be used to prevent any
302 plugins from running.
303 $MACHINE_ID can be set for kernel-install to override
305 $KERNEL_INSTALL_MACHINE_ID, the machine ID.
306 $BOOT_ROOT can be set for kernel-install to override
308 $KERNEL_INSTALL_BOOT_ROOT, the installation location for boot entries.
309 The last two variables may also be set in install.conf. Variables set
311 in the environment take precedence over the values specified in the
312 config file.
313
315 If every executable returns 0 or 77, 0 is returned, and a non-zero
316 failure code otherwise.
317
319 /usr/lib/kernel/install.d/*.install /etc/kernel/install.d/*.install
320 Drop-in files which are executed by kernel-install.
321 /usr/lib/kernel/cmdline /etc/kernel/cmdline /proc/cmdline
323 Read by 90-loaderentry.install. The content of the file
324 /etc/kernel/cmdline specifies the kernel command line to use. If
325 that file does not exist, /usr/lib/kernel/cmdline is used. If that
326 also does not exist, /proc/cmdline is used.
327 $KERNEL_INSTALL_CONF_ROOT may be used to override the path.
328 /etc/kernel/tries
330 Read by 90-loaderentry.install and 90-uki-copy.install. If this
331 file exists a numeric value is read from it and the naming of the
332 generated entry file or UKI is slightly altered to include it as
333 $BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION+TRIES.conf or
334 $BOOT/EFI/Linux/ENTRY-TOKEN-KERNEL-VERSION+TRIES.efi, respectively.
335 This is useful for boot loaders such as systemd-boot(7) which
336 implement boot attempt counting with a counter embedded in the
337 entry file name. $KERNEL_INSTALL_CONF_ROOT may be used to override
338 the path.
339 /etc/kernel/entry-token
341 If this file exists it is read and used as "entry token" for this
342 system, i.e. is used for naming Boot Loader Specification entries,
343 see $KERNEL_INSTALL_ENTRY_TOKEN above for details.
344 $KERNEL_INSTALL_CONF_ROOT may be used to override the path.
345 /etc/machine-id
347 The content of this file specifies the machine identification
348 MACHINE-ID.
349 /etc/os-release /usr/lib/os-release
351 Read by 90-loaderentry.install. If available, PRETTY_NAME= is read
352 from these files and used as the title of the boot menu entry.
353 Otherwise, "Linux KERNEL-VERSION" will be used.
354 /usr/lib/kernel/install.conf /etc/kernel/install.conf
356 Configuration options for kernel-install, as a series of KEY=VALUE
357 assignments, compatible with shell syntax, following the same rules
358 as described in os-release(5). /etc/kernel/install.conf will be
359 read if present, and /usr/lib/kernel/install.conf otherwise. This
360 file is optional. $KERNEL_INSTALL_CONF_ROOT may be used to
361 override the path.
362 Currently, the following keys are supported: MACHINE_ID=,
364 BOOT_ROOT=, layout=, initrd_generator=, uki_generator=. See the
365 Environment variables section above for details.
366 /etc/kernel/uki.conf
368 Ini-style configuration file for ukify(1) which is only effective
369 when $KERNEL_INSTALL_LAYOUT or layout= in install.conf is set to
370 uki and $KERNEL_INSTALL_UKI_GENERATOR or uki_generator= in
371 install.conf is set to ukify. $KERNEL_INSTALL_CONF_ROOT may be
372 used to override the path.
373
375 machine-id(5), os-release(5), depmod(8), systemd-boot(7), ukify(1),
376 Boot Loader Specification[2]
377
379 1. Nowadays actually CPIO archives used as an "initramfs", rather than
380 "initrd". See bootup(7) for an explanation.
381 2. Boot Loader Specification
383 https://uapi-group.org/specifications/specs/boot_loader_specification
384systemd 254 KERNEL-INSTALL(8)