Difference between revisions of "REFInd"

From ArchWiki
Jump to: navigation, search
(Manual boot stanzas: better link for label assigning)
 
(200 intermediate revisions by 23 users not shown)
Line 1: Line 1:
 +
{{Lowercase title}}
 
[[Category:Boot loaders]]
 
[[Category:Boot loaders]]
 +
[[ja:REFInd]]
 +
[[ru:REFInd]]
 
[[zh-CN:REFInd]]
 
[[zh-CN:REFInd]]
{{Lowercase title}}
+
{{Related articles start}}
rEFInd is a fork of rEFIt Boot Manager (used in Intel Macs) by Rod Smith (author of gdisk). rEFInd fixes many issues in rEFIt with respect to non-Mac UEFI booting and also has support for booting [[EFISTUB]] kernels and contains some features specific to them.
+
{{Related|Arch boot process}}
 +
{{Related|Boot loaders}}
 +
{{Related|Unified Extensible Firmware Interface}}
 +
{{Related|EFISTUB}}
 +
{{Related articles end}}
 +
''rEFInd'' is a [[UEFI]] boot manager capable of launching [[EFISTUB]] kernels. It is a fork of the no-longer-maintained [http://refit.sourceforge.net/ 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.
  
== Planning the partitions and kernel location ==
+
{{Note|In the entire article {{ic|''esp''}} denotes the mountpoint of the [[EFI System Partition]] aka ESP.}}
  
rEFInd is a UEFI boot manager that was written to handle EFI boot, and make booting Windows, Linux and Mac OS a relatively pain free process, particularly as the linux kernel is now built with its own EFI stub boot loader.
+
== Installation ==
  
It is convenient to set up the arch linux system so that the kernel and initial ramdisk files are in a journalled filesystem, so that repairs are possible in the event of errors in the
+
[[Install]] {{pkg|refind-efi}} from the [[Official repositories]].
filesystem, and keep only a minimal set of necessary files on the EFI, which is required to be formatted as VFAT.  
+
  
It is also desirable to have the system rebootable immediately after a kernel update, without further preparation or moving the kernel files from the location that they are created by pacman.
+
{{Warning|Your kernel and initramfs need to reside on a file system which ''rEFInd'' can read.}}
+
The assumption here is that the EFI will be mounted after the install as /boot/efi
+
  
If the root partition is mounted as / and a directory called /boot is created, then a convenient way to mount the EFI partition is to mount it as /boot/efi. Then the normal install location for the kernel and initial ramdisk is in /boot/ and the (VFAT) EFI is mounted at /boot/efi/. Then the rEFInd binary and associated directories and files can be placed in a newly created directory at /boot/efi/EFI/refind/
+
''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).
  
