REFInd: Difference between revisions

Latest revision as of 02:37, 11 September 2025

rEFInd provides a graphical boot menu for UEFI systems that enables a user/administrator to select which operating system to boot from among those that are found on the available partitions. rEFInd is therefore also known as a boot manager.

Installation

As of now, refind is available in the testing repository. It can be safely installed by following the guidelines for enabling the testing repo and for installing such packages with the use of the @testing tag.

The command below installs the Alpine Linux rEFInd package:

# apk add refind@testing

Configuration

rEFInd's refind-install script creates a sample file: /boot/refind_linux.conf.

# refind-install

The steps above should be sufficient for most use cases in order to start using rEFInd as a boot manager.

Consider further another sample /boot/refind_linux.conf; this time, from the rEFInd website, for a system with an ext4 filesystem, as given below:

Contents of /boot/refind_linux.conf

"Boot with standard options"  "ro root=UUID=084f544a-7559-4d4b-938a-b920f59edc7e splash=silent quiet showopts "
"Boot to single-user mode"    "ro root=UUID=084f544a-7559-4d4b-938a-b920f59edc7e splash=silent quiet showopts single"
"Boot with minimal options"   "ro root=UUID=084f544a-7559-4d4b-938a-b920f59edc7e"
# This line is a comment

This sample file defines three entries:-

The first entry uses options derived from the contents of /proc/cmdline when the script was run, unless the script was run from an emergency system, in which case refind-install tries to translate from options in /etc/default/grub.
The second entry provides the same boot options as the first but adds the code single, which causes most distributions to boot into a single-user maintenance mode.
The final entry subtracts most options from the list, leaving only ro root=rootfs, where rootfs is the identified root (/) filesystem. This option may not be bootable on some systems that need unusual options, but if it does boot, it will normally do so with verbose startup messages, which can be helpful when debugging boot problems.

Given below is another sample /boot/refind_linux.conf file, created automatically by rEFInd for a system with a Btrfs filesystem whose layout is given further below from blkid output:

Contents of /boot/refind_linux.conf

"Boot with standard options" "root=LABEL=_SYS0_ modules=sd-mod,usb-storage,btrfs rootflags=subvol=@ resume=LABEL=_SWAP_ ro quiet"
"Boot to single-user mode" "root=LABEL=_SYS0_ modules=sd-mod,usb-storage,btrfs rootflags=subvol=@ resume=LABEL=_SWAP_ ro quiet single"
"Boot with minimal options" "ro root=UUID=aafbf6b0-7d54-4222-a3dd-a8f45c0ac607"

Output of blkid from Busybox is given below:

/dev/sda4: LABEL="_SWAP_" UUID="33899521-599f-458e-9bfe-f4b59254eb7c" TYPE="swap" 
/dev/sda3: LABEL="_SYS0_" UUID="aafbf6b0-7d54-4222-a3dd-a8f45c0ac607" TYPE="btrfs"
/dev/sda1: LABEL="_BOOT_" UUID="6771-DB5C" TYPE="vfat"

The single-user mode with minimal options does not work in Alpine Linux for a Btrfs filesystem, as reported by user u/Xerotras.

Note: The refind utility currently does not have an Alpine Linux icon file. You can save the adjunct icon file into /boot/efi/EFI/refind/icons/ or into the /boot/EFI/refind/icons/ folder.

Proceed to the Manual configuration section only if rebooting did not result in rEFInd appearing as a boot manager.

Manual configuration

There is also a second configuration file, refind.conf, which is located inside the EFI partition. The configuration file is self-explanatory and has to be manually edited. Please refer to the rEFInd website for additional information.

Note: At the time of writing, it was still required to use backslashes in the .conf file.
The path in the configuration file needs to be relative to the partition that the kernel resides on. If /boot resides on its own separate partition, then \boot needs to be removed from the paths.

The instructions below assume an esp partition, mounted as shown:

