1BOOTCTL(1) bootctl BOOTCTL(1)
2
6 bootctl - Control EFI firmware boot settings and manage boot loader
7
9 bootctl [OPTIONS...] {COMMAND}
10
12 bootctl can check the EFI firmware and boot loader status, list and
13 manage available boot loaders and boot loader entries, and install,
14 update, or remove the systemd-boot(7) boot loader on the current
15 system.
16
18 These commands are available on any EFI system, regardless of the boot
19 loader used.
20 status
22 Shows brief information about the system firmware, the boot loader
23 that was used to boot the system, the boot loaders currently
24 available in the ESP, the boot loaders listed in the firmware's
25 list of boot loaders and the current default boot loader entry. If
26 no command is specified, this is the implied default.
27 See the example below for details of the output.
29 reboot-to-firmware [BOOL]
31 Query or set the "Reboot-Into-Firmware-Setup" flag of the EFI
32 firmware. Takes a boolean argument which controls whether to show
33 the firmware setup on next system reboot. If the argument is
34 omitted shows the current status of the flag, or whether the flag
35 is supported. This controls the same flag as systemctl reboot
36 --firmware-setup, but is more low-level and allows setting the flag
37 independently from actually requesting a reboot.
38 Hint: use systemctl reboot --firmware-setup to reboot into firmware
40 setup once. See systemctl(1) for details.
41 systemd-efi-options [STRING]
43 When called without the optional argument, prints the current value
44 of the "SystemdOptions" EFI variable. When called with an argument,
45 sets the variable to that value. See systemd(1) for the meaning of
46 that variable.
47
49 These commands are available for all boot loaders that implement the
50 Boot Loader Specification[1], such as systemd-boot.
51 list
53 Shows all available boot loader entries implementing the Boot
54 Loader Specification[1], as well as any other entries discovered or
55 automatically generated by a boot loader implementing the Boot
56 Loader Interface[2]. JSON output may be requested with --json=.
57 See the example below for details of the output.
59 unlink ID
61 Removes a boot loader entry including the files it refers to. Takes
62 a single boot loader entry ID string or a glob pattern as argument.
63 Referenced files such as kernel or initrd are only removed if no
64 other entry refers to them.
65 cleanup
67 Removes files from the ESP and XBOOTLDR partitions that belong to
68 the entry token but are not referenced in any boot loader entries.
69
71 These commands are available for all boot loaders that implement the
72 Boot Loader Specification[1] and the Boot Loader Interface[2], such as
73 systemd-boot.
74 set-default ID, set-oneshot ID
76 Sets the default boot loader entry. Takes a single boot loader
77 entry ID string or a glob pattern as argument. The set-oneshot
78 command will set the default entry only for the next boot, the
79 set-default will set it persistently for all future boots.
80 bootctl list can be used to list available boot loader entries and
82 their IDs.
83 In addition, the boot loader entry ID may be specified as one of:
85 @default, @oneshot or @current, which correspond to the current
86 default boot loader entry for all future boots, the current default
87 boot loader entry for the next boot, and the currently booted boot
88 loader entry. These special IDs are resolved to the current values
89 of the EFI variables LoaderEntryDefault, LoaderEntryOneShot and
90 LoaderEntrySelected, see Boot Loader Specification[1] for details.
91 These special IDs are primarily useful as a quick way to
92 persistently make the currently booted boot loader entry the
93 default choice, or to upgrade the default boot loader entry for the
94 next boot to the default boot loader entry for all future boots,
95 but may be used for other operations too.
96 If set to @saved the chosen entry will be saved as an EFI variable
98 on every boot and automatically selected the next time the boot
99 loader starts.
100 When an empty string ("") is specified as the ID, then the
102 corresponding EFI variable will be unset.
103 Hint: use systemctl reboot --boot-loader-entry=ID to reboot into a
105 specific boot entry and systemctl reboot --boot-loader-menu=timeout
106 to reboot into the boot loader menu once. See systemctl(1) for
107 details.
108 set-timeout TIMEOUT, set-timeout-oneshot TIMEOUT
110 Sets the boot loader menu timeout in seconds. The
111 set-timeout-oneshot command will set the timeout only for the next
112 boot. See systemd.time(7) for details about the syntax of time
113 spans.
114 If this is set to menu-hidden or 0 no menu is shown and the default
116 entry will be booted immediately, while setting this to menu-force
117 disables the timeout while always showing the menu. When an empty
118 string ("") is specified the bootloader will revert to its default
119 menu timeout.
120
122 These commands manage the systemd-boot EFI boot loader, and do not work
123 in conjunction with other boot loaders.
124 install
126 Installs systemd-boot into the EFI system partition. A copy of
127 systemd-boot will be stored as the EFI default/fallback loader at
128 ESP/EFI/BOOT/BOOT*.EFI. The boot loader is then added to the top of
129 the firmware's boot loader list.
130 update
132 Updates all installed versions of systemd-boot(7), if the available
133 version is newer than the version installed in the EFI system
134 partition. This also includes the EFI default/fallback loader at
135 ESP/EFI/BOOT/BOOT*.EFI. The boot loader is then added to end of the
136 firmware's boot loader list if missing.
137 remove
139 Removes all installed versions of systemd-boot from the EFI system
140 partition and the firmware's boot loader list.
141 is-installed
143 Checks whether systemd-boot is installed in the ESP. Note that a
144 single ESP might host multiple boot loaders; this hence checks
145 whether systemd-boot is one (of possibly many) installed boot
146 loaders — and neither whether it is the default nor whether it is
147 registered in any EFI variables.
148 random-seed
150 Generates a random seed and stores it in the EFI System Partition,
151 for use by the systemd-boot boot loader. Also, generates a random
152 'system token' and stores it persistently as an EFI variable, if
153 one has not been set before. If the boot loader finds the random
154 seed in the ESP and the system token in the EFI variable it will
155 derive a random seed to pass to the OS and a new seed to store in
156 the ESP from the combination of both. The random seed passed to the
157 OS is credited to the kernel's entropy pool by the system manager
158 during early boot, and permits userspace to boot up with an entropy
159 pool fully initialized very early on. Also see systemd-boot-random-
160 seed.service(8).
161 See Random Seeds[3] for further information.
163
165 kernel-identify kernel
166 Takes a kernel image as argument. Checks what kind of kernel the
167 image is. Returns one of "uki", "pe", and "unknown".
168 kernel-inspect kernel
170 Takes a kernel image as argument. Prints details about the image.
171
173 The following options are understood:
174 --esp-path=
176 Path to the EFI System Partition (ESP). If not specified, /efi/,
177 /boot/, and /boot/efi/ are checked in turn. It is recommended to
178 mount the ESP to /efi/, if possible.
179 --boot-path=
181 Path to the Extended Boot Loader partition, as defined in the Boot
182 Loader Specification[1]. If not specified, /boot/ is checked. It is
183 recommended to mount the Extended Boot Loader partition to /boot/,
184 if possible.
185 --root=root
187 Takes a directory path as an argument. All paths will be prefixed
188 with the given alternate root path, including config search paths.
189 --image=image
191 Takes a path to a disk image file or block device node. If
192 specified, all operations are applied to file system in the
193 indicated disk image. This option is similar to --root=, but
194 operates on file systems stored in disk images or block devices.
195 The disk image should either contain just a file system or a set of
196 file systems within a GPT partition table, following the
197 Discoverable Partitions Specification[4]. For further information
198 on supported disk images, see systemd-nspawn(1)'s switch of the
199 same name.
200 --install-source=
202 When installing binaries with --root= or --image=, selects where to
203 source them from. Takes one of "auto" (the default), "image" or
204 "host". With "auto" binaries will be picked from the specified
205 directory or image, and if not found they will be picked from the
206 host. With "image" or "host" no fallback search will be performed
207 if the binaries are not found in the selected source.
208 -p, --print-esp-path
210 This option modifies the behaviour of status. Only prints the path
211 to the EFI System Partition (ESP) to standard output and exits.
212 -x, --print-boot-path
214 This option modifies the behaviour of status. Only prints the path
215 to the Extended Boot Loader partition if it exists, and the path to
216 the ESP otherwise to standard output and exit. This command is
217 useful to determine where to place boot loader entries, as they are
218 preferably placed in the Extended Boot Loader partition if it
219 exists and in the ESP otherwise.
220 Boot Loader Specification Type #1 entries should generally be
222 placed in the directory "$(bootctl -x)/loader/entries/". Existence
223 of that directory may also be used as indication that boot loader
224 entry support is available on the system. Similarly, Boot Loader
225 Specification Type #2 entries should be placed in the directory
226 "$(bootctl -x)/EFI/Linux/".
227 Note that this option (similarly to the --print-booth-path option
229 mentioned above), is available independently from the boot loader
230 used, i.e. also without systemd-boot being installed.
231 --no-variables
233 Do not touch the firmware's boot loader list stored in EFI
234 variables.
235 --graceful
237 Ignore failure when the EFI System Partition cannot be found, when
238 EFI variables cannot be written, or a different or newer boot
239 loader is already installed. Currently only applies to
240 is-installed, update, and random-seed verbs.
241 -q, --quiet
243 Suppress printing of the results of various commands and also the
244 hints about ESP being unavailable.
245 --make-entry-directory=yes|no
247 Controls creation and deletion of the Boot Loader Specification[1]
248 Type #1 entry directory on the file system containing resources
249 such as kernel and initrd images during install and remove,
250 respectively. The directory is named after the entry token, as
251 specified with --entry-token= parameter described below, and is
252 placed immediately below the $BOOT root directory (i.e. beneath the
253 file system returned by the --print-boot-path option, see above).
254 Defaults to "no".
255 --entry-token=
257 Controls how to name and identify boot loader entries for this OS
258 installation. Accepted during install, and takes one of "auto",
259 "machine-id", "os-id", "os-image-id" or an arbitrary string
260 prefixed by "literal:" as argument.
261 If set to machine-id the entries are named after the machine ID of
263 the running system (e.g. "b0e793a9baf14b5fa13ecbe84ff637ac"). See
264 machine-id(5) for details about the machine ID concept and file.
265 If set to os-id the entries are named after the OS ID of the
267 running system, i.e. the ID= field of os-release(5) (e.g.
268 "fedora"). Similarly, if set to os-image-id the entries are named
269 after the OS image ID of the running system, i.e. the IMAGE_ID=
270 field of os-release (e.g. "vendorx-cashier-system").
271 If set to auto (the default), the /etc/kernel/entry-token file will
273 be read if it exists, and the stored value used. Otherwise if the
274 local machine ID is initialized it is used. Otherwise IMAGE_ID=
275 from os-release will be used, if set. Otherwise, ID= from
276 os-release will be used, if set.
277 Unless set to "machine-id", or when --make-entry-directory=yes is
279 used the selected token string is written to a file
280 /etc/kernel/entry-token, to ensure it will be used for future
281 entries. This file is also read by kernel-install(8), in order to
282 identify under which name to generate boot loader entries for newly
283 installed kernels, or to determine the entry names for removing old
284 ones.
285 Using the machine ID for naming the entries is generally
287 preferable, however there are cases where using the other
288 identifiers is a good option. Specifically: if the identification
289 data that the machine ID entails shall not be stored on the
290 (unencrypted) $BOOT partition, or if the ID shall be generated on
291 first boot and is not known when the entries are prepared. Note
292 that using the machine ID has the benefit that multiple parallel
293 installations of the same OS can coexist on the same medium, and
294 they can update their boot loader entries independently. When using
295 another identifier (such as the OS ID or the OS image ID), parallel
296 installations of the same OS would try to use the same entry name.
297 To support parallel installations, the installer must use a
298 different entry token when adding a second installation.
299 --all-architectures
301 Install binaries for all supported EFI architectures (this implies
302 --no-variables).
303 --efi-boot-option-description=
305 Description of the entry added to the firmware's boot option list.
306 Defaults to "Linux Boot Manager".
307 Using the default entry name "Linux Boot Manager" is generally
309 preferable as only one bootloader installed to a single ESP
310 partition should be used to boot any number of OS installations
311 found on the various disks installed in the system. Specifically
312 distributions should not use this flag to install a branded entry
313 in the boot option list. However in situations with multiple disks,
314 each with their own ESP partition, it can be beneficial to make it
315 easier to identify the bootloader being used in the firmware's boot
316 option menu.
317 --dry-run
319 Dry run for --unlink and --cleanup.
320 In dry run mode, the unlink and cleanup operations only print the
322 files that would get deleted without actually deleting them.
323 --no-pager
325 Do not pipe output into a pager.
326 --json=MODE
328 Shows output formatted as JSON. Expects one of "short" (for the
329 shortest possible output without any redundant whitespace or line
330 breaks), "pretty" (for a pretty version of the same, with
331 indentation and line breaks) or "off" (to turn off JSON output, the
332 default).
333 -h, --help
335 Print a short help text and exit.
336 --version
338 Print a short version string and exit.
339
341 bootctl install and update will look for a systemd-boot file ending
342 with the ".efi.signed" suffix first, and copy that instead of the
343 normal ".efi" file. This allows distributions or end-users to provide
344 signed images for UEFI SecureBoot.
345
347 On success, 0 is returned, a non-zero failure code otherwise.
348
350 If $SYSTEMD_RELAX_ESP_CHECKS=1 is set the validation checks for the ESP
351 are relaxed, and the path specified with --esp-path= may refer to any
352 kind of file system on any kind of partition.
353 Similarly, $SYSTEMD_RELAX_XBOOTLDR_CHECKS=1 turns off some validation
355 checks for the Extended Boot Loader partition.
356
358 Example 1. Output from status and list
359 $ bootctl status
361 System:
362 Firmware: UEFI 2.40 (firmware-version) ← firmware vendor and version
363 Secure Boot: disabled (setup) ← Secure Boot status
364 TPM2 Support: yes
365 Boot into FW: supported ← does the firmware support booting into itself
366 Current Boot Loader: ← details about sd-boot or another boot loader
368 Product: systemd-boot version implementing the Boot Loader Interface[2]
369 Features: ✓ Boot counting
370 ✓ Menu timeout control
371 ✓ One-shot menu timeout control
372 ✓ Default entry control
373 ✓ One-shot entry control
374 ✓ Support for XBOOTLDR partition
375 ✓ Support for passing random seed to OS
376 ✓ Load drop-in drivers
377 ✓ Boot loader sets ESP information
378 ESP: /dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000
379 File: └─/EFI/systemd/systemd-bootx64.efi
380 Random Seed: ← random seed used for entropy in early boot
382 Passed to OS: yes
383 System Token: set
384 Exists: yes
385 Available Boot Loaders on ESP:
387 ESP: /boot/efi (/dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000)
388 File: └─/EFI/systemd/systemd-bootx64.efi (systemd-boot 251
389 File: └─/EFI/BOOT/BOOTX64.EFI (systemd-boot 251
390 Boot Loaders Listed in EFI Variables:
392 Title: Linux Boot Manager
393 ID: 0x0001
394 Status: active, boot-order
395 Partition: /dev/disk/by-partuuid/...
396 File: └─/EFI/systemd/systemd-bootx64.efi
397 Title: Fedora
399 ID: 0x0000
400 Status: active, boot-order
401 Partition: /dev/disk/by-partuuid/...
402 File: └─/EFI/fedora/shimx64.efi
403 Title: Linux-Firmware-Updater
405 ID: 0x0002
406 Status: active, boot-order
407 Partition: /dev/disk/by-partuuid/...
408 File: └─/EFI/fedora/fwupdx64.efi
409 Boot Loader Entries:
411 $BOOT: /boot/efi (/dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000)
412 Default Boot Loader Entry:
414 type: Boot Loader Specification Type #1 (.conf)
415 title: Fedora Linux 36 (Workstation Edition)
416 id: ...
417 source: /boot/efi/loader/entries/entry-token-kernel-version.conf
418 version: kernel-version
419 machine-id: ...
420 linux: /entry-token/kernel-version/linux
421 initrd: /entry-token/kernel-version/initrd
422 options: root=...
423 $ bootctl list
425 Boot Loader Entries:
426 type: Boot Loader Specification Type #1 (.conf)
427 title: Fedora Linux 36 (Workstation Edition) (default) (selected)
428 id: ...
429 source: /boot/efi/loader/entries/entry-token-kernel-version.conf
430 version: kernel-version
431 machine-id: ...
432 linux: /entry-token/kernel-version/linux
433 initrd: /entry-token/kernel-version/initrd
434 options: root=...
435 type: Boot Loader Specification Type #2 (.efi)
437 title: Fedora Linux 35 (Workstation Edition)
438 id: ...
439 source: /boot/efi/EFI/Linux/fedora-kernel-version.efi
440 version: kernel-version
441 machine-id: ...
442 linux: /EFI/Linux/fedora-kernel-version.efi
443 options: root=...
444 type: Automatic
446 title: Reboot Into Firmware Interface
447 id: auto-reboot-to-firmware-setup
448 source: /sys/firmware/efi/efivars/LoaderEntries-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
449 In the listing, "(default)" specifies the entry that will be used by
451 default, and "(selected)" specifies the entry that was selected the
452 last time (i.e. is currently running).
453
455 systemd-boot(7), Boot Loader Specification[1], Boot Loader
456 Interface[2], systemd-boot-random-seed.service(8)
457
459 1. Boot Loader Specification
460 https://uapi-group.org/specifications/specs/boot_loader_specification
461 2. Boot Loader Interface
463 https://systemd.io/BOOT_LOADER_INTERFACE
464 3. Random Seeds
466 https://systemd.io/RANDOM_SEEDS
467 4. Discoverable Partitions Specification
469 https://uapi-group.org/specifications/specs/discoverable_partitions_specification
470systemd 253 BOOTCTL(1)