]>
Commit | Line | Data |
---|---|---|
1bc64d77 | 1 | <?xml version='1.0'?> <!--*-nxml-*--> |
3a54a157 | 2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
eea10b26 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
db9ecf05 | 4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
1bc64d77 | 5 | |
dfca5587 | 6 | <refentry id="bootctl" conditional='ENABLE_BOOTLOADER' |
798d3a52 | 7 | xmlns:xi="http://www.w3.org/2001/XInclude"> |
798d3a52 ZJS |
8 | <refentryinfo> |
9 | <title>bootctl</title> | |
10 | <productname>systemd</productname> | |
798d3a52 ZJS |
11 | </refentryinfo> |
12 | ||
13 | <refmeta> | |
14 | <refentrytitle>bootctl</refentrytitle> | |
15 | <manvolnum>1</manvolnum> | |
16 | </refmeta> | |
17 | ||
18 | <refnamediv> | |
19 | <refname>bootctl</refname> | |
64a7fcc5 | 20 | <refpurpose>Control EFI firmware boot settings and manage boot loader</refpurpose> |
798d3a52 ZJS |
21 | </refnamediv> |
22 | ||
23 | <refsynopsisdiv> | |
24 | <cmdsynopsis> | |
c779b82a YW |
25 | <command>bootctl</command> |
26 | <arg choice="opt" rep="repeat">OPTIONS</arg> | |
27 | <arg choice="req">COMMAND</arg> | |
798d3a52 ZJS |
28 | </cmdsynopsis> |
29 | </refsynopsisdiv> | |
30 | ||
31 | <refsect1> | |
32 | <title>Description</title> | |
33 | ||
64a7fcc5 LP |
34 | <para><command>bootctl</command> can check the EFI firmware and boot loader status, list and manage |
35 | available boot loaders and boot loader entries, and install, update, or remove the | |
36 | <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> boot | |
37 | loader on the current system.</para> | |
798d3a52 ZJS |
38 | </refsect1> |
39 | ||
c779b82a | 40 | <refsect1> |
64a7fcc5 LP |
41 | <title>Generic EFI Firmware/Boot Loader Commands</title> |
42 | ||
43 | <para>These commands are available on any EFI system, regardless of the boot loader used.</para> | |
c779b82a | 44 | |
64a7fcc5 | 45 | <variablelist> |
c779b82a YW |
46 | <varlistentry> |
47 | <term><option>status</option></term> | |
48 | ||
db9eabd6 ZJS |
49 | <listitem><para>Shows brief information about the system firmware, the boot loader that was used to |
50 | boot the system, the boot loaders currently available in the ESP, the boot loaders listed in the | |
51 | firmware's list of boot loaders and the current default boot loader entry. If no command is | |
e12335ba ZJS |
52 | specified, this is the implied default.</para> |
53 | ||
54 | <para>See the example below for details of the output.</para> | |
aefdc112 AK |
55 | |
56 | <xi:include href="version-info.xml" xpointer="v239"/> | |
e12335ba | 57 | </listitem> |
c779b82a | 58 | </varlistentry> |
64a7fcc5 | 59 | |
db9eabd6 ZJS |
60 | <varlistentry> |
61 | <term><option>reboot-to-firmware</option> <optional><replaceable>BOOL</replaceable></optional></term> | |
62 | ||
63 | <listitem><para>Query or set the "Reboot-Into-Firmware-Setup" flag of the EFI firmware. Takes a | |
64 | boolean argument which controls whether to show the firmware setup on next system reboot. If the | |
65 | argument is omitted shows the current status of the flag, or whether the flag is supported. This | |
66 | controls the same flag as <command>systemctl reboot --firmware-setup</command>, but is more low-level | |
76c068b7 ZJS |
67 | and allows setting the flag independently from actually requesting a reboot.</para> |
68 | ||
69 | <para>Hint: use <command>systemctl reboot --firmware-setup</command> to reboot into firmware setup | |
70 | once. See | |
71 | <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
ec07c3c8 AK |
72 | for details.</para> |
73 | ||
74 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
db9eabd6 | 75 | </varlistentry> |
db9eabd6 | 76 | </variablelist> |
64a7fcc5 LP |
77 | </refsect1> |
78 | ||
79 | <refsect1> | |
80 | <title>Boot Loader Specification Commands</title> | |
81 | ||
eab70618 LP |
82 | <para>These commands are available for all boot loaders that |
83 | implement the <ulink | |
84 | url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot | |
85 | Loader Specification</ulink>, such as | |
64a7fcc5 LP |
86 | <command>systemd-boot</command>.</para> |
87 | ||
88 | <variablelist> | |
64a7fcc5 LP |
89 | <varlistentry> |
90 | <term><option>list</option></term> | |
91 | ||
92 | <listitem><para>Shows all available boot loader entries implementing the <ulink | |
db811444 | 93 | url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink>, as well as any |
64a7fcc5 | 94 | other entries discovered or automatically generated by a boot loader implementing the <ulink |
e12335ba ZJS |
95 | url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>. |
96 | JSON output may be requested with <option>--json=</option>.</para> | |
0d1506d4 | 97 | |
e12335ba | 98 | <para>See the example below for details of the output.</para> |
aefdc112 AK |
99 | |
100 | <xi:include href="version-info.xml" xpointer="v239"/> | |
0d1506d4 | 101 | </listitem> |
64a7fcc5 LP |
102 | </varlistentry> |
103 | ||
eab70618 LP |
104 | <varlistentry> |
105 | <term><option>unlink</option> <replaceable>ID</replaceable></term> | |
106 | ||
107 | <listitem><para>Removes a boot loader entry including the files it refers to. Takes a single boot | |
108 | loader entry ID string or a glob pattern as argument. Referenced files such as kernel or initrd are | |
ec07c3c8 AK |
109 | only removed if no other entry refers to them.</para> |
110 | ||
111 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
eab70618 LP |
112 | </varlistentry> |
113 | ||
114 | <varlistentry> | |
115 | <term><option>cleanup</option></term> | |
116 | ||
117 | <listitem><para>Removes files from the ESP and XBOOTLDR partitions that belong to the entry token but | |
ec07c3c8 AK |
118 | are not referenced in any boot loader entries.</para> |
119 | ||
120 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
eab70618 LP |
121 | </varlistentry> |
122 | </variablelist> | |
123 | </refsect1> | |
124 | ||
125 | <refsect1> | |
126 | <title>Boot Loader Interface Commands</title> | |
127 | ||
128 | <para>These commands are available for all boot loaders that implement the <ulink | |
129 | url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> and the <ulink | |
130 | url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>, such as | |
131 | <command>systemd-boot</command>.</para> | |
132 | ||
133 | <variablelist> | |
64a7fcc5 LP |
134 | <varlistentry> |
135 | <term><option>set-default</option> <replaceable>ID</replaceable></term> | |
136 | <term><option>set-oneshot</option> <replaceable>ID</replaceable></term> | |
137 | ||
0c674ce5 JJ |
138 | <listitem><para>Sets the default boot loader entry. Takes a single boot loader entry ID string or a glob |
139 | pattern as argument. The <option>set-oneshot</option> command will set the default entry only for the next boot, | |
db9eabd6 | 140 | the <option>set-default</option> will set it persistently for all future boots.</para> |
c4b84347 | 141 | |
76c068b7 ZJS |
142 | <para><command>bootctl list</command> can be used to list available boot loader entries and their |
143 | IDs.</para> | |
144 | ||
145 | <para>In addition, the boot loader entry ID may be specified as one of: <option>@default</option>, | |
c4b84347 ДГ |
146 | <option>@oneshot</option> or <option>@current</option>, which correspond to the current default boot loader |
147 | entry for all future boots, the current default boot loader entry for the next boot, and the currently booted | |
148 | boot loader entry. These special IDs are resolved to the current values of the EFI variables | |
149 | <varname>LoaderEntryDefault</varname>, <varname>LoaderEntryOneShot</varname> and <varname>LoaderEntrySelected</varname>, | |
db811444 | 150 | see <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> for details. |
c4b84347 ДГ |
151 | These special IDs are primarily useful as a quick way to persistently make the currently booted boot loader |
152 | entry the default choice, or to upgrade the default boot loader entry for the next boot to the default boot | |
ee4fd9cb JJ |
153 | loader entry for all future boots, but may be used for other operations too.</para> |
154 | ||
155 | <para>If set to <option>@saved</option> the chosen entry will be saved as an EFI variable | |
156 | on every boot and automatically selected the next time the boot loader starts.</para> | |
157 | ||
76c068b7 ZJS |
158 | <para>When an empty string ("") is specified as the ID, then the corresponding EFI variable will be |
159 | unset.</para> | |
160 | ||
161 | <para>Hint: use <command>systemctl reboot --boot-loader-entry=<replaceable>ID</replaceable></command> | |
162 | to reboot into a specific boot entry and | |
163 | <command>systemctl reboot --boot-loader-menu=<replaceable>timeout</replaceable></command> | |
164 | to reboot into the boot loader menu once. See | |
165 | <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
aefdc112 AK |
166 | for details.</para> |
167 | ||
168 | <xi:include href="version-info.xml" xpointer="v240"/></listitem> | |
64a7fcc5 LP |
169 | </varlistentry> |
170 | ||
39ddc32a JJ |
171 | <varlistentry> |
172 | <term><option>set-timeout</option> <replaceable>TIMEOUT</replaceable></term> | |
173 | <term><option>set-timeout-oneshot</option> <replaceable>TIMEOUT</replaceable></term> | |
174 | ||
175 | <listitem><para>Sets the boot loader menu timeout in seconds. The <option>set-timeout-oneshot</option> | |
176 | command will set the timeout only for the next boot. See | |
177 | <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> | |
178 | for details about the syntax of time spans.</para> | |
179 | ||
6efdd7fe EV |
180 | <para>If this is set to <option>menu-disabled</option> or <option>menu-hidden</option> or |
181 | <option>0</option>, no menu is shown and the default entry will be booted immediately, while | |
182 | setting this to <option>menu-force</option> disables the timeout while always showing the menu. | |
183 | When an empty string ("") is specified the bootloader will revert to its default menu timeout.</para> | |
aefdc112 AK |
184 | |
185 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
39ddc32a | 186 | </varlistentry> |
64a7fcc5 LP |
187 | </variablelist> |
188 | </refsect1> | |
189 | ||
190 | <refsect1> | |
191 | <title><command>systemd-boot</command> Commands</title> | |
192 | ||
193 | <para>These commands manage the <command>systemd-boot</command> EFI boot loader, and do not work in | |
194 | conjunction with other boot loaders.</para> | |
195 | ||
196 | <variablelist> | |
c779b82a | 197 | <varlistentry> |
4eb5636b | 198 | <term><option>install</option></term> |
c779b82a | 199 | |
3da2b703 LP |
200 | <listitem><para>Installs <command>systemd-boot</command> into the EFI system partition. A copy of |
201 | <command>systemd-boot</command> will be stored as the EFI default/fallback loader at | |
202 | <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. The boot loader is then added | |
aefdc112 AK |
203 | to the top of the firmware's boot loader list.</para> |
204 | ||
205 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
c779b82a YW |
206 | </varlistentry> |
207 | ||
208 | <varlistentry> | |
4eb5636b | 209 | <term><option>update</option></term> |
c779b82a | 210 | |
4eb5636b LP |
211 | <listitem><para>Updates all installed versions of |
212 | <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, if the | |
213 | available version is newer than the version installed in the EFI system partition. This also includes the EFI | |
214 | default/fallback loader at <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. The boot | |
aefdc112 AK |
215 | loader is then added to end of the firmware's boot loader list if missing.</para> |
216 | ||
217 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
c779b82a YW |
218 | </varlistentry> |
219 | ||
220 | <varlistentry> | |
221 | <term><option>remove</option></term> | |
222 | ||
4eb5636b | 223 | <listitem><para>Removes all installed versions of <command>systemd-boot</command> from the EFI system partition |
aefdc112 AK |
224 | and the firmware's boot loader list.</para> |
225 | ||
226 | <xi:include href="version-info.xml" xpointer="v239"/></listitem> | |
c779b82a YW |
227 | </varlistentry> |
228 | ||
4e5aa791 ZJS |
229 | <varlistentry> |
230 | <term><option>is-installed</option></term> | |
231 | ||
232 | <listitem><para>Checks whether <command>systemd-boot</command> is installed in the ESP. Note that a | |
233 | single ESP might host multiple boot loaders; this hence checks whether | |
234 | <command>systemd-boot</command> is one (of possibly many) installed boot loaders — and neither | |
aefdc112 AK |
235 | whether it is the default nor whether it is registered in any EFI variables.</para> |
236 | ||
237 | <xi:include href="version-info.xml" xpointer="v243"/></listitem> | |
4e5aa791 ZJS |
238 | </varlistentry> |
239 | ||
39867bb9 LP |
240 | <varlistentry> |
241 | <term><option>random-seed</option></term> | |
242 | ||
2d085515 LP |
243 | <listitem><para>Generates a random seed and stores it in the EFI System Partition (ESP), for use by |
244 | the <command>systemd-boot</command> boot loader. If a random seed already exists in the ESP it is | |
245 | refreshed. Also generates a random 'system token' and stores it persistently as an EFI variable, if | |
246 | one has not been set before. If the boot loader finds the random seed in the ESP and the system token | |
247 | in the EFI variable it will derive a random seed to pass to the OS and a new seed to store in the ESP | |
248 | from the combination of both. The random seed passed to the OS is credited to the kernel's entropy | |
249 | pool by the system manager during early boot, and permits userspace to boot up with an entropy pool | |
250 | fully initialized very early on. Also see | |
921fc451 | 251 | <citerefentry><refentrytitle>systemd-boot-random-seed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> |
93f59100 LP |
252 | |
253 | <para>See <ulink url="https://systemd.io/RANDOM_SEEDS">Random Seeds</ulink> for further | |
aefdc112 AK |
254 | information.</para> |
255 | ||
256 | <xi:include href="version-info.xml" xpointer="v243"/></listitem> | |
39867bb9 LP |
257 | </varlistentry> |
258 | ||
c779b82a YW |
259 | </variablelist> |
260 | </refsect1> | |
261 | ||
e1fac8a6 | 262 | <refsect1> |
1e7d6cc0 | 263 | <title>Kernel Image Commands</title> |
53c368d7 GH |
264 | |
265 | <variablelist> | |
266 | <varlistentry> | |
267 | <term><option>kernel-identify</option> <replaceable>kernel</replaceable></term> | |
268 | ||
8072c9c8 ZJS |
269 | <listitem><para>Takes a kernel image as argument. Checks what kind of kernel the image is. Returns |
270 | one of <literal>uki</literal>, <literal>pe</literal>, and <literal>unknown</literal>. | |
ec07c3c8 AK |
271 | </para> |
272 | ||
273 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
53c368d7 | 274 | </varlistentry> |
a0525598 GH |
275 | |
276 | <varlistentry> | |
277 | <term><option>kernel-inspect</option> <replaceable>kernel</replaceable></term> | |
278 | ||
ec07c3c8 AK |
279 | <listitem><para>Takes a kernel image as argument. Prints details about the image.</para> |
280 | ||
281 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
a0525598 | 282 | </varlistentry> |
53c368d7 GH |
283 | </variablelist> |
284 | </refsect1> | |
285 | ||
286 | <refsect1> | |
e1fac8a6 ZJS |
287 | <title>Options</title> |
288 | <para>The following options are understood:</para> | |
289 | ||
290 | <variablelist> | |
4cff5e92 YW |
291 | <xi:include href="standard-options.xml" xpointer="esp-path"/> |
292 | <xi:include href="standard-options.xml" xpointer="boot-path"/> | |
e1fac8a6 | 293 | |
80a2381d LB |
294 | <varlistentry> |
295 | <term><option>--root=<replaceable>root</replaceable></option></term> | |
296 | <listitem><para>Takes a directory path as an argument. All | |
297 | paths will be prefixed with the given alternate | |
298 | <replaceable>root</replaceable> path, including config search | |
ec07c3c8 AK |
299 | paths. </para> |
300 | ||
301 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
80a2381d LB |
302 | </varlistentry> |
303 | ||
304 | <varlistentry> | |
305 | <term><option>--image=<replaceable>image</replaceable></option></term> | |
306 | ||
15102ced ZJS |
307 | <listitem><para>Takes a path to a disk image file or block device node. If specified, all operations |
308 | are applied to file system in the indicated disk image. This option is similar to | |
309 | <option>--root=</option>, but operates on file systems stored in disk images or block devices. The | |
310 | disk image should either contain just a file system or a set of file systems within a GPT partition | |
db811444 | 311 | table, following the <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions |
80a2381d LB |
312 | Specification</ulink>. For further information on supported disk images, see |
313 | <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s | |
ec07c3c8 AK |
314 | switch of the same name.</para> |
315 | ||
316 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
80a2381d LB |
317 | </varlistentry> |
318 | ||
9ea81191 LP |
319 | <xi:include href="standard-options.xml" xpointer="image-policy-open" /> |
320 | ||
02d06ba1 LB |
321 | <varlistentry> |
322 | <term><option>--install-source=</option></term> | |
323 | <listitem><para>When installing binaries with <option>--root=</option> or | |
324 | <option>--image=</option>, selects where to source them from. Takes one of <literal>auto</literal> | |
325 | (the default), <literal>image</literal> or <literal>host</literal>. With <literal>auto</literal> | |
326 | binaries will be picked from the specified directory or image, and if not found they will be picked | |
327 | from the host. With <literal>image</literal> or <literal>host</literal> no fallback search will be | |
ec07c3c8 AK |
328 | performed if the binaries are not found in the selected source.</para> |
329 | ||
330 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
02d06ba1 LB |
331 | </varlistentry> |
332 | ||
e1fac8a6 ZJS |
333 | <varlistentry> |
334 | <term><option>-p</option></term> | |
335 | <term><option>--print-esp-path</option></term> | |
336 | <listitem><para>This option modifies the behaviour of <command>status</command>. Only prints the path | |
aefdc112 AK |
337 | to the EFI System Partition (ESP) to standard output and exits.</para> |
338 | ||
339 | <xi:include href="version-info.xml" xpointer="v236"/></listitem> | |
e1fac8a6 ZJS |
340 | </varlistentry> |
341 | ||
342 | <varlistentry> | |
343 | <term><option>-x</option></term> | |
344 | <term><option>--print-boot-path</option></term> | |
345 | <listitem><para>This option modifies the behaviour of <command>status</command>. Only prints the path | |
346 | to the Extended Boot Loader partition if it exists, and the path to the ESP otherwise to standard | |
347 | output and exit. This command is useful to determine where to place boot loader entries, as they are | |
348 | preferably placed in the Extended Boot Loader partition if it exists and in the ESP otherwise.</para> | |
349 | ||
350 | <para>Boot Loader Specification Type #1 entries should generally be placed in the directory | |
351 | <literal>$(bootctl -x)/loader/entries/</literal>. Existence of that directory may also be used as | |
352 | indication that boot loader entry support is available on the system. Similarly, Boot Loader | |
353 | Specification Type #2 entries should be placed in the directory <literal>$(bootctl | |
354 | -x)/EFI/Linux/</literal>.</para> | |
355 | ||
f8b7ff84 | 356 | <para>Note that this option (similarly to the <option>--print-boot-path</option> option mentioned |
e1fac8a6 | 357 | above), is available independently from the boot loader used, i.e. also without |
aefdc112 AK |
358 | <command>systemd-boot</command> being installed.</para> |
359 | ||
360 | <xi:include href="version-info.xml" xpointer="v242"/></listitem> | |
e1fac8a6 ZJS |
361 | </varlistentry> |
362 | ||
c56be2c2 LP |
363 | <varlistentry> |
364 | <term><option>-R</option></term> | |
365 | <term><option>--print-root-device</option></term> | |
366 | ||
367 | <listitem><para>Print the path to the block device node backing the root file system of the local | |
368 | OS. This prints a path such as <filename>/dev/nvme0n1p5</filename>. If the root file system is backed | |
369 | by dm-crypt/LUKS or dm-verity the underlying block device is returned. If the root file system is | |
370 | backed by multiple block devices (as supported by btrfs) the operation will fail. If the switch is | |
371 | specified twice (i.e. <option>-RR</option>) and the discovered block device is a partition device the | |
372 | "whole" block device it belongs to is determined and printed | |
373 | (e.g. <filename>/dev/nvme0n1</filename>). If the root file system is <literal>tmpfs</literal> (or a | |
374 | similar in-memory file system), the block device backing <filename>/usr/</filename> is returned if | |
375 | applicable. If the root file system is a network file system (e.g. NFS, CIFS) the operation will | |
ec07c3c8 AK |
376 | fail.</para> |
377 | ||
378 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
c56be2c2 LP |
379 | </varlistentry> |
380 | ||
e1fac8a6 ZJS |
381 | <varlistentry> |
382 | <term><option>--no-variables</option></term> | |
ec07c3c8 AK |
383 | <listitem><para>Do not touch the firmware's boot loader list stored in EFI variables.</para> |
384 | ||
385 | <xi:include href="version-info.xml" xpointer="v220"/></listitem> | |
e1fac8a6 ZJS |
386 | </varlistentry> |
387 | ||
351de38e LP |
388 | <varlistentry> |
389 | <term><option>--graceful</option></term> | |
e5a8b4b5 LP |
390 | <listitem><para>Ignore failure when the EFI System Partition cannot be found, when EFI variables |
391 | cannot be written, or a different or newer boot loader is already installed. Currently only applies | |
18eb56c3 | 392 | to <command>is-installed</command>, <command>update</command>, and <command>random-seed</command> |
ec07c3c8 AK |
393 | verbs.</para> |
394 | ||
395 | <xi:include href="version-info.xml" xpointer="v244"/></listitem> | |
351de38e LP |
396 | </varlistentry> |
397 | ||
14e6e444 ZJS |
398 | <varlistentry> |
399 | <term><option>-q</option></term> | |
400 | <term><option>--quiet</option></term> | |
401 | ||
402 | <listitem><para>Suppress printing of the results of various commands and also the hints about ESP | |
ec07c3c8 AK |
403 | being unavailable.</para> |
404 | ||
405 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
14e6e444 ZJS |
406 | </varlistentry> |
407 | ||
6a3fff75 | 408 | <varlistentry> |
f337f903 LP |
409 | <term><option>--make-entry-directory=yes|no</option></term> |
410 | <listitem><para>Controls creation and deletion of the <ulink | |
db811444 | 411 | url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> Type #1 entry |
b66a6e1a ZJS |
412 | directory on the file system containing resources such as kernel and initrd images during |
413 | <option>install</option> and <option>remove</option>, respectively. The directory is named after the | |
414 | entry token, as specified with <option>--entry-token=</option> parameter described below, and is | |
415 | placed immediately below the <varname>$BOOT</varname> root directory (i.e. beneath the file system | |
416 | returned by the <option>--print-boot-path</option> option, see above). Defaults to | |
ec07c3c8 AK |
417 | <literal>no</literal>.</para> |
418 | ||
419 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
f337f903 LP |
420 | </varlistentry> |
421 | ||
422 | <varlistentry> | |
423 | <term><option>--entry-token=</option></term> | |
424 | ||
425 | <listitem><para>Controls how to name and identify boot loader entries for this OS | |
426 | installation. Accepted during <option>install</option>, and takes one of <literal>auto</literal>, | |
427 | <literal>machine-id</literal>, <literal>os-id</literal>, <literal>os-image-id</literal> or an | |
428 | arbitrary string prefixed by <literal>literal:</literal> as argument.</para> | |
429 | ||
430 | <para>If set to <option>machine-id</option> the entries are named after the machine ID of the running | |
431 | system (e.g. <literal>b0e793a9baf14b5fa13ecbe84ff637ac</literal>). See | |
7eea910d LP |
432 | <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for |
433 | details about the machine ID concept and file.</para> | |
434 | ||
f337f903 LP |
435 | <para>If set to <option>os-id</option> the entries are named after the OS ID of the running system, |
436 | i.e. the <varname>ID=</varname> field of | |
15102ced ZJS |
437 | <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> (e.g. |
438 | <literal>fedora</literal>). Similarly, if set to <option>os-image-id</option> the entries are named | |
439 | after the OS image ID of the running system, i.e. the <varname>IMAGE_ID=</varname> field of | |
f337f903 LP |
440 | <filename>os-release</filename> (e.g. <literal>vendorx-cashier-system</literal>).</para> |
441 | ||
442 | <para>If set to <option>auto</option> (the default), the <filename>/etc/kernel/entry-token</filename> | |
443 | file will be read if it exists, and the stored value used. Otherwise if the local machine ID is | |
444 | initialized it is used. Otherwise <varname>IMAGE_ID=</varname> from <filename>os-release</filename> | |
445 | will be used, if set. Otherwise, <varname>ID=</varname> from <filename>os-release</filename> will be | |
446 | used, if set.</para> | |
447 | ||
448 | <para>Unless set to <literal>machine-id</literal>, or when | |
449 | <option>--make-entry-directory=yes</option> is used the selected token string is written to a file | |
450 | <filename>/etc/kernel/entry-token</filename>, to ensure it will be used for future entries. This file | |
451 | is also read by | |
452 | <citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
453 | in order to identify under which name to generate boot loader entries for newly installed kernels, or | |
454 | to determine the entry names for removing old ones.</para> | |
455 | ||
456 | <para>Using the machine ID for naming the entries is generally preferable, however there are cases | |
457 | where using the other identifiers is a good option. Specifically: if the identification data that the | |
458 | machine ID entails shall not be stored on the (unencrypted) <varname>$BOOT</varname> partition, or if | |
459 | the ID shall be generated on first boot and is not known when the entries are prepared. Note that | |
460 | using the machine ID has the benefit that multiple parallel installations of the same OS can coexist | |
461 | on the same medium, and they can update their boot loader entries independently. When using another | |
462 | identifier (such as the OS ID or the OS image ID), parallel installations of the same OS would try to | |
463 | use the same entry name. To support parallel installations, the installer must use a different entry | |
ec07c3c8 AK |
464 | token when adding a second installation.</para> |
465 | ||
466 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
6a3fff75 | 467 | </varlistentry> |
468 | ||
6e916539 JJ |
469 | <varlistentry> |
470 | <term><option>--all-architectures</option></term> | |
ec07c3c8 AK |
471 | <listitem><para>Install binaries for all supported EFI architectures (this implies <option>--no-variables</option>).</para> |
472 | ||
473 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
6e916539 JJ |
474 | </varlistentry> |
475 | ||
d9bdb29b RH |
476 | <varlistentry> |
477 | <term><option>--efi-boot-option-description=</option></term> | |
478 | <listitem><para>Description of the entry added to the firmware's boot option list. Defaults to <literal>Linux | |
479 | Boot Manager</literal>.</para> | |
480 | ||
481 | <para>Using the default entry name <literal>Linux Boot Manager</literal> is generally preferable as only | |
482 | one bootloader installed to a single ESP partition should be used to boot any number of OS installations | |
483 | found on the various disks installed in the system. Specifically distributions should not use this flag | |
484 | to install a branded entry in the boot option list. However in situations with multiple disks, each with | |
485 | their own ESP partition, it can be beneficial to make it easier to identify the bootloader being used in | |
ec07c3c8 AK |
486 | the firmware's boot option menu.</para> |
487 | ||
488 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
d9bdb29b RH |
489 | </varlistentry> |
490 | ||
8702496b LN |
491 | <varlistentry> |
492 | <term><option>--dry-run</option></term> | |
1bc116a1 | 493 | <listitem><para>Dry run for <option>unlink</option> and <option>cleanup</option>.</para> |
8702496b LN |
494 | |
495 | <para>In dry run mode, the unlink and cleanup operations only print the files that would get deleted | |
ec07c3c8 AK |
496 | without actually deleting them.</para> |
497 | ||
498 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
8702496b LN |
499 | </varlistentry> |
500 | ||
e1fac8a6 | 501 | <xi:include href="standard-options.xml" xpointer="no-pager"/> |
0d1506d4 | 502 | <xi:include href="standard-options.xml" xpointer="json" /> |
e1fac8a6 ZJS |
503 | <xi:include href="standard-options.xml" xpointer="help"/> |
504 | <xi:include href="standard-options.xml" xpointer="version"/> | |
505 | </variablelist> | |
506 | </refsect1> | |
507 | ||
12caf727 ДГ |
508 | <refsect1> |
509 | <title>Signed .efi files</title> | |
510 | <para><command>bootctl</command> <option>install</option> and <option>update</option> will look for a | |
511 | <command>systemd-boot</command> file ending with the <literal>.efi.signed</literal> suffix first, and copy | |
512 | that instead of the normal <literal>.efi</literal> file. This allows distributions or end-users to provide | |
513 | signed images for UEFI SecureBoot.</para> | |
514 | </refsect1> | |
515 | ||
798d3a52 ZJS |
516 | <refsect1> |
517 | <title>Exit status</title> | |
c56be2c2 LP |
518 | <para>On success, 0 is returned, a non-zero failure code otherwise. <command>bootctl |
519 | --print-root-device</command> returns exit status 80 in case the root file system is not backed by single | |
60c5bd77 | 520 | block device, and other non-zero exit statuses on other errors.</para> |
798d3a52 ZJS |
521 | </refsect1> |
522 | ||
8cbb7d87 LP |
523 | <refsect1> |
524 | <title>Environment</title> | |
3da2b703 LP |
525 | <para>If <varname>$SYSTEMD_RELAX_ESP_CHECKS=1</varname> is set the validation checks for the ESP are |
526 | relaxed, and the path specified with <option>--esp-path=</option> may refer to any kind of file system on | |
527 | any kind of partition.</para> | |
528 | ||
529 | <para>Similarly, <varname>$SYSTEMD_RELAX_XBOOTLDR_CHECKS=1</varname> turns off some validation checks for | |
530 | the Extended Boot Loader partition.</para> | |
8cbb7d87 LP |
531 | </refsect1> |
532 | ||
e12335ba ZJS |
533 | <refsect1> |
534 | <title>Examples</title> | |
535 | ||
536 | <example> | |
537 | <title>Output from <command>status</command> and <command>list</command></title> | |
538 | ||
539 | <programlisting>$ <command>bootctl status</command> | |
540 | System: | |
541 | Firmware: UEFI 2.40 (<replaceable>firmware-version</replaceable>) ← firmware vendor and version | |
8b9f0921 | 542 | Secure Boot: disabled (setup) ← Secure Boot status |
e12335ba ZJS |
543 | TPM2 Support: yes |
544 | Boot into FW: supported ← does the firmware support booting into itself | |
545 | ||
546 | Current Boot Loader: ← details about sd-boot or another boot loader | |
547 | Product: systemd-boot <replaceable>version</replaceable> implementing the <ulink | |
548 | url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink> | |
549 | Features: ✓ Boot counting | |
550 | ✓ Menu timeout control | |
551 | ✓ One-shot menu timeout control | |
552 | ✓ Default entry control | |
553 | ✓ One-shot entry control | |
554 | ✓ Support for XBOOTLDR partition | |
555 | ✓ Support for passing random seed to OS | |
556 | ✓ Load drop-in drivers | |
557 | ✓ Boot loader sets ESP information | |
6efdd7fe | 558 | ✓ Menu can be disabled |
e12335ba ZJS |
559 | ESP: /dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000 |
560 | File: └─/EFI/systemd/systemd-bootx64.efi | |
561 | ||
562 | Random Seed: ← random seed used for entropy in early boot | |
563 | Passed to OS: yes | |
564 | System Token: set | |
565 | Exists: yes | |
566 | ||
567 | Available Boot Loaders on ESP: | |
568 | ESP: /boot/efi (/dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000) | |
569 | File: └─/EFI/systemd/systemd-bootx64.efi (systemd-boot 251 | |
570 | File: └─/EFI/BOOT/BOOTX64.EFI (systemd-boot 251 | |
571 | ||
572 | Boot Loaders Listed in EFI Variables: | |
573 | Title: Linux Boot Manager | |
574 | ID: 0x0001 | |
575 | Status: active, boot-order | |
576 | Partition: /dev/disk/by-partuuid/… | |
577 | File: └─/EFI/systemd/systemd-bootx64.efi | |
578 | ||
579 | Title: Fedora | |
580 | ID: 0x0000 | |
581 | Status: active, boot-order | |
582 | Partition: /dev/disk/by-partuuid/… | |
583 | File: └─/EFI/fedora/shimx64.efi | |
584 | ||
585 | Title: Linux-Firmware-Updater | |
586 | ID: 0x0002 | |
587 | Status: active, boot-order | |
588 | Partition: /dev/disk/by-partuuid/… | |
589 | File: └─/EFI/fedora/fwupdx64.efi | |
590 | ||
591 | Boot Loader Entries: | |
592 | $BOOT: /boot/efi (/dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000) | |
593 | ||
594 | Default Boot Loader Entry: | |
595 | type: Boot Loader Specification Type #1 (.conf) | |
596 | title: Fedora Linux 36 (Workstation Edition) | |
597 | id: … | |
598 | source: /boot/efi/loader/entries/<replaceable>entry-token</replaceable>-<replaceable>kernel-version</replaceable>.conf | |
599 | version: <replaceable>kernel-version</replaceable> | |
600 | machine-id: … | |
601 | linux: /<replaceable>entry-token</replaceable>/<replaceable>kernel-version</replaceable>/linux | |
602 | initrd: /<replaceable>entry-token</replaceable>/<replaceable>kernel-version</replaceable>/initrd | |
603 | options: root=… | |
604 | </programlisting> | |
605 | ||
606 | <programlisting>$ <command>bootctl list</command> | |
607 | Boot Loader Entries: | |
608 | type: Boot Loader Specification Type #1 (.conf) | |
609 | title: Fedora Linux 36 (Workstation Edition) (default) (selected) | |
610 | id: … | |
611 | source: /boot/efi/loader/entries/<replaceable>entry-token</replaceable>-<replaceable>kernel-version</replaceable>.conf | |
612 | version: <replaceable>kernel-version</replaceable> | |
613 | machine-id: … | |
614 | linux: /<replaceable>entry-token</replaceable>/<replaceable>kernel-version</replaceable>/linux | |
615 | initrd: /<replaceable>entry-token</replaceable>/<replaceable>kernel-version</replaceable>/initrd | |
616 | options: root=… | |
617 | ||
618 | type: Boot Loader Specification Type #2 (.efi) | |
619 | title: Fedora Linux 35 (Workstation Edition) | |
620 | id: … | |
621 | source: /boot/efi/EFI/Linux/fedora-<replaceable>kernel-version</replaceable>.efi | |
622 | version: <replaceable>kernel-version</replaceable> | |
623 | machine-id: … | |
624 | linux: /EFI/Linux/fedora-<replaceable>kernel-version</replaceable>.efi | |
625 | options: root=… | |
626 | ||
627 | type: Automatic | |
628 | title: Reboot Into Firmware Interface | |
629 | id: auto-reboot-to-firmware-setup | |
630 | source: /sys/firmware/efi/efivars/LoaderEntries-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f | |
631 | </programlisting> | |
632 | ||
633 | <para>In the listing, <literal>(default)</literal> specifies the entry that will be | |
634 | used by default, and <literal>(selected)</literal> specifies the entry that was | |
635 | selected the last time (i.e. is currently running).</para> | |
636 | </example> | |
637 | </refsect1> | |
638 | ||
798d3a52 ZJS |
639 | <refsect1> |
640 | <title>See Also</title> | |
13a69c12 DT |
641 | <para><simplelist type="inline"> |
642 | <member><citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry></member> | |
643 | <member><ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink></member> | |
644 | <member><ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink></member> | |
645 | <member><citerefentry><refentrytitle>systemd-boot-random-seed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
646 | </simplelist></para> | |
798d3a52 | 647 | </refsect1> |
1bc64d77 | 648 | </refentry> |