From Gentoo Wiki
(Redirected from Refind)
Jump to:navigation Jump to:search
Other languages:

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.



EFI framebuffer support (CONFIG_FB_EFI) or a vendor specific Framebuffer is required to display video when launching the kernel from an EFI such as rEFInd:

KERNEL Enable EFI framebuffer support
Device Drivers --->
   Graphics support --->
      Frame buffer Devices --->
         <*> Support for frame buffer devices --->
            [*] EFI-based Framebuffer Support

USE flags

rEFInd has optional support for scanning several filesystems for EFI executables before loading the operating system. This allows to keep the kernels outside of the EFI System Partition (ESP) but needs the rEFInd built with the respective USE flags enabled.

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

btrfs Builds the EFI binary btrfs filesystem driver
doc Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
ext2 Builds the EFI binary ext2 filesystem driver
ext4 Builds the EFI binary ext4 filesystem driver
hfs Builds the EFI binary hfs filesystem driver
iso9660 Builds the EFI binary iso9660 filesystem driver
ntfs Builds the EFI binary ntfs filesystem driver
reiserfs Builds the EFI binary reiserfs filesystem driver
secureboot Automatically sign efi executables using user specified key


root #emerge --ask sys-boot/refind
rEFInd has been built and installed into ${EROOT%/}/usr/share/${P}
You will need to use the command 'refind-install' to install
the binaries into your EFI System Partition

ESP installation

Once the rEFInd package has been emerged, a second step is needed to install the binaries to the ESP. If an ESP does not exist, one needs to be created. See EFI System Partition.

File system layout

For kernel storage there are multiple options.

During boot, rEFInd can automatically find EFI boot images and Linux kernels. It looks for files ending in .efi or beginning with vmlinuz, bzImage or kernel. On the filesystems it can read (based on above USE flags), it scans in the following locations[1]:

  • File system root (/).
  • /boot directory.
  • Most of the sub-directories of /EFI. (See example in the Kernel image at ESP section).

Boot partition configuration is quite flexible. For example, choose one of:

  • Separate boot, ESP and root partitions
  • Separate ESP partition with /boot part of the root filesystem. (Provided it is a non-encrypted, non-LVM and one of the above supported filesystems).
  • Only ESP partition, with kernels living in /EFI/Gentoo/. This will require some additional steps when installing the kernel.

Installation with NVRAM modification

The rEFInd package comes with the refind-install command. Running it will:

  1. Looks if the ESP is already mounted. If not, automount the ESP according to /etc/fstab
  2. Install its refind_x64.efi application and other stuff into the ESP
  3. Call efibootmgr to set itself as the default boot manager.
root #refind-install
ShimSource is none
Installing rEFInd on Linux....
ESP was found at /boot using vfat
Copied rEFInd binary files
Copying sample configuration file as refind.conf; edit this file to configure
Installing it!
rEFInd has been set as the default boot manager.
Creating //boot/refind_linux.conf; edit it to adjust kernel options.
Installation has completed successfully.
user $tree -L 3 /boot
├── EFI
│   ├── refind
│   │   ├── icons
│   │   ├── keys
│   │   ├── refind.conf
│   │   └── refind_x64.efi
│   └── tools
└── refind_linux.conf
user $efibootmgr -v
Boot000x* rEFInd Boot Manager   HD(1,GPT,1729a003-cf0d-4bd4-88c9-cc24d8d418c4,0x800,0x2f000)/File(\EFI\refind\refind_x64.efi)

Boot000x* can vary depending on existing entries.

If /boot cannot be found in /etc/fstab, refind-install will default to using /boot/efi/EFI and even move an existing /boot/EFI to /boot/efi/EFI.
It is important to manually remount the efivarfs with rw option or rEFInd won't be able to set itself as the default boot manager, issuing an error message.

In order to do this, use the following command:

root #mount -o remount,rw -t efivarfs efivarfs /sys/firmware/efi/efivars

Installation to the EFI Default/Fallback path

rEFInd can be installed to a disk using the default/fallback filename of EFI/BOOT/bootx64.efi. The computer's NVRAM entries will not be modified when installing in this way. 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.

root #refind-install --usedefault /dev/sda

