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...] COMMAND KERNEL-VERSION KERNEL-IMAGE
11 [INITRD-FILE...]
12
14 kernel-install is used to install and remove kernel and initrd images
15 [1] to and from the boot loader partition, referred to as $BOOT here.
16 It will usually be one of /boot/, /efi/, or /boot/efi/, see below.
17 kernel-install will run the executable files ("plugins") located in the
19 directory /usr/lib/kernel/install.d/ and the local administration
20 directory /etc/kernel/install.d/. All files are collectively sorted and
21 executed in lexical order, regardless of the directory in which they
22 live. However, files with identical filenames replace each other. Files
23 in /etc/kernel/install.d/ take precedence over files with the same name
24 in /usr/lib/kernel/install.d/. This can be used to override a
25 system-supplied executables with a local file if needed; a symbolic
26 link in /etc/kernel/install.d/ with the same name as an executable in
27 /usr/lib/kernel/install.d/, pointing to /dev/null, disables the
28 executable entirely. Executables must have the extension ".install";
29 other extensions are ignored.
30 An executable placed in these directories should return 0 on success.
32 It may also return 77 to cause the whole operation to terminate
33 (executables later in lexical order will be skipped).
34
36 The following commands are understood:
37 add KERNEL-VERSION KERNEL-IMAGE [INITRD-FILE ...]
39 This command expects a kernel version string and a path to a kernel
40 image file as arguments. Optionally, one or more initrd images may
41 be specified as well (note that plugins might generate additional
42 ones). kernel-install calls the executable files from
43 /usr/lib/kernel/install.d/*.install and
44 /etc/kernel/install.d/*.install (i.e. the plugins) with the
45 following arguments:
46 add KERNEL-VERSION $BOOT/ENTRY-TOKEN/KERNEL-VERSION/ KERNEL-IMAGE [INITRD-FILE ...]
48 The third argument directly refers to the path where to place
50 kernel images, initrd images and other resources for Boot Loader
51 Specification[2] Type #1 entries (the "entry directory"). If other
52 boot loader schemes are used the parameter may be ignored. The
53 ENTRY-TOKEN string is typically the machine ID and is supposed to
54 identify the local installation on the system. For details see
55 below.
56 Two default plugins execute the following operations in this case:
58 • kernel-install creates $BOOT/ENTRY-TOKEN/KERNEL-VERSION, if
60 enabled (see $KERNEL_INSTALL_LAYOUT).
61 • 50-depmod.install runs depmod(8) for the KERNEL-VERSION.
63 • 90-loaderentry.install copies KERNEL-IMAGE to
65 $BOOT/ENTRY-TOKEN/KERNEL-VERSION/linux. If INITRD-FILEs are
66 provided, it also copies them to
67 $BOOT/ENTRY-TOKEN/KERNEL_VERSION/INITRD-FILE. It also creates a
68 boot loader entry according to the Boot Loader Specification[2]
69 (Type #1) in
70 $BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION.conf. The title
71 of the entry is the PRETTY_NAME parameter specified in
72 /etc/os-release or /usr/lib/os-release (if the former is
73 missing), or "Linux KERNEL-VERSION", if unset.
74 If $KERNEL_INSTALL_LAYOUT is not "bls", this plugin does
76 nothing.
77 • 90-uki-copy.install copies a file uki.efi from
79 $KERNEL_INSTALL_STAGING_AREA or if it does not exist the
80 KERNEL-IMAGE argument, iff it has a ".efi" extension, to
81 $BOOT/EFI/Linux/ENTRY-TOKEN-KERNEL-VERSION.efi.
82 If $KERNEL_INSTALL_LAYOUT is not "uki", this plugin does
84 nothing.
85 remove KERNEL-VERSION
87 This command expects a kernel version string as single argument.
88 This calls executables from /usr/lib/kernel/install.d/*.install and
89 /etc/kernel/install.d/*.install with the following arguments:
90 remove KERNEL-VERSION $BOOT/ENTRY-TOKEN/KERNEL-VERSION/
92 Afterwards, kernel-install removes the entry directory
94 $BOOT/ENTRY-TOKEN/KERNEL-VERSION/ and its contents, if it exists.
95 Two default plugins execute the following operations in this case:
97 • 50-depmod.install removes the files generated by depmod for
99 this kernel again.
100 • 90-loaderentry.install removes the file
102 $BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION.conf.
103 • 90-uki-copy.install removes the file
105 $BOOT/EFI/Linux/ENTRY-TOKEN-KERNEL-VERSION.efi.
106 inspect
108 Shows the various paths and parameters configured or auto-detected.
109 In particular shows the values of the various $KERNEL_INSTALL_*
110 environment variables listed below.
111
113 The partition where the kernels and Boot Loader Specification[2]
114 snippets are located is called $BOOT. kernel-install determines the
115 location of this partition by checking /efi/, /boot/, and /boot/efi/ in
116 turn. The first location where $BOOT/loader/entries/ or
117 $BOOT/ENTRY-TOKEN/ exists is used.
118
120 The following options are understood:
121 -v, --verbose
123 Output additional information about operations being performed.
124 -h, --help
126 Print a short help text and exit.
127 --version
129 Print a short version string and exit.
130
132 Environment variables exported for plugins
133 If --verbose is used, $KERNEL_INSTALL_VERBOSE=1 will be exported for
134 plugins. They may output additional logs in this case.
135 $KERNEL_INSTALL_IMAGE_TYPE=uki|pe|unknown is set for the plugins to
137 specify the type of the kernel image.
138 uki
140 Unified kernel image.
141 pe
143 PE binary.
144 unknown
146 Unknown type.
147 $KERNEL_INSTALL_MACHINE_ID is set for the plugins to the desired
149 machine-id to use. It's always a 128-bit ID. Normally it's read from
150 /etc/machine-id, but it can also be overridden via $MACHINE_ID (see
151 below). If not specified via these methods, a fallback value will
152 generated by kernel-install and used only for a single invocation.
153 $KERNEL_INSTALL_ENTRY_TOKEN is set for the plugins to the desired entry
155 "token" to use. It's an identifier that shall be used to identify the
156 local installation, and is often the machine ID, i.e. same as
157 $KERNEL_INSTALL_MACHINE_ID, but might also be a different type of
158 identifier, for example a fixed string or the ID=, IMAGE_ID= values
159 from /etc/os-release. The string passed here will be used to name Boot
160 Loader Specification entries, or the directories the kernel image and
161 initial RAM disk images are placed into.
162 Note that while $KERNEL_INSTALL_ENTRY_TOKEN and
164 $KERNEL_INSTALL_MACHINE_ID are often set to the same value, the latter
165 is guaranteed to be a valid 32 character ID in lowercase hexadecimals
166 while the former can be any short string. The entry token to use is
167 read from /etc/kernel/entry-token, if it exists. Otherwise a few
168 possible candidates below $BOOT are checked for Boot Loader
169 Specification Type 1 entry directories, and if found the entry token is
170 derived from that. If that is not successful,
171 $KERNEL_INSTALL_MACHINE_ID is used as fallback.
172 $KERNEL_INSTALL_BOOT_ROOT is set for the plugins to the absolute path
174 of the root directory (mount point, usually) of the hierarchy where
175 boot loader entries, kernel images, and associated resources should be
176 placed. This usually is the path where the XBOOTLDR partition or the
177 ESP (EFI System Partition) are mounted, and also conceptually referred
178 to as $BOOT. Can be overridden by setting $BOOT_ROOT (see below).
179 $KERNEL_INSTALL_LAYOUT=bls|uki|other|... is set for the plugins to
181 specify the installation layout. Defaults to bls if $BOOT/ENTRY-TOKEN
182 exists, or other otherwise. Additional layout names may be defined by
183 convention. If a plugin uses a special layout, it's encouraged to
184 declare its own layout name and configure layout= in install.conf upon
185 initial installation. The following values are currently understood:
186 bls
188 Standard Boot Loader Specification[2] Type #1 layout, compatible
189 with systemd-boot(7): entries in
190 $BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION[+TRIES].conf,
191 kernel and initrds under $BOOT/ENTRY-TOKEN/KERNEL-VERSION/
192 Implemented by 90-loaderentry.install.
194 uki
196 Standard Boot Loader Specification[2] Type #2 layout, compatible
197 with systemd-boot(7): unified kernel images under $BOOT/EFI/Linux
198 as $BOOT/EFI/Linux/ENTRY-TOKEN-KERNEL-VERSION[+TRIES].efi.
199 Implemented by 90-uki-copy.install.
201 other
203 Some other layout not understood natively by kernel-install.
204 $KERNEL_INSTALL_INITRD_GENERATOR is set for plugins to select the
206 initrd generator. This may be configured as initrd_generator= in
207 install.conf, see below.
208 $KERNEL_INSTALL_STAGING_AREA is set for plugins to a path to a
210 directory. Plugins may drop files in that directory, and they will be
211 installed as part of the loader entry, based on the file name and
212 extension.
213 Environment variables understood by kernel-install
215 $KERNEL_INSTALL_CONF_ROOT can be set to override the location of the
216 configuration files read by kernel-install. When set, install.conf,
217 entry-token, and other files will be read from this directory.
218 $KERNEL_INSTALL_PLUGINS can be set to override the list of plugins
220 executed by kernel-install. The argument is a whitespace-separated list
221 of paths. "KERNEL_INSTALL_PLUGINS=:" may be used to prevent any
222 plugins from running.
223 $MACHINE_ID can be set for kernel-install to override
225 $KERNEL_INSTALL_MACHINE_ID, the machine ID.
226 $BOOT_ROOT can be set for kernel-install to override
228 $KERNEL_INSTALL_BOOT_ROOT, the installation location for boot entries.
229 The last two variables may also be set in install.conf. Variables set
231 in the environment take precedence over the values specified in the
232 config file.
233
235 If every executable returns 0 or 77, 0 is returned, and a non-zero
236 failure code otherwise.
237
239 /usr/lib/kernel/install.d/*.install /etc/kernel/install.d/*.install
240 Drop-in files which are executed by kernel-install.
241 /usr/lib/kernel/cmdline /etc/kernel/cmdline /proc/cmdline
243 Read by 90-loaderentry.install. The content of the file
244 /etc/kernel/cmdline specifies the kernel command line to use. If
245 that file does not exist, /usr/lib/kernel/cmdline is used. If that
246 also does not exist, /proc/cmdline is used.
247 $KERNEL_INSTALL_CONF_ROOT may be used to override the path.
248 /etc/kernel/tries
250 Read by 90-loaderentry.install and 90-uki-copy.install. If this
251 file exists a numeric value is read from it and the naming of the
252 generated entry file or UKI is slightly altered to include it as
253 $BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION+TRIES.conf or
254 $BOOT/EFI/Linux/ENTRY-TOKEN-KERNEL-VERSION+TRIES.efi, respectively.
255 This is useful for boot loaders such as systemd-boot(7) which
256 implement boot attempt counting with a counter embedded in the
257 entry file name. $KERNEL_INSTALL_CONF_ROOT may be used to override
258 the path.
259 /etc/kernel/entry-token
261 If this file exists it is read and used as "entry token" for this
262 system, i.e. is used for naming Boot Loader Specification entries,
263 see $KERNEL_INSTALL_ENTRY_TOKEN above for details.
264 $KERNEL_INSTALL_CONF_ROOT may be used to override the path.
265 /etc/machine-id
267 The content of this file specifies the machine identification
268 MACHINE-ID.
269 /etc/os-release /usr/lib/os-release
271 Read by 90-loaderentry.install. If available, PRETTY_NAME= is read
272 from these files and used as the title of the boot menu entry.
273 Otherwise, "Linux KERNEL-VERSION" will be used.
274 /usr/lib/kernel/install.conf /etc/kernel/install.conf
276 Configuration options for kernel-install, as a series of KEY=VALUE
277 assignments, compatible with shell syntax, following the same rules
278 as described in os-release(5). /etc/kernel/install.conf will be
279 read if present, and /usr/lib/kernel/install.conf otherwise. This
280 file is optional. $KERNEL_INSTALL_CONF_ROOT may be used to
281 override the path.
282 Currently, the following keys are supported: MACHINE_ID=,
284 BOOT_ROOT=, layout=, initrd_generator=. See the Environment
285 variables section above for details.
286 /etc/kernel/uki.conf
288 Ini-style configuration file for ukify(1) which is only effective
289 when $KERNEL_INSTALL_LAYOUT or layout= in install.conf is set to
290 uki and $KERNEL_INSTALL_UKI_GENERATOR or uki_generator= in
291 install.conf is set to ukify. $KERNEL_INSTALL_CONF_ROOT may be
292 used to override the path.
293
295 machine-id(5), os-release(5), depmod(8), systemd-boot(7), ukify(1),
296 Boot Loader Specification[2]
297
299 1. Nowadays actually CPIO archives used as an "initramfs", rather than
300 "initrd". See bootup(7) for an explanation.
301 2. Boot Loader Specification
303 https://uapi-group.org/specifications/specs/boot_loader_specification
304systemd 253 KERNEL-INSTALL(8)