rEFInd

From Gentoo Wiki
Jump to:navigation Jump to:search
Translate this page
Other languages:

Warning: Display title "rEFInd" overrides earlier display title "REFInd".

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.

Installation

Kernel

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
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
secureboot Automatically sign efi executables using user specified key
Data provided by the Gentoo Package Database · Last update: 2023-10-17 06:09 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

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 mounted at /boot, or unified kernel images living in /EFI/Linux/.

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
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 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 vmlinuz-5.4.66-gentoo. 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.

(Unified) kernel image on the ESP (Optional)

It is possible to store the kernels and initial RAM disks on the ESP by mounting it at /boot. Because the kernel is on a separate partition refind can not automatically determine which distribution the kernel belongs to and will therefore fall back to the default Tux logo. To automatically install a Gentoo icon file for refind to pickup alongside the kernel image, enable the refind USE flag on sys-kernel/installkernel.

A similar problem occurs when using Unified Kernel Images, these will be installed in the EFI/Linux directory on the ESP. Refind is then unable to get any information on which distribution this unified kernel image belongs to. To automatically install a Gentoo icon file for refind to pickup alongside the unified kernel image, enable the refind USE flag on sys-kernel/installkernel.

Tip
Which icon file is installed may be overridden by setting REFIND_ICON in the environment.

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/refind_linux.conf
"Default"	"root=/dev/sda2 rootfstype=xfs ro quiet"
"Console"	"root=/dev/sda2 rootfstype=xfs ro quiet nox nogui"
"Emergency"	"root=/dev/sda2 rootfstype=xfs ro 1"

Custom (static) initramfs and microcode loading:

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

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

Icons

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.
Tip
To automatically install a custom icon alongside the (unified) kernel image, enable the refind USE flag on sys-kernel/installkernel and set REFIND_ICON to the desired icon in the environment. If this variable is unset, the Gentoo logo is installed by default.

See also

External resources

Retrieved from "https://wiki.gentoo.org/index.php?title=REFInd/en&oldid=1278834"