Where /dev/sda is the ESP. This installation method can be used as either a permanent setup to create a bootable USB flash drive or install rEFInd on a computer that tends to "forget" its NVRAM settings or as a temporary bootstrap to get the system to boot in EFI mode.

Kernel management

Regardless if /boot is a separate partition or part of the root file system, rEFInd should be able to find a kernel if standard naming convention is used. This makes it compatible with (semi-) automatic kernel installation methods such as genkernel --install or make install without further configuration.

Initial RAM filesystem

At boot, rEFInd looks for an initial RAM disk that starts with init and ends in a kernel version string. For example initramfs-5.4.66-gentoo.img matches with initramfs-5.4.66-gentoo.img. Provided that refind_linux.conf does not specify an initrd, it is automatically appended to the kernel command line.

When using tools like Genkernel or Dracut, no additional configuration is required. However, if a Custom Initramfs is used some care is required. Either, the initramfs should be named using the same convention, or its name should be specified in refind_linux.conf.

Kernel image at ESP (Optional)

It is possible to store the kernels and initial RAM disks on the ESP, instead of /boot. In order to play nice with icon assertion, the kernel must be stored in EFI/Gentoo.

This section is optional. It will not work with tools such as make --install or genkernel --install and requires manual copying of kernel and initial RAM system images. Also, it is not the only method to make icons work.

Moving of the kernel:

root #mv /boot/vmlinuz-4.2.0-gentoo /boot/EFI/Gentoo/vmlinuz-4.9.16-gentoo.efi
root #mv /boot/initramfs-4.2.0-gentoo /boot/EFI/Gentoo/initramfs-4.9.16-gentoo.img

Kernels and initramfs go into their EFI sub-directory:

user $tree -L 3 /boot
├── EFI
│   ├── Gentoo
│   │   ├── vmlinuz-4.9.16-gentoo.efi
│   │   └── initramfs-4.9.16-gentoo.img
│   ├── refind
│   │   ├── icons
│   │   ├── keys
│   │   ├── refind.conf
│   │   └── refind_x64.efi
│   └── tools
└── refind_linux.conf
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.

Linux command line options

refind_linux.conf should live in the same directory as the kernels. It is automatically generated in /boot during refind_install or with mkrlconf. Each entry will show up as an option for each kernel.

The default entry is based on the current /proc/cmdline. Single is the same as default, but with single added. And minimal is contains only the current root device, with the ro argument. None of the entries contain the initramfs, as it is established automatically at boot.

This file usually works out of the box when it is generated from the same boot session as it is supposed to start. For instance, when replacing the bootloader for rEFInd. However, when generated from another OS, for instance during installation of Gentoo, care must be taken and the entries must be corrected manually.

Simple example configuration:

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

Custom (static) initramfs and microcode loading:

FILE /boot/EFI/gentoo/refind_linux.conf
"Standard boot"       "root=LABEL=root initrd=intel-ucode.img initrd=initramfs-custom.img quiet"
"Single-user mode"    "root=LABEL=root initrd=intel-ucode.img initrd=initramfs-custom.img single"
"Minimal options"     "ro root=LABEL=root initrd=initramfs-custom.img"

The main selection screen for rEFInd will use the first option as the default option, however alternate boot entries can be accessed by highlighting the kernel and pressing F2. Also cmdline can be modified 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 - The user will need to have its own options that allow the kernel to boot for the system.


rEFInd comes with a collection of icons for different Linux distributions. In order to set an icon on the menu entry, it needs to know the OS name. For that it looks in the following places, in this order:

  1. An icon base name matches the kernel base name. For instance vmlinuz-5.4.66-gentoo.png
  2. The kernel is in an ESP sub-directory, named after the OS. For instance the kernel is at /EFI/Gentoo/vmlinuz-5.4.66-gentoo.png See "Kernel image at ESP" for more info.
  3. Filesystem label contains a space, underscore or dash delimited OS name. For instance with tunetfs -L Gentoo-boot /dev/sdaX.
  4. GPT partition name, following the same convention as filesystem labels.
  5. From the /etc/os-release file on the same partition. For instance, when /boot is part of the root partition.
  6. Hard coded rules based on words kernel names. For instance, vmlinux and bzImage default to the Linux "Tux" icon.

See also

External resources