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