== Boot EFISTUB using rEFInd ==
+
To find additional drivers see [http://www.rodsbooks.com/refind/drivers.html#finding The rEFInd Boot Manager: Using EFI Drivers: Finding Additional EFI Drivers].
{{Tip|If you're new to [[EFISTUB]] and/or rEFInd, you need to read [http://www.rodsbooks.com/refind/linux.html The rEFInd Boot Manager: Methods of Booting Linux] before going any further. This section illustrates only one possible use-case for a pure Arch linux system which is not suitable for all configurations, and includes a section with one use-case for dual booting Archlinux with Windows 8.1.}}
+
  
{{Note|{{pkg|refind-efi}} includes a install script from upstream at {{ic|/usr/bin/refind-install}} which does the job of setting-up of rEFInd similar to the steps below.}}
+
=== Scripted installation ===
  
{{Note|For 32-bit aka IA32 EFI, replace '''x64''' with '''ia32''' (case-sensitive) in the commands below.}}
+
The rEFInd package includes the {{ic|/usr/bin/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, but for many systems it should be sufficient to simply run:
  
* Mount efivarfs
+
# refind-install
  
# mount -t efivarfs efivarfs /sys/firmware/efi/efivars              # ignore if already mounted
+
This will attempt to find and mount your [[ESP]], copy ''rEFInd'''s files to {{ic|/EFI/refind/}} on the ESP, and use {{ic|efibootmgr}} to make ''rEFInd'' the default EFI boot application.
  
* Install the {{Pkg|refind-efi}} package.
+
Alternatively you can install ''rEFInd'' to the default/fallback boot path {{ic|/EFI/BOOT/BOOT*.EFI}}. This is helpful for bootable USB flash drives or on systems that have issues with the NVRAM changes made by {{ic|efibootmgr}}:
  
* Copy the following files from their source directory to their destination
+
# refind-install --usedefault ''/dev/sdXY''
  
# cp /usr/share/refind/refind_x64.efi /boot/efi/EFI/refind/refind_x64.efi
+
Where {{ic|''/dev/sdXY''}} is the partition of your ESP.
# cp /usr/share/refind/refind.conf-sample  /boot/efi/EFI/refind/refind.conf
+
# cp -r /usr/share/refind/icons /boot/efi/EFI/refind/
+
# cp -r /usr/share/refind/fonts /boot/efi/EFI/refind/
+
# cp -r /usr/share/refind/drivers_x64 /boot/efi/EFI/refind/
+
  
* Edit rEFInd's config file at {{ic|/boot/efi/EFI/refind/refind.conf}}. The file is well commented and self explanatory. rEFInd should automatically find kernel files in /boot, but it is also possible to add a menu entry for Arch Linux. Set the default boot item to the Archlinux kernel by adding the line:
+
You can read the comments in the install script for explanations of the various installation options.
  
  default_selection vmlinuz
+
{{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.:
 +
  # refind-install --usedefault ''/dev/sdXY'' --alldrivers
 +
}}
  
A menu entry can be added to refind.conf such as
+
After installing rEFInd's files to the ESP, verify that ''rEFInd'' has created {{ic|refind_linux.conf}} containing the required [[kernel parameters]] (e.g. {{ic|1=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.
  
{{hc|refind.conf|<nowiki>
+
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.
menuentry "Arch Linux" {
+
        icon    EFI/refind/icons/os_linux.icns
+
        volume  "/"
+
        loader  /boot/vmlinuz-linux
+
        initrd  /boot/initramfs-linux.img
+
        options  "root=PARTUUID=3518bb68-d01e-45c9-b973-0b5d918aae96 rw rootfstype=ext4"
+
}
+
</nowiki>}}
+
  
but this may not be necessary unless standard options need to be changed. Note that the "volume" line contains the label of the volume where the root partition is. For alphameric characters only it is not necessary to put the name in quotes, but if you use special characters then the kernel will not boot unless the name is in quotes. Also the partition can be referenced using the PARTUUID or the UUID provided the appropriate string is used as verified from the output of the blkid command. If the root partition is not ext4 then the rootfstype will be as needed for the partition type, but should be detected automatically without this parameter.
+
{{Tip|It is always a good idea to edit the default config {{ic|/EFI/refind/refind.conf}} on the ESP to ensure that the default options work for you.}}
  
Note that if you choose to mount your ESP as a different name to /boot/efi then replace these paths as appropriate as in the lines above.
+
==== Secure Boot ====
  
{{Note|Modify the loader and initrd paths if you did not place them in your ESP's root. Replace the string after PARTUUID with your root's PARTUUID. Please note in the example above that PARTUUID/PARTLABEL identifies a GPT partition, and differs from the UUID/LABEL, which identifies a filesystem. Using the PARTUUID/PARTLABEL is advantageous because it is invariant if you reformat the partition with another filesystem. It's also useful if you don't have a filesystem on the partition (or use LUKS, which doesn't support LABELs).}}
+
===== Using PreLoader =====
  
To find the PARTUUID (or UUID) for the root partition use:
+
See [[Secure Boot#Set up PreLoader]] to acquire signed {{ic|PreLoader.efi}} and {{ic|HashTool.efi}} binaries.
  
  # blkid
+
Execute {{ic|refind-install}} with the option {{ic|--preloader ''/path/to/preloader''}}
 +
  # refind-install --preloader ''PreLoader.efi''
  
and
+
The script will
 +
* copy {{ic|PreLoader.efi}} to {{ic|''esp''/EFI/refind/refind_x64.efi}} or {{ic|''esp''/EFI/BOOT/BOOT_X64.EFI}} if used with {{ic|--usedefault}} option
 +
* copy rEFInd binary as {{ic|loader.efi}} to the same directory as PreLoader on ESP
 +
* copy {{ic|HashTool.efi}} to same directory as PreLoader on ESP
 +
* setup boot entry with {{ic|efibootmgr}} unless used with {{ic|--usedefault}} option
  
# lsblk -f
+
Next time you boot with Secure Boot enabled, HashTool will launch and you will need to register rEFInd ({{ic|loader.efi}}) as a trusted application.
  
to get the partition information matched to the correct root partition.
+
===== Using your own keys =====
  
* If the kernel and initramfs are located at /boot as default, you can create a {{ic|refind_linux.conf}} file inside the directory where the kernel and initramfs files are located. Or you can copy the sample file to the same directory that the kernel and initramfs are located using:
+
Follow [[Secure Boot#Using your own keys]] to create keys.
  
# cp /usr/share/refind/refind_linux.conf-sample /boot/refind_linux.conf
+
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}}.
  
{{hc|refind_linux.conf|<nowiki>
+
When running install script add option {{ic|--localkeys}}, e.g.:
"Boot with defaults"    "root=PARTUUID=XXXXXXXX rootfstype=XXXX ro"
+
# refind-install --localkeys
"Boot to terminal"      "root=PARTUUID=XXXXXXXX rootfstype=XXXX ro systemd.unit=multi-user.target"</nowiki>}}
+
  
where the PARTUUID from the blkid command is used, and the rootfstype is commonly ext4.
+
''rEFInd'' EFI binary will be signed with supplied key and certificate.
  
This file tells rEFInd where the root partition is located for the system boot, so the PARTUUID is that for the root partition.
+
=== Manual installation ===
  
The drivers that were copied to the refind directory in the ESP include an ext4 driver, and allow the rEFInd binary to read the kernel and initramfs file in the ext4 /boot directory.
+
{{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.}}
 +
{{Note|For 32-bit EFI, replace '''x64''' with '''ia32''' in the commands below.}}
  
{{Tip|Each line of {{ic|refind_linux.conf}} is displayed as a submenu by rEFInd. Access the submenu with "+" or "insert" or "F2" keys.}}
+
If the {{ic|refind-install}} script does not work for you, ''rEFInd'' can be set up manually.
  
* Create a boot entry in the UEFI NVRAM in the motherboard using efibootmgr
+
First, copy the executable to the ESP:
  
  # efibootmgr -c -d /dev/sdX -p Y -l /EFI/refind/refind_x64.efi -L "rEFInd"
+
  # cp /usr/share/refind/refind_x64.efi ''esp''/EFI/refind/
  
where sdX is drive containing the EFI partition, and Y is the partition number for the EFI on that drive.
+
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|/EFI/BOOT/BOOTX64.EFI}}, you can probably skip this step.
  
The entries can be checked by just using the command
+
# efibootmgr --create --disk ''/dev/sdX'' --part ''Y'' --loader /EFI/refind/refind_x64.efi --label "rEFInd Boot Manager"
  
# efibootmgr
+
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.
  
on its own to verify that there is now a refind entry, and the boot order should show that this is the first entry in the list.
+
''rEFInd'' automatically loads all drivers from the subdirectories {{ic|drivers}} and {{ic|drivers_''arch''}} (e.g. {{ic|drivers_x64}}) in its install directory.
  
For a few system types if the efibootmgr command does not create NVRAM entries correctly, then an alternative is to use bcfg from within a UEFI shell version 2, to write and manage NVRAM entries. Information about this is available elsewhere in the wiki.
+
# mkdir ''esp''/EFI/refind/drivers_x64
 +
# cp /usr/share/refind/drivers_x64/'''drivername'''_x64.efi ''esp''/EFI/refind/drivers_x64/
  
{{Note|As of {{Pkg|refind-efi}} 0.2.7, refind can auto-detect kernels in {{ic|/boot}}, if there are UEFI drivers for the filesystem used by /boot partition (or / partition if no separate /boot is used) in the ESP, and are loaded by rEFInd. This is enabled in the default configuration in {{ic|refind.conf}} (you may need to include the PATH to the drivers folders in the ESP). See [http://www.rodsbooks.com/refind/drivers.html] for more info.}}
+
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:
  
Once the system is rebooted when the install is complete the system should then boot to the graphical rEFInd screen after the POST is complete, and by default a 20 second timeout
+
# cp /usr/share/refind/refind.conf-sample ''esp''/EFI/refind/refind.conf
will run after which the system should boot by default to Archlinux (The timeout period can be changed by editing refind.conf). Once the system has booted then the root user can login and continue to configure the newly installed system.
+
  
During the 20 second timeout period the rEFInd boot manager can be interrupted to select different icons that can be booted, and it is also possible to change the boot kernel parameters
+
The sample config is well commented and self-explanatory.
in a similar way to what many users have been familiar with in the past using grub.
+
  
It is also possible to get a screenshot of the graphical rEFInd screen by hitting F10 and a bmp image file will be written to the top level directory of the EFI.
+
Unless you have set {{ic|textonly}} in the config file, you should copy ''rEFInd'''s icons to get rid of the ugly placeholders:
  
When the Archlinux kernel is updated via pacman then no further action is needed other than to reboot if the setup described above is used. For customised setups where the kernel is not placed in the /boot directory then the kernel and initramfs files may need to be moved to the directory where they will be booted before the new kernel will be active after reboot.
+
# cp -r /usr/share/refind/icons ''esp''/EFI/refind/
  
== A dual boot setup for Archlinux and Windows 8.1 using rEFInd ==
+
You can try out different fonts by copying them and changing the {{ic|font}} setting in {{ic|refind.conf}}:
  
A second use-case is where an arch install is to be added to a pre-existing Windows 8.1 setup as a dual boot system, where booting to both operating systems is desired as well as any factory Recovery partitions.
+
# cp -r /usr/share/refind/fonts ''esp''/EFI/refind/
  
Here only the differences between the pure Archlinux setup above and the dual boot system are highlighted.
+
{{Tip|Pressing F10 in ''rEFInd'' will save a screenshot to the top level directory of the ESP.}}
  
Normally Windows 8 or 8.1 boots under Secure Boot. Although in principle Secure Boot could be setup for Archlinux it is not straighforward, and it is recommended to switch off Secure Boot in the BIOS if the machine is to be dual booted with Archlinux. Check that the machine still boots correctly with Secure Boot turned off.
+
=== Upgrading ===
  
It is also necessary to switch off Fastboot from within Windows 8.1 before attempting to install Archlinux in a dual boot system.  Fastboot is a type of hybrid suspend with part of the
+
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.
system stored during shutdown. If Fastboot is not turned off then corruption is likely if Windows is booted again after the system has booted Archlinux.
+
  
The changes that are therefore recommended for a pre-existing Windows 8 or 8.1 system on which Archlinux is going to be installed are as follows:
+
==== Pacman hook ====
  
1) Within Windows 8.1 switch off Fastboot and check that Windows restarts without any problem.
+
You can automate the update process using a hook:
2) Switch off Secure Boot from the BIOS settings, and check that Windows restarts correctly.
+
  
In order to create space on the disk for linux partitions it is recommended that, with Windows 8.1 running, go to the Windows Disk Management facility and shrink the C: drive to make
+
{{hc|/etc/pacman.d/hooks/refind.hook|2=[Trigger]
space for new partitions in which Archlinux will be installed.
+
Operation=Upgrade
 +
Type=Package
 +
Target=refind-efi
  
Note here that if you change the partitions using an externally booted partition editor such as gparted it is possible that Windows, or any Recovery boot partitions may not boot once the partitions, or particularly the partition numbers, have been changed.
+
[Action]
 +
When=PostTransaction
 +
Exec=/usr/bin/refind-install}}
  
It is straightforward to create new partitions using the Archlinux install iso during the install process using the gdisk command.
+
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.
  
It is recommended not to create additional EFI partitions, and to utilise the existing EFI partition that the pre-existing Windows system uses. Hence it is only necessary to create a root partition ( / ), and possibly an additional partition for /home or /opt ( often as ext4, but any suitable linux partition type can be used by preference). A linux swap partition may also be desirable and in this use case it is no different to a standard Archlinux install. For an existing UEFI system the main hard drive will have a GPT partition table, and from the Archlinux install iso, once booted, the gdisk facility is simple to use to create the additional linux partitions.
+
== Configuration ==
  
Once the partitions have been created then a filesystem must be created in each new partition except swap.
+
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.
  
This can be done using for example mkfs -t ext4 /dev/sdXY as necessary for each new linux partition.
+
=== Passing kernel parameters ===
  
The only difference between a dual boot system and the pure linux install described in the first section of this page, is that the rEFInd files are placed in a new directory that is
+
There are two methods for setting the [[kernel parameters]] that ''rEFInd'' will pass to the kernel.
created in the pre-existing EFI, leaving the existing directories and files for Windows and recovery binary files untouched.
+
  
Hence create a new directory within the EFI:
+
==== For kernels automatically detected by rEFInd ====
  
/boot/efi/EFI/refind
+
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}}.
  
Then install rEFInd as in the pure linux case above, and copy the same set of files and directories as above into this directory.
+
{{hc|/boot/refind_linux.conf|<nowiki>
 +
"Boot using default options"    "root=PARTUUID=XXXXXXXX rw add_efi_memmap"
 +
"Boot using fallback initramfs"  "root=PARTUUID=XXXXXXXX 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"
 +
</nowiki>}}
  
The remainder of the install is the same as for a pure Archlinux install.
+
Alternatively, try running:
  
Once the remainder of the Archlinux install is complete, then booting the new system should result in the rEFInd screen with Archlinux as the default entry visible, but with additional icons visible for booting Windows 8.1 as well as Recovery to Factory Settings if this was provided by the original manufacturer. Note that if the Recovery boot is initiated it will overwrite the linux partitions, and so would normally only be used in the event that the Windows 8.1 system was unrecoverable, in which case Archlinux would then need to be installed again from scratch.
+
# refind-mkrlconf
  
== Upgrading rEFInd ==
+
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.
  
When a new version of the refind package is installed as an update via pacman, then all that is necessary is to copy the refind directories and files, except the refind.conf and refind_linux.conf as in the pure Archlinux install section above.
+
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}}.
  
