From Gentoo Wiki
Jump to: navigation, search

rEFInd is a boot manager for EFI and UEFI platforms forked from and successor to rEFIt. It provides a graphical interface for launching EFI-based operating systems and accessing EFI-based utilities, and has the functionality to scan multiple filesystems for executable EFI binaries.

Parts of this page have been copied from Syslinux as they are both capable (u)EFI boot managers and have similar steps with regards to management of the ESP.


Installing rEFInd builds the EFI binaries for your system but does not install them into your EFI System Partition (ESP) - additional steps are needed to finish installing rEFInd after the package has been emerged.

USE flags

rEFInd has optional support for reading several filesystems before loading the operating system. This can allow you to keep your kernels on your root partition or /boot partition instead of on the ESP. It should be noted, however, that filesystem drivers are not needed if you intend to copy your kernels to the ESP - they are only needed if you want rEFInd to scan the relevant filesystem for EFI executables.

USE flags for sys-boot/refind The rEFInd UEFI Boot Manager by Rod Smith

btrfs Builds the EFI binary btrfs filesystem driver local
custom-cflags Build with user-specified CFLAGS (unsupported) global
doc Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally global
ext2 Builds the EFI binary ext2 filesystem driver local
ext4 Builds the EFI binary ext4 filesystem driver local
gnuefi Compile using GNU-EFI instead of Tianocore local
hfs Builds the EFI binary hfs filesystem driver local
iso9660 Builds the EFI binary iso9660 filesystem driver local
ntfs Builds the EFI binary ntfs filesystem driver local
reiserfs Builds the EFI binary reiserfs filesystem driver local


root #emerge --ask sys-boot/refind
An update to the rEFInd package will not affect any EFI binaries that have been installed to the EFI System Partition. After each update to the rEFInd package you will need to install the binaries to your ESP as per the below instructions.

ESP Installation

Once the rEFInd package has been emerged, you will need to perform a second step to install the binaries to your EFI System Partition. There are two methods to installing the EFI binaries into your EFI System Partition.

For the following instructions it will be assumed that your EFI System Partition is located on /dev/sda1 and is typically mounted to /boot/efi.

EFI System Partition

Create a partition of type EF (MBR) or EF00 (GPT) with a FAT32 file system. It is also possible to use an existing EFI system partition if one is present. It is advisable to mount this partition at /boot/efi/

It is important to note that you do not necessarily need a separate partition for /boot unless:

  • You want rEFInd to scan for kernels from your /boot directory instead of loading from your ESP, and
    • You use full-disk encryption such as DM-Crypt_LUKS on your root partition, or
    • Your kernels are located on a filesystem for which there is no EFI filesystem driver

Manual installation

Assuming your ESP is mounted as per the above note, create the top-level directory for your EFI binaries in your ESP.

root #mkdir -p /boot/efi/EFI

Copy the EFI binaries, fonts, icons, images and drivers installed by the rEFInd package into your ESP. They will go into their own directory separate from any operating system kernels or loaders.

root #cp -r /usr/share/refind-*/refind /boot/efi/EFI/

The EFI filesystem drivers are loaded dynamically - just because they were built when rEFInd was emerged, it doesn't mean that the drivers need to be copied to the ESP. You may selectively reject one or all drivers as necessary. On x86 platforms the drivers are located in /boot/efi/EFI/refind/drivers_x86.efi and on amd64 platforms it is /boot/efi/EFI/refind/drivers_x64.

Configuration file

rEFInd can operate without a configuration file, however a well documented sample file is available which can be installed by copying into the refind directory on your ESP. You can then edit it once it is there.

root #cp /usr/share/doc/refind-*/refind.conf-sample /boot/efi/EFI/refind/refind.conf

rEFInd is now installed to your EFI System Partition with all the resources it will need.

Automated install script

The rEFInd package comes with a shell script for installing the binaries and supporting files to the EFI System Partition called Typically this should be a case of simply running the script, however it also has a number of options available - see --help. This also installs the refind configuration file as /boot/efi/EFI/refind/refind.conf.

