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 execute the files located in the directory
20 /usr/lib/kernel/install.d/ and the local administration directory
21 /etc/kernel/install.d/. All files are collectively sorted and executed
22 in lexical order, regardless of the directory in which they live.
23 However, files with identical filenames replace each other. Files in
24 /etc/kernel/install.d/ take precedence over files with the same name in
25 /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 should return 0 on success. It may also return 77 to
33 cause the whole operation to terminate (executables later in lexical
34 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. kernel-install calls the executables from
42 /usr/lib/kernel/install.d/*.install and
43 /etc/kernel/install.d/*.install with the following arguments:
44 add KERNEL-VERSION $BOOT/MACHINE-ID/KERNEL-VERSION/ KERNEL-IMAGE [INITRD-FILE ...]
46 Two default plugins execute the following operations in this case:
48 • kernel-install creates $BOOT/MACHINE-ID/KERNEL-VERSION, if
50 enabled (see $KERNEL_INSTALL_LAYOUT=).
51 • 50-depmod.install runs depmod(8) for the KERNEL-VERSION.
53 • 90-loaderentry.install copies KERNEL-IMAGE to
55 $BOOT/MACHINE-ID/KERNEL-VERSION/linux. If INITRD-FILEs are
56 provided, it also copies them to
57 $BOOT/MACHINE-ID/KERNEL_VERSION/INITRD-FILE. It also creates a
58 boot loader entry according to the Boot Loader Specification[1]
59 in $BOOT/loader/entries/MACHINE-ID-KERNEL-VERSION.conf. The
60 title of the entry is the PRETTY_NAME parameter specified in
61 /etc/os-release or /usr/lib/os-release (if the former is
62 missing), or "Linux KERNEL-VERSION", if unset.
63 If $KERNEL_INSTALL_LAYOUT= is not "bls", this plugin does
65 nothing.
66 remove KERNEL-VERSION
68 This command expects a kernel version string as single argument.
69 This calls executables from /usr/lib/kernel/install.d/*.install and
70 /etc/kernel/install.d/*.install with the following arguments:
71 remove KERNEL-VERSION $BOOT/MACHINE-ID/KERNEL-VERSION/
73 Afterwards, kernel-install removes the directory
75 $BOOT/MACHINE-ID/KERNEL-VERSION/ and its contents.
76 Two default plugins execute the following operations in this case:
78 • 50-depmod.install removes the files generated by depmod for
80 this kernel again.
81 • 90-loaderentry.install removes the file
83 $BOOT/loader/entries/MACHINE-ID-KERNEL-VERSION.conf.
84 • kernel-install removes $BOOT/MACHINE-ID/KERNEL-VERSION, if
86 enabled (see $KERNEL_INSTALL_LAYOUT=).
87
89 The partition where the kernels and Boot Loader Specification[1]
90 snippets are located is called $BOOT. kernel-install determines the
91 location of this partition by checking /efi/, /boot/, and /boot/efi/ in
92 turn. The first location where $BOOT/loader/entries/ or
93 $BOOT/$MACHINE_ID/ exists is used.
94
96 The following options are understood:
97 -v, --verbose
99 Output additional information about operations being performed.
100 -h, --help
102 Print a short help text and exit.
103
105 If --verbose is used, $KERNEL_INSTALL_VERBOSE=1 will be set for the
106 plugins. They may output additional logs in this case.
107 If MACHINE_ID= is set and not empty, it will be used as MACHINE-ID,
109 overriding any automatic detection attempts. The value must be a valid
110 machine ID (32 hexadecimal characters).
111 KERNEL_INSTALL_MACHINE_ID= is set for the plugins to the desired
113 MACHINE-ID – either 32 hexadecimal characters or the special value
114 "Default".
115 KERNEL_INSTALL_BOOT_ROOT= is set for the plugins to the root directory
117 (mount point, usually) of the hierarchy where boot-loader entries,
118 kernel images, and associated resources should be placed. Can be
119 overridden by setting BOOT_ROOT=.
120 KERNEL_INSTALL_LAYOUT=bls|other|... specifies the installation layout.
122 Defaults to bls if $BOOT/MACHINE-ID exists, or other otherwise.
123 Additional layout names may be defined by convention. If a plugin uses
124 a special layout, it's encouraged to declare its own layout name and
125 configure layout= in install.conf upon initial installation.
126 bls
128 Standard Boot Loader Specification[1] layout, compatible with
129 systemd-boot(7): entries in
130 $BOOT/loader/entries/MACHINE-ID-KERNEL-VERSION[+TRIES].conf, kernel
131 and initrds under $BOOT/MACHINE-ID/KERNEL-VERSION/
132 Provided by 90-loaderentry.install.
134 other
136 Some other layout not understood natively by kernel-install.
137
139 If every executable returns 0 or 77, 0 is returned, and a non-zero
140 failure code otherwise.
141
143 /usr/lib/kernel/install.d/*.install /etc/kernel/install.d/*.install
144 Drop-in files which are executed by kernel-install.
145 /usr/lib/kernel/cmdline /etc/kernel/cmdline /proc/cmdline
147 Read by 90-loaderentry.install. The content of the file
148 /etc/kernel/cmdline specifies the kernel command line to use. If
149 that file does not exist, /usr/lib/kernel/cmdline is used. If that
150 also does not exist, /proc/cmdline is used.
151 /etc/kernel/tries
153 Read by 90-loaderentry.install. If this file exists a numeric value
154 is read from it and the naming of the generated entry file is
155 slightly altered to include it as
156 $BOOT/loader/entries/MACHINE-ID-KERNEL-VERSION+TRIES.conf. This is
157 useful for boot loaders such as systemd-boot(7) which implement
158 boot attempt counting with a counter embedded in the entry file
159 name.
160 /etc/machine-id
162 The content of this file specifies the machine identification
163 MACHINE-ID. If /etc/machine-id cannot be read or is temporary
164 (backed by a file on tmpfs), kernel-install will use "Default"
165 instead.
166 /etc/machine-info
168 If this file contains the KERNEL_INSTALL_MACHINE_ID variable,
169 kernel-install will use it as MACHINE-ID instead of the contents of
170 /etc/machine-id. If the variable is not found in /etc/machine-info,
171 kernel-install will try to save the machine ID it uses to install
172 to $BOOT to this file.
173 /etc/os-release /usr/lib/os-release
175 Read by 90-loaderentry.install. If available, PRETTY_NAME is read
176 from these files and used as the title of the boot menu entry.
177 Otherwise, "Linux KERNEL-VERSION" will be used.
178 /usr/lib/kernel/install.conf /etc/kernel/install.conf
180 Configuration options for kernel-install, as a series of KEY=VALUE
181 assignments, compatible with shell syntax. See the Environment
182 variables section for supported keys.
183
185 machine-id(5), os-release(5), depmod(8), systemd-boot(7), Boot Loader
186 Specification[1]
187
189 1. Boot Loader Specification
190 https://systemd.io/BOOT_LOADER_SPECIFICATION
191systemd 250 KERNEL-INSTALL(8)