To automatically update rEFInd to the latest version, you could run refind-install (in cronjob) as alternative to the systemd script below.
+
{{Warning|{{ic|initrd}} path is relative to the root of the file system on which the kernel resides.}}
The command will be executed as follow:
+
{{hc|/usr/bin/refind-install|<nowiki>
+
Installing rEFInd on Linux....
+
ESP was found at /boot/efi using vfat
+
Found rEFInd installation in /boot/efi/EFI/refind; upgrading it.
+
Installing driver for ext4 (ext4_x64.efi)
+
Copied rEFInd binary files
+
  
Notice: Backed up existing icons directory as icons-backup.
+
==== Manual boot stanzas ====
Existing refind.conf file found; copying sample file as refind.conf-sample
+
to avoid overwriting your customizations.
+
  
rEFInd has been set as the default boot manager.
+
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).
Existing //boot/refind_linux.conf found; not overwriting.
+
  
Installation has completed successfully.
+
{{hc|''esp''/EFI/refind/refind.conf|<nowiki>
 +
...
 +
 
 +
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 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"
 +
}
 +
}
 
</nowiki>}}
 
</nowiki>}}
  
== Systemd Automation (Upgrading) ==
+
It is likely that you will need to change {{ic|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.
  
To automate the process of copying refind files and updating the nvram (if needed) use the following script.
+
{{Warning|{{ic|loader}} and {{ic|initrd}} paths are relative to the root of {{ic|volume}}.}}
  
{{Note|If you want to change the directory that refind is installed in the UEFISYS partition, just change the value of $refind_dir in the script}}
+
== Using rEFInd with an existing UEFI Windows installation ==
{{hc|/usr/lib/systemd/scripts/refind_name_patchv2|<nowiki>
+
#!/usr/bin/env bash
+
## COPYRIGHT 2013 : MARK E. LEE (BLUERIDER) : mlee24@binghamton.edu; mark@markelee.com
+
  
## LOG
+
{{Note|The usual caveats of [[Dual boot with Windows]] apply.}}
## 1/17/2013 : Version 2 of refind_name_patch is released
+
##          : Supports long subdirectory location for refind
+
##          : Updates nvram when needed
+
##          : 10% speed boost
+
## 7/15/2013 : Changed arch to match 32-bit (ia32) and 64-bit (x64) naming scheme
+
##          : Changed directory copying in update-efi-dir to copy tools and drivers directories explicitly
+
##          : Changed efibootmgr writing code to be more concise and added (-w) to write the entry as per dusktreader's excellent guide : https://docs.google.com/document/d/1pvgm3BprpXoadsQi38FxqMOCUZhcSqFhZ26FZBkmn9I/edit
+
##          : Function to check if NVRAM boot entry was already listed was fixed to use awk and an if then clause
+
##          : ref_bin_escape was modified from : ref_bin_escape=${ref_bin//\//\\\\} to remove extra backslashes (error does not show up when using cmdline)
+
## 7/29/2013 : Changed location of tools,drivers, and binary directory to match capricious upstream move to /usr/share/refind
+
  
function main () {  ## main insertion function
+
''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.
  declare -r refind_dir="/boot/efi/EFI/refind"; ## set the refind directory
+
  arch=$(uname -m | awk -F'_' '{if ($1 == "x86") {print "x"$2} else if ($1 == "i686") {print "ia32"}}') &&  ## get bit architecture
+
  update-efi-dir;  ## updates or creates the refind directory
+
  update-efi-nvram;  ## updates nvram if needed
+
}
+
  
function update-efi-dir () {  ## setup the refind directory
+
== Tools ==
  if [ ! -d $refind_dir ]; then  ## check if refind directory exists
+
    echo "Couldn't find $refind_dir";
+
    mkdir $refind_dir &&  ## make the refind directory if needed
+
    echo "Made $refind_dir";
+
  fi;
+
  if [ "$arch" ]; then  ## check if anything was stored in $arch
+
    cp -r /usr/share/refind/{refind_$arch.efi,keys,images,icons,fonts,docs,{tools,drivers}_$arch} $refind_dir/  && ## update the bins and dirs
+
    echo "Updated binaries and directory files for refind at $refind_dir";
+
  else
+
    echo "Failed to detect an x86 architecture";
+
    exit;
+
  fi;
+
}
+
  
function update-efi-nvram () { ## update the nvram with efibootmgr
+
{{Move|Unified Extensible Firmware Interface|Although ''rEFInd'' has a special interface for these common tools, they are not a feature of ''rEFInd''.}}
  declare -r ref_bin=${refind_dir/\/boot\/efi}/refind_$arch.efi;  ## get path of refind binary (without /boot/efi)
+
  declare -r ref_bin_escape=${ref_bin//\//\\};  ## insert escape characters into $ref_bin
+
  [ "$(efibootmgr -v | awk "/${ref_bin_escape//\\/\\\\}/")" ] && ( ## check if boot entry is in nvram \
+
    echo "Found boot entry, no need to update nvram";
+
    ) || ( ## if boot entry is not in nvram; add it
+
    declare -r esp=$(mount -l | awk '/ESP/ {print $1}') &&  ## get ESP partition
+
    efibootmgr -cgw -d ${esp:0:8} -p ${esp:8} -L "rEFInd" -l $ref_bin_escape && ## update nvram
+
    echo "
+
    Updated nvram with entry rEFInd to boot $ref_bin
+
    Did not copy configuration files, please move refind.conf to $refind_dir/";
+
    )
+
}
+
main;  ## run the main insertion function
+
</nowiki>}}
+
  
{{hc|/usr/lib/systemd/system/refind_update.path|<nowiki>
+
''rEFInd'' supports running various 3rd-party tools. Tools need to be installed separately. Edit {{ic|showtools}} in {{ic|refind.conf}} to choose which ones to show.
[Unit]
+
{{hc|''esp''/EFI/refind/refind.conf|
Description=Update rEFInd bootloader files
+
...
 +
showtools '''shell''', '''memtest''', '''gdisk''', '''netboot''', ...
 +
...
 +
}}
  
[Path]
+
=== UEFI shell ===
PathChanged=/usr/share/refind/refind_<arch>.efi
+
See [[Unified_Extensible_Firmware_Interface#UEFI_Shell|UEFI shell]].
Unit=refind_update.service
+
  
[Install]
+
Copy {{ic|shellx64.efi}} to the root of the [[EFI System Partition]].
WantedBy=multi-user.target
+
</nowiki>}}
+
  
{{hc|/usr/lib/systemd/system/refind_update.service|<nowiki>
+
=== Memtest86 ===
[Unit]
+
Install {{AUR|memtest86-efi}} and copy it to {{ic|''esp''/EFI/tools/}}.
Description=Update rEFInd directories, binaries, and nvram
+
# cp /usr/share/memtest86-efi/bootx64.efi ''esp''/EFI/tools/memtest86.efi
  
[Service]
+
=== GPT fdisk (gdisk) ===
Type=oneshot
+
 
ExecStart=/usr/bin/bash /usr/lib/systemd/scripts/refind_name_patchv2
+
There is no package for the EFI version of ''gdisk'', but you can download a binary from ''gdisk'''s author.
RemainAfterExit=no
+
 
 +
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}}.
 +
 
 +
=== iPXE ===
 +
{{Note|PXE support in ''rEFInd'' is '''experimental'''.}}
 +
{{pkg|refind-efi}} contains the iPXE UEFI binaries, you just need to copy them to {{ic|''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
 +
 
 +
== Troubleshooting ==
 +
 
 +
=== Using drivers in UEFI shell ===
 +
 
 +
To use ''rEFInd'''s drivers in UEFI shell load them using command {{ic|load}} and refresh mapped drives with {{ic|map -r}}.
 +
 
 +
Shell> load FS0:\EFI\refind\drivers\ext4_x64.efi
 +
Shell> map -r
 +
 
 +
Now you can access your file system from UEFI shell.
 +
 
 +
=== btrfs subvolume root support ===
 +
{{Merge|Btrfs|There is nothing ''rEFInd'' specific about this issue.}}
 +
If booting a [[btrfs]] subvolume as root, amend the {{ic|options}} line with {{ic|rootflags<nowiki>=</nowiki>subvol<nowiki>=</nowiki><root subvolume>}}. In the example below, root has been mounted as a btrfs subvolume called 'ROOT' (e.g. {{ic|mount -o subvol<nowiki>=</nowiki>ROOT /dev/sdxY /mnt}}):
 +
 
 +
{{hc|''esp''/EFI/refind/refind.conf|<nowiki>
 +
...
 +
 
 +
menuentry "Arch Linux" {
 +
        icon    /EFI/refind/icons/os_arch.png
 +
        volume  Boot
 +
        loader  /boot/vmlinuz-linux
 +
        initrd  /boot/initramfs-linux.img
 +
        options  "root=PARTUUID=XXXXXXXX rw rootflags=subvol=ROOT"
 +
 
 +
...
 +
        }
 
</nowiki>}}
 
</nowiki>}}
  
Enable the systemd path unit by running:
+
A failure to do so will otherwise result in the following error message: {{ic|ERROR: Root device mounted successfully, but /sbin/init does not exist.}}
# systemctl enable refind_update.path
+
 
 +
=== 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:
  
== Apple Macs ==
+
# bless --setBoot --folder ''esp''/EFI/refind --file ''esp''/EFI/refind/refind_x64.efi
  
In case of Apple Macs, try {{AUR|mactel-boot}} for an experimental "bless" utility for Linux. If that does not work, use "bless" from within OSX to set rEFInd as default bootloader. Assuming UEFISYS partition is mounted at {{ic|/mnt/efi}} within OSX, do
+
=== VirtualBox ===
  
$ sudo bless --setBoot --folder /mnt/efi/EFI/refind --file /mnt/efi/EFI/refind/refind_x64.efi
+
Currently, VirtualBox will only boot the default {{ic|/EFI/BOOT/BOOT*.EFI}} path, so {{ic|refind-install}} needs to be used with at least the {{ic|--usedefault}} option. See [[VirtualBox#Installation in EFI mode]] for more information.
  
== VirtualBox ==
+
== See also ==
  
In case of VirtualBox, see [[VirtualBox#Using_Arch_under_Virtualbox_EFI_mode]].
+
* [http://www.rodsbooks.com/refind/ The rEFInd Boot Manager] by Roderick W. Smith.
 +
* {{ic|/usr/share/refind/docs/README.txt}}

Latest revision as of 13:17, 23 September 2016

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 refind-efi from the Official repositories.

Warning: Your kernel and initramfs need to reside on a file system which rEFInd can read.

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

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

Scripted installation

The rEFInd package includes the /usr/bin/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, but for many systems it should be sufficient to simply run:

# refind-install

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

Alternatively you can install rEFInd to the default/fallback boot path /EFI/BOOT/BOOT*.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 the partition of your ESP.

You can read the comments in the install script for explanations of the various installation options.

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 config /EFI/refind/refind.conf on the ESP to ensure that the default options work for you.

Secure Boot

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 PreLoader.efi

The script will

  • copy PreLoader.efi to esp/EFI/refind/refind_x64.efi or esp/EFI/BOOT/BOOT_X64.EFI if used with --usedefault option
  • copy rEFInd binary as loader.efi to the same directory as PreLoader on ESP
  • copy HashTool.efi to same directory as PreLoader on ESP
  • setup boot entry with efibootmgr unless used with --usedefault option

Next time you boot with Secure Boot enabled, HashTool will launch and you will need to register rEFInd (loader.efi) as a trusted application.

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, refind_local.crt and refind_local.cer.

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

# refind-install --localkeys

rEFInd EFI binary will be signed with 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.
Note: For 32-bit EFI, replace x64 with ia32 in the commands below.

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

First, copy the executable to the ESP:

# cp /usr/share/refind/refind_x64.efi esp/EFI/refind/

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 ESP. If you are installing rEFInd to the default UEFI path /EFI/BOOT/BOOTX64.EFI, you can probably skip this step.

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

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 config file:

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

The sample config is well commented and self-explanatory.

Unless you have set textonly in the config 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 config file will be copied as 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 hook

You can automate the update process using a hook:

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

[Action]
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.

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 config contains extensive comments explaining all its options.

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

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 rw add_efi_memmap"
"Boot using fallback initramfs"  "root=PARTUUID=XXXXXXXX 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"

Alternatively, try running:

# refind-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: ... initrd=/boot/intel-ucode.img initrd=/boot/initramfs-linux.img.

Warning: initrd path is relative to the root of the file system on which the kernel resides.

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

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

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

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

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, gdisk, netboot, ...
...

UEFI shell

See 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

GPT fdisk (gdisk)

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

Download gdisk-efi-*.zip from SourceForge, extract the archive, and copy gdisk_x64.efi to esp/EFI/tools.

iPXE

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

Troubleshooting

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.

btrfs subvolume root support

Merge-arrows-2.pngThis article or section is a candidate for merging with Btrfs.Merge-arrows-2.png

Notes: There is nothing rEFInd specific about this issue. (Discuss in Talk:REFInd#)

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   Boot
        loader   /boot/vmlinuz-linux
        initrd   /boot/initramfs-linux.img
        options  "root=PARTUUID=XXXXXXXX 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 /EFI/BOOT/BOOT*.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