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.

Users of AMD64 SYMLINK_LIB=no layout see bug #627744 or use sys-boot/refind version 0.11.2 or higher.


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
custom-cflags Build with user-specified CFLAGS (unsupported)
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


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

Installation with NVRAM modification

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. It is advisable to set its mountpoint to /boot.

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

  • Automount the ESP according to /etc/fstab
  • Install its refind_x64.efi application and other stuff into the ESP
  • 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

Kernel image at ESP

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, move the kernel (and initramfs if required) to /boot/EFI/Gentoo.

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 subdirectory:

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.

Kernel image outside ESP

Alternatively, kernels (and initramfs if in use) may be kept in /boot. As previously stated, when used with the appropriate filesystem driver, rEFInd can scan the root partition for suitable Linux kernels to boot. To simplify kernel updates, features of the installkernel script can be used, which is part of the sys-apps/debianutils package:

root #emerge -av debianutils

As the ESP's filesystem doesn't support symlinks, which will be updated by installkernel script, we will use default /boot directory outside the ESP (e.g. root partition with EXT4 filesystem).

Umount /boot, and navigate to the default /boot directory, where the kernels images will be stored:

root #umount /boot
root #cd /boot

As the installkernel script only update symlinks, we need to create it first:

root #ln -s vmlinuz-`uname -r` vmlinuz
root #ln -s vmlinuz-`uname -r`.old vmlinuz.old
root #ln -s config-`uname -r` config
root #ln -s config-`uname -r`.old config.old
root #ln -s`uname -r`
root #ln -s`uname -r`.old

As result, initial symlinks were created, pointed to the current kernel version. The `uname -r` could be replaced part with the relevant kernel version.

Now mount the ESP:

root #mount /boot

And update menuentry in the refind.confː

FILE /boot/EFI/BOOT/refind.conf:
menuentry "Gentoo Linux" {
	icon     /EFI/refind/icons/os_gentoo.png
	loader   /boot/vmlinuz
	submenuentry "Boot using old kernel image" {
		loader /boot/vmlinuz.old
loader and initrd paths are relative to the root of volume. volume needs to be changed volume to math filesystem's LABEL, a PARTLABEL, or a PARTUUID of the partition where the kernel images resides.

Next time, if make install is called when installing new kernel image, the installkernel script will update symlinks at the /boot directory automatically and point vmlinuz, config, symlinks to current version of the kernel, also, it will update vmlinuz.old, config.old, symlinks and point it to previous version of the kernel and no update is needed for rEFInd config file or NVRAM to use new version of the kernel.

Different boot configurations

Also different boot configurations can be specified to appear as different menu options within the rEFInd menu. This is done by creating the file /boot/EFI/gentoo/refind_linux.conf with a menu title and the matching cmdline options on each line.

FILE /boot/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 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.

See also

External resources