1KERNEL-INSTALL(8) kernel-install KERNEL-INSTALL(8)
2
6 kernel-install - Add and remove kernel and initramfs images to and from
7 /boot
8
10 kernel-install COMMAND [OPTIONS...] KERNEL-VERSION KERNEL-IMAGE
11 [INITRD-FILE...]
12
14 kernel-install is used to install and remove kernel and initramfs
15 images to and from the boot loader partition, referred to as $BOOT
16 here. It will usually be one of /boot/, /efi/, or /boot/efi/, see
17 below.
18 kernel-install will run the executable files ("plugins") located in the
20 directory /usr/lib/kernel/install.d/ and the local administration
21 directory /etc/kernel/install.d/. All files are collectively sorted and
22 executed in lexical order, regardless of the directory in which they
23 live. However, files with identical filenames replace each other. Files
24 in /etc/kernel/install.d/ take precedence over files with the same name
25 in /usr/lib/kernel/install.d/. This can be used to override a
26 system-supplied executables with a local file if needed; a symbolic
27 link in /etc/kernel/install.d/ with the same name as an executable in
28 /usr/lib/kernel/install.d/, pointing to /dev/null, disables the
29 executable entirely. Executables must have the extension ".install";
30 other extensions are ignored.
31 An executable placed in these directories should return 0 on success.
33 It may also return 77 to cause the whole operation to terminate
34 (executables later in lexical order will be skipped).
35
37 The following commands are understood:
38 add KERNEL-VERSION KERNEL-IMAGE [INITRD-FILE ...]
40 This command expects a kernel version string and a path to a kernel
41 image file as arguments. Optionally, one or more initial RAM disk
42 images may be specified as well (note that plugins might generate
43 additional ones). kernel-install calls the executable files from
44 /usr/lib/kernel/install.d/*.install and
45 /etc/kernel/install.d/*.install (i.e. the plugins) with the
46 following arguments:
47 add KERNEL-VERSION $BOOT/ENTRY-TOKEN/KERNEL-VERSION/ KERNEL-IMAGE [INITRD-FILE ...]
49 The third argument directly refers to the path where to place
51 kernel images, initial RAM disk images and other resources for Boot
52 Loader Specification[1] Type #1 entries (the "entry directory"). If
53 other boot loader schemes are used the parameter may be ignored.
54 The ENTRY-TOKEN string is typically the machine ID and is supposed
55 to identify the local installation on the system. For details see
56 below.
57 Two default plugins execute the following operations in this case:
59 • kernel-install creates $BOOT/ENTRY-TOKEN/KERNEL-VERSION, if
61 enabled (see $KERNEL_INSTALL_LAYOUT).
62 • 50-depmod.install runs depmod(8) for the KERNEL-VERSION.
64 • 90-loaderentry.install copies KERNEL-IMAGE to
66 $BOOT/ENTRY-TOKEN/KERNEL-VERSION/linux. If INITRD-FILEs are
67 provided, it also copies them to
68 $BOOT/ENTRY-TOKEN/KERNEL_VERSION/INITRD-FILE. It also creates a
69 boot loader entry according to the Boot Loader Specification[1]
70 (Type #1) in
71 $BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION.conf. The title
72 of the entry is the PRETTY_NAME parameter specified in
73 /etc/os-release or /usr/lib/os-release (if the former is
74 missing), or "Linux KERNEL-VERSION", if unset.
75 If $KERNEL_INSTALL_LAYOUT is not "bls", this plugin does
77 nothing.
78 remove KERNEL-VERSION
80 This command expects a kernel version string as single argument.
81 This calls executables from /usr/lib/kernel/install.d/*.install and
82 /etc/kernel/install.d/*.install with the following arguments:
83 remove KERNEL-VERSION $BOOT/ENTRY-TOKEN/KERNEL-VERSION/
85 Afterwards, kernel-install removes the entry directory
87 $BOOT/ENTRY-TOKEN/KERNEL-VERSION/ and its contents, if it exists.
88 Two default plugins execute the following operations in this case:
90 • 50-depmod.install removes the files generated by depmod for
92 this kernel again.
93 • 90-loaderentry.install removes the file
95 $BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION.conf.
96 inspect
98 Shows the various paths and parameters configured or auto-detected.
99 In particular shows the values of the various $KERNEL_INSTALL_*
100 environment variables listed below.
101
103 The partition where the kernels and Boot Loader Specification[1]
104 snippets are located is called $BOOT. kernel-install determines the
105 location of this partition by checking /efi/, /boot/, and /boot/efi/ in
106 turn. The first location where $BOOT/loader/entries/ or
107 $BOOT/ENTRY-TOKEN/ exists is used.
108
110 The following options are understood:
111 -v, --verbose
113 Output additional information about operations being performed.
114 -h, --help
116 Print a short help text and exit.
117 --version
119 Print a short version string and exit.
120
122 If --verbose is used, $KERNEL_INSTALL_VERBOSE=1 will be set for the
123 plugins. They may output additional logs in this case.
124 If $MACHINE_ID is set and not empty when kernel-install is invoked, it
126 will be used as MACHINE-ID, overriding any automatic detection
127 attempts. The value must be a valid machine ID (32 hexadecimal
128 characters).
129 $KERNEL_INSTALL_MACHINE_ID is set for the plugins to the desired
131 MACHINE-ID to use. It's always a 128bit ID, and typically the ID from
132 /etc/machine-id or the one passed in via $MACHINE_ID. (If no machine ID
133 was specified via these methods it might be generated randomly by
134 kernel-install, in which case it only applies to this invocation.)
135 $KERNEL_INSTALL_ENTRY_TOKEN is set for the plugins to the desired entry
137 "token" to use. It's an identifier that shall be used to identify the
138 local installation, and is often the machine ID, i.e. same as
139 $KERNEL_INSTALL_MACHINE_ID, but might also be a different type of
140 identifier, for example a fixed string or the ID=, IMAGE_ID= values
141 from /etc/os-release. The string passed here will be used to name Boot
142 Loader Specification entries, or the directories the kernel image and
143 initial RAM disk images are placed into. Note that while oftentimes
144 $KERNEL_INSTALL_ENTRY_TOKEN and $KERNEL_INSTALL_MACHINE_ID are set to
145 the same value, the latter is guaranteed to be a valid 32 character ID
146 in lowercase hexadecimals while the former can be any short string. The
147 entry token to use is read from /etc/kernel/entry-token, if it exists.
148 Otherwise a few possible candidates below the $BOOT are searched for
149 Boot Loader Specification Type 1 entry directories, and if found the
150 entry token is derived from that. If that is not successful the machine
151 ID is used as fallback.
152 $KERNEL_INSTALL_BOOT_ROOT is set for the plugins to the absolute path
154 of the root directory (mount point, usually) of the hierarchy where
155 boot loader entries, kernel images, and associated resources should be
156 placed. This usually is the path where the XBOOTLDR partition or the
157 ESP (EFI System Partition) are mounted, and also conceptually referred
158 to as $BOOT. Can be overridden by setting $BOOT_ROOT.
159 $KERNEL_INSTALL_LAYOUT=bls|other|... is set for the plugins to specify
161 the installation layout. Defaults to bls if $BOOT/ENTRY-TOKEN exists,
162 or other otherwise. Additional layout names may be defined by
163 convention. If a plugin uses a special layout, it's encouraged to
164 declare its own layout name and configure layout= in install.conf upon
165 initial installation. The following values are currently understood:
166 bls
168 Standard Boot Loader Specification[1] Type #1 layout, compatible
169 with systemd-boot(7): entries in
170 $BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION[+TRIES].conf,
171 kernel and initrds under $BOOT/ENTRY-TOKEN/KERNEL-VERSION/
172 Implemented by 90-loaderentry.install.
174 other
176 Some other layout not understood natively by kernel-install.
177 $KERNEL_INSTALL_INITRD_GENERATOR is set for plugins to select the
179 initrd generator. This may be configured as initrd_generator= in
180 install.conf. See below.
181 $KERNEL_INSTALL_STAGING_AREA is set for plugins to a path to a
183 directory. Plugins may drop files in that directory, and they will be
184 installed as part of the loader entry, based on the file name and
185 extension.
186
188 If every executable returns 0 or 77, 0 is returned, and a non-zero
189 failure code otherwise.
190
192 /usr/lib/kernel/install.d/*.install /etc/kernel/install.d/*.install
193 Drop-in files which are executed by kernel-install.
194 /usr/lib/kernel/cmdline /etc/kernel/cmdline /proc/cmdline
196 Read by 90-loaderentry.install. The content of the file
197 /etc/kernel/cmdline specifies the kernel command line to use. If
198 that file does not exist, /usr/lib/kernel/cmdline is used. If that
199 also does not exist, /proc/cmdline is used.
200 /etc/kernel/tries
202 Read by 90-loaderentry.install. If this file exists a numeric value
203 is read from it and the naming of the generated entry file is
204 slightly altered to include it as
205 $BOOT/loader/entries/MACHINE-ID-KERNEL-VERSION+TRIES.conf. This is
206 useful for boot loaders such as systemd-boot(7) which implement
207 boot attempt counting with a counter embedded in the entry file
208 name.
209 /etc/kernel/entry-token
211 If this file exists it is read and used as "entry token" for this
212 system, i.e. is used for naming Boot Loader Specification entries,
213 see $KERNEL_INSTALL_ENTRY_TOKEN above for details.
214 /etc/machine-id
216 The content of this file specifies the machine identification
217 MACHINE-ID.
218 /etc/os-release /usr/lib/os-release
220 Read by 90-loaderentry.install. If available, PRETTY_NAME= is read
221 from these files and used as the title of the boot menu entry.
222 Otherwise, "Linux KERNEL-VERSION" will be used.
223 /usr/lib/kernel/install.conf /etc/kernel/install.conf
225 Configuration options for kernel-install, as a series of KEY=VALUE
226 assignments, compatible with shell syntax. This currently supports
227 two keys: layout= and initrd_generator=, for details see the
228 Environment variables section above.
229
231 machine-id(5), os-release(5), depmod(8), systemd-boot(7), Boot Loader
232 Specification[1]
233
235 1. Boot Loader Specification
236 https://systemd.io/BOOT_LOADER_SPECIFICATION
237systemd 251 KERNEL-INSTALL(8)