Contents of /etc/fstab

...
UUID=ABCD-1234	/boot/efi	vfat	rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=utf8,shortname=mixed,errors=remount-ro 0 2
...

If your setup is different from the one above, adjust the path in the files below, accordingly.

Tip: The Volume directive tells rEFInd which filesystem contains the kernel/initrd files. This could be the EFI partition, a separate /boot partition, or even the root filesystem itself. Use the appropriate partition's filesystem label here.

EFI Mount	Kernel Location	Filesystem Label	loader path
/boot/efi or /efi	Root filesystem	`ROOT`	/boot/vmlinuz-lts
/boot	EFI partition	`BOOT`	/vmlinuz-lts

For a default Alpine Linux sys mode installation, a sample refind.conf to dual boot Alpine Linux and windows would be:

Contents of /boot/efi/EFI/refind/refind.conf

timeout 20
resolution 1920 1080
use_graphics_for windows,linux

menuentry "Windows" {
   loader /EFI/Microsoft/Boot/bootmgfw.efi
   icon /EFI/refind/icons/os_win.png
}
menuentry "Alpine Linux" {
    icon     /EFI/refind/icons/os_alpine.png
    volume   ROOT
    loader   /boot/vmlinuz-lts
    initrd   /boot/initramfs-lts
    options  "root=UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx rw"
}  

If one is using a Btrfs filesystem with the /etc/fstab setup above, then the necessary boot entry for Alpine Linux could be as follows:

Contents of /boot/efi/EFI/refind/refind.conf

menuentry "Alpine Linux" {
    icon     /EFI/refind/icons/os_alpine.png
    volume   ROOT
    loader   @/boot/vmlinuz-lts
    initrd   @/boot/initramfs-lts
    options  "root=UUID=823a3283-30a7-4fef-b50b-8a2230c71b5b rw rootflags=subvol=@ rootfstype=btrfs"
    # PARTUUID not working for alpine
 }
  

Tip: If the configuration above is working perfectly, then there is no need for other boot managers, and they could be safely removed.

Troubleshooting

Invalid loader file

starting vmlinux-lts using load options options 'root=UUID=823a3283-30a7-4fef-b50b-8a2230c71b5b rw rootflags=subvol=@alpine rootfstype=btrfs initrd=@alpine\boot\initramfs-lts' Invalid loader file! Error:Not found while loading vmlinuz-lts

If a Btrfs filesystem is used, then the error above is caused by missing drivers. Ensure that driver file btrfs_x64.efi is copied from /usr/share/refind/drivers_x86_64/btrfs_x64.efi into the appropriate folder in the efi partition e.g. /boot/efi/EFI/refind/drivers_x64/ .

