Difference between revisions of "REFInd"

From ArchWiki
Jump to: navigation, search
(Revert. #Scripted installation means using refind-install SCRIPT, manually copying rEFInd files belongs to #Manual installation, refind.conf editing belongs to #Configuration.)
(Undo revision 538596 by Ameed (talk) - unlike UUIDs, PARTUUIDs should always work (unless the disk has a MBR partition table))
 
(60 intermediate revisions by 6 users not shown)
Line 6: Line 6:
 
{{Related articles start}}
 
{{Related articles start}}
 
{{Related|Arch boot process}}
 
{{Related|Arch boot process}}
{{Related|Boot loaders}}
+
{{Related|:Category:Boot loaders}}
 
{{Related|Unified Extensible Firmware Interface}}
 
{{Related|Unified Extensible Firmware Interface}}
 
{{Related|EFISTUB}}
 
{{Related|EFISTUB}}
 
{{Related articles end}}
 
{{Related articles end}}
[http://www.rodsbooks.com/refind/ rEFInd] is a [[UEFI]] boot manager capable of launching [[EFISTUB]] kernels. It is a fork of the no-longer-maintained rEFIt and fixes many issues with respect to non-Mac UEFI booting. It is designed to be platform-neutral and to simplify booting multiple OSes.
+
[https://www.rodsbooks.com/refind/ rEFInd] is a [[UEFI]] boot manager capable of launching [[EFISTUB]] kernels. It is a fork of the no-longer-maintained rEFIt and fixes many issues with respect to non-Mac UEFI booting. It is designed to be platform-neutral and to simplify booting multiple OSes.
  
{{Note|In the entire article {{ic|''esp''}} denotes the mountpoint of the [[EFI System Partition]] aka ESP.}}
+
{{Note|In the entire article {{ic|''esp''}} denotes the mountpoint of the [[EFI system partition]] aka ESP.}}
  
 
== Installation ==
 
== Installation ==
Line 18: Line 18:
 
[[Install]] the {{pkg|refind-efi}} package.
 
[[Install]] the {{pkg|refind-efi}} package.
  
rEFInd has '''read-only''' drivers for ReiserFS, Ext2, Ext4, Btrfs, ISO-9660, HFS+, and NTFS. Additionally rEFInd can use drivers from the UEFI firmware i.e. FAT (or HFS+ on Macs or ISO-9660 on some systems).
+
rEFInd has '''read-only''' drivers for ReiserFS, Ext2, Ext4, Btrfs, ISO-9660, HFS+, and NTFS. Additionally rEFInd can use drivers from the UEFI firmware i.e. FAT (and HFS+ on Macs or ISO-9660 on some systems).
  
{{Note|Your kernel and initramfs need to reside on a file system which rEFInd can read.}}
+
{{Note|Your kernel and initramfs must reside on a file system that rEFInd can read.}}
  
To find additional drivers see [http://www.rodsbooks.com/refind/drivers.html#finding The rEFInd Boot Manager: Using EFI Drivers: Finding Additional EFI Drivers].
+
To find additional drivers see [https://www.rodsbooks.com/refind/drivers.html#finding The rEFInd Boot Manager: Using EFI Drivers: Finding Additional EFI Drivers].
  
=== Scripted installation ===
+
=== Installation with refind-install script ===
  
The rEFInd package includes the ''refind-install'' script to simplify the process of setting rEFInd as your default EFI boot entry. The script has several options for handling differing setups and UEFI implementations. See {{man|8|refind-install}}. For many systems it should be sufficient to simply run:
+
The rEFInd package includes the ''refind-install'' script to simplify the process of setting rEFInd as your default EFI boot entry. The script has several options for handling differing setups and UEFI implementations. See {{man|8|refind-install}} or read the comments in the install script for explanations of the various installation options.
 +
 
 +
For many systems it should be sufficient to simply run:
  
 
  # refind-install
 
  # refind-install
  
This will attempt to find and mount your [[ESP]], copy rEFInd files to {{ic|''esp''/EFI/refind/}}, and use {{ic|efibootmgr}} to make rEFInd the default EFI boot application.
+
This will attempt to find and mount your [[ESP]], copy rEFInd files to {{ic|''esp''/EFI/refind/}}, and use [[efibootmgr]] to make rEFInd the default EFI boot application.
  
Alternatively you can install rEFInd to the default/fallback boot path {{ic|''esp''/EFI/BOOT/bootx64.efi}}. This is helpful for bootable USB flash drives or on systems that have issues with the NVRAM changes made by {{ic|efibootmgr}}:
+
Alternatively you can install rEFInd to the default/fallback boot path {{ic|''esp''/EFI/BOOT/bootx64.efi}}. This is helpful for bootable USB flash drives or on systems that have issues with the NVRAM changes made by ''efibootmgr'':
  
 
  # refind-install --usedefault ''/dev/sdXY''
 
  # refind-install --usedefault ''/dev/sdXY''
  
Where {{ic|''/dev/sdXY''}} is the partition of your ESP.
+
Where {{ic|''/dev/sdXY''}} is of your EFI System Partition.
 
 
You can read the comments in the install script for explanations of the various installation options.
 
  
 
{{Note|By default {{ic|refind-install}} installs only the driver for the file system on which kernel resides. Additional file systems need to be installed manually or you can install all drivers with the {{ic|--alldrivers}} option. This is useful for bootable USB flash drives e.g.:
 
{{Note|By default {{ic|refind-install}} installs only the driver for the file system on which kernel resides. Additional file systems need to be installed manually or you can install all drivers with the {{ic|--alldrivers}} option. This is useful for bootable USB flash drives e.g.:
Line 50: Line 50:
 
By default, rEFInd will scan all of your drives (that it has drivers for) and add a boot entry for each EFI bootloader it finds, which should include your kernel (since Arch enables [[EFISTUB]] by default). So you may have a bootable system at this point.
 
By default, rEFInd will scan all of your drives (that it has drivers for) and add a boot entry for each EFI bootloader it finds, which should include your kernel (since Arch enables [[EFISTUB]] by default). So you may have a bootable system at this point.
  
{{Tip|It is always a good idea to edit the default config {{ic|''esp''/EFI/refind/refind.conf}} to ensure that the default options work for you.}}
+
{{Tip|It is always a good idea to edit the default configuration file {{ic|''esp''/EFI/refind/refind.conf}} to ensure that the default options work for you.}}
  
{{Warning|When refind-install is run in chroot (e.g. in live system when installing Arch Linux) {{ic|/boot/refind_linux.conf}} is populated with kernel options from the live system not the one on which it is installed. You need to adjust kernel options in {{ic|/boot/refind_linux.conf}} manually.}}
+
{{Warning|When {{ic|refind-install}} is run in chroot (e.g. in live system when installing Arch Linux) {{ic|/boot/refind_linux.conf}} is populated with kernel options from the live system not the one on which it is installed. You will need to edit {{ic|/boot/refind_linux.conf}} and adjust the kernel options manually. See [[#refind_linux.conf]] for an example.}}
  
 
==== Secure Boot ====
 
==== Secure Boot ====
  
See [http://www.rodsbooks.com/refind/secureboot.html Managing Secure Boot] for [[Secure Boot]] support in rEFInd.
+
See [https://www.rodsbooks.com/refind/secureboot.html Managing Secure Boot] for [[Secure Boot]] support in rEFInd.
  
 
===== Using PreLoader =====
 
===== Using PreLoader =====
Line 66: Line 66:
 
  # refind-install --preloader /usr/share/preloader-signed/PreLoader.efi
 
  # refind-install --preloader /usr/share/preloader-signed/PreLoader.efi
  
Next time you boot with Secure Boot enabled, HashTool will launch and you will need to enrol the hash of rEFInd ({{ic|loader.efi}}), rEFInd's drivers (e.g. {{ic|ext4_x64.efi}}) and kernel.
+
Next time you boot with Secure Boot enabled, HashTool will launch and you will need to enroll the hash of rEFInd ({{ic|loader.efi}}), rEFInd's drivers (e.g. {{ic|ext4_x64.efi}}) and kernel (e.g. {{ic|vmlinuz-linux}}).
  
 
See {{man|8|refind-install}} for more information.
 
See {{man|8|refind-install}} for more information.
  
{{Tip|The signed ''HashTool'' is only capable of accessing the partition it was launched from. This means if your kernel is not on the ESP, you will not be able to enrol its hash from ''HashTool''. You can workaround this by using [[#KeyTool]], since it is capable of enrolling a hash in MokList and is not limited to one partition. Remember to enrol ''KeyTool'''s hash before before using it.}}
+
{{Tip|The signed ''HashTool'' is only capable of accessing the partition it was launched from. This means if your kernel is not on the ESP, you will not be able to enroll its hash from ''HashTool''. You can workaround this by using [[#KeyTool]], since it is capable of enrolling a hash in MokList and is not limited to one partition. Remember to enroll ''KeyTool'''s hash before using it.}}
  
 
===== Using shim =====
 
===== Using shim =====
Line 76: Line 76:
 
[[Install]] {{AUR|shim-signed}}. Read [[Secure Boot#shim]], but skip all file copying.
 
[[Install]] {{AUR|shim-signed}}. Read [[Secure Boot#shim]], but skip all file copying.
  
 +
====== Using hashes ======
 
To use only hashes with ''shim'', execute {{ic|refind-install}} with the option {{ic|--shim ''/path/to/shim''}}
 
To use only hashes with ''shim'', execute {{ic|refind-install}} with the option {{ic|--shim ''/path/to/shim''}}
  
 
  # refind-install --shim /usr/share/shim-signed/shimx64.efi
 
  # refind-install --shim /usr/share/shim-signed/shimx64.efi
  
Next time you boot with Secure Boot enabled, MokManager will launch and you will need to enrol the hash of rEFInd ({{ic|grubx64.efi}}), rEFInd's drivers (e.g. {{ic|ext4_x64.efi}}) and kernel.
+
Next time you boot with Secure Boot enabled, MokManager will launch and you will need to enroll the hash of rEFInd ({{ic|grubx64.efi}}), rEFInd's drivers (e.g. {{ic|ext4_x64.efi}}) and kernel (e.g. {{ic|vmlinuz-linux}}).
 +
 
 +
====== Using Machine Owner Key======
  
To sign rEFInd with a Machine Owner Key, install {{Pkg|sbsigntools}}.
+
To sign rEFInd with a Machine Owner Key (MOK), install {{Pkg|sbsigntools}}.
  
{{Tip|If you already have [[Secure Boot#shim with key|created a MOK]], place the files in the directory {{ic|/etc/refind.d/keys}} with the names {{ic|refind_local.key}}, {{ic|refind_local.crt}} and {{ic|refind_local.cer}}.}}
+
{{Tip|If you already have [[Secure Boot#shim with key|created a MOK]], place the files in the directory {{ic|/etc/refind.d/keys}} with the names {{ic|refind_local.key}} (PEM format private key), {{ic|refind_local.crt}} (PEM format certificate) and {{ic|refind_local.cer}} (DER format certificate).}}
  
 
Execute {{ic|refind-install}} with the options {{ic|--shim ''/path/to/shim''}} and {{ic|--localkeys}}:
 
Execute {{ic|refind-install}} with the options {{ic|--shim ''/path/to/shim''}} and {{ic|--localkeys}}:
Line 93: Line 96:
  
 
  # sbsign --key /etc/refind.d/keys/refind_local.key --cert /etc/refind.d/keys/refind_local.crt --output /boot/vmlinuz-linux /boot/vmlinuz-linux
 
  # sbsign --key /etc/refind.d/keys/refind_local.key --cert /etc/refind.d/keys/refind_local.crt --output /boot/vmlinuz-linux /boot/vmlinuz-linux
 +
 +
{{Tip|The kernel signing can be automated with a [[pacman hook]], e.g.:
 +
 +
{{hc|/etc/pacman.d/hooks/999-sign_kernel_for_secureboot.hook|2=
 +
[Trigger]
 +
Operation = Install
 +
Operation = Upgrade
 +
Type = Package
 +
Target = linux
 +
 +
[Action]
 +
Description = Signing kernel with Machine Owner Key for Secure Boot
 +
When = PostTransaction
 +
Exec = /usr/bin/sbsign --key /etc/refind.d/keys/refind_local.key --cert /etc/refind.d/keys/refind_local.crt --output /boot/vmlinuz-linux /boot/vmlinuz-linux
 +
Depends = sbsigntools
 +
}}
 +
}}
  
 
Once in MokManager add {{ic|refind_local.cer}} to MoKList. {{ic|refind_local.cer}} can be found inside a directory called {{ic|keys}} in the rEFInd's installation directory, e.g. {{ic|''esp''/EFI/refind/keys/refind_local.cer}}.
 
Once in MokManager add {{ic|refind_local.cer}} to MoKList. {{ic|refind_local.cer}} can be found inside a directory called {{ic|keys}} in the rEFInd's installation directory, e.g. {{ic|''esp''/EFI/refind/keys/refind_local.cer}}.
Line 102: Line 122:
 
Follow [[Secure Boot#Using your own keys]] to create keys.
 
Follow [[Secure Boot#Using your own keys]] to create keys.
  
Create directory {{ic|/etc/refind.d/keys}} and place Signature Database ('''db''') key and certificates in it. Name the files: {{ic|refind_local.key}}, {{ic|refind_local.crt}} and {{ic|refind_local.cer}}.
+
Create directory {{ic|/etc/refind.d/keys}} and place Signature Database ('''db''') key and certificates in it. Name the files: {{ic|refind_local.key}} (PEM format private key), {{ic|refind_local.crt}} (PEM format certificate) and {{ic|refind_local.cer}} (DER format certificate).
  
 
When running install script add option {{ic|--localkeys}}, e.g.:
 
When running install script add option {{ic|--localkeys}}, e.g.:
Line 108: Line 128:
 
  # refind-install --localkeys
 
  # refind-install --localkeys
  
rEFInd EFI binary will be signed with supplied key and certificate.
+
rEFInd EFI binaries will be signed with the supplied key and certificate.
  
 
=== Manual installation ===
 
=== Manual installation ===
  
{{Tip|rEFInd can boot Linux in many ways. See [http://www.rodsbooks.com/refind/linux.html The rEFInd Boot Manager: Methods of Booting Linux] for coverage of the various approaches.}}
+
{{Tip|rEFInd can boot Linux in many ways. See [https://www.rodsbooks.com/refind/linux.html The rEFInd Boot Manager: Methods of Booting Linux] for coverage of the various approaches.}}
  
 
If the {{ic|refind-install}} script does not work for you, rEFInd can be set up manually.
 
If the {{ic|refind-install}} script does not work for you, rEFInd can be set up manually.
Line 121: Line 141:
 
  # cp /usr/share/refind/refind_x64.efi ''esp''/EFI/refind/
 
  # cp /usr/share/refind/refind_x64.efi ''esp''/EFI/refind/
  
{{Tip|If you want to install rEFInd to the default/fallback boot path, copy rEFInd executable to {{ic|''esp''/EFI/BOOT/bootx64.efi}}:
+
If you want to install rEFInd to the default/fallback boot path replace {{ic|''esp''/EFI/refind/}} with {{ic|''esp''/EFI/BOOT/}} in the following instructions and copy rEFInd EFI executable to {{ic|''esp''/EFI/BOOT/bootx64.efi}}:
  
 
  # mkdir -p ''esp''/EFI/BOOT
 
  # mkdir -p ''esp''/EFI/BOOT
 
  # cp /usr/share/refind/refind_x64.efi ''esp''/EFI/BOOT/bootx64.efi
 
  # cp /usr/share/refind/refind_x64.efi ''esp''/EFI/BOOT/bootx64.efi
  
Replace {{ic|''esp''/EFI/refind/}} with {{ic|''esp''/EFI/BOOT/}} in the following instructions.
+
Then use [[efibootmgr]] to create a boot entry in the UEFI NVRAM, where {{ic|''/dev/sdX''}} and {{ic|''Y''}} are the device and partition number of your EFI System Partition. If you are installing rEFInd to the default/fallback boot path {{ic|''esp''/EFI/BOOT/bootx64.efi}}, you can skip this step.
}}
 
 
 
Then use [[UEFI#efibootmgr|efibootmgr]] to create a boot entry in the UEFI NVRAM, where {{ic|''/dev/sdX''}} and {{ic|''Y''}} are the device and partition number of your ESP. If you are installing rEFInd to the default UEFI path {{ic|''esp''/EFI/BOOT/bootx64.efi}}, you can skip this step.
 
  
  # efibootmgr --create --disk ''/dev/sdX'' --part ''Y'' --loader /EFI/refind/refind_x64.efi --label "rEFInd Boot Manager"
+
  # efibootmgr --create --disk ''/dev/sdX'' --part ''Y'' --loader /EFI/refind/refind_x64.efi --label "rEFInd Boot Manager" --verbose
  
 
At this point, you should be able to reboot into rEFInd, but it will not be able to boot your kernel. If your kernel does not reside on your ESP, rEFInd can mount your partitions to find it - provided it has the right drivers.
 
At this point, you should be able to reboot into rEFInd, but it will not be able to boot your kernel. If your kernel does not reside on your ESP, rEFInd can mount your partitions to find it - provided it has the right drivers.
Line 140: Line 157:
 
  # cp /usr/share/refind/drivers_x64/'''drivername'''_x64.efi ''esp''/EFI/refind/drivers_x64/
 
  # cp /usr/share/refind/drivers_x64/'''drivername'''_x64.efi ''esp''/EFI/refind/drivers_x64/
  
Now rEFInd should have a boot entry for your kernel, but it will not pass the correct kernel parameters. Set up [[#Passing kernel parameters]]. You should now be able to boot your kernel using rEFInd. If you are still unable to boot or if you want to tweak rEFInd's settings, many options can be changed with a config file:
+
Now rEFInd should have a boot entry for your kernel, but it will not pass the correct kernel parameters. Set up [[#Passing kernel parameters]]. You should now be able to boot your kernel using rEFInd. If you are still unable to boot or if you want to tweak rEFInd's settings, many options can be changed with a configuration file:
  
 
  # cp /usr/share/refind/refind.conf-sample ''esp''/EFI/refind/refind.conf
 
  # cp /usr/share/refind/refind.conf-sample ''esp''/EFI/refind/refind.conf
  
The sample config is well commented and self-explanatory.
+
The sample configuration file is well commented and self-explanatory.
  
Unless you have set {{ic|textonly}} in the config file, you should copy rEFInd's icons to get rid of the ugly placeholders:
+
Unless you have set {{ic|textonly}} in the configuration file, you should copy rEFInd's icons to get rid of the ugly placeholders:
  
 
  # cp -r /usr/share/refind/icons ''esp''/EFI/refind/
 
  # cp -r /usr/share/refind/icons ''esp''/EFI/refind/
Line 158: Line 175:
 
=== Upgrading ===
 
=== Upgrading ===
  
Pacman updates the rEFInd files in {{ic|/usr/share/refind/}} and will not copy new files to the ESP for you. If {{ic|refind-install}} worked for your original installation of rEFInd, you can rerun it to copy the updated files. The new config file will be copied as {{ic|refind.conf-sample}} so that you can integrate changes into your config file using a diff tool. If your rEFInd required [[#Manual installation]], you will need to figure out which files to copy yourself.
+
Pacman updates the rEFInd files in {{ic|/usr/share/refind/}} and will not copy new files to the ESP for you. If {{ic|refind-install}} worked for your original installation of rEFInd, you can rerun it to copy the updated files. The new configuration file will be copied as {{ic|refind.conf-sample}} so that you can integrate changes into your existing configuration file using a diff tool. If your rEFInd required [[#Manual installation]], you will need to figure out which files to copy yourself.
  
 
==== Pacman hook ====
 
==== Pacman hook ====
  
You can automate the update process using a [[pacman#Hooks|pacman hook]]:
+
You can automate the update process using a [[pacman hook]]:
  
 
{{hc|/etc/pacman.d/hooks/refind.hook|2=[Trigger]
 
{{hc|/etc/pacman.d/hooks/refind.hook|2=[Trigger]
Line 176: Line 193:
  
 
Where the {{ic|1=Exec=}} may need to be changed to the correct update command for your setup. If you did [[#Manual installation]], you could create your own update script to call with the hook.
 
Where the {{ic|1=Exec=}} may need to be changed to the correct update command for your setup. If you did [[#Manual installation]], you could create your own update script to call with the hook.
 +
 +
{{Tip|If you setup rEFInd with [[#Secure Boot]], you may want to additionally add the option {{ic|--yes}} to the {{ic|refind-install}} command. It will prevent the command from failing if it gets executed when Secure Boot is disabled. See {{man|8|refind-install}} for more information.}}
  
 
== Configuration ==
 
== Configuration ==
  
The rEFInd configuration {{ic|refind.conf}} is located in the same directory as the rEFInd EFI application (usually {{ic|''esp''/EFI/refind}} or {{ic|''esp''/EFI/BOOT}}). The default config contains extensive comments explaining all its options, see [http://www.rodsbooks.com/refind/configfile.html Configuring the Boot Manager] for more detailed explanations.
+
The rEFInd configuration {{ic|refind.conf}} is located in the same directory as the rEFInd EFI application (usually {{ic|''esp''/EFI/refind}} or {{ic|''esp''/EFI/BOOT}}). The default configuration file contains extensive comments explaining all its options, see [https://www.rodsbooks.com/refind/configfile.html Configuring the Boot Manager] for more detailed explanations.
  
 
=== Passing kernel parameters ===
 
=== Passing kernel parameters ===
Line 185: Line 204:
 
There are two methods for setting the [[kernel parameters]] that rEFInd will pass to the kernel.
 
There are two methods for setting the [[kernel parameters]] that rEFInd will pass to the kernel.
  
{{Expansion|Add "Full auto detection" using Discoverable Partitions Specification and {{ic|/etc/fstab}} reading.}}
+
==== For kernels automatically detected by rEFInd ====
 +
 
 +
For automatically detected kernels you can either specify the kernel parameters explicitly in {{ic|/boot/refind_linux.conf}} or rely on rEFInd's ability to identify the root partition and kernel parameters. See [https://www.rodsbooks.com/refind/linux.html#easiest Methods of Booting Linux: For Those With Foresight or Luck: The Easiest Method] for more information.
 +
 
 +
{{Tip|rEFInd will automatically choose the Arch Linux icon ({{ic|os_arch.png}}) for the boot entry when {{ic|/etc/os-release}} is on the same partition as the kernel. If your {{ic|/boot}} is a separate partition see [https://www.rodsbooks.com/refind/configfile.html#icons Configuring the Boot Manager: Setting OS Icons].}}
 +
 
 +
For rEFInd to properly match multiple kernels with their respective initramfs you must uncomment and edit {{ic|extra_kernel_version_strings}} option in {{ic|refind.conf}}. E.g.:
 +
 
 +
{{hc|''esp''/EFI/refind/refind.conf|
 +
...
 +
extra_kernel_version_strings linux-hardened,linux-zen,linux-lts,linux
 +
...
 +
}}
 +
 
 +
{{Note|rEFInd only supports detecting one initramfs image per kernel, meaning it will not detect fallback initramfs nor [[microcode]] images.}}
  
==== For kernels automatically detected by rEFInd ====
+
===== refind_linux.conf =====
  
 
If rEFInd automatically detects your kernel, you can place a {{ic|refind_linux.conf}} file containing the kernel parameters in the same directory as your kernel. You can use {{ic|/usr/share/refind/refind_linux.conf-sample}} as a starting point. The first uncommented line of {{ic|refind_linux.conf}} will be the default parameters for the kernel. Subsequent lines will create entries in a submenu accessible using {{ic|+}}, {{ic|F2}}, or {{ic|Insert}}.
 
If rEFInd automatically detects your kernel, you can place a {{ic|refind_linux.conf}} file containing the kernel parameters in the same directory as your kernel. You can use {{ic|/usr/share/refind/refind_linux.conf-sample}} as a starting point. The first uncommented line of {{ic|refind_linux.conf}} will be the default parameters for the kernel. Subsequent lines will create entries in a submenu accessible using {{ic|+}}, {{ic|F2}}, or {{ic|Insert}}.
  
 
{{hc|/boot/refind_linux.conf|2=
 
{{hc|/boot/refind_linux.conf|2=
"Boot using default options"    "root=PARTUUID=XXXXXXXX rw add_efi_memmap"
+
"Boot using default options"    "root=PARTUUID=''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'' rw add_efi_memmap"
"Boot using fallback initramfs"  "root=PARTUUID=XXXXXXXX rw add_efi_memmap initrd=/boot/initramfs-linux-fallback.img"
+
"Boot using fallback initramfs"  "root=PARTUUID=''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'' rw add_efi_memmap initrd=/boot/initramfs-linux-fallback.img"
"Boot to terminal"              "root=PARTUUID=XXXXXXXX rw add_efi_memmap systemd.unit=multi-user.target"
+
"Boot to terminal"              "root=PARTUUID=''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'' rw add_efi_memmap systemd.unit=multi-user.target"
 
}}
 
}}
  
Line 203: Line 236:
 
Which will attempt to find your kernel in {{ic|/boot}} and automatically generate {{ic|refind_linux.conf}}. The script will only set up the most basic kernel parameters, so be sure to check the file it created for correctness.
 
Which will attempt to find your kernel in {{ic|/boot}} and automatically generate {{ic|refind_linux.conf}}. The script will only set up the most basic kernel parameters, so be sure to check the file it created for correctness.
  
If you do not specify an {{ic|1=initrd=}} parameter, rEFInd will automatically add it by searching for common RAM disk filenames in the same directory as the kernel. If you need multiple {{ic|1=initrd=}} parameters, you must specify them manually in {{ic|refind_linux.conf}}. For example, a [[Microcode]] passed before the initramfs: {{ic|1=... initrd=/boot/intel-ucode.img initrd=/boot/initramfs-linux.img}}.
+
If you do not specify an {{ic|1=initrd=}} parameter, rEFInd will automatically add it by searching for common RAM disk filenames in the same directory as the kernel. If you need multiple {{ic|1=initrd=}} parameters, you must specify them manually in {{ic|refind_linux.conf}}. For example, a [[microcode]] passed before the initramfs:
 +
 
 +
"Boot using default options"    "root=PARTUUID=''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'' rw add_efi_memmap initrd=/boot/intel-ucode.img initrd=/boot/amd-ucode.img initrd=/boot/initramfs-linux.img"
 +
 
 +
{{Note|Specifying {{ic|1=initrd=}} in {{ic|/boot/refind_linux.conf}} will prevent you from using the same kernel options for multiple kernels.}}
  
 
{{Warning|{{ic|initrd}} path is relative to the root of the file system on which the kernel resides. This could be {{ic|1=initrd=/boot/initramfs-linux.img}} or, if ESP is mounted to {{ic|/boot}}, {{ic|1=initrd=/initramfs-linux.img}}.}}
 
{{Warning|{{ic|initrd}} path is relative to the root of the file system on which the kernel resides. This could be {{ic|1=initrd=/boot/initramfs-linux.img}} or, if ESP is mounted to {{ic|/boot}}, {{ic|1=initrd=/initramfs-linux.img}}.}}
  
For rEFInd to properly match multiple kernels with their respective initramfs you must uncomment and edit {{ic|extra_kernel_version_strings}} option in {{ic|refind.conf}}. E.g.:
+
===== Without configuration =====
 +
 
 +
{{Expansion|Add "Full auto detection" using Discoverable Partitions Specification and {{ic|/etc/fstab}} reading.}}
 +
 
 +
As a fallback mechanism rEFInd can:
 +
 
 +
* Identify the root partition (for {{ic|1=root=}} parameter ) via the [https://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/ Discoverable Partitions Specification] or {{ic|/etc/fstab}}.
 +
* Detect kernel options ({{ic|ro}} or {{ic|rw}}) from [[Wikipedia:GUID Partition Table#Partition entries (LBA 2-33)|GPT partition attributes]] (using attribute {{ic|60}} "read-only") or {{ic|/etc/fstab}}.
  
{{hc|''esp''/EFI/refind/refind.conf|
+
{{Note|rEFInd does not support escape codes (e.g. for [[fstab#Filepath spaces|spaces]]) in {{ic|/etc/fstab}}.}}
...
 
extra_kernel_version_strings linux-hardened,linux-zen,linux-lts,linux
 
...
 
}}
 
  
 
==== Manual boot stanzas ====
 
==== Manual boot stanzas ====
Line 219: Line 259:
 
If your kernel is not autodetected, or if you simply want more control over the options for a menu entry, you can manually create boot entries using stanzas in {{ic|refind.conf}}. Ensure that {{ic|scanfor}} includes {{ic|manual}} or these entries will not appear in rEFInd's menu. Kernel parameters are set with the {{ic|options}} keyword. rEFInd will append the {{ic|1=initrd=}} parameter using the file specified by the {{ic|initrd}} keyword in the stanza. If you need additional initrds (e.g. for [[Microcode]]), you can specify them in {{ic|options}} (and the one specified by the {{ic|initrd}} keyword will be added to the end).
 
If your kernel is not autodetected, or if you simply want more control over the options for a menu entry, you can manually create boot entries using stanzas in {{ic|refind.conf}}. Ensure that {{ic|scanfor}} includes {{ic|manual}} or these entries will not appear in rEFInd's menu. Kernel parameters are set with the {{ic|options}} keyword. rEFInd will append the {{ic|1=initrd=}} parameter using the file specified by the {{ic|initrd}} keyword in the stanza. If you need additional initrds (e.g. for [[Microcode]]), you can specify them in {{ic|options}} (and the one specified by the {{ic|initrd}} keyword will be added to the end).
  
Manual boot stanzas are explained in [http://www.rodsbooks.com/refind/configfile.html#stanzas Creating Manual Boot Stanzas].
+
Manual boot stanzas are explained in [https://www.rodsbooks.com/refind/configfile.html#stanzas Creating Manual Boot Stanzas].
  
 
{{hc|''esp''/EFI/refind/refind.conf|2=
 
{{hc|''esp''/EFI/refind/refind.conf|2=
Line 229: Line 269:
 
loader  /boot/vmlinuz-linux
 
loader  /boot/vmlinuz-linux
 
initrd  /boot/initramfs-linux.img
 
initrd  /boot/initramfs-linux.img
options  "root=PARTUUID=''XXXXXXXX'' rw add_efi_memmap"
+
options  "root=PARTUUID=''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'' rw add_efi_memmap"
 
submenuentry "Boot using fallback initramfs" {
 
submenuentry "Boot using fallback initramfs" {
 
initrd /boot/initramfs-linux-fallback.img
 
initrd /boot/initramfs-linux-fallback.img
Line 248: Line 288:
  
 
rEFInd is compatible with the EFI system partition created by a UEFI Windows installation, so there is no need to create or format another FAT32 partition when installing Arch alongside Windows. Simply mount the existing ESP and install rEFInd as usual. By default, rEFInd's autodetection feature should recognize any existing Windows/recovery bootloaders.
 
rEFInd is compatible with the EFI system partition created by a UEFI Windows installation, so there is no need to create or format another FAT32 partition when installing Arch alongside Windows. Simply mount the existing ESP and install rEFInd as usual. By default, rEFInd's autodetection feature should recognize any existing Windows/recovery bootloaders.
 +
 +
{{Note|In some cases, Windows behaves differently (low resolution boot screen, OEM logo replaced by Windows logo, black screen after boot screen, artifacting). If you face such issues, try setting {{ic|use_graphics_for +,windows}} in {{ic|''esp''/EFI/refind/refind.conf}} or adding {{ic|graphics on}} to the Windows boot stanza.}}
  
 
== Tools ==
 
== Tools ==
Line 253: Line 295:
 
{{Move|Unified Extensible Firmware Interface|Although rEFInd has a special interface for these common tools, they are not a feature of rEFInd.}}
 
{{Move|Unified Extensible Firmware Interface|Although rEFInd has a special interface for these common tools, they are not a feature of rEFInd.}}
  
rEFInd supports running various [http://www.rodsbooks.com/refind/installing.html#addons 3rd-party tools]. Tools need to be installed separately. Edit {{ic|showtools}} in {{ic|refind.conf}} to choose which ones to show.
+
rEFInd supports running various [https://www.rodsbooks.com/refind/installing.html#addons 3rd-party tools]. Tools need to be installed separately. Edit {{ic|showtools}} in {{ic|refind.conf}} to choose which ones to show.
  
 
{{hc|''esp''/EFI/refind/refind.conf|
 
{{hc|''esp''/EFI/refind/refind.conf|
 
...
 
...
showtools [[#UEFI shell|shell]], [[#Memtest86|memtest]], [[#Key management tools|mok_tool]], [[#GPT fdisk (gdisk)|gdisk]], [[#iPXE|netboot]], ...
+
showtools [[#UEFI shell|shell]], [[#Memtest86|memtest]], [[#Key management tools|mok_tool]], [[#GPT fdisk (gdisk)|gdisk]], [[#iPXE|netboot]], [[#fwupdate|fwupdate]] ...
 
...
 
...
 
}}
 
}}
Line 265: Line 307:
 
See [[Unified Extensible Firmware Interface#UEFI Shell]].
 
See [[Unified Extensible Firmware Interface#UEFI Shell]].
  
Copy {{ic|shellx64.efi}} to the root of the [[EFI System Partition]].
+
Copy {{ic|shellx64.efi}} to the root of the [[EFI system partition]].
  
 
=== Memtest86 ===
 
=== Memtest86 ===
Line 295: Line 337:
 
=== GPT fdisk (gdisk) ===
 
=== GPT fdisk (gdisk) ===
  
There is no package for the EFI version of ''gdisk'', but you can download a binary from ''gdisk'''s author.
+
There is no package for the EFI version of [[gdisk]], but you can download a binary from SourceForge.
  
Download {{ic|gdisk-efi-*.zip}} from [http://sourceforge.net/projects/gptfdisk/files/gptfdisk/ SourceForge], extract the archive, and copy {{ic|gdisk_x64.efi}} to {{ic|''esp''/EFI/tools}}.
+
Download {{ic|gdisk-efi-*.zip}} from https://sourceforge.net/projects/gptfdisk/files/gptfdisk/, extract the archive, and copy {{ic|gdisk_x64.efi}} to {{ic|''esp''/EFI/tools/}}.
  
 
=== iPXE ===
 
=== iPXE ===
Line 309: Line 351:
 
  # cp /usr/share/refind/tools_x64/ipxe_discovery_x64.efi ''esp''/EFI/tools/ipxe_discovery.efi
 
  # cp /usr/share/refind/tools_x64/ipxe_discovery_x64.efi ''esp''/EFI/tools/ipxe_discovery.efi
 
  # cp /usr/share/refind/tools_x64/ipxe_x64.efi ''esp''/EFI/tools/ipxe.efi
 
  # cp /usr/share/refind/tools_x64/ipxe_x64.efi ''esp''/EFI/tools/ipxe.efi
 +
 +
=== fwupdate ===
 +
 +
Install and setup [[fwupd]].
 +
 +
Copy the {{ic|fwupx64.efi}} binary and firmware files to {{ic|''esp''/EFI/tools/}}:
 +
 +
# cp -r /usr/lib/fwupdate/EFI/arch/* ''esp''/EFI/tools/
  
 
== Tips and tricks ==
 
== Tips and tricks ==
Line 331: Line 381:
 
{{hc|''esp''/EFI/refind/refind.conf|
 
{{hc|''esp''/EFI/refind/refind.conf|
 
...
 
...
also_scan_dirs ''subvolume''/boot
+
also_scan_dirs +,''subvolume''/boot
 
...
 
...
 
}}
 
}}
Line 338: Line 388:
  
 
{{hc|/boot/refind_linux.conf|2=
 
{{hc|/boot/refind_linux.conf|2=
"Boot using standard options"  "root=PARTUUID=XXXXXXXX rootflags=rw,subvol=''subvolume'' initrd=''subvolume''/boot/initramfs-linux.img"
+
"Boot using standard options"  "root=PARTUUID=''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'' rw '''rootflags=subvol=''subvolume''''' initrd='''''subvolume'''''/boot/initramfs-linux.img"
 
}}
 
}}
  
 
==== Manual boot stanza ====
 
==== Manual boot stanza ====
  
If booting a [[btrfs]] subvolume as root, amend the {{ic|options}} line with {{ic|1=rootflags=subvol=<root subvolume>}}. In the example below, root has been mounted as a btrfs subvolume called 'ROOT' (e.g. {{ic|1=mount -o subvol=ROOT /dev/sdxY /mnt}}):
+
If booting a [[btrfs]] subvolume as root, amend the {{ic|options}} line with {{ic|1=rootflags=subvol=''root_subvolume''}}. In the example below, root has been mounted as a btrfs subvolume called 'ROOT' (e.g. {{ic|1=mount -o subvol=ROOT /dev/sdxY /mnt}}):
  
 
{{hc|''esp''/EFI/refind/refind.conf|2=
 
{{hc|''esp''/EFI/refind/refind.conf|2=
Line 352: Line 402:
 
         loader  /boot/vmlinuz-linux
 
         loader  /boot/vmlinuz-linux
 
         initrd  /boot/initramfs-linux.img
 
         initrd  /boot/initramfs-linux.img
         options  "root=PARTUUID=''XXXXXXXX'' rw '''rootflags=subvol=ROOT'''"
+
         options  "root=PARTUUID=''XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'' rw '''rootflags=subvol=ROOT'''"
 
...
 
...
 
}
 
}
Line 361: Line 411:
 
=== Apple Macs ===
 
=== Apple Macs ===
  
{{AUR|mactel-boot}} is an experimental "bless" utility for Linux. If that does not work, use "bless" from within OSX to set rEFInd as the default boot entry:
+
{{AUR|mactel-boot}} is an experimental ''bless'' utility for Linux. If that does not work, use ''bless'' from within OSX to set rEFInd as the default boot entry:
  
 
  # bless --setBoot --folder ''esp''/EFI/refind --file ''esp''/EFI/refind/refind_x64.efi
 
  # bless --setBoot --folder ''esp''/EFI/refind --file ''esp''/EFI/refind/refind_x64.efi
Line 371: Line 421:
 
== See also ==
 
== See also ==
  
* [http://www.rodsbooks.com/refind/ The rEFInd Boot Manager] by Roderick W. Smith.
+
* [https://www.rodsbooks.com/refind/ The rEFInd Boot Manager] by Roderick W. Smith.
 +
* [[Wikipedia:rEFInd]]
 
* {{ic|/usr/share/refind/docs/README.txt}}
 
* {{ic|/usr/share/refind/docs/README.txt}}
 
* [https://sourceforge.net/p/refind/discussion/ rEFInd discussion forum on Sourceforge]
 
* [https://sourceforge.net/p/refind/discussion/ rEFInd discussion forum on Sourceforge]

Latest revision as of 07:06, 30 August 2018

rEFInd is a UEFI boot manager capable of launching EFISTUB kernels. It is a fork of the no-longer-maintained rEFIt and fixes many issues with respect to non-Mac UEFI booting. It is designed to be platform-neutral and to simplify booting multiple OSes.

Note: In the entire article esp denotes the mountpoint of the EFI system partition aka ESP.

Installation

Install the refind-efi package.

rEFInd has read-only drivers for ReiserFS, Ext2, Ext4, Btrfs, ISO-9660, HFS+, and NTFS. Additionally rEFInd can use drivers from the UEFI firmware i.e. FAT (and HFS+ on Macs or ISO-9660 on some systems).

Note: Your kernel and initramfs must reside on a file system that rEFInd can read.

To find additional drivers see The rEFInd Boot Manager: Using EFI Drivers: Finding Additional EFI Drivers.

Installation with refind-install script

The rEFInd package includes the refind-install script to simplify the process of setting rEFInd as your default EFI boot entry. The script has several options for handling differing setups and UEFI implementations. See refind-install(8) or read the comments in the install script for explanations of the various installation options.

For many systems it should be sufficient to simply run:

# refind-install

This will attempt to find and mount your ESP, copy rEFInd files to esp/EFI/refind/, and use efibootmgr to make rEFInd the default EFI boot application.

Alternatively you can install rEFInd to the default/fallback boot path esp/EFI/BOOT/bootx64.efi. This is helpful for bootable USB flash drives or on systems that have issues with the NVRAM changes made by efibootmgr:

# refind-install --usedefault /dev/sdXY

Where /dev/sdXY is of your EFI System Partition.

Note: By default refind-install installs only the driver for the file system on which kernel resides. Additional file systems need to be installed manually or you can install all drivers with the --alldrivers option. This is useful for bootable USB flash drives e.g.:
# refind-install --usedefault /dev/sdXY --alldrivers

After installing rEFInd's files to the ESP, verify that rEFInd has created refind_linux.conf containing the required kernel parameters (e.g. root=) in the same directory as your kernel. If it has not created this file, you will need to set up #Passing kernel parameters manually or you will most likely get a kernel panic on your next boot.

By default, rEFInd will scan all of your drives (that it has drivers for) and add a boot entry for each EFI bootloader it finds, which should include your kernel (since Arch enables EFISTUB by default). So you may have a bootable system at this point.

Tip: It is always a good idea to edit the default configuration file esp/EFI/refind/refind.conf to ensure that the default options work for you.
Warning: When refind-install is run in chroot (e.g. in live system when installing Arch Linux) /boot/refind_linux.conf is populated with kernel options from the live system not the one on which it is installed. You will need to edit /boot/refind_linux.conf and adjust the kernel options manually. See #refind_linux.conf for an example.

Secure Boot

See Managing Secure Boot for Secure Boot support in rEFInd.

Using PreLoader

See Secure Boot#Set up PreLoader to acquire signed PreLoader.efi and HashTool.efi binaries.

Execute refind-install with the option --preloader /path/to/preloader

# refind-install --preloader /usr/share/preloader-signed/PreLoader.efi

Next time you boot with Secure Boot enabled, HashTool will launch and you will need to enroll the hash of rEFInd (loader.efi), rEFInd's drivers (e.g. ext4_x64.efi) and kernel (e.g. vmlinuz-linux).

See refind-install(8) for more information.

Tip: The signed HashTool is only capable of accessing the partition it was launched from. This means if your kernel is not on the ESP, you will not be able to enroll its hash from HashTool. You can workaround this by using #KeyTool, since it is capable of enrolling a hash in MokList and is not limited to one partition. Remember to enroll KeyTool's hash before using it.
Using shim

Install shim-signedAUR. Read Secure Boot#shim, but skip all file copying.

Using hashes

To use only hashes with shim, execute refind-install with the option --shim /path/to/shim

# refind-install --shim /usr/share/shim-signed/shimx64.efi

Next time you boot with Secure Boot enabled, MokManager will launch and you will need to enroll the hash of rEFInd (grubx64.efi), rEFInd's drivers (e.g. ext4_x64.efi) and kernel (e.g. vmlinuz-linux).

Using Machine Owner Key

To sign rEFInd with a Machine Owner Key (MOK), install sbsigntools.

Tip: If you already have created a MOK, place the files in the directory /etc/refind.d/keys with the names refind_local.key (PEM format private key), refind_local.crt (PEM format certificate) and refind_local.cer (DER format certificate).

Execute refind-install with the options --shim /path/to/shim and --localkeys:

# refind-install --shim /usr/share/shim-signed/shimx64.efi --localkeys

refind-install will create the keys for you and sign itself and its drivers. You will need to sign the kernel with the same key, e.g.:

# sbsign --key /etc/refind.d/keys/refind_local.key --cert /etc/refind.d/keys/refind_local.crt --output /boot/vmlinuz-linux /boot/vmlinuz-linux
Tip: The kernel signing can be automated with a pacman hook, e.g.:
/etc/pacman.d/hooks/999-sign_kernel_for_secureboot.hook
[Trigger]
Operation = Install
Operation = Upgrade
Type = Package
Target = linux

[Action]
Description = Signing kernel with Machine Owner Key for Secure Boot
When = PostTransaction
Exec = /usr/bin/sbsign --key /etc/refind.d/keys/refind_local.key --cert /etc/refind.d/keys/refind_local.crt --output /boot/vmlinuz-linux /boot/vmlinuz-linux
Depends = sbsigntools

Once in MokManager add refind_local.cer to MoKList. refind_local.cer can be found inside a directory called keys in the rEFInd's installation directory, e.g. esp/EFI/refind/keys/refind_local.cer.

See refind-install(8) for more information.

Using your own keys

Follow Secure Boot#Using your own keys to create keys.

Create directory /etc/refind.d/keys and place Signature Database (db) key and certificates in it. Name the files: refind_local.key (PEM format private key), refind_local.crt (PEM format certificate) and refind_local.cer (DER format certificate).

When running install script add option --localkeys, e.g.:

# refind-install --localkeys

rEFInd EFI binaries will be signed with the supplied key and certificate.

Manual installation

Tip: rEFInd can boot Linux in many ways. See The rEFInd Boot Manager: Methods of Booting Linux for coverage of the various approaches.

If the refind-install script does not work for you, rEFInd can be set up manually.

First, copy the executable to the ESP:

# mkdir -p esp/EFI/refind
# cp /usr/share/refind/refind_x64.efi esp/EFI/refind/

If you want to install rEFInd to the default/fallback boot path replace esp/EFI/refind/ with esp/EFI/BOOT/ in the following instructions and copy rEFInd EFI executable to esp/EFI/BOOT/bootx64.efi:

# mkdir -p esp/EFI/BOOT
# cp /usr/share/refind/refind_x64.efi esp/EFI/BOOT/bootx64.efi

Then use efibootmgr to create a boot entry in the UEFI NVRAM, where /dev/sdX and Y are the device and partition number of your EFI System Partition. If you are installing rEFInd to the default/fallback boot path esp/EFI/BOOT/bootx64.efi, you can skip this step.

# efibootmgr --create --disk /dev/sdX --part Y --loader /EFI/refind/refind_x64.efi --label "rEFInd Boot Manager" --verbose

At this point, you should be able to reboot into rEFInd, but it will not be able to boot your kernel. If your kernel does not reside on your ESP, rEFInd can mount your partitions to find it - provided it has the right drivers.

rEFInd automatically loads all drivers from the subdirectories drivers and drivers_arch (e.g. drivers_x64) in its install directory.

# mkdir esp/EFI/refind/drivers_x64
# cp /usr/share/refind/drivers_x64/drivername_x64.efi esp/EFI/refind/drivers_x64/

Now rEFInd should have a boot entry for your kernel, but it will not pass the correct kernel parameters. Set up #Passing kernel parameters. You should now be able to boot your kernel using rEFInd. If you are still unable to boot or if you want to tweak rEFInd's settings, many options can be changed with a configuration file:

# cp /usr/share/refind/refind.conf-sample esp/EFI/refind/refind.conf

The sample configuration file is well commented and self-explanatory.

Unless you have set textonly in the configuration file, you should copy rEFInd's icons to get rid of the ugly placeholders:

# cp -r /usr/share/refind/icons esp/EFI/refind/

You can try out different fonts by copying them and changing the font setting in refind.conf:

# cp -r /usr/share/refind/fonts esp/EFI/refind/
Tip: Pressing F10 in rEFInd will save a screenshot to the top level directory of the ESP.

Upgrading

Pacman updates the rEFInd files in /usr/share/refind/ and will not copy new files to the ESP for you. If refind-install worked for your original installation of rEFInd, you can rerun it to copy the updated files. The new configuration file will be copied as refind.conf-sample so that you can integrate changes into your existing configuration file using a diff tool. If your rEFInd required #Manual installation, you will need to figure out which files to copy yourself.

Pacman hook

You can automate the update process using a pacman hook:

/etc/pacman.d/hooks/refind.hook
[Trigger]
Operation=Upgrade
Type=Package
Target=refind-efi

[Action]
Description = Updating rEFInd on ESP
When=PostTransaction
Exec=/usr/bin/refind-install

Where the Exec= may need to be changed to the correct update command for your setup. If you did #Manual installation, you could create your own update script to call with the hook.

Tip: If you setup rEFInd with #Secure Boot, you may want to additionally add the option --yes to the refind-install command. It will prevent the command from failing if it gets executed when Secure Boot is disabled. See refind-install(8) for more information.

Configuration

The rEFInd configuration refind.conf is located in the same directory as the rEFInd EFI application (usually esp/EFI/refind or esp/EFI/BOOT). The default configuration file contains extensive comments explaining all its options, see Configuring the Boot Manager for more detailed explanations.

Passing kernel parameters

There are two methods for setting the kernel parameters that rEFInd will pass to the kernel.

For kernels automatically detected by rEFInd

For automatically detected kernels you can either specify the kernel parameters explicitly in /boot/refind_linux.conf or rely on rEFInd's ability to identify the root partition and kernel parameters. See Methods of Booting Linux: For Those With Foresight or Luck: The Easiest Method for more information.

Tip: rEFInd will automatically choose the Arch Linux icon (os_arch.png) for the boot entry when /etc/os-release is on the same partition as the kernel. If your /boot is a separate partition see Configuring the Boot Manager: Setting OS Icons.

For rEFInd to properly match multiple kernels with their respective initramfs you must uncomment and edit extra_kernel_version_strings option in refind.conf. E.g.:

esp/EFI/refind/refind.conf
...
extra_kernel_version_strings linux-hardened,linux-zen,linux-lts,linux
...
Note: rEFInd only supports detecting one initramfs image per kernel, meaning it will not detect fallback initramfs nor microcode images.
refind_linux.conf

If rEFInd automatically detects your kernel, you can place a refind_linux.conf file containing the kernel parameters in the same directory as your kernel. You can use /usr/share/refind/refind_linux.conf-sample as a starting point. The first uncommented line of refind_linux.conf will be the default parameters for the kernel. Subsequent lines will create entries in a submenu accessible using +, F2, or Insert.

/boot/refind_linux.conf
"Boot using default options"     "root=PARTUUID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX rw add_efi_memmap"
"Boot using fallback initramfs"  "root=PARTUUID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX rw add_efi_memmap initrd=/boot/initramfs-linux-fallback.img"
"Boot to terminal"               "root=PARTUUID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX rw add_efi_memmap systemd.unit=multi-user.target"

Alternatively, try running:

# mkrlconf

Which will attempt to find your kernel in /boot and automatically generate refind_linux.conf. The script will only set up the most basic kernel parameters, so be sure to check the file it created for correctness.

If you do not specify an initrd= parameter, rEFInd will automatically add it by searching for common RAM disk filenames in the same directory as the kernel. If you need multiple initrd= parameters, you must specify them manually in refind_linux.conf. For example, a microcode passed before the initramfs:

"Boot using default options"     "root=PARTUUID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX rw add_efi_memmap initrd=/boot/intel-ucode.img initrd=/boot/amd-ucode.img initrd=/boot/initramfs-linux.img"
Note: Specifying initrd= in /boot/refind_linux.conf will prevent you from using the same kernel options for multiple kernels.
Warning: initrd path is relative to the root of the file system on which the kernel resides. This could be initrd=/boot/initramfs-linux.img or, if ESP is mounted to /boot, initrd=/initramfs-linux.img.
Without configuration

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: Add "Full auto detection" using Discoverable Partitions Specification and /etc/fstab reading. (Discuss in Talk:REFInd#)

As a fallback mechanism rEFInd can:

Note: rEFInd does not support escape codes (e.g. for spaces) in /etc/fstab.

Manual boot stanzas

If your kernel is not autodetected, or if you simply want more control over the options for a menu entry, you can manually create boot entries using stanzas in refind.conf. Ensure that scanfor includes manual or these entries will not appear in rEFInd's menu. Kernel parameters are set with the options keyword. rEFInd will append the initrd= parameter using the file specified by the initrd keyword in the stanza. If you need additional initrds (e.g. for Microcode), you can specify them in options (and the one specified by the initrd keyword will be added to the end).

Manual boot stanzas are explained in Creating Manual Boot Stanzas.

esp/EFI/refind/refind.conf
...

menuentry "Arch Linux" {
	icon     /EFI/refind/icons/os_arch.png
	volume   "Arch Linux"
	loader   /boot/vmlinuz-linux
	initrd   /boot/initramfs-linux.img
	options  "root=PARTUUID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX rw add_efi_memmap"
	submenuentry "Boot using fallback initramfs" {
		initrd /boot/initramfs-linux-fallback.img
	}
	submenuentry "Boot to terminal" {
		add_options "systemd.unit=multi-user.target"
	}
}

It is likely that you will need to change volume to match either a filesystem's LABEL, a PARTLABEL, or a PARTUUID of the partition where the kernel image resides. See Persistent block device naming#by-label for examples of assigning a volume label. If volume is not specified it defaults to volume from which rEFInd was launched (typically EFI System Partition).

Warning: loader and initrd paths are relative to the root of volume.

Installation alongside an existing UEFI Windows installation

Note: The usual caveats of Dual boot with Windows apply.

rEFInd is compatible with the EFI system partition created by a UEFI Windows installation, so there is no need to create or format another FAT32 partition when installing Arch alongside Windows. Simply mount the existing ESP and install rEFInd as usual. By default, rEFInd's autodetection feature should recognize any existing Windows/recovery bootloaders.

Note: In some cases, Windows behaves differently (low resolution boot screen, OEM logo replaced by Windows logo, black screen after boot screen, artifacting). If you face such issues, try setting use_graphics_for +,windows in esp/EFI/refind/refind.conf or adding graphics on to the Windows boot stanza.

Tools

Tango-go-next.pngThis article or section is a candidate for moving to Unified Extensible Firmware Interface.Tango-go-next.png

Notes: Although rEFInd has a special interface for these common tools, they are not a feature of rEFInd. (Discuss in Talk:REFInd#)

rEFInd supports running various 3rd-party tools. Tools need to be installed separately. Edit showtools in refind.conf to choose which ones to show.

esp/EFI/refind/refind.conf
...
showtools shell, memtest, mok_tool, gdisk, netboot, fwupdate ...
...

UEFI shell

See Unified Extensible Firmware Interface#UEFI Shell.

Copy shellx64.efi to the root of the EFI system partition.

Memtest86

Install memtest86-efiAUR and copy it to esp/EFI/tools/.

# cp /usr/share/memtest86-efi/bootx64.efi esp/EFI/tools/memtest86.efi

Key management tools

rEFInd can detect Secure Boot key management tools if they are placed in rEFInd's directory on ESP, esp/ or esp/EFI/tools/.

HashTool

Follow #Using PreLoader and HashTool.efi will be placed in rEFInd's directory.

MokManager

Follow #Using shim and MokManager will be placed in rEFInd's directory.

KeyTool

Install efitools.

Place KeyTool EFI binary in esp/ or esp/EFI/tools/ with the name KeyTool.efi or KeyTool-signed.efi.

See Secure Boot#Using KeyTool for instructions on signing KeyTool.efi.

GPT fdisk (gdisk)

There is no package for the EFI version of gdisk, but you can download a binary from SourceForge.

Download gdisk-efi-*.zip from https://sourceforge.net/projects/gptfdisk/files/gptfdisk/, extract the archive, and copy gdisk_x64.efi to esp/EFI/tools/.

iPXE

Tango-view-refresh-red.pngThis article or section is out of date.Tango-view-refresh-red.png

Reason: iPXE is not packaged in refind-efi anymore. (Discuss in Talk:REFInd#)
Note: PXE support in rEFInd is experimental.

refind-efi contains the iPXE UEFI binaries, you just need to copy them to esp/EFI/tools/.

# cp /usr/share/refind/tools_x64/ipxe_discovery_x64.efi esp/EFI/tools/ipxe_discovery.efi
# cp /usr/share/refind/tools_x64/ipxe_x64.efi esp/EFI/tools/ipxe.efi

fwupdate

Install and setup fwupd.

Copy the fwupx64.efi binary and firmware files to esp/EFI/tools/:

# cp -r /usr/lib/fwupdate/EFI/arch/* esp/EFI/tools/

Tips and tricks

Using drivers in UEFI shell

To use rEFInd's drivers in UEFI shell load them using command load and refresh mapped drives with map -r.

Shell> load FS0:\EFI\refind\drivers\ext4_x64.efi
Shell> map -r

Now you can access your file system from UEFI shell.

Troubleshooting

Btrfs subvolume support

Auto detection

To allow kernel auto detection on a Btrfs subvolume uncomment and edit also_scan_dirs in refind.conf.

esp/EFI/refind/refind.conf
...
also_scan_dirs +,subvolume/boot
...

Next add subvol=subvolume to rootflags in refind_linux.conf and then prepend subvolume to the initrd path.

/boot/refind_linux.conf
"Boot using standard options"  "root=PARTUUID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX rw rootflags=subvol=subvolume initrd=subvolume/boot/initramfs-linux.img"

Manual boot stanza

If booting a btrfs subvolume as root, amend the options line with rootflags=subvol=root_subvolume. In the example below, root has been mounted as a btrfs subvolume called 'ROOT' (e.g. mount -o subvol=ROOT /dev/sdxY /mnt):

esp/EFI/refind/refind.conf
...
menuentry "Arch Linux" {
        icon     /EFI/refind/icons/os_arch.png
        volume   "Arch Linux"
        loader   /boot/vmlinuz-linux
        initrd   /boot/initramfs-linux.img
        options  "root=PARTUUID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX rw rootflags=subvol=ROOT"
...
}

A failure to do so will otherwise result in the following error message: ERROR: Root device mounted successfully, but /sbin/init does not exist.

Apple Macs

mactel-bootAUR is an experimental bless utility for Linux. If that does not work, use bless from within OSX to set rEFInd as the default boot entry:

# bless --setBoot --folder esp/EFI/refind --file esp/EFI/refind/refind_x64.efi

VirtualBox

Currently, VirtualBox will only boot the default esp/EFI/BOOT/bootx64.efi path, so refind-install needs to be used with at least the --usedefault option. See VirtualBox#Installation in EFI mode for more information.

See also