root #/usr/share/refind-*/

Listing rEFInd as a boot option

This requires that the system is booted in EFI mode and that sys-boot/efibootmgr is installed. If efibootmgr is not installed it can be with:
root #emerge --ask sys-boot/efibootmgr
As rEFInd will not be the default bootloader, a one-off method of booting into EFI mode will be required. This can often be achieved by using the F2, F8 or F11 keys (depending on the firmware) to manually select an EFI binary from which to boot. Failing this, an alternative boot medium that can boot into EFI mode and has sys-boot/efibootmgr installed such as SystemRescue CD can be used.

Ensure that CONFIG_EFI_VARS is enabled in the kernel. If it was built as a module, ensure that it is loaded into memory. This action can be done using the modprobe utility. After the modules have been loaded create a new boot entry using efibootmgr:

root #efibootmgr -c -l '\EFI\refind\refind_x64.efi' -L rEFInd -p 1
If installing on an x86 platform, the binary name will be refind_x86.efi.

efibootmgr will automatically adjust the EFI boot order to put the most recently created entry at the top of the list. If that is undesired, change the boot order with the -o option.

EFI Fallback Boot Image

Most EFI and UEFI firmware support a fallback EFI image to boot from if the configured EFI file cannot be found, and some will also override the configured boot selection if the fallback boot image is found. This can be used to boot into EFI mode when doing so otherwise is difficult.

Simply copy the refind directory on the ESP to BOOT and rename the refind EFI file according to your platform.

root #cp -r /boot/efi/EFI/refind /boot/efi/EFI/BOOT
root #mv /boot/efi/EFI/BOOT/refind_x64.efi /boot/efi/EFI/BOOT/bootx64.efi

This can be used as either a permanent setup or as a temporary bootstrap to get your system to boot in EFI mode. Note that on x86 platforms, the x64 component is replaced with x86.

Kernel management

As previously stated, when used with the appropriate filesystem driver, rEFInd can scan your root partition for suitable Linux kernels to boot. Alternatively, you can copy your kernel (and initramfs if you use one) to your ESP. If this method is used and filesystem drivers are not installed, this can potentially speed up your boot by a couple of seconds.

rEFInd detects and displays an icon appropriate for the operating system kernel based on the directory it is in. To display a nice Gentoo logo, copy your kernel (and initramfs if required) to /boot/efi/EFI/gentoo.

root #cp /boot/vmlinuz-4.2.0-gentoo /boot/efi/EFI/gentoo/vmlinuz-4.2.0-gentoo.efi
root #cp /boot/initramfs-4.2.0-gentoo /boot/efi/EFI/gentoo/initramfs-4.2.0-gentoo.img
File names are important to rEFInd, especially for matching kernels with their initramfs. Follow the above naming convention for best results, though more detail can be found in the config file.

Kernel cmdline

When booting a kernel using the Linux EFI stub, the kernel cmdline typically has to be built in to the kernel itself with CONFIG_CMDLINE. This can still be done with rEFInd, however you can also specify different boot configurations to appear as different menu options within the rEFInd menu. This is done by creating the file /boot/efi/EFI/gentoo/refind_linux.conf with a menu title and the matching cmdline options on each line.

FILE /boot/efi/EFI/gentoo/refind_linux.conf
"Default"	"root=/dev/sda2 rootfstype=ext4 ro quiet"
"Console"	"root=/dev/sda2 rootfstype=ext4 ro quiet nox"
"Emergency"	"root=/dev/sda2 rootfstype=ext4 ro 1"

The main selection screen for rEFInd will use the first option as the default option, however alternate boot entries can be accessed by highlighting your kernel and pressing F2. You can also modify cmdline on-the-fly by pressing F2 on a menu item to open it in an editor. When ready, press Enter to boot the kernel.

The kernel cmdline options above are for example only - you will need to have your own options that allow your kernel to boot for your system.

See also

External resources