1KERNEL-INSTALL(8)               kernel-install               KERNEL-INSTALL(8)
2
3
4

NAME

6       kernel-install - Add and remove kernel and initramfs images to and from
7       /boot
8

SYNOPSIS

10       kernel-install COMMAND [OPTIONS...] KERNEL-VERSION KERNEL-IMAGE
11                      [INITRD-FILE...]
12

DESCRIPTION

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
19       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
32       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

COMMANDS

37       The following commands are understood:
38
39       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
45               add KERNEL-VERSION $BOOT/MACHINE-ID/KERNEL-VERSION/ KERNEL-IMAGE [INITRD-FILE ...]
46
47           Two default plugins execute the following operations in this case:
48
49kernel-install creates $BOOT/MACHINE-ID/KERNEL-VERSION, if
50               enabled (see $KERNEL_INSTALL_LAYOUT=).
51
52           •   50-depmod.install runs depmod(8) for the KERNEL-VERSION.
53
54           •   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
64               If $KERNEL_INSTALL_LAYOUT= is not "bls", this plugin does
65               nothing.
66
67       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
72               remove KERNEL-VERSION $BOOT/MACHINE-ID/KERNEL-VERSION/
73
74           Afterwards, kernel-install removes the directory
75           $BOOT/MACHINE-ID/KERNEL-VERSION/ and its contents.
76
77           Two default plugins execute the following operations in this case:
78
79           •   50-depmod.install removes the files generated by depmod for
80               this kernel again.
81
82           •   90-loaderentry.install removes the file
83               $BOOT/loader/entries/MACHINE-ID-KERNEL-VERSION.conf.
84
85kernel-install removes $BOOT/MACHINE-ID/KERNEL-VERSION, if
86               enabled (see $KERNEL_INSTALL_LAYOUT=).
87

THE $BOOT PARTITION

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

OPTIONS

96       The following options are understood:
97
98       -v, --verbose
99           Output additional information about operations being performed.
100
101       -h, --help
102           Print a short help text and exit.
103

ENVIRONMENT VARIABLES

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
108       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
112       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
116       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
121       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
127       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
133           Provided by 90-loaderentry.install.
134
135       other
136           Some other layout not understood natively by kernel-install.
137

EXIT STATUS

139       If every executable returns 0 or 77, 0 is returned, and a non-zero
140       failure code otherwise.
141

FILES

143       /usr/lib/kernel/install.d/*.install /etc/kernel/install.d/*.install
144           Drop-in files which are executed by kernel-install.
145
146       /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
152       /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
161       /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
167       /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
174       /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
179       /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

SEE ALSO

185       machine-id(5), os-release(5), depmod(8), systemd-boot(7), Boot Loader
186       Specification[1]
187

NOTES

189        1. Boot Loader Specification
190           https://systemd.io/BOOT_LOADER_SPECIFICATION
191
192
193
194systemd 250                                                  KERNEL-INSTALL(8)
Impressum