@@ Line 1: / Line 1: @@
-{{DISPLAYTITLE:rEFInd}}[https://www.rodsbooks.com/refind/ rEFInd] provides a graphical boot menu for [[UEFI]] systems, that allows to boot operating systems that are found on the available partitions.
+{{DISPLAYTITLE:rEFInd}}[https://www.rodsbooks.com/refind/ rEFInd] provides a graphical boot menu for [[UEFI]] systems that enables a user/administrator to select which operating system to boot from among those that are found on the available partitions.  rEFInd is therefore also known as a [[Bootloaders|boot manager]].
 == Installation ==
-As of now, {{pkg|refind}} is available in the [[Repositories#Testing|testing]] repository. It can be safely installed by following the [[Repositories#Using_testing_repository|guidelines]].
+As of now, {{pkg|refind}} is available in the [[Repositories#Testing|testing]] repository. It can be safely installed by following the [[Repositories#Using_testing_repository|guidelines]] for enabling the testing repo and for installing such packages with the use of the ''@testing'' tag.
-The below command installs the alpine-linux rEFInd package:
+The command below installs the Alpine Linux rEFInd package:
 {{cmd|# apk add refind@testing }}
 == Configuration ==
-rEFInd's refind-install script creates a sample file {{Path|/boot/refind_linux.conf}}.
+rEFInd's {{Path|refind-install}} script creates a sample file: {{Path|/boot/refind_linux.conf}}.
 {{cmd| # refind-install}}
@@ Line 20: / Line 20: @@
 </nowiki>}}
 -->
-The above steps should be sufficient for most cases to start using rEFInd as boot loader.
+The steps above should be sufficient for most use cases in order to start using rEFInd as a boot manager.
-A sample {{Path|/boot/refind_linux.conf}} from rEFInd website for a system with ext4 filesystem is given below:
+Consider further another sample {{Path|/boot/refind_linux.conf}};  this time, from the rEFInd website, for a system with an ''ext4'' filesystem, as given below:
 {{Cat|/boot/refind_linux.conf|<nowiki>"Boot with standard options"  "ro root=UUID=084f544a-7559-4d4b-938a-b920f59edc7e splash=silent quiet showopts "
 "Boot to single-user mode"    "ro root=UUID=084f544a-7559-4d4b-938a-b920f59edc7e splash=silent quiet showopts single"
@@ Line 27: / Line 29: @@
 # This line is a comment</nowiki>}}
-This sample file defines three entries:
+This sample file defines three entries:-
-* The first entry uses options derived from the contents of {{Path|/proc/cmdline}} when the script was run, unless the script was run from an emergency system, in which case refind-install tries to translate from options in {{Path|/etc/default/grub}}.
+* The first entry uses options derived from the contents of {{Path|/proc/cmdline}} when the script was run, unless the script was run from an emergency system, in which case {{Path|refind-install}} tries to translate from options in {{Path|/etc/default/grub}}.
-* The second entry provides the same boot options as the first, but adds single, which causes most distributions to boot into a single-user maintenance mode.
+* The second entry provides the same boot options as the first but adds the code {{ic|single}}, which causes most distributions to boot into a ''single-user'' maintenance mode.
-* The final entry subtracts most options from the list, leaving only ro root=rootfs, where rootfs is the identified root (/) filesystem. This option may not be bootable on some systems that need unusual options, but if it does boot, it will normally do so with verbose startup messages, which can be helpful when debugging boot problems.
+* The final entry subtracts most options from the list, leaving only {{ic|ro root{{=}}rootfs}}, where {{ic|rootfs}} is the identified ''root'' ({{ic|/}}) filesystem. This option may not be bootable on some systems that need unusual options, but if it does boot, it will normally do so with verbose startup messages, which can be helpful when debugging boot problems.
+Given below is another sample {{Path|/boot/refind_linux.conf}} file, created automatically by rEFInd for a system with a [[Btrfs]] filesystem whose layout is given further below from {{ic|blkid}} output:
-Given below is a sample {{Path|/boot/refind_linux.conf}} created automatically by rEFInd for a system with [[Btrfs]] filesystem whose layout is given further below as <Code>blkid</Code> output:
 {{Cat|/boot/refind_linux.conf|<nowiki>"Boot with standard options" "root=LABEL=_SYS0_ modules=sd-mod,usb-storage,btrfs rootflags=subvol=@ resume=LABEL=_SWAP_ ro quiet"
 "Boot to single-user mode" "root=LABEL=_SYS0_ modules=sd-mod,usb-storage,btrfs rootflags=subvol=@ resume=LABEL=_SWAP_ ro quiet single"
 "Boot with minimal options" "ro root=UUID=aafbf6b0-7d54-4222-a3dd-a8f45c0ac607"</nowiki>}}
-Output of <Code>blkid</Code> from [[Busybox]] is given below.
+Output of <Code>blkid</Code> from [[Busybox]] is given below:
 <Pre>
 /dev/sda4: LABEL="_SWAP_" UUID="33899521-599f-458e-9bfe-f4b59254eb7c" TYPE="swap"
@@ Line 43: / Line 46: @@
 /dev/sda1: LABEL="_BOOT_" UUID="6771-DB5C" TYPE="vfat"
 </Pre>
-The single-user mode and minimal options does not work in Alpine Linux for [[Btrfs]] filesystem as per user u/Xerotras in https://redd.it/1hbog74
-{{Note|The {{pkg|refind}} utility currently does not have Alpine Linux icon file. You can place the [[Media:Os alpine.png| icon file]] in {{Path|/boot/efi/EFI/refind/icons/}} or {{Path|/boot/EFI/refind/icons/}} folder.}}
+The ''single-user'' mode with minimal options does not work in Alpine Linux for a [[Btrfs]] filesystem, [https://redd.it/1hbog74 as reported] by user u/Xerotras.
+{{Note|The {{pkg|refind}} utility currently does not have an Alpine Linux icon file. You can save the adjunct [[Media:Os alpine.png| icon file]] into {{Path|/boot/efi/EFI/refind/icons/}} or into the {{Path|/boot/EFI/refind/icons/}} folder.}}
 [[File:Os alpine.png|thumb|right|100px|alt=Alpine linux icon file for refind|icon file]]
-Proceed to [[#Manual configuration|Manual configuration]] only if rebooting did not result in rEFInd appearing as boot loader.
+Proceed to the [[#Manual configuration|Manual configuration]] section only if rebooting did not result in rEFInd appearing as a boot manager.
 === Manual configuration ===
-And a first (default) boot menu line needs to be configured with Alpine's default boot parameters. Assuming the bootable partition is mounted at {{path|/media/sdXY}} it can be done like this (at time of writing):
+There is also a second configuration file, {{Path|refind.conf}}, which is located inside the EFI partition. The configuration file is self-explanatory and has to be manually edited. Please refer to the [https://www.rodsbooks.com/refind/configfile.html rEFInd website] for additional information.
+<!--
+During Installation a (default) boot menu line can be configured with Alpine's default boot parameters. Assuming the bootable partition is mounted at {{path|/media/sdXY}} it can be done like this (at time of writing):
 {{cmd|<nowiki># echo '"Alpine" "modules=loop,squashfs,sd-mod,usb-storage quiet initrd=\boot\intel-ucode.img initrd=\boot\amd-ucode.img initrd=\boot\initramfs-lts"' > /media/sdXY/boot/refind_linux.conf</nowiki>}}
+-->
+{{Note|At the time of writing, it was still required to use backslashes in the {{Path|.conf}} file.<br>
+The path in the configuration file needs to be relative to the partition that the kernel resides on. If {{path|/boot}} resides on its own separate partition, then <code>\boot</code> needs to be removed from the paths.}}
+The instructions below assume an ''esp'' partition, mounted as shown:
+{{cat|/etc/fstab|<nowiki>...
+UUID=ABCD-1234	/boot/efi	vfat	rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=utf8,shortname=mixed,errors=remount-ro 0 2
+...</nowiki>}}
-{{Note|At the time of writing, it was still needed to use backslashes in the .conf file.<br>
+If your setup is different from the one above, adjust the path in the files below, accordingly.
-The path in the config file needs to be relative to the partition that the kernel resides on. If {{path|/boot}} resides on its own separate partition, then <code>\boot</code> needs to be removed from the paths.}}
-There is also a second config file, '''refind.conf''' which is located inside the EFI partition. The config file is self-explanatory and has to be manually edited. Refer [https://www.rodsbooks.com/refind/configfile.html refind website] for additional information.
+{{Tip|The '''Volume''' directive tells rEFInd which filesystem contains the kernel/{{Path|initrd}} files. This could be the EFI partition, a separate {{Path|/boot}} partition, or even the root filesystem itself. Use the appropriate partition's [[Filesystems#Filesystem_labels|filesystem label]] here.}}
-The below instructions assume esp partition is mounted as shown:{{cat|/etc/fstab|<nowiki>...
+{| class="wikitable"
-UUID=ABCD-1234	/boot/efi	vfat	rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=utf8,shortname=mixed,errors=remount-ro 0 2
+|-
-...</nowiki>}}
+! EFI Mount !! Kernel Location !! Filesystem Label !! loader path
-If your setup is different from above, adjust the path in below files accordingly.
+|-
+| {{Path|/boot/efi}} or {{Path|/efi}} || Root filesystem || {{ic|ROOT}} || {{Path|/boot/vmlinuz-lts}}
+|-
+| {{Path|/boot}} || EFI partition || {{ic|BOOT}} || {{Path|/vmlinuz-lts}}
+|}
+For a default Alpine Linux [[Installation#System_Disk_Mode|sys]] mode installation, a sample {{Path|refind.conf}} to [[Dualbooting|dual boot]] Alpine Linux and windows would be:
-For default alpine [[Installation#System_Disk_Mode|sys]] mode installation, a sample refind.conf to [[Dualbooting|dual boot]] Alpine Linux and windows will be: {{Cat|/boot/efi/EFI/refind/refind.conf|<nowiki>timeout 20
+{{Cat|/boot/efi/EFI/refind/refind.conf|<nowiki>timeout 20
 resolution 1920 1080
 use_graphics_for windows,linux
@@ Line 81: / Line 101: @@
 } </nowiki> }}
-If you use [[btrfs]] filesystem, for the above {{Path|/etc/fstab}} setup, the necessary boot entry for Alpine Linux is as follows:
+If one is using a [[Btrfs]] filesystem with the {{Path|/etc/fstab}} setup above, then the necessary boot entry for Alpine Linux could be as follows:
 {{Cat|/boot/efi/EFI/refind/refind.conf|
 <nowiki>menuentry "Alpine Linux" {
      icon     /EFI/refind/icons/os_alpine.png
-     volume   BTRFSVOL
+     volume   ROOT
-     loader   @alpine/boot/vmlinuz-lts
+     loader   @/boot/vmlinuz-lts
-     initrd   @alpine/boot/initramfs-lts
+     initrd   @/boot/initramfs-lts
-     options  "root=UUID=823a3283-30a7-4fef-b50b-8a2230c71b5b rw rootflags=subvol=@alpine rootfstype=btrfs"
+     options  "root=UUID=823a3283-30a7-4fef-b50b-8a2230c71b5b rw rootflags=subvol=@ rootfstype=btrfs"
      # PARTUUID not working for alpine
   }
@@ Line 95: / Line 115: @@
 }}
-{{Tip|If the above configuration is working perfectly,there is no need for other bootloaders and they can be safely removed.}}
+{{Tip|If the configuration above is working perfectly, then there is no need for other boot managers, and they could be safely removed.}}
 == Troubleshooting ==
+=== Invalid loader file ===
+{{Cmd|<nowiki>starting vmlinux-lts
+using load options options 'root=UUID=823a3283-30a7-4fef-b50b-8a2230c71b5b rw rootflags=subvol=@alpine rootfstype=btrfs initrd=@alpine\boot\initramfs-lts'
+Invalid loader file!
+Error:Not found while loading vmlinuz-lts</nowiki>}}
+If a [[Btrfs]] filesystem is used, then the error above is caused by missing drivers. Ensure that driver file {{Path|btrfs_x64.efi}} is copied from {{Path|/usr/share/refind/drivers_x86_64/btrfs_x64.efi}} into the appropriate folder in the {{Path|efi}} partition e.g. {{Path|/boot/efi/EFI/refind/drivers_x64/}} .
 ==See also ==
 * [[Bootloaders]]
-* [https://www.rodsbooks.com/refind/configfile.html Official configuration guide]
+* [https://www.rodsbooks.com/refind/configfile.html rEFInd - Official configuration guide]
-* [
 [[Category:Installation]]
 [[Category:Booting]]