The rEFInd Boot Manager:
Configuring the Boot Manager

by Roderick W. Smith, rodsmith@rodsbooks.com

Originally written: March 14, 2012; last Web page update: April 6, 2024, referencing rEFInd 0.14.2

This Web page is provided free of charge and with no annoying outside ads; however, I did take time to prepare it, and Web hosting does cost money. If you find this Web page useful, please consider making a small donation to help keep this site up and running. Thanks!

This page is part of the documentation for the rEFInd boot manager. If a Web search has brought you here, you may want to start at the main page.

Many casual users will be able to use rEFInd without making changes to its settings; in its default configuration, the boot manager automatically detects all the EFI boot loader programs you have on your EFI System Partition (ESP) (or your macOS boot partition, in the case of Macs) in conventional locations and displays icons for them. On Macs, rEFInd also presents legacy BIOS boot options by default. Sometimes, though, you may want to tweak rEFInd's configuration. Sometimes you can obtain your desired results by adjusting the filenames of your boot loaders. Other times, you can edit rEFInd's configuration file, refind.conf, which resides in the same directory as its binary file (refind_x64.efi or whatever you've renamed it).

Broadly speaking, rEFInd's configuration file is broken down into two sections: global options and OS stanzas. The global options section sets options that apply globally—to set the timeout period, enable graphics or text mode, and so on. OS stanzas are optional, but if present, they enable you to add new boot options or replace the auto-detected options with customized ones. Both sections include configuration lines and comment lines, the latter being denoted by a leading hash mark (#). rEFInd ignores comment lines, so you can add explanatory text. The default configuration file includes numerous comments explaining each of the options.

A common complaint among rEFInd users is that rEFInd displays too many boot options. This problem is getting worse as OS vendors deliver more and more tools in the form of EFI programs installed on the ESP. It's difficult for me to keep up with this flood, and what one person considers a necessary program another may consider pointless clutter, making it hard to set useful defaults. Fortunately, rEFInd provides several ways to hide OSes—or to make them appear, if they don't by default. Methods to do this include:

Note: Beginning with rEFInd 0.13.1, the default configuration file causes rEFInd to store its dynamic tags on disk. This works fine in most cases, but beginning with version 0.13.2, if your ESP is read-only, rEFInd will fall back to NVRAM-based variable storage. Be aware that NVRAM is a limited resource, so it's possible to exhaust it, at which point the computer can begin behaving strangely.

• Hiding entries dynamically—rEFInd 0.11.0 introduced a dynamic tag hiding feature. To use it, highlight a tag and hit the Delete (on PCs) or minus (-) key. (The Delete key on Macs is the Backspace key on PCs, and will not work for this; however, some Mac keyboards have a key marked Del that will do the job.) rEFInd will ask for confirmation. If you give it, the OS or external tool tag will disappear, and should remain hidden indefinitely. (Note that you cannot hide built-in tools, such as the About/Info display and the reboot-to-firmware option, in this way.) rEFInd stores the list of EFI OS tags so hidden in NVRAM or on disk (as determined by the use_nvram token in refind.conf) using the HiddenTags variable, BIOS/CSM/legacy OS tags as HiddenLegacy, hidden firmware reboot tags using the HiddenFirmware variable, and tool tags as HiddenTools. If you want to recover a tag you've hidden, you can do so by using the hidden tag maintenance function, which appears on the second row of the rEFInd menu as a recycling symbol. You can disable both the ability to hide tags and to recover them by uncommenting the showtools item in refind.conf and ensuring that hidden_tags is not among the options. (Even if you disable this feature, rEFInd continues to honor tags it finds in NVRAM or on disk.)

Note: ESPs use the FAT filesystem, which is case-insensitive. Unfortunately, at least one EFI implementation (Gigabyte's Hybrid EFI) contains a bug that causes string comparisons that should be case-insensitive to actually be done in a case-sensitive way. This can cause files that are present to appear to be missing. rEFInd includes code to work around this bug in some situations, but not in all of them. If boot loaders appear to be missing, try changing the case on their filenames or on the EFI directory in the ESP. (It's coded as uppercase in rEFInd; but EFI loader filename extensions are coded as lowercase .efi. I made these choices because they seem to be the most common uses on real-world installations.)

• Moving, deleting, or renaming files—By default, rEFInd scans all the filesystems it can read for boot loaders. It scans most of the subdirectories of the EFI directory, as well as the root (/) and boot directories, on every filesystem it can access for files with names that end in .efi or that begin with vmlinuz, bzImage (Image on ARM64), or kernel. (rEFInd gives special treatment to the EFI/tools subdirectory, where it looks for system tools rather than boot loaders.) Thus, you can delete EFI program files, move them out of the directory tree that rEFInd scans, or rename them so that they don't have .efi extensions. Note that rEFInd does not scan its own directory or the EFI/tools directory, so those can be good places to stash seldom-used EFI binaries.
• dont_scan_volumes—This token in refind.conf specifies volumes that rEFInd will not scan. For EFI boot loaders, you can identify a volume by its filesystem label, partition name, or partition unique GUID value. On Macs, you can identify BIOS/CSM/legacy-mode OSes to hide by specifying any unique subset of the OS tag description shown in the rEFInd main menu. In either case, this token takes a comma-delimited list, as in dont_scan_volumes ESP7,BadVolume to exclude the ESP7 and BadVolume partitions. This token cannot be used to hide BIOS/CSM/legacy-mode loaders on UEFI-based PCs.
• dont_scan_dirs—This token provides finer-grained control than the preceding one; you identify directories with this option. For instance, you might specify dont_scan_dirs EFI/ignore,BigDisk:/EFI/OldOS to ignore the EFI/ignore directory on all volumes and the EFI/OldOS directory on the BigDisk volume. This token cannot be used to hide BIOS/CSM/legacy-mode loaders.
• dont_scan_files—You can hide individual files with this token. Files can be specified alone, with a leading directory path, or with a leading directory path and volume name or GUID. For instance, dont_scan_files badloader.efi,EFI/ignoreme/boring.efi,MyDisk:/EFI/someos/grubx64.efi causes badloader.efi to be ignored in any location, EFI/ignoreme/boring.efi to be ignored on any disk, and EFI/someos/grubx64.efi to be ignored only on MyDisk. As with the previous items, you can identify a disk by filesystem label, partition name, or partition unique GUID.
• dont_scan_firmware—This token specifies strings that match (case-insensitively) as substrings of EFI firmware boot options that are to be excluded from automatic scanning when scanfor specifies firmware as an option.
• also_scan_dirs—This token does the opposite of the preceding ones: It adds a directory to the scan list, so that rEFInd can locate boot loaders stored in unusual locations. This token takes a directory path, and optionally a name (filesystem or partition), but cannot currently take a GUID value as a volume identifier.
• scanfor—This token identifies the types of OSes for which rEFInd scans, and the types of devices on which it scans. On Macs, BIOS/CSM/legacy-mode scans are currently enabled by default; but you may want to disable this support by uncommenting the scanfor line and ensuring the hdbios, biosexternal, and cd are not present. BIOS-mode boot scans are disabled by default on UEFI-based PCs, so if you want to boot BIOS-mode OSes, you must uncomment scanfor and add an appropriate option. The firmware option is disabled by default on all computers; but if you add this option, rEFInd will present boot options corresponding to those defined by the firmware's built-in boot manager. (This topic is covered in more detail later, in Using Firmware Boot Options.)

Overall, dynamic hiding is the quickest and easiest way to hide one or two unwanted entries — you can do it from within rEFInd, with just a few keystrokes. Other methods may be preferable if you want to hide multiple tags or if a tag name changes unpredictably (like a Linux kernel with a version number in its filename, which changes whenever the kernel is updated). Changing scanfor is also appropriate if you want to hide all boot tags related to certain boot methods, such as all external devices or all BIOS/CSM/legacy boot options.

In addition to hiding boot loaders, you can adjust their icons. You can do this in any of seven ways for auto-detected boot loaders:

• You can name an icon file after your boot loader, but with an extension of .icns, .png, .bmp, .jpg, or .jpeg depending on the icon's format. For instance, if you're using loader.efi, you might name the icon file loader.png. (If you use the scan_all_linux_kernels option, you can give an icon for a Linux kernel without a .efi extension a name based on the kernel name but with an appropriate extension—for instance, bzImage-5.4.0.png will serve as the icon for the bzImage-5.4.0 kernel.)
• If you're booting macOS from its standard boot loader, or if you place a boot loader file for any OS in the root directory of a partition, you can create a file called .VolumeIcon.icns, .VolumeIcon.png, .VolumeIcon.bmp, .VolumeIcon.jpg, or .VolumeIcon.jpeg that holds an icon file. MacOS uses the .VolumeIcon.icns file for its volume icons, so rEFInd picks up these icons automatically, provided they include appropriate bitmaps.
• You can place a boot loader in a directory with a name that matches one of rEFInd's standard icons, which take names of the form os_name.icns or os_name.png. To use such an icon, you would place the boot loader in the directory called name. For instance, the boot loader in the EFI/freebsd directory will use rEFInd's os_freebsd.png icon.
• You can give the filesystem from which the boot loader is loaded a name that matches the OS name component of the icon filename. For instance, if you call your boot filesystem CentOS, it matches the os_centos.png icon. This match is performed on a word-by-word basis within the name, with "words" being delimited by spaces, dashes (-), colons (:), and underscores (_). Thus, a volume called Debian-boot will match os_debian.png or os_boot.png.
• You can give the GPT partition from which the boot loader is loaded a name that matches the OS name component of the icon filename. This works much like the previous method, except that you'd use a tool like gdisk or parted to set the partition's name, rather than tune2fs or GParted to set the filesystem's name. Note that rEFInd ignores some common default partition names (namely Microsoft basic data, Linux filesystem, and Apple HFS/HFS+) when implementing this rule, since other rules are likely to produce more accurate results.
• rEFInd attempts to guess the Linux distribution based on data in the /etc/os-release file. This file will only be accessible if a separate /boot partition is not used, though. Manually adjusting the os-release file to change an OS icon in rEFInd is not recommended.
• Certain boot loaders have hard-coded icons associated with them. For instance, filenames beginning with vmlinuz or bzImage acquire the Linux "Tux" icon and the bootmgfw.efi loader acquires a Windows icon. Fedora and Red Hat kernels can be identified by the presence of .fc or .el strings in their filenames, and so acquire suitable icons automatically. For the most part, these are the associations you want to overcome with the preceding rules, but sometimes renaming a boot loader to a more conventional name is the better approach. Renaming a locally-compiled kernel so that it acquires a Fedora or Red Hat icon is reasonable, but I don't recommend renaming precompiled kernels unless you also manually copy them to the ESP.

As a special case, rEFInd assigns icons to the Windows and macOS boot loaders based on their conventional locations, so they get suitable icons even if they don't follow these rules. Many of these methods don't apply to the icons assigned to boot tags based on the firmware's built-in boot manager, since there is no disk scanning associated with this detection method. For such tags, your only chance to change their icons is to create an icon file that matches a word in the description, such as os_lenovo.png to match an item called Lenovo Diagnostics. The icon for BIOS/CSM/legacy-mode boot options on UEFI-based PCs cannot be changed.

These icon files should be in Apple's ICNS format, Portable Network Graphics (PNG) format, bitmap image file (BMP) format, or Joint Photographic Experts Group (JPEG) format, depending on the filename extension. As a general rule, PNG and ICNS files work best for icons, because they both support transparency, which is highly desirable in rEFInd icons, especially when the icon is shown against a full-screen banner. ICNS is an Apple-specific format, whereas PNG is cross-platform. BMP and JPEG files may be used as icons, but rEFInd does not support transparency with these formats. rEFInd relies on the LodePNG and NanoJPEG libraries for PNG and JPEG support, respectively. These libraries have certain limitations; for instance, NanoJPEG, and therefore rEFInd, does not support progressive JPEGs. If you have problems with a specific icon or banner image, check the libraries' pages and re-save or convert the image into a more generic form, or even to a different format.

In addition to the main OS tag icon, you can set the badge icon for a volume by creating a file called .VolumeBadge.icns, .VolumeBadge.png, .VolumeBadge.bmp, .VolumeBadge.jpg, or .VolumeBadge.jpeg in the root directory of a partition. If present, it replaces the disk-type icons that are overlaid on the main OS icon. If you use this feature, the badge is applied to all the boot loaders read from the disk, not just those stored in the root directory or the Apple boot loader location. You could use this feature to set a custom badge for different specific disks or to help differentiate multiple macOS installations on one computer. If you don't want any badges, you can add the badges option to hideui in refind.conf. Alternatively, or to hide just certain types of badges, you can replace the four badge icons in the rEFInd icons subdirectory (vol_external.png, vol_internal.png, vol_optical.png, and vol_net.png) with a completely transparent badge. The transparent.png file in the rEFInd icons directory may be used for this purpose.

The default icon sizes are 128x128 pixels for OS icons, 48x48 pixels for the second-row tools, and 32x32 pixels for badges. (These figures are all doubled on displays wider than 1920 pixels.) You can change the sizes of the big OS icons and the small tool icons with the big_icon_size and small_icon_size tokens in refind.conf, as noted in Table 1. The size of the disk-type badges is 1/4 the size of OS icons.

You can tell rEFInd to use any configuration filename by passing -c filename as an option, as in refind_x64.efi -c myrefind.conf to use myrefind.conf in rEFInd's main directory. You can specify a configuration file in another directory, but to do so, you must use backslashes as directory separators, as in -c \EFI\other\refind.conf. This feature is intended for users who want to have rEFInd appear in its own menu, with the version launched in this way behaving differently from the original—for instance, to have a secondary rEFInd that provides boot options hidden by the main one. In this scenario, the default refind.conf would have a manual boot stanza defining the new rEFInd instance, including its -c option.

You can adjust many of rEFInd's options by editing its configuration file, which is called refind.conf. You must first find this file, though. It is located in the rEFInd directory. On a UEFI-based PC, this directory will be located on the EFI System Partition (ESP), which can be in any number of places:

• Under Linux, the ESP is usually mounted at /boot/efi, although some users, particularly in Arch and Gentoo, prefer to mount the ESP at /boot, or sometimes at /efi.
• Under macOS, the ESP is not mounted by default, so you must mount it yourself to access it. Since 0.9.3, rEFInd has provided a script called mountesp, which locates and mounts the ESP. Open a Terminal and type sudo mountesp to mount the ESP. The program should tell you where it's mounted the ESP. It will remain mounted until you manually unmount it or until you reboot.
• Under Windows, the ESP is not mounted by default. You can do so manually by opening an Administrator Command Prompt window and typing mountvol R: /S to mount it at R:. (You can change the drive letter if you like.) Note that you will be able to access the ESP only from this Administrator Command Prompt window.

As a further twist, on Macs rEFInd can exist on its own partition or on the main macOS partition, depending on the version of rEFInd you've installed and the options you passed to the installation script. rEFInd has installed to the ESP by default since version 0.8.4. rEFInd typically lives on the ESP in the EFI/refind directory, or sometimes in EFI/BOOT or elsewhere. Thus, the rEFInd configuration file might be /boot/efi/EFI/refind/refind.conf, /boot/EFI/BOOT/refind.conf, /Volumes/ESP/EFI/refind/refind.conf, R:\EFI\refind\refind.conf, or something else, depending on your OS and mount point.

You can use any text editor you like to edit refind.conf, but be sure it saves the file in plain ASCII text, not in a word processing format. (In theory, a UTF-16 encoding should also work, but this has been poorly tested.) Note that the EFI shell includes its own editor. If you need to make a change before you launch an OS, you can launch a shell, change to the rEFInd directory, and type edit refind.conf to edit the file. This EFI editor is quite primitive, but it gets the job done. After editing, you'll need to reboot or re-launch rEFInd, or hit the Esc key, for rEFInd to read the changed configuration file.

Global configuration file options consist of a name token followed by one or more parameters, as in:

timeout 20

This example's name token is timeout and its parameter is 20. The net effect of this line is to set the timeout period to 20 seconds—rEFInd will wait 20 seconds before launching the default boot loader. Some options can take multiple parameters. These may be separated by commas, spaces, or tabs. The global options are summarized in the Table 1.

As an example of rEFInd configuration, consider the following refind.conf file:

# Sample refind.conf file
timeout 5
banner custom.bmp
scan_driver_dirs drivers,EFI/tools/drivers
scanfor manual,external,optical
default_selection grub

This example sets a timeout of 5 seconds; loads a custom graphic file called custom.bmp from the directory in which the rEFInd binary resides; scans the drivers and EFI/tools/drivers directories for EFI drivers; uses manual boot loader configuration but also scans for external EFI boot loaders and EFI boot loaders on optical discs; and sets the default boot loader to the first loader found that includes the string grub. Of course, since this file specifies use of manual boot loader configuration, it's not complete; you'll need to add at least one OS stanza to be able to boot from anything but an external disk or optical drive, as described shortly.

Note: Don't create manual boot stanzas unless you need to do so! Many people try to create them when rEFInd's auto-detection mechanisms will do the job just as well and with less hassle and chance of error. (Note that you can pass kernel options to a Linux kernel in the /boot/refind_linux.conf file; see the Methods of Booting Linux page for details.) Efforts to create manual boot stanzas when auto-detection can do the job just create pointless work for yourself!

Manual boot stanzas in rEFInd are similar to those in GRUB Legacy, GRUB 2, or ELILO. You can use them to add EFI boot loaders or firmware boot redirection to those that are auto-detected. rEFInd does not yet support manual boot stanzas for BIOS-mode boot loaders, although if an EFI creates its own NVRAM boot entry for a BIOS-mode boot option, a firmware redirection manual boot stanza might do the trick. You also cannot modify the auto-detected options using a manual boot stanza; if you just want to tweak one OS's configuration, you have several options:

• You can hide the tag you want to modify, then create a manual boot stanza to replace it.
• You can move or rename the boot loader file for the boot loader you want to tweak.
• You can disable all auto-detection options and add manual configurations for all your boot loaders, even those that work fine when auto-detected.
• You can put up with having duplicate or otherwise sub-optimal tags in your OS list.

Each OS stanza begins with the keyword menuentry, a name for the entry, and an open curly brace ({). Subsequent lines constitute the bulk of the stanza, which concludes with a line containing nothing but a close curly brace (}). Table 2 summarizes the keywords that you can include in a stanza.

As an example, consider the following entries:

menuentry "Ubuntu" {
    loader /EFI/ubuntu/grubx64.efi
    disabled
}

menuentry Arch {
    icon /EFI/refind/icons/os_arch.png
    volume ARCHBOOT
    loader /vmlinuz-linux
    initrd /initramfs-linux.img
    options "root=/dev/sda3 ro"
}

menuentry "Windows via shell script" {
    icon \EFI\refind\icons\os_win.png
    loader \EFI\tools\shell.efi
    options "fs0:\EFI\tools\launch_windows.nsh"
}

This example sets up three entries: one for Ubuntu, one for Arch Linux, and one to launch a shell script. Note that the final entry uses different directory separators from the first two, simply to demonstrate the fact that it's possible. (The form of directory separators in options lines is important, though, because the program being launched may expect a particular directory separator character.) The Ubuntu entry sets no icon, since rEFInd will note that the boot loader is stored in the ubuntu directory, and it will automatically find the appropriate Ubuntu icon (os_ubuntu.png). This entire entry is, however, disabled, so no matching icon will appear when you reboot unless you first comment out or delete the disabled line.

Tip: Under Linux, you can learn a filesystem's label by using blkid, as in blkid /dev/sda1. The filesystem's label, if set, is identified by the keyword LABEL in the output. Some versions also return the partition's label and partition GUID (referred to as PARTUUID by blkid). You can obtain the partition's name and unique GUID using sgdisk, as in sgdisk -i 1 /dev/sda to find the data on /dev/sda1.

The Arch entry begins with an icon specification to be sure that the icon is loaded from the same volume as rEFInd. (If the icon were stored on the same filesystem as the kernel, you'd place the icon line after the volume line.) This entry uses the volume token to tell rEFInd to load the kernel and initial RAM disk file from the filesystem or partition called ARCHBOOT. It passes the filename for an initial RAM disk using the initrd line and free-form options using the options line.

The Windows via shell script entry may seem puzzling, but its purpose is to launch an OS (Windows in this case) after performing additional pre-boot initialization, which is handled by an EFI shell script. This works because you can pass the name of a shell script to an EFI shell—the script is named on the stanza's options line, using EFI file notation. The shell script, in turn, does whatever it needs to do and then launches the OS's boot loader:

mm 0003003E 8 -pci
fs0:\EFI\Microsoft\Boot\bootmgfw.efi

This example writes data to the computer's PCI bus via the EFI shell's mm command and then launches Windows. Chances are you won't need to engage in such operations, and I do not recommend you try this exact example unless you know what you're doing! This command was required to activate the video hardware prior to booting Windows on a computer of a person with whom I corresponded, but such needs are rare. (Using the spoof_osx_version option in rEFInd 0.9.3 and later may also help with some such problems, at least on Macs.) A few pointers on finding addresses for your hardware can be found in this post.

You can combine these OS stanzas with the global refind.conf options presented earlier. The result would contain just two entries on the rEFInd boot menu (for Arch and Windows, since the Ubuntu entry is disabled), unless rEFInd found other boot options on an external or optical disk.

As described on the Using rEFInd page, rEFInd can present a menu of options for certain loader tags when you press the Insert, F2, or + key. rEFInd does this automatically when it detects macOS or ELILO boot loaders, when you set the OS type via the ostype option, or when booting a Linux kernel directly. The macOS boot loader, in particular, accepts various options that you can use to boot in various ways.

Sometimes, you might want to create your own custom submenu entries, and rEFInd enables you to do this. To create a custom submenu, you use the submenuentry keyword inside a menuentry stanza. Normally, you'll set the submenu definitions after you've set the main menu options, since the submenu options take the main menu options as defult, and so the main options must be set first. Like a menuentry stanza, a submenuentry definition begins with the keyword, the name of the item, and an open curly brace ({). It continues until a close curly brace (}). A submenu definition can use the keywords described in Table 3. Except as otherwise noted, using an option of a given name completely overrides the setting in the main stanza.

The following menu entry illustrates the use of submenu entries. This is a variant of the second entry presented earlier:

menuentry Arch {
    icon /EFI/refind/icons/os_arch.png
    loader /vmlinuz-linux
    initrd /initramfs-linux.img
    options "root=/dev/sda3 ro"
    submenuentry "single-user mode" {
        add_options "single"
    }
    submenuentry "Use fallback initrd" {
        initrd /initramfs-linux-fallback.img
    }
    submenuentry "boot via SYSLINUX" {
        loader \EFI\syslinux\syslinux.efi
	initrd
	options
    }
}

The main menu item for this entry won't look different with the submenus defined than without them; but if you press the F2 or Insert key, you'll see the submenu items:

The main menu item appears at the top of the list—Boot using default options. The three submenus defined in this example's configuration file appear next, enabling you to launch in single-user mode, boot the standard kernel with the fallback initrd file, or boot via SYSLINUX, respectively. Submenus also include an item called Return to Main Menu that does just as it says. (Alternatively, you can return to the main menu by pressing the Esc key.)

This example illustrates some of the things you can do with submenu entries:

• You can add kernel options when booting via the EFI stub loader—to launch single-user mode, to add graphical boot options, or what have you.
• You can remove options. Note the empty initrd and options lines in the SYSLINUX entry, for example; these empty lines override the default entries, which are carried over to submenu entries by default.
• You can change kernel options when booting via the EFI stub loader—to remove graphical boot options, to boot to a different root device, and so on.
• You can change your kernel and/or initial RAM disk when booting via the EFI stub loader.
• You can give users a choice of boot loaders. In this example, the main option boots via the kernel stub loader, but the submenu gives users the chance to boot via SYSLINUX instead. In fact, you could even boot two entirely different OSes from manually-defined submenu entries, although that could be confusing.

rEFInd's ability to reboot into a boot program specified via the EFI's own boot manager, introduced with rEFInd 0.13.0, is unusual and requires special elaboration. This option can be used in any of three ways:

• Auto-scanning — One method is to set firmware as an option to the scanfor line. This method causes rEFInd to display most or all of the available EFI boot entries (as revealed by Linux's efibootmgr, among other methods) as first-line boot options. (One exception is described shortly, and in some cases some options may be omitted.)
• Manual boot stanzas — The firmware_bootnum token in a manual boot stanza creates an entry that launches the specified Boot#### entry. This token takes a single hexadecimal number as an option, so you can copy the number specified by efibootmgr to create an entry. This is a good way to use this feature if you want to access just one boot option in this way.
• Built-in EFI shells — If an option contains the string shell (case-insensitive) in its description, it is added to the list of available EFI shell programs and is displayed on the second line of the rEFInd options list, but is omitted from the first line of OS loaders. This second-row option is created only if shell is an option to showtools, and whether or not you've set firmware as an option to scanfor. Note that most desktop and laptop computers lack a built-in EFI shell, although they do exist on a few. This feature is more common on server computers.

In the rEFInd menu, entries launched in this way are identified by a computer chip badge, as shown to the right (applied there to a macOS loader icon). Their descriptions (which appear when they're highlighted) also begin with the string "Reboot to" (the "Reboot to Computer Setup Utility" second-row option also contains this string, and works in a way that's similar, but not identical, to the firmware reboot options).

No matter how they're created, these options work by setting the EFI's BootNext variable to point to the specified boot option and then reboot the computer. In theory, the effect is identical to setting this variable using the -n option to efibootmgr in Linux and then rebooting. There are several reasons you might want to use this option:

• Overcoming HiDPI limitations in macOS — On some Macs with HiDPI (aka "Retina") displays, booting macOS from rEFInd 0.12.0 and earlier or using other methods with later versions, produces a lower-than-optimal resolution. For instance, my own iMac, when booted directly, produces a 4096x2304 display; but when booted via rEFInd's normal methods, the display is only 3360x1890 with macOS 10.x (but 3840x2160 with macOS 11). When using this firmware boot method, the full resolution becomes available.
• Overcoming other macOS problems — Apple has a history of changing its boot loader location and otherwise making changes that cause problems for rEFInd. In theory, this method of booting should be more robust against such changes.
• Overcoming TPM/Secure Boot/BitLocker problems with Windows — If you activate a combination of the Trusted Platform Module (TPM) feature of modern computers, Secure Boot, and the Windows BitLocker drive encryption feature, you won't be able to boot Windows through rEFInd. This is because this combination activates a very strict check of the Secure Boot keys used to sign all the boot components; only programs signed with Microsoft's Secure Boot keys will pass this check. Because rEFInd relies on a MOK or a custom set of Secure Boot keys, it won't work. Using the firmware-mediated reboot feature, though, effectively removes rEFInd from the boot path when the computer reboots, so Windows can be launched in this way. See this SuperUser discussion for more information on this subject.
• Booting over the network — Most computers have options to boot over the network using the Pre-Execution Environment (PXE) or the Hypertext Transfer Protocol (HTTP). Although rEFInd has long supported an experimental PXE-boot implementation that relies on a third-party binary called iPXE, this method is limited and has seen little development since it was introduced. Redirecting to a network boot method implemented in the firmware is likely to be more reliable; however, at the time of introducing this feature, this aspect of it has been given limited testing.
• Booting built-in EFI shells — As noted earlier, firmware-mediated boot methods enable rEFInd to launch built-in EFI shells, which can be more convenient than installing EFI shell binaries yourself. Also, whatever shell is provided by your EFI should be compatible with the EFI. Random EFI shell binaries downloaded off the Internet might or might not be compatible.
• Accessing obscure EFI-specific utilities — Some EFIs provide EFI boot order options to access the firmware setup utility, hardware RAID card configuration tools, and other obscure utilities. Making these tools available via rEFInd can be helpful.
• Booting strange OSes — Although rEFInd usually does a good job of auto-detecting and launching boot loaders, some oddball configurations might give it problems. (The macOS issues noted earlier are examples of this.) If you run into such problems, and if existing EFI boot entries can launch your OS, then this rEFInd feature may be a good way to get things working. Creating a more conventional manual boot stanza might also work in some cases.
• Secure Boot issues — Sometimes, a boot chain from one boot program to another to another can wreak havoc with Secure Boot checks. Rebooting from rEFInd into another boot chain erases the effects of rEFInd and whatever Shim it uses, which may help with such issues.

To be sure, in most cases this new rEFInd feature will provide minimal or no benefits. For this reason, and because the number of useless extra options detected can be quite high, the firmware option to scanfor is disabled by default. If you try this feature, you may run into several other limitations:

• Speed — Because this boot method employs a reboot, extra time is added to the boot process. For instance, booting macOS normally on my iMac takes 13 seconds from the moment I press Enter on the macOS option in rEFInd to the time that the macOS login appears. Booting via the firmware reboot feature takes 26 seconds for the same measure.
• Mac HiDPI video benefits apply only to macOS — I have not tested every OS or boot method, but in my limited tests so far, Linux booted via a direct EFI stub entry did not gain the video resolution benefits noted above for macOS. I don't have Windows installed on this computer, so I can't be sure how it would react; but it's my understanding that Windows is affected even when booted via Apple's own boot manager, so I suspect Windows would not be helped, either.
• Lost rEFInd environment features — Because this method of booting employs a reboot, any environment options set by rEFInd will be lost. Such options include the video resolution, Shim (if rEFInd was launched via Shim), and any EFI drivers that rEFInd loaded. Thus, you won't be able to launch a Linux kernel stored on an ext4 filesystem using this method; and if you launch an EFI shell in this way, it won't be able to read filesystems handled by your EFI filesystem drivers, either.
• Some boot options don't work — For reasons I don't understand, some boot options simply don't work. This boot method seems to be completely useless on an ancient i386-based Mac Mini and on an "early 2014" MacBook Air 6,2, both of which run Apple's EFI 1.10. (My iMac with the HiDPI display has a UEFI 2.4 implementation, and it works with this feature.) In my testing, I've also seen other options randomly fail on various non-Apple computers.
• Boot options can change — EFIs and OSes can alter the EFI boot option list independently of the contents of the ESP. Thus, options can unexpectedly appear on or disappear from this list. You might see boot options appear if you insert a removable disk, for instance, even if you've disabled removable devices via a custom scanfor line. This is most likely to be an issue if you use the firmware option to scanfor, although a manual boot stanza definition might stop working if the Boot#### entry to which it refers were to change or disappear.
• Boot options can be misleading — EFI boot options can be mis-labeled. Of particular interest, if you installed rEFInd from macOS, chances are the boot option called Mac OS X and numbered Boot0080 will in fact launch rEFInd. This can make it impossible to launch macOS via this method. This particular problem can be overcome by some juggling of boot options:
  1. Prepare a USB flash drive or CD-R that holds rEFInd. (You can download images from the Getting rEFInd page.)
  2. Boot to macOS.
  3. Use Startup Disk under Control Panel to pick your macOS system for the next boot. This will replace the EFI's Boot0080 option that points to rEFInd with one that points to macOS.
  4. Reboot. MacOS should appear directly, bypassing rEFInd.
  5. Insert the rEFInd-containing USB flash drive or CD-R into your computer.
  6. Restart and hold down the Option (or Alt) key. You should see Apple's boot manager, showing an option to boot your rEFInd medium.
  7. Boot the rEFInd external medium.
  8. From here, you can either install rEFInd from rEFInd (although this approach has some caveats, as described in the Installing rEFInd from within rEFInd section of Installing and Uninstalling rEFInd; or boot to Linux and re-install rEFInd from there. (In fact, if you reboot to Linux, you need only create a new EFI boot entry for rEFInd; but it's likely to be easier to re-install it completely.)
  Similar problems can occur when installing rEFInd from Windows, if you don't set the name of the boot loader; or in some other contexts. There's likely to be less need to boot in this way in these situations, though.

Overall, I don't recommend relying on this boot method in most cases; it's slow and may not be very reliable. In some cases, though, it can be very useful. This is definitely the case for HiDPI Macs and when booting windows with TPM, Secure Boot, and BitLocker enabled. It may be the case if you need to occasionally boot from a network device. To avoid cluttering your display, you may want to create a manual boot stanza to support only the boot options you need. You can identify the boot number using efibootmgr in Linux or rEFInd's own boot order management tool. (This tool is disabled by default, but can be enabled by adding bootorder to the showtools line in refind.conf.) Alternatively, you can add firmware to the scanfor line and then hide the options you don't want to see using some of the methods described earlier, in Hiding and Displaying EFI Boot Loaders.

Note: If you set use_nvram false in refind.conf, rEFInd stores its variables in files in the vars subdirectory of the rEFInd binary directory, rather than in NVRAM. You can read and modify these files in any OS that has access to the ESP.

Just before launching an OS, rEFInd stores the description in the EFI variable PreviousBoot with a GUID of 36d08fa7-cf0b-42f5-8f14-68df73ed3740. The next time rEFInd launches, it reads that same variable and sets the default boot loader to that value, if it's still available and if the first item in default_selection in the refind.conf file is a plus sign (+).

Under Linux, the variable that rEFInd uses to store this information is accessible as /sys/firmware/efi/efivars/PreviousBoot-36d08fa7-cf0b-42f5-8f14-68df73ed3740. Thus, you can back up this value, modify it, and write it back out to adjust your next-booted OS. Getting this string just right can be a bit tricky, though, and if the kernel doesn't like its format, it will not let you modify the variable. If you try to modify the variable, be aware that it's stored in UTF-16 format. As with the default_selection token in refind.conf, you can enter any substring that uniquely identifies the entry you want to boot.

In principle, you should be able to use a similar procedure to force rEFInd to boot another OS by default in any other OS that supports writing EFI runtime variables. Unfortunately, I don't know the mechanisms used for this task in Windows, macOS, FreeBSD, or any other OS.

If you want to consistently boot a particular OS by default and ignore the previous boot, you can use default_selection, but omit the + at the start of the line.

copyright © 2012–2024 by Roderick W. Smith

This document is licensed under the terms of the GNU Free Documentation License (FDL), version 1.3.

If you have problems with or comments about this Web page, please e-mail me at rodsmith@rodsbooks.com. Thanks.

Go to the main rEFInd page

Learn about how to use EFI drivers with rEFInd

Return to my main Web page.