This is Gentoo's testing wiki. It is a non-operational environment and its textual content is outdated.

Please visit our production wiki at https://wiki.gentoo.org

rEFInd

From Gentoo Wiki (test)
Jump to:navigation Jump to: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.

Warning
Users of SYMLINK_LIB=no layout see bug #627744 or use version 0.11.2 or higher.

Installation

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

+ext2 Builds the EFI binary ext2 filesystem driver
+ext4 Builds the EFI binary ext4 filesystem driver
+iso9660 Builds the EFI binary iso9660 filesystem driver
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
hfs Builds the EFI binary hfs 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
Data provided by the Gentoo Package Database · Last update: 2025-02-17 09:25 More information about USE flags

Emerge

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
rEFInd.

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

Warning
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.
Warning
It is important to manually remount your 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

You can install rEFInd to a disk using the default/fallback filename of EFI/BOOT/bootx64.efi. Your 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 your EFI System Partition. This isntallation 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 partition

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
/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

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.

Note
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 partition

To simplify kernel updates, you can use features of the installkernel script, which is part of the sys-apps/debianutils package:

root #emerge -av debianutils

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

Umount ESP boot partition, and navigate to your default /boot directory, where you will store the kernels images:

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 System.map-`uname -r` System.map
root #ln -s System.map-`uname -r`.old System.map.old

As result, we created initial symlinks, pointed to the current kernel version. You could replace the `uname -r` part with kernel version of your choice.

Now mount ESP partition:

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
	volume   XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
	loader   /boot/vmlinuz
	options  "root=PARTUUID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
	submenuentry "Boot using old kernel image" {
		volume   XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
		loader /boot/vmlinuz.old
	}
}
Note
loader and initrd paths are relative to the root of volume. You need to change volume to math filesystem's LABEL, a PARTLABEL, or a PARTUUID of the partition where the kernel images resides.

Next time, if you call make install when installing new kernel image, the installkernel script will update symlinks at your /boot directory automatically and point vmlinuz, config, System.map symlinks to current version of the kernel, also, it will update vmlinuz.old, config.old, System.map.old symlinks and point it to previous version of the kernel and you don't need to update 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 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.

Note
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

Retrieved from "https://wikitest.gentoo.org/index.php?title=Refind&oldid=725634"