]>
Commit | Line | Data |
---|---|---|
514094f9 | 1 | <?xml version='1.0'?> |
3a54a157 ZJS |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> | |
db9ecf05 | 4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
81516adc | 5 | |
9858e6d2 | 6 | <refentry id="kernel-install" conditional='ENABLE_KERNEL_INSTALL' |
7054308a | 7 | xmlns:xi="http://www.w3.org/2001/XInclude"> |
81516adc HH |
8 | |
9 | <refentryinfo> | |
10 | <title>kernel-install</title> | |
11 | <productname>systemd</productname> | |
81516adc HH |
12 | </refentryinfo> |
13 | ||
14 | <refmeta> | |
15 | <refentrytitle>kernel-install</refentrytitle> | |
16 | <manvolnum>8</manvolnum> | |
17 | </refmeta> | |
18 | ||
19 | <refnamediv> | |
20 | <refname>kernel-install</refname> | |
b66a6e1a | 21 | <refpurpose>Add and remove kernel and initrd images to and from /boot</refpurpose> |
81516adc HH |
22 | </refnamediv> |
23 | ||
24 | <refsynopsisdiv> | |
25 | <cmdsynopsis> | |
845c5324 | 26 | <command>kernel-install</command> |
7054308a | 27 | <arg choice="opt" rep="repeat">OPTIONS</arg> |
f5c0edd1 | 28 | <arg choice="plain">add</arg> |
845c5324 | 29 | <arg choice="plain"><replaceable>KERNEL-VERSION</replaceable></arg> |
04ca4d19 | 30 | <arg choice="plain"><replaceable>KERNEL-IMAGE</replaceable></arg> |
0912c0b8 | 31 | <arg choice="opt" rep="repeat"><replaceable>INITRD-FILE</replaceable></arg> |
81516adc | 32 | </cmdsynopsis> |
f5c0edd1 YW |
33 | <cmdsynopsis> |
34 | <command>kernel-install</command> | |
35 | <arg choice="opt" rep="repeat">OPTIONS</arg> | |
36 | <arg choice="plain">remove</arg> | |
37 | <arg choice="plain"><replaceable>KERNEL-VERSION</replaceable></arg> | |
38 | </cmdsynopsis> | |
39 | <cmdsynopsis> | |
40 | <command>kernel-install</command> | |
41 | <arg choice="opt" rep="repeat">OPTIONS</arg> | |
42 | <arg choice="plain">inspect</arg> | |
bdd36c00 | 43 | <arg choice="opt"><replaceable>KERNEL-VERSION</replaceable></arg> |
f7665b7f | 44 | <arg choice="opt"><replaceable>KERNEL-IMAGE</replaceable></arg> |
bdd36c00 | 45 | <arg choice="opt" rep="repeat"><replaceable>INITRD-FILE</replaceable></arg> |
f5c0edd1 | 46 | </cmdsynopsis> |
658e6cc4 LP |
47 | <cmdsynopsis> |
48 | <command>kernel-install</command> | |
49 | <arg choice="opt" rep="repeat">OPTIONS</arg> | |
50 | <arg choice="plain">list</arg> | |
51 | </cmdsynopsis> | |
81516adc HH |
52 | </refsynopsisdiv> |
53 | ||
54 | <refsect1> | |
55 | <title>Description</title> | |
b66a6e1a ZJS |
56 | <para><command>kernel-install</command> is used to install and remove kernel and initrd images |
57 | <footnote> | |
58 | <para>Nowadays actually CPIO archives used as an "initramfs", rather than "initrd". See | |
59 | <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry> for an | |
60 | explanation.</para> | |
61 | </footnote> | |
62 | to and from the boot loader partition, referred to as <varname>$BOOT</varname> here. It will usually be | |
63 | one of <filename>/boot/</filename>, <filename>/efi/</filename>, or <filename>/boot/efi/</filename>, see | |
64 | below.</para> | |
81516adc | 65 | |
fe81e346 LP |
66 | <para><command>kernel-install</command> will run the executable files ("plugins") located in the |
67 | directory <filename>/usr/lib/kernel/install.d/</filename> and the local administration directory | |
68 | <filename>/etc/kernel/install.d/</filename>. All files are collectively sorted and executed in lexical | |
69 | order, regardless of the directory in which they live. However, files with identical filenames replace | |
70 | each other. Files in <filename>/etc/kernel/install.d/</filename> take precedence over files with the | |
71 | same name in <filename>/usr/lib/kernel/install.d/</filename>. This can be used to override a | |
72 | system-supplied executables with a local file if needed; a symbolic link in | |
73 | <filename>/etc/kernel/install.d/</filename> with the same name as an executable in | |
74 | <filename>/usr/lib/kernel/install.d/</filename>, pointing to <filename>/dev/null</filename>, disables the | |
75 | executable entirely. Executables must have the extension <literal>.install</literal>; other extensions | |
76 | are ignored.</para> | |
77 | ||
78 | <para>An executable placed in these directories should return <constant>0</constant> on success. It may | |
79 | also return <constant>77</constant> to cause the whole operation to terminate (executables later in | |
80 | lexical order will be skipped).</para> | |
81516adc HH |
81 | </refsect1> |
82 | ||
83 | <refsect1> | |
84 | <title>Commands</title> | |
85 | <para>The following commands are understood:</para> | |
86 | <variablelist> | |
87 | <varlistentry> | |
4454ca10 | 88 | <term> |
9d9e99a8 | 89 | <command>add [[[<replaceable>KERNEL-VERSION</replaceable>] <replaceable>KERNEL-IMAGE</replaceable>] [<replaceable>INITRD-FILE</replaceable> ...]]</command> |
4454ca10 ZJS |
90 | </term> |
91 | ||
81516adc | 92 | <listitem> |
9d9e99a8 LP |
93 | <para>This command takes a kernel version string and a path to a kernel image file as arguments. If |
94 | the former is omitted, specified as an empty string or as "-" it defaults to the current kernel | |
95 | version, i.e. the same string <command>uname -r</command> returns. If the latter is omitted, | |
96 | specified as an empty string or as "-" defaults to | |
97 | <filename>/usr/lib/modules/<replaceable>KERNEL_VERSION</replaceable>/vmlinuz</filename>. Optionally, | |
98 | one or more initrd images may be specified as well (note that plugins might generate additional | |
99 | ones).</para> | |
4454ca10 ZJS |
100 | |
101 | <para>The executable files from <filename>/usr/lib/kernel/install.d/*.install</filename> and | |
102 | <filename>/etc/kernel/install.d/*.install</filename> (i.e. the plugins) are called with the | |
103 | following arguments:</para> | |
4b2d80bb | 104 | |
4454ca10 ZJS |
105 | <programlisting>add <replaceable>KERNEL-VERSION</replaceable> <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> <replaceable>KERNEL-IMAGE</replaceable> \ |
106 | [<replaceable>INITRD-FILE</replaceable> ...]</programlisting> | |
fe81e346 | 107 | |
b66a6e1a | 108 | <para>The third argument directly refers to the path where to place kernel images, initrd |
4454ca10 ZJS |
109 | images and other resources for |
110 | <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot | |
fe81e346 | 111 | Loader Specification</ulink> Type #1 entries (the "entry directory"). If other boot loader schemes |
4454ca10 ZJS |
112 | are used the parameter may be ignored.</para> |
113 | ||
114 | <para>The <replaceable>ENTRY-TOKEN</replaceable> string is typically the machine ID and is supposed | |
115 | to identify the local installation on the system. For details see below.</para> | |
845c5324 | 116 | |
641e2124 | 117 | <para>Two default plugins execute the following operations in this case:</para> |
4b2d80bb LP |
118 | |
119 | <itemizedlist> | |
641e2124 | 120 | <listitem><para><command>kernel-install</command> creates |
fe81e346 LP |
121 | <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable></filename>, |
122 | if enabled (see <varname>$KERNEL_INSTALL_LAYOUT</varname>).</para></listitem> | |
4b2d80bb LP |
123 | |
124 | <listitem><para><filename>50-depmod.install</filename> runs | |
b7a47345 | 125 | <citerefentry project='man-pages'><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry> for the |
4b2d80bb LP |
126 | <replaceable>KERNEL-VERSION</replaceable>.</para></listitem> |
127 | ||
fe81e346 LP |
128 | <listitem><para><filename>90-loaderentry.install</filename> copies |
129 | <replaceable>KERNEL-IMAGE</replaceable> to | |
130 | <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/linux</filename>. | |
641e2124 | 131 | If <replaceable>INITRD-FILE</replaceable>s are provided, it also copies them to |
fe81e346 | 132 | <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL_VERSION</replaceable>/<replaceable>INITRD-FILE</replaceable></filename>. |
42210652 | 133 | This can also be used to prepend microcode before the actual initrd. It also creates a boot loader entry according to the <ulink |
db811444 | 134 | url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> (Type #1) in |
fe81e346 | 135 | <filename>$BOOT/loader/entries/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>. |
4b2d80bb | 136 | The title of the entry is the <replaceable>PRETTY_NAME</replaceable> parameter specified in |
fe81e346 LP |
137 | <filename>/etc/os-release</filename> or <filename>/usr/lib/os-release</filename> (if the former |
138 | is missing), or "Linux <replaceable>KERNEL-VERSION</replaceable>", if unset.</para> | |
cf73f650 | 139 | |
fe81e346 | 140 | <para>If <varname>$KERNEL_INSTALL_LAYOUT</varname> is not "bls", this plugin does nothing.</para></listitem> |
0ccfd356 JB |
141 | |
142 | <listitem><para><filename>90-uki-copy.install</filename> copies a file | |
143 | <filename>uki.efi</filename> from <varname>$KERNEL_INSTALL_STAGING_AREA</varname> or if it does | |
642617f4 | 144 | not exist the <replaceable>KERNEL-IMAGE</replaceable> argument, only if it has a |
0ccfd356 JB |
145 | <literal>.efi</literal> extension, to |
146 | <filename>$BOOT/EFI/Linux/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.efi</filename>.</para> | |
147 | ||
148 | <para>If <varname>$KERNEL_INSTALL_LAYOUT</varname> is not "uki", this plugin does nothing.</para></listitem> | |
4b2d80bb | 149 | </itemizedlist> |
ec07c3c8 | 150 | |
aefdc112 | 151 | <xi:include href="version-info.xml" xpointer="v198"/> |
81516adc HH |
152 | </listitem> |
153 | </varlistentry> | |
ec1399f5 LP |
154 | <varlistentry> |
155 | <term> | |
156 | <command>add-all</command> | |
157 | </term> | |
158 | ||
159 | <listitem> | |
160 | <para>This is the same as <command>add</command> (see above), but invokes the operation iteratively | |
161 | for every installed kernel in <filename>/usr/lib/modules/</filename>. This operation is only | |
162 | supported on systems where the kernel image is installed in | |
163 | <filename>/usr/lib/modules/<replaceable>KERNEL-VERSION</replaceable>/vmlinuz</filename>.</para> | |
164 | ||
165 | <xi:include href="version-info.xml" xpointer="v255"/> | |
166 | </listitem> | |
167 | </varlistentry> | |
81516adc | 168 | <varlistentry> |
8f51399e | 169 | <term><command>remove <replaceable>KERNEL-VERSION</replaceable></command></term> |
845c5324 | 170 | <listitem> |
4454ca10 ZJS |
171 | <para>This command expects a kernel version string as single argument.</para> |
172 | ||
173 | <para>The executable files from <filename>/usr/lib/kernel/install.d/*.install</filename> and | |
174 | <filename>/etc/kernel/install.d/*.install</filename> (i.e. the plugins) are called with the | |
175 | following arguments:</para> | |
845c5324 | 176 | |
fe81e346 LP |
177 | <programlisting>remove <replaceable>KERNEL-VERSION</replaceable> <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename></programlisting> |
178 | ||
179 | <para>Afterwards, <command>kernel-install</command> removes the entry directory | |
180 | <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> | |
181 | and its contents, if it exists.</para> | |
4b2d80bb LP |
182 | |
183 | <para>Two default plugins execute the following operations in this case:</para> | |
184 | ||
185 | <itemizedlist> | |
4454ca10 ZJS |
186 | <listitem><para><filename>50-depmod.install</filename> removes the files generated by |
187 | <command>depmod</command> for this kernel again.</para></listitem> | |
4b2d80bb LP |
188 | |
189 | <listitem><para><filename>90-loaderentry.install</filename> removes the file | |
4454ca10 ZJS |
190 | <filename>$BOOT/loader/entries/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>. |
191 | </para></listitem> | |
0ccfd356 JB |
192 | |
193 | <listitem><para><filename>90-uki-copy.install</filename> removes the file | |
4454ca10 ZJS |
194 | <filename>$BOOT/EFI/Linux/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.efi</filename>. |
195 | </para></listitem> | |
641e2124 | 196 | </itemizedlist> |
ec07c3c8 | 197 | |
aefdc112 | 198 | <xi:include href="version-info.xml" xpointer="v198"/> |
81516adc HH |
199 | </listitem> |
200 | </varlistentry> | |
fe81e346 | 201 | <varlistentry> |
bdd36c00 | 202 | <term> |
758d1476 | 203 | <command>inspect [[[<replaceable>KERNEL-VERSION</replaceable>] <replaceable>KERNEL-IMAGE</replaceable>] [<replaceable>INITRD-FILE</replaceable> ...]]</command> |
bdd36c00 | 204 | </term> |
fe81e346 | 205 | <listitem> |
758d1476 LP |
206 | <para>Takes the same parameters as <command>add</command>.</para> |
207 | ||
fe81e346 | 208 | <para>Shows the various paths and parameters configured or auto-detected. In particular shows the |
758d1476 LP |
209 | values of the various <varname>$KERNEL_INSTALL_*</varname> environment variables listed below, as |
210 | they would be passed to plugins. The <option>--json</option> option can be used to get the output | |
211 | of this verb as a JSON object.</para> | |
ec07c3c8 | 212 | |
aefdc112 | 213 | <xi:include href="version-info.xml" xpointer="v251"/> |
fe81e346 LP |
214 | </listitem> |
215 | </varlistentry> | |
658e6cc4 LP |
216 | <varlistentry> |
217 | <term><command>list</command></term> | |
218 | <listitem> | |
219 | <para>Shows the various installed kernels. This enumerates the subdirectories of | |
220 | <filename>/usr/lib/modules/</filename>, and shows whether a kernel image is installed there.</para> | |
221 | ||
222 | <xi:include href="version-info.xml" xpointer="v255"/> | |
223 | </listitem> | |
224 | </varlistentry> | |
81516adc | 225 | </variablelist> |
694fe6da | 226 | </refsect1> |
81516adc | 227 | |
eb25844f ZJS |
228 | <refsect1> |
229 | <title>Compatibility with the kernel build system</title> | |
230 | ||
231 | <cmdsynopsis> | |
232 | <command>installkernel</command> | |
233 | <arg choice="opt" rep="repeat">OPTIONS</arg> | |
234 | <arg choice="plain">VERSION</arg> | |
235 | <arg choice="plain">VMLINUZ</arg> | |
236 | <arg choice="opt">MAP</arg> | |
237 | <arg choice="opt">INSTALLATION-DIR</arg> | |
238 | </cmdsynopsis> | |
239 | ||
240 | <para>When invoked as <command>installkernel</command>, this program accepts arguments as specified by | |
241 | the kernel build system's <command>make install</command> command. The <parameter>VERSION</parameter> and | |
242 | <parameter>VMLINUZ</parameter> parameters specify the kernel version and the kernel binary. The other two | |
243 | parameters (<parameter>MAP</parameter> and <parameter>INSTALLATION-DIR</parameter>) are currently | |
244 | ignored. | |
245 | </para> | |
246 | </refsect1> | |
247 | ||
694fe6da ZJS |
248 | <refsect1> |
249 | <title>The <varname>$BOOT</varname> partition</title> | |
f5f5047f | 250 | |
db811444 | 251 | <para>The partition where the kernels and <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot |
694fe6da ZJS |
252 | Loader Specification</ulink> snippets are located is called <varname>$BOOT</varname>. |
253 | <command>kernel-install</command> determines the location of this partition by checking | |
fe81e346 LP |
254 | <filename>/efi/</filename>, <filename>/boot/</filename>, and <filename>/boot/efi/</filename> in turn. The |
255 | first location where <filename>$BOOT/loader/entries/</filename> or | |
256 | <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/</filename> exists is used.</para> | |
81516adc HH |
257 | </refsect1> |
258 | ||
7054308a ZJS |
259 | <refsect1> |
260 | <title>Options</title> | |
261 | <para>The following options are understood:</para> | |
262 | ||
263 | <variablelist> | |
4cff5e92 YW |
264 | <xi:include href="standard-options.xml" xpointer="esp-path"/> |
265 | <xi:include href="standard-options.xml" xpointer="boot-path"/> | |
266 | ||
b79621aa YW |
267 | <varlistentry> |
268 | <term><option>--make-entry-directory=yes|no|auto</option></term> | |
269 | <listitem> | |
270 | <para>Controls creation and deletion of the | |
271 | <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> | |
272 | Type #1 entry directory on the file system containing resources such as kernel and initrd images | |
273 | during <option>add</option> and <option>remove</option>, respectively. The directory is named after | |
274 | the entry token, and is placed immediately below the boot root directory. When | |
275 | <literal>auto</literal>, the directory is created or removed only when the install layout is | |
276 | <literal>bls</literal>. Defaults to <literal>auto</literal>.</para> | |
ec07c3c8 AK |
277 | |
278 | <xi:include href="version-info.xml" xpointer="v254"/> | |
b79621aa YW |
279 | </listitem> |
280 | </varlistentry> | |
281 | ||
1fd90ed3 YW |
282 | <varlistentry> |
283 | <term><option>--entry-token=</option></term> | |
284 | ||
285 | <listitem> | |
286 | <para>Controls how to name and identify boot loader entries for this kernel installation or | |
287 | deletion. Takes one of <literal>auto</literal>, <literal>machine-id</literal>, | |
288 | <literal>os-id</literal>, <literal>os-image-id</literal>, or an arbitrary string prefixed by | |
289 | <literal>literal:</literal> as argument.</para> | |
290 | ||
291 | <para>If set to <option>machine-id</option> the entries are named after the machine ID of the | |
292 | running system (e.g. <literal>b0e793a9baf14b5fa13ecbe84ff637ac</literal>). See | |
293 | <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for | |
294 | details about the machine ID concept and file.</para> | |
295 | ||
296 | <para>If set to <option>os-id</option> the entries are named after the OS ID of the running system, | |
297 | i.e. the <varname>ID=</varname> field of | |
298 | <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
299 | (e.g. <literal>fedora</literal>). Similarly, if set to <option>os-image-id</option> the entries are | |
300 | named after the OS image ID of the running system, i.e. the <varname>IMAGE_ID=</varname> field of | |
301 | <filename>os-release</filename> (e.g. <literal>vendorx-cashier-system</literal>).</para> | |
302 | ||
303 | <para>If set to <option>auto</option> (the default), the | |
304 | <filename>/etc/kernel/entry-token</filename> (or | |
305 | <filename>$KERNEL_INSTALL_CONF_ROOT/entry-token</filename>) file will be read if it exists, and the | |
306 | stored value used. Otherwise if the local machine ID is initialized it is used. Otherwise | |
307 | <varname>IMAGE_ID=</varname> from <filename>os-release</filename> will be used, if set. Otherwise, | |
308 | <varname>ID=</varname> from <filename>os-release</filename> will be used, if set. Otherwise a | |
309 | randomly generated machine ID is used.</para> | |
310 | ||
311 | <para>Using the machine ID for naming the entries is generally preferable, however there are cases | |
312 | where using the other identifiers is a good option. Specifically: if the identification data that | |
313 | the machine ID entails shall not be stored on the (unencrypted) <varname>$BOOT_ROOT</varname> | |
314 | partition, or if the ID shall be generated on first boot and is not known when the entries are | |
315 | prepared. Note that using the machine ID has the benefit that multiple parallel installations of | |
316 | the same OS can coexist on the same medium, and they can update their boot loader entries | |
317 | independently. When using another identifier (such as the OS ID or the OS image ID), parallel | |
318 | installations of the same OS would try to use the same entry name. To support parallel | |
319 | installations, the installer must use a different entry token when adding a second installation. | |
320 | </para> | |
ec07c3c8 AK |
321 | |
322 | <xi:include href="version-info.xml" xpointer="v254"/> | |
1fd90ed3 YW |
323 | </listitem> |
324 | </varlistentry> | |
325 | ||
7054308a ZJS |
326 | <varlistentry> |
327 | <term><option>-v</option></term> | |
328 | <term><option>--verbose</option></term> | |
329 | <listitem> | |
330 | <para>Output additional information about operations being performed.</para> | |
ec07c3c8 AK |
331 | |
332 | <xi:include href="version-info.xml" xpointer="v242"/> | |
7054308a ZJS |
333 | </listitem> |
334 | </varlistentry> | |
335 | ||
04a8c2ce DDM |
336 | <varlistentry> |
337 | <term><option>--root=<replaceable>root</replaceable></option></term> | |
338 | ||
339 | <listitem><para>Takes a directory path as an argument. All paths will be prefixed with the given | |
340 | alternate <replaceable>root</replaceable> path, including config search paths. This is useful to | |
341 | operate on a system image mounted to the specified directory instead of the host system | |
342 | itself.</para> | |
343 | ||
344 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
345 | </varlistentry> | |
346 | ||
347 | <varlistentry> | |
348 | <term><option>--image=<replaceable>image</replaceable></option></term> | |
349 | ||
350 | <listitem><para>Takes a path to a disk image file or block device node. If specified, all operations | |
351 | are applied to the file system in the indicated disk image. This option is similar to | |
352 | <option>--root=</option>, but operates on file systems stored in disk images or block devices. The | |
353 | disk image should either contain just a file system or a set of file systems within a GPT partition | |
354 | table, following the <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions | |
355 | Specification</ulink>. For further information on supported disk images, see | |
356 | <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s | |
357 | switch of the same name.</para> | |
358 | ||
359 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
360 | </varlistentry> | |
361 | ||
7054308a | 362 | <xi:include href="standard-options.xml" xpointer="help" /> |
99d8cbce | 363 | <xi:include href="standard-options.xml" xpointer="version" /> |
bdd36c00 DDM |
364 | <xi:include href="standard-options.xml" xpointer="no-pager"/> |
365 | <xi:include href="standard-options.xml" xpointer="json" /> | |
04a8c2ce | 366 | <xi:include href="standard-options.xml" xpointer="image-policy-open" /> |
658e6cc4 | 367 | <xi:include href="standard-options.xml" xpointer="no-legend"/> |
7054308a ZJS |
368 | </variablelist> |
369 | </refsect1> | |
370 | ||
371 | <refsect1> | |
372 | <title>Environment variables</title> | |
dcd9d196 | 373 | |
f5f5047f ZJS |
374 | <refsect2> |
375 | <title>Environment variables exported for plugins</title> | |
376 | ||
377 | <para>If <option>--verbose</option> is used, <varname>$KERNEL_INSTALL_VERBOSE=1</varname> will be | |
378 | exported for plugins. They may output additional logs in this case.</para> | |
379 | ||
cb5f21de AAF |
380 | <para><varname>$KERNEL_INSTALL_IMAGE_TYPE=uki|pe|unknown</varname> is set for the plugins to specify the |
381 | type of the kernel image.</para> | |
382 | ||
383 | <variablelist> | |
384 | <varlistentry> | |
385 | <term>uki</term> | |
386 | <listitem> | |
387 | <para>Unified kernel image.</para> | |
388 | ||
389 | <xi:include href="version-info.xml" xpointer="v254"/> | |
390 | </listitem> | |
391 | </varlistentry> | |
392 | <varlistentry> | |
393 | <term>pe</term> | |
394 | <listitem> | |
395 | <para>PE binary.</para> | |
396 | ||
397 | <xi:include href="version-info.xml" xpointer="v254"/> | |
398 | </listitem> | |
399 | </varlistentry> | |
400 | <varlistentry> | |
401 | <term>unknown</term> | |
402 | <listitem> | |
403 | <para>Unknown type.</para> | |
404 | ||
405 | <xi:include href="version-info.xml" xpointer="v254"/> | |
406 | </listitem> | |
407 | </varlistentry> | |
408 | </variablelist> | |
409 | ||
f5f5047f ZJS |
410 | <para><varname>$KERNEL_INSTALL_MACHINE_ID</varname> is set for the plugins to the desired machine-id to |
411 | use. It's always a 128-bit ID. Normally it's read from <filename>/etc/machine-id</filename>, but it can | |
8b9f0921 ZJS |
412 | also be overridden via <varname>$MACHINE_ID</varname> (see below). If not specified via these methods, |
413 | a fallback value will generated by <command>kernel-install</command> and used only for a single | |
f5f5047f ZJS |
414 | invocation.</para> |
415 | ||
416 | <para><varname>$KERNEL_INSTALL_ENTRY_TOKEN</varname> is set for the plugins to the desired entry | |
417 | "token" to use. It's an identifier that shall be used to identify the local installation, and is often | |
418 | the machine ID, i.e. same as <varname>$KERNEL_INSTALL_MACHINE_ID</varname>, but might also be a | |
419 | different type of identifier, for example a fixed string or the <varname>ID=</varname>, | |
420 | <varname>IMAGE_ID=</varname> values from <filename>/etc/os-release</filename>. The string passed here | |
421 | will be used to name Boot Loader Specification entries, or the directories the kernel image and initial | |
422 | RAM disk images are placed into.</para> | |
423 | ||
424 | <para>Note that while <varname>$KERNEL_INSTALL_ENTRY_TOKEN</varname> and | |
425 | <varname>$KERNEL_INSTALL_MACHINE_ID</varname> are often set to the same value, the latter is guaranteed | |
426 | to be a valid 32 character ID in lowercase hexadecimals while the former can be any short string. The | |
427 | entry token to use is read from <filename>/etc/kernel/entry-token</filename>, if it exists. Otherwise a | |
428 | few possible candidates below <varname>$BOOT</varname> are checked for Boot Loader Specification Type 1 | |
429 | entry directories, and if found the entry token is derived from that. If that is not successful, | |
430 | <varname>$KERNEL_INSTALL_MACHINE_ID</varname> is used as fallback.</para> | |
431 | ||
432 | <para><varname>$KERNEL_INSTALL_BOOT_ROOT</varname> is set for the plugins to the absolute path of the | |
433 | root directory (mount point, usually) of the hierarchy where boot loader entries, kernel images, and | |
434 | associated resources should be placed. This usually is the path where the XBOOTLDR partition or the ESP | |
435 | (EFI System Partition) are mounted, and also conceptually referred to as <varname>$BOOT</varname>. Can | |
436 | be overridden by setting <varname>$BOOT_ROOT</varname> (see below).</para> | |
437 | ||
3d5f0bfe GH |
438 | <para><varname>$KERNEL_INSTALL_LAYOUT=auto|bls|uki|other|...</varname> is set for the plugins to specify the |
439 | installation layout. Additional layout names may be defined by convention. If a plugin uses a special layout, | |
f5f5047f ZJS |
440 | it's encouraged to declare its own layout name and configure <varname>layout=</varname> in |
441 | <filename>install.conf</filename> upon initial installation. The following values are currently | |
442 | understood:</para> | |
443 | ||
444 | <variablelist> | |
445 | <varlistentry> | |
446 | <term>bls</term> | |
447 | <listitem> | |
db811444 | 448 | <para>Standard <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader |
f5f5047f ZJS |
449 | Specification</ulink> Type #1 layout, compatible with |
450 | <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>: | |
451 | entries in | |
452 | <filename>$BOOT/loader/entries/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>[+<replaceable>TRIES</replaceable>].conf</filename>, | |
453 | kernel and initrds under | |
454 | <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename></para> | |
455 | <para>Implemented by <filename>90-loaderentry.install</filename>.</para> | |
aefdc112 AK |
456 | |
457 | <xi:include href="version-info.xml" xpointer="v250"/> | |
f5f5047f ZJS |
458 | </listitem> |
459 | </varlistentry> | |
0ccfd356 JB |
460 | <varlistentry> |
461 | <term>uki</term> | |
462 | <listitem> | |
463 | <para>Standard <ulink | |
464 | url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader | |
465 | Specification</ulink> Type #2 layout, compatible with | |
466 | <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>: | |
467 | unified kernel images under <filename>$BOOT/EFI/Linux</filename> as | |
468 | <filename>$BOOT/EFI/Linux/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>[+<replaceable>TRIES</replaceable>].efi</filename>.</para> | |
469 | <para>Implemented by <filename>90-uki-copy.install</filename>.</para> | |
ec07c3c8 AK |
470 | |
471 | <xi:include href="version-info.xml" xpointer="v253"/> | |
0ccfd356 JB |
472 | </listitem> |
473 | </varlistentry> | |
f5f5047f ZJS |
474 | <varlistentry> |
475 | <term>other</term> | |
476 | <listitem> | |
477 | <para>Some other layout not understood natively by <command>kernel-install</command>.</para> | |
aefdc112 AK |
478 | |
479 | <xi:include href="version-info.xml" xpointer="v250"/> | |
f5f5047f ZJS |
480 | </listitem> |
481 | </varlistentry> | |
3d5f0bfe GH |
482 | <varlistentry> |
483 | <term>auto</term> | |
484 | <listitem> | |
485 | <para>Pick the layout automatically. If the kernel is a UKI set layout to | |
486 | <option>uki</option>. If not default to <option>bls</option> if | |
487 | <filename>$BOOT/loader/entries.srel</filename> with content <literal>type1</literal> or | |
488 | <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable></filename> exists, or | |
489 | <option>other</option> otherwise.</para> | |
490 | <para>Leaving layout blank has the same effect. This is the default.</para> | |
ec07c3c8 AK |
491 | |
492 | <xi:include href="version-info.xml" xpointer="v254"/> | |
3d5f0bfe GH |
493 | </listitem> |
494 | </varlistentry> | |
f5f5047f | 495 | </variablelist> |
367165a4 | 496 | |
85db5602 YW |
497 | <para><varname>$KERNEL_INSTALL_INITRD_GENERATOR</varname> and <varname>$KERNEL_INSTALL_UKI_GENERATOR</varname> |
498 | are set for plugins to select the initrd and/or UKI generator. This may be configured as | |
600362aa | 499 | <varname>initrd_generator=</varname> and <varname>uki_generator=</varname> in <filename>install.conf</filename>, see below.</para> |
f5f5047f ZJS |
500 | |
501 | <para><varname>$KERNEL_INSTALL_STAGING_AREA</varname> is set for plugins to a path to a directory. | |
502 | Plugins may drop files in that directory, and they will be installed as part of the loader entry, based | |
30dd8e74 | 503 | on the file name and extension: Files named <filename>initrd*</filename> will be installed as <replaceable>INITRD-FILE</replaceable>s, |
42210652 | 504 | and files named <filename>microcode*</filename> will be prepended before <replaceable>INITRD-FILE</replaceable>s.</para> |
30dd8e74 | 505 | |
f5f5047f ZJS |
506 | </refsect2> |
507 | ||
508 | <refsect2> | |
509 | <title>Environment variables understood by <command>kernel-install</command></title> | |
510 | ||
91199185 ZJS |
511 | <para><varname>$KERNEL_INSTALL_CONF_ROOT</varname> can be set to override the location of the |
512 | configuration files read by <command>kernel-install</command>. When set, | |
513 | <filename>install.conf</filename>, <filename>entry-token</filename>, and other files will be | |
514 | read from this directory.</para> | |
515 | ||
6755285c ZJS |
516 | <para><varname>$KERNEL_INSTALL_PLUGINS</varname> can be set to override the list of plugins executed by |
517 | <command>kernel-install</command>. The argument is a whitespace-separated list of paths. | |
518 | <literal>KERNEL_INSTALL_PLUGINS=:</literal> may be used to prevent any plugins from running. | |
519 | </para> | |
520 | ||
f5f5047f ZJS |
521 | <para><varname>$MACHINE_ID</varname> can be set for <command>kernel-install</command> to override |
522 | <varname>$KERNEL_INSTALL_MACHINE_ID</varname>, the machine ID.</para> | |
fe81e346 | 523 | |
f5f5047f ZJS |
524 | <para><varname>$BOOT_ROOT</varname> can be set for <command>kernel-install</command> to override |
525 | <varname>$KERNEL_INSTALL_BOOT_ROOT</varname>, the installation location for boot entries.</para> | |
fe81e346 | 526 | |
91199185 | 527 | <para>The last two variables may also be set in <filename>install.conf</filename>. Variables set in the |
f5f5047f ZJS |
528 | environment take precedence over the values specified in the config file.</para> |
529 | </refsect2> | |
7054308a ZJS |
530 | </refsect1> |
531 | ||
81516adc HH |
532 | <refsect1> |
533 | <title>Exit status</title> | |
c4c50112 | 534 | <para>If every executable returns 0 or 77, 0 is returned, and a non-zero failure code otherwise.</para> |
81516adc HH |
535 | </refsect1> |
536 | ||
537 | <refsect1> | |
538 | <title>Files</title> | |
539 | <variablelist> | |
540 | <varlistentry> | |
7a9d86bc ZJS |
541 | <term><filename>/etc/kernel/install.d/*.install</filename></term> |
542 | <term><filename>/usr/lib/kernel/install.d/*.install</filename></term> | |
543 | <listitem> | |
544 | <para>Drop-in files which are executed by <command>kernel-install</command>.</para> | |
ec07c3c8 AK |
545 | |
546 | <xi:include href="version-info.xml" xpointer="v198"/> | |
7a9d86bc | 547 | </listitem> |
81516adc | 548 | </varlistentry> |
7a9d86bc | 549 | |
2d0614d3 | 550 | <varlistentry> |
7a9d86bc ZJS |
551 | <term><filename>/etc/kernel/cmdline</filename></term> |
552 | <term><filename>/usr/lib/kernel/cmdline</filename></term> | |
553 | <term><filename>/proc/cmdline</filename></term> | |
554 | <listitem> | |
555 | <para>Specifies the kernel command line to use. The first of the files that is found will be used. | |
556 | <varname>$KERNEL_INSTALL_CONF_ROOT</varname> may be used to override the search path; see below for | |
557 | details.</para> | |
ec07c3c8 | 558 | |
aefdc112 | 559 | <xi:include href="version-info.xml" xpointer="v198"/> |
7a9d86bc ZJS |
560 | </listitem> |
561 | </varlistentry> | |
562 | ||
563 | <varlistentry> | |
564 | <term><filename>/etc/kernel/devicetree</filename></term> | |
565 | <term><filename>/usr/lib/kernel/devicetree</filename></term> | |
566 | <listitem> | |
567 | <para>Specifies the partial path to the file containing the device tree blob to install with the | |
568 | kernel and use at boot. The first of the files that is found will be used. | |
569 | <varname>$KERNEL_INSTALL_CONF_ROOT</varname> may be used to override the search path; see below for | |
570 | details.</para> | |
571 | ||
572 | <para>The <filename>devicetree</filename> file contains a path, and this path specifies a location | |
573 | relative to the kernel install tree. A set of locations is checked, including in particular | |
574 | <filename>/usr/lib/modules/<replaceable>KERNEL_VERSION</replaceable>/dtb/</filename>, which is the | |
575 | recommended location to place the dtb files under. For example, with | |
576 | <literal>broadcom/bcm2711-rpi-4-b.dtb</literal> in the <filename>devicetree</filename> file, the | |
577 | device tree blob for the Raspberry Pi 4 Model B would be installed, and the actual file would be | |
578 | <filename index='false'>/usr/lib/modules/<replaceable>KERNEL_VERSION</replaceable>/dtb/broadcom/bcm2711-rpi-4-b.dtb</filename>. | |
579 | </para> | |
580 | ||
581 | <xi:include href="version-info.xml" xpointer="v255"/> | |
582 | </listitem> | |
4b2d80bb | 583 | </varlistentry> |
7a9d86bc | 584 | |
4b2d80bb | 585 | <varlistentry> |
7a9d86bc ZJS |
586 | <term><filename>/etc/kernel/tries</filename></term> |
587 | <listitem> | |
588 | <para>Read by <filename>90-loaderentry.install</filename> and | |
589 | <filename>90-uki-copy.install</filename>. If this file exists, a numeric value is read from it and | |
590 | the naming of the generated entry file or UKI is altered to include it as | |
591 | <filename>$BOOT/loader/entries/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>+<replaceable>TRIES</replaceable>.conf</filename> | |
592 | or | |
593 | <filename>$BOOT/EFI/Linux/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>+<replaceable>TRIES</replaceable>.efi</filename>, | |
594 | respectively. This is useful for boot loaders such as | |
595 | <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> | |
596 | which implement boot attempt counting with a counter embedded in the entry file name. | |
597 | <varname>$KERNEL_INSTALL_CONF_ROOT</varname> may be used to override the search path; see below for | |
598 | details.</para> | |
ec07c3c8 AK |
599 | |
600 | <xi:include href="version-info.xml" xpointer="v240"/> | |
7a9d86bc | 601 | </listitem> |
2d0614d3 | 602 | </varlistentry> |
7a9d86bc | 603 | |
2d0614d3 | 604 | <varlistentry> |
7a9d86bc ZJS |
605 | <term><filename>/etc/kernel/entry-token</filename></term> |
606 | <listitem> | |
607 | <para>If this file exists it is read and used as "entry token" for this system, i.e. is used for | |
608 | naming Boot Loader Specification entries. See <varname>$KERNEL_INSTALL_ENTRY_TOKEN</varname> above | |
609 | for details. <varname>$KERNEL_INSTALL_CONF_ROOT</varname> may be used to override the search path; see | |
610 | below for details.</para> | |
ec07c3c8 | 611 | |
7a9d86bc ZJS |
612 | <xi:include href="version-info.xml" xpointer="v251"/> |
613 | </listitem> | |
2d0614d3 | 614 | </varlistentry> |
7a9d86bc | 615 | |
357376d0 DDM |
616 | <varlistentry> |
617 | <term> | |
fe81e346 | 618 | <filename>/etc/machine-id</filename> |
357376d0 DDM |
619 | </term> |
620 | <listitem> | |
fe81e346 LP |
621 | <para>The content of this file specifies the machine identification |
622 | <replaceable>MACHINE-ID</replaceable>.</para> | |
ec07c3c8 AK |
623 | |
624 | <xi:include href="version-info.xml" xpointer="v198"/> | |
357376d0 DDM |
625 | </listitem> |
626 | </varlistentry> | |
7a9d86bc | 627 | |
2d0614d3 | 628 | <varlistentry> |
7a9d86bc ZJS |
629 | <term><filename>/etc/os-release</filename></term> |
630 | <term><filename>/usr/lib/os-release</filename></term> | |
fe81e346 | 631 | <listitem> |
7a9d86bc ZJS |
632 | <para>Read by <filename>90-loaderentry.install</filename>. If available, |
633 | <varname>PRETTY_NAME=</varname> is read from these files and used as the title of the boot menu | |
634 | entry. Otherwise, <literal>Linux <replaceable>KERNEL-VERSION</replaceable></literal> will be | |
635 | used.</para> | |
ec07c3c8 | 636 | |
7a9d86bc | 637 | <xi:include href="version-info.xml" xpointer="v198"/> |
2d0614d3 HH |
638 | </listitem> |
639 | </varlistentry> | |
641e2124 | 640 | <varlistentry> |
7a9d86bc ZJS |
641 | <term><filename>/etc/kernel/install.conf</filename></term> |
642 | <term><filename>/usr/lib/kernel/install.conf</filename></term> | |
643 | <listitem> | |
644 | <para>Configuration file with options for <command>kernel-install</command>, as a series of | |
645 | <varname>KEY=</varname><replaceable>VALUE</replaceable> assignments, compatible with shell syntax, | |
646 | following the same rules as described in | |
647 | <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The | |
648 | first of the files that is found will be used. <varname>$KERNEL_INSTALL_CONF_ROOT</varname> may be | |
649 | used to override the search path; see below for details.</para> | |
650 | ||
651 | <para>Currently, the following keys are supported: | |
652 | <varname>MACHINE_ID=</varname>, | |
653 | <varname>BOOT_ROOT=</varname>, | |
654 | <varname>layout=</varname>, | |
655 | <varname>initrd_generator=</varname>, | |
656 | <varname>uki_generator=</varname>. | |
657 | See the Environment variables section above for details.</para> | |
ec07c3c8 | 658 | |
7a9d86bc ZJS |
659 | <xi:include href="version-info.xml" xpointer="v250"/> |
660 | </listitem> | |
641e2124 | 661 | </varlistentry> |
f5263dd0 | 662 | <varlistentry> |
7a9d86bc ZJS |
663 | <term><filename>/etc/kernel/uki.conf</filename></term> |
664 | <listitem> | |
665 | <para>Ini-style configuration file for | |
666 | <citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry> which is | |
667 | only effective when <varname>$KERNEL_INSTALL_LAYOUT</varname> or <varname>layout=</varname> in | |
668 | <filename>install.conf</filename> is set to <option>uki</option> and | |
669 | <varname>$KERNEL_INSTALL_UKI_GENERATOR</varname> or <varname>uki_generator=</varname> in | |
f712b11d | 670 | <filename>install.conf</filename> is set to <option>ukify</option>, or is unset. |
7a9d86bc ZJS |
671 | <varname>$KERNEL_INSTALL_CONF_ROOT</varname> may be used to override the search path; see below for |
672 | details.</para> | |
673 | ||
674 | <xi:include href="version-info.xml" xpointer="v255"/> | |
675 | </listitem> | |
f5263dd0 | 676 | </varlistentry> |
35f58f8c LP |
677 | |
678 | <varlistentry> | |
679 | <term><filename>/usr/lib/modules/<replaceable>KERNEL-VERSION/</replaceable></filename></term> | |
680 | ||
681 | <listitem> | |
682 | <para>Location for installed kernel modules and other kernel related resources. For each locally | |
683 | installed kernel a directory named after the kernel version (<command>uname -r</command>) is | |
684 | kept.</para> | |
685 | ||
686 | <xi:include href="version-info.xml" xpointer="v255"/> | |
687 | </listitem> | |
688 | </varlistentry> | |
689 | ||
690 | <varlistentry> | |
691 | <term><filename>/usr/lib/modules/<replaceable>KERNEL-VERSION/vmlinuz</replaceable></filename></term> | |
692 | ||
693 | <listitem> | |
694 | <para>Location for installed kernel images. This is the recommended location for OS package | |
695 | managers to install kernel images into (as applicable), from which <command>kernel-install | |
696 | add</command> then copies it into the final boot partition.</para> | |
697 | ||
698 | <xi:include href="version-info.xml" xpointer="v255"/> | |
699 | </listitem> | |
700 | </varlistentry> | |
701 | ||
81516adc | 702 | </variablelist> |
7a9d86bc ZJS |
703 | |
704 | <para>For various cases listed above, if the <varname>$KERNEL_INSTALL_CONF_ROOT</varname> environment | |
705 | variable is set, it will override the search path. The files will be loaded <emphasis>only</emphasis> | |
706 | from the directory specified by the environment variable. When the variable is not set, the listed paths | |
707 | are tried in turn, and the first file that exists is used.</para> | |
81516adc HH |
708 | </refsect1> |
709 | ||
710 | <refsect1> | |
711 | <title>See Also</title> | |
13a69c12 DT |
712 | <para><simplelist type="inline"> |
713 | <member><citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> | |
714 | <member><citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> | |
715 | <member><citerefentry project='man-pages'><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
716 | <member><citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry></member> | |
717 | <member><citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
718 | <member><ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink></member> | |
719 | </simplelist></para> | |
81516adc HH |
720 | </refsect1> |
721 | ||
722 | </refentry> |