The rEFInd Boot Manager:
Installing rEFInd

by Roderick W. Smith, rodsmith@rodsbooks.com

Originally written: 3/14/2012; last Web page update: 5/25/2012, referencing rEFInd 0.4.1

I'm a technical writer and consultant specializing in Linux technologies. This Web page is provided free of charge and with no annoying outside ads; however, I did take time to prepare it, and Web hosting does cost money. If you find this Web page useful, please consider making a small donation to help keep this site up and running. Thanks!

Donate $1.00	Donate $2.50	Donate $5.00	Donate $10.00	Donate another value

This page is part of the documentation for the rEFInd boot manager. If a Web search has brought you here, you may want to start at the main page.

Important: A rEFInd zip file, when uncompressed, creates a directory called refind-version, where version is the version number. This directory includes a subdirectory called refind that holds the boot loader, along with another that holds documentation, as well as miscellaneous files in refind-version itself. When I refer to "the refind directory" on this page, I mean the directory with that precise name, not the refind-version directory that is its parent.

Once you've uncompressed a rEFInd binary zip file, you must install it to your computer's ESP (or conceivably to some other location). The details of how you do this depend on your OS and your computer (UEFI-based PC vs. Macintosh). The upcoming sections provide details. For Linux and Mac OS X, you can use the installation script, install.sh, which provides easy one-command installation on most systems. Occasionally this script will fail, though, so I also provide explicit instructions for Linux and Mac OS X. Installation under Windows also must be done manually. In some cases, you'll have to deviate from the default naming conventions, as described in a section on this topic. If you're upgrading rEFInd, see the section on upgrading. Finally, I describe how to install some additional components you might find useful. Note that this page describes installing the main rEFInd program; if you want to use the EFI filesystem drivers included with rEFInd, you should consult the page on using drivers with rEFInd.

Before running this script under Linux, you should ensure that your ESP is mounted at /boot or /boot/efi, as described in more detail in the Installing rEFInd Manually Using Linux section. (If you installed Linux in EFI mode, chances are your ESP is properly mounted.) This precaution isn't necessary under OS X.

A sample run under Linux looks something like this:

# ./install.sh
Installing rEFInd on Linux....
ESP was found at /boot/efi using vfat
Copied rEFInd binary file refind_x64.efi

Copying sample configuration file as refind.conf; edit this file to configure
rEFInd.


Installation has completed successfully.

The output under OS X is a bit different:

$ ./install.sh
Not running as root; attempting to elevate privileges via sudo....
Password:
Installing rEFInd on OS X....
Installing rEFInd to the partition mounted at '/'
Copied rEFInd binary file refind_ia32.efi

Copying sample configuration file as refind.conf; edit this file to configure
rEFInd.


WARNING: If you have an Advanced Format disk, *DO NOT* attempt to check the
bless status with 'bless --info', since this is known to cause disk corruption
on some systems!!


Installation has completed successfully.

In either case, the details of the output differ depending on your existing configuration and how you ran the program. Some details that can affect how the script runs include the following:

• If you run the script as an ordinary user, it attempts to acquire root privileges by using the sudo command. This works on Mac OS X and some Linux installations (such as under Ubuntu or if you've added yourself to the sudo users list), but on some Linux installations this will fail. On such systems, you should run install.sh as root.
• Under OS X, you can run the script with a mouse by opening a Terminal session and then dragging-and-dropping the install.sh file to the Terminal window. You'll need to press the Return or Enter key to run the script.
• Under OS X, passing the "esp" option causes the script to install rEFInd to the ESP. The script finds the first ESP that's identified by the diskutil program and, if it's not already mounted, mounts it to install rEFInd. Thus, it's conceivable that install.sh will install rEFInd to the wrong partition if you have multiple disks or if a disk has multiple ESPs. If you believe this has happened, you may need to re-install manually.
• If you're using OS X 10.7's Whole Disk Encryption (WDE) feature, you must install rEFInd to the ESP, so the esp option to install.sh is required. I'm still a little bit foggy about what's required to boot the system once this is done; see this forum thread for a discussion of the topic.
• If you're replacing rEFIt with rEFInd on a Mac, there's a chance that install.sh will warn you about the presence of a file called /Library/StartupItems/rEFItBlesser and ask if you want to delete the file. This file is designed to keep rEFIt set as the boot manager by automatically re-blessing it if the default boot manager changes. This is obviously undesirable if you install rEFInd as your primary boot manager, so it's generally best to remove this file. If you prefer to keep your options open, you can answer N when install.sh asks if you want to delete rEFItBlesser, and instead manually copy it elsewhere. If you subsequently decide to go back to using rEFIt as your primary boot manager, you can restore rEFItBlesser to its place.
• If you're using OS X and an Advanced Format disk, heed the warning that install.sh displays and do not use bless --info to check your installation status; this combination has been reported to cause disk corruption on some Macs!

In any event, you should peruse the script's output to ensure that everything looks OK. install.sh displays error messages when it encounters errors, such as if the ESP is mounted read-only or if you run out of disk space. You may need to correct such problems manually and re-run the script. In some cases you may need to fall back on manual installation, which gives you better control over details such as which partition to use for installation.

On a UEFI-based PC, you'll normally install rEFInd to the ESP, which is usually mounted at /boot/efi. You can verify that this is the case by using the df command:

$ df /boot/efi
Filesystem     1K-blocks  Used Available Use% Mounted on
/dev/sda1         191284 16604    174681   9% /boot/efi

Warning: If you're running Linux on a Mac, I recommend you install rEFInd under OS X. The Mac's boot process deviates a bit from EFI standards, so you'll probably have to use a tool called bless under Mac OS to do the job. Alternatively, there's a new Linux program, hfs-bless, part of the mactel-boot package, that's supposed to work with efibootmgr to make a Mac HFS partition bootable. I've not yet tried it, though. There are also reports that the efibootmgr tool used under Linux can corrupt some Macs' firmware. Although I've seen some vague suggestions that this problem has been fixed under 3.x kernels, I haven't tested this claim.

This example shows that /dev/sda1 is mounted at /boot/efi, which is a typical configuration. (The ESP can be on another disk or partition, but /dev/sda1 is the most common place for an ESP.) If your output shows /boot or / under the Mounted on column, then your ESP isn't mounted. (An exception is if you're mounting the ESP at /boot. This is an unusual configuration. If you're using it, you can proceed, making suitable adjustments to subsequent commands.) If you get a df: `/boot/efi': No such file or directory error message, then the /boot/efi directory doesn't even exist. In such cases, you may need to jump through some extra hoops, as described on my EFI Boot Loader Installation page.

Assuming the ESP is mounted at /boot/efi, you can install the rEFInd files as follows (you must be root to issue these commands, or precede each of them with sudo):

1. Type cp -r refind /boot/efi/EFI/ from the refind-version directory in which the refind directory exists. This copies all the files that rEFInd needs to work. Note that this includes all of rEFInd's drivers.
2. Type cd /boot/efi/EFI/refind to change into rEFInd's new directory on the ESP.
3. Type rm refind_ia32.efi to remove the IA32 binary if you're using an x86-64 (64-bit) system; or type rm refind_x64.efi to remove the x86-64 binary if you're using an x86 (32-bit) system. You can optionally rename the binary you keep as refind.efi, but this isn't required. (Note that you must keep the version that's the correct bit width for your EFI; if you've installed a 32-bit Linux on a 64-bit PC with a 64-bit EFI, you'd keep refind_x64.efi.
4. Optionally, type rm -r drivers_ia32 to remove the x86 drivers from an x86-64 system, or rm -r drivers_x64 to remove the x86-64 drivers from a 32-bit x86 system. You may also want to remove some or all of the drivers for the architecture you are using; if you don't need them, they'll slow down the start process. See the page on drivers for more on this topic.
5. Rename the configuration file by typing mv refind.conf-sample refind.conf. Consult the Editing the rEFInd Configuration File page for information on how to adjust your options.
6. On a UEFI-based system, type efibootmgr -c -l \\EFI\\refind\\refind_x64.efi -L rEFInd to add rEFInd to your EFI's list of available boot loaders, which it stores in NVRAM. (Adjust the path to the binary as required if you install somewhere else.) You may need to install this program on some systems; it's a standard part of most distributions' repositories.
7. If other boot loaders are already installed, you can use efibootmgr to adjust their boot order. For instance, efibootmgr -o 3,7,2 sets the firmware to try boot loader #3 first, followed by #7, followed by #2. (The program should have displayed a list of boot loaders when you added yours in the preceding step.) Place rEFInd's number first to set it as the default boot program.

Note the use of doubled-up backslashes (\\) rather than forward slashes (/) in the directory separators when using efibootmgr. This command will work on most systems that are already booted into EFI mode; however, it won't work if you're booted in BIOS mode. You may also need to add options if your ESP is in some unusual location or if your system is unusual in some way. Consult the efibootmgr man page if you need help.

On some systems, efibootmgr won't do what you expect. On such systems, you may have better luck renaming the rEFInd files, as described in the Alternative Naming Options section.

Before installing rEFInd on a Mac, you must determine whether it uses a 32-bit or 64-bit EFI implementation. Most Intel-based Macs have 64-bit EFIs, so you should use the refind_x64.efi file with them; but very early Intel-based Macs have 32-bit EFIs (and sometimes 32-bit CPUs), which require the refind_ia32.efi file. You can determine whether your Mac needs the x86-64 or IA32 build by typing the following command in a Mac Terminal window:

$ ioreg -l -p IODeviceTree | grep firmware-abi

The result should include either EFI32 or EFI64, indicating that you should use the refind_ia32.efi or refind_x64.efi binary, respectively.

Warning: Numerous rEFIt bug reports indicate disk corruption problems on disks over about 500 GiB. This report on the problem, and particularly the post by mic-marchen, suggests that the problem is related to a bug in OS X's bless utility, and particularly its --info option, that causes it to corrupt data on disks with 4 KiB sectors. These Advanced Format disks are becoming increasingly common, particularly at larger disk sizes. Therefore, I strongly recommend that you not type sudo bless --info to check the status of your installation if you have such a disk, or even if you suspect you might have such a disk. (I've seen Advanced Format disks as small as 320 GB.)

The procedure for installing rEFInd on a Mac is similar to that for installing it under Linux, except that you can (and probably should) install it to OS X's system partition or some other HFS+ partition rather than to the ESP, and you must use the bless utility rather than efibootmgr. To be precise, you should follow these steps:

1. Open a Terminal window in which you'll type the following commands.
2. If you want to install rEFInd on your ESP, you must first mount it. You can do this by typing mkdir /Volumes/esp followed by sudo mount -t msdos /dev/disk0s1 /Volumes/esp. Note that this step is usually optional, and it makes the procedure a bit more complex, so you might want to forego it. On the other hand, installing to the ESP is required if you're using the whole-disk encryption feature of OS X 10.7. Note that you may need to change /dev/disk0s1 to something else if your ESP is at an unusual location. Use a tool such as my GPT fdisk (gdisk) to examine your partition table to find your ESP if necessary.
3. Type sudo mkdir -p /efi/refind to create a suitable directory for rEFInd. If you want to place rEFInd on the ESP or some other partition, you should adjust the pathname appropriately, as in /Volumes/esp/efi/refind. Alternatively, you can use the Finder to create the directory.
4. Copy the files in the refind subdirectory of the rEFInd binary package to the like-named directory you've just created. You can do this in the Finder or by typing sudo cp -r refind/* /efi/refind/ in your Terminal window after changing into the rEFInd package's main directory.
5. Remove the file for the version of rEFInd you're not using, as in sudo rm /efi/refind/refind_ia32.efi on a Mac with a 64-bit EFI or sudo rm /efi/refind/refind_x64.efi on a Mac with a 32-bit EFI.
6. Optionally, remove the drivers directory for the architecture you're not using—/efi/refind/drivers_ia32 or /efi/refind/drivers_x64, as appropriate. You may also want to remove some or all of the drivers for the architecture you are using; if you don't need them, they'll slow down the start process. See the page on drivers for more on this topic. Note that Apple's firmware includes its own HFS+ driver, so the HFS+ driver provided with rEFInd is useless on Macs.
7. If this is your first installation, type sudo mv /efi/refind/refind.conf-sample /efi/refind/refind.conf (adjusting the path as necessary) to rename the sample configuration file so that it will serve as a real configuration file. (Again, you can do this with the Finder, if you prefer.)
8. "Bless" rEFInd by typing one of the following two commands:
   • If you're installing rEFInd to an ordinary HFS+ volume, type sudo bless --setBoot --folder /efi/refind --file /efi/refind/refind_x64.efi. (Adjust the path and filename as necessary if you're placing rEFInd somewhere else or using the 32-bit version.)
   • If you're installing rEFInd on the ESP, type sudo bless --mount /Volumes/esp --setBoot --file /Volumes/esp/efi/refind/refind_x64.efi, adjusting the mount point and exact path to the file as appropriate for your installation.
   As per the Warning earlier, do not use bless's --info option to try to confirm the change to the boot status unless you're certain you do not have an Advanced Format hard disk.

When you reboot, your Mac should bring up the rEFInd menu, and should continue to do so thereafter. If you make changes that break this association, you can re-run the bless command (if necessary, restoring the rEFInd files first). This might be necessary after installing system updates from Apple or if you upgrade rEFInd to a newer version.

If you're replacing rEFIt, you may discover that rEFInd works on the first boot, but the system reverts back to rEFIt or a direct boot to OS X on the second boot. To fix this problem, you can remove the rEFItBlesser program, which is located at /Library/StartupItems/rEFItBlesser. This program attempts to keep rEFIt set as the default boot loader, but it also has the purpose of protecting the computer from launching the wrong OS after waking from sleep. If you want that protection, my suggestion is to install rEFIt and rEFItBlesser and then replace the refit.efi file with refind_x64.efi or refind_ia32.efi (renaming it to refit.efi. Used in this way, rEFInd will still look for its own configuration file, refind.conf, so you'll need to move it but not rename it. If you don't move the icons from the rEFInd package, your icons will continue to look like rEFIt icons, and you'll be missing the new icons for specific Linux distributions that rEFInd provides. One final caveat: It's conceivable that rEFItBlesser is what's causing filesystem corruption for some users, so if you've been having this problem with rEFIt, it might be worth disabling this program and not using it with rEFInd.

If you want to remove rEFInd from your system, you can delete its files. The Mac will revert to booting using whatever standard boot loader it can find. Alternatively, you can use bless to bless another EFI boot loader. The GUI Startup Disk utility in System Preferences provides a simplified interface that enables you to select which OS X installation to boot, but it doesn't look for non-Apple boot loaders, so you can't use it to enable rEFInd.

To install rEFInd under Windows, you must first find a way to access the ESP, which Windows normally hides from view. One way to accomplish this goal, and to proceed forward once the ESP is accessible, is as follows:

1. Locate Command Prompt in the Start menu, right-click it, and select Run as Administrator. This action opens a Command Prompt window with administrative privileges.
2. Type mountvol S: /S in the Administrator Command Prompt window. This makes the ESP accessible as drive S: from that window. (You can use a drive identifier other than S: if you like.)
3. Change into the main rEFInd package directory, so that the refind subdirectory is visible when you type dir.
4. Type xcopy /E refind S:\EFI\refind\ to copy the refind directory tree to the ESP's EFI directory. If you omit the trailing backslash from this command, xcopy will ask if you want to create the refind directory. Tell it to do so.
5. Type cd S: to change to the ESP.
6. Type cd EFI\refind to change into the refind subdirectory
7. Type del refind_ia32.efi to delete the unused 32-bit version of rEFInd. (Windows only supports EFI boots on 64-bit EFI implementations and in 64-bit versions of Windows.)
8. Optionally type rd /s drivers_ia32 to delete the drivers_ia32 directory and its contents. You may also want to selectively delete some of the drivers in the drivers_x64 directory, depending on your needs. Unnecessary drivers may slow the rEFInd start process. See the page on drivers for more on this topic.
9. Type rename refind.conf-sample refind.conf to rename rEFInd's configuration file.
10. Type bcdedit /set {bootmgr} path \EFI\refind\refind_x64.efi to set rEFInd as the default EFI boot program. Note that {bootmgr} is entered as such; that's not a notation for a variable.
11. If you like, type bcdedit /set {bootmgr} description "rEFInd description" to set a description (change rEFInd description as you see fit).

At this point, when you reboot, rEFInd should appear as your new default boot program. One caveat: My only EFI Windows installation uses UEFI DUET, which "forgets" its boot options upon reboot. Thus, I'm unable to test the last two steps (which were provided by a helpful user) myself. If it doesn't work for you, you have several other options, such as:

• You can rename files on the ESP. as described in the next section, Alternative Naming Options.
• You can boot from an optical disc into an emergency OS to do the job. Ubuntu, for instance, provides an EFI-bootable installer with a "try before installation" mode. You'll need to type sudo apt-get install efibootmgr to install efibootmgr, but you can then use that program as described earlier. (If you're using Ubuntu, you'll need to precede the command with sudo.
• You may be able to use rEFInd's bootable CD image to use rEFInd to boot an OS that's been installed but rendered inoperable because of changes to your boot order. You can then use efibootmgr, bless, or some other tool to restore rEFInd as the default boot loader.

Some EFI implementations do a poor job of honoring the boot options set via Linux's efibootmgr or other tools. You may also lack access to such utilities, such as if you must install rEFInd in Windows. In such cases, you may need to change the boot loader's name so that the EFI will see it as the default boot loader. rEFInd should then boot when your NVRAM lacks information on specific boot loaders to use. To do this, follow these steps:

1. Access your ESP and install rEFInd to it, as described in earlier sections.
2. Look for an existing directory called EFI/BOOT or EFI/Microsoft/BOOT. If neither of these directories exist, skip the next step. (Note that FAT is case-insensitive, so the name may vary in case.)
3. Rename the existing directory or boot loader file to something else. For EFI/BOOT, try renaming it to EFI/Oldboot. For EFI/Microsoft/BOOT, move or rename the bootmgfw.efi file it contains. For instance, you can move it to EFI/Microsoft. This will keep the boot loader accessible to rEFInd's menu, while preventing the firmware from launching it automatically.
4. Rename/move your EFI/refind directory to EFI/BOOT. If you're working from EFI/Microsoft/BOOT, you should move the contents of your rEFInd directory to EFI/Microsoft/BOOT.
5. Rename EFI/BOOT/refind_x64.efi to the name of the boot loader it's replacing—it should become EFI/BOOT/bootx64.efi or EFI/Microsoft/BOOT/bootmgfw.efi.

When you reboot, rEFInd should come up. With any luck, it will detect your old boot loader as an option, if one was installed before.

If you've installed an earlier version of rEFInd, you can upgrade a bit more easily than you can install directly:

• On a UEFI-based PC, under any OS, you should be able to replace your old rEFInd file with the new one. Make sure that the new rEFInd has the same name as the old one, and that it's for the correct CPU type. Since UEFI launches boot programs by filename, a simple file replacement will suffice to launch the new version. If the new version includes new icons, you may want to copy some or all of them.
• On a Mac, you can copy over the old rEFInd binary file from Linux and it will usually work, provided you copy directly over the old file (rather than rename or delete the old file and then copy the new one in its place). The same caveats about icons as apply to UEFI-based PCs apply in this case. This method requires an extra step in Mac OS X, though....
• In OS X, if you copy over the original file with the new one, you'll probably have to re-bless it to make it work.
• Under Linux or OS X, you can re-run the install.sh script. In most cases this works fine, but you'll end up with a duplicate of the icons directory (icons-backup, which holds the original icons, whereas icons holds the icons from the new package). Normally this just wastes some disk space; but if you've customized your icons, you'll need to copy your altered icons back.

In all cases, if the new version includes new or altered configuration file options, you may need to manually update your configuration file. Alternatively, if you've used the default configuration file, you can replace your working refind.conf with refind.conf-sample from the rEFInd zip file. (When using install.sh, this file will be copied to rEFInd's installation directory under its original name, so you can rename it within that directory to replace the old file.

rEFInd includes the ability to launch any EFI program; however, rEFInd detects only certain programs. These include boot loaders in traditional locations and a handful of other programs. To launch these other programs, you must download and install them separately from rEFInd:

• shell.efi—This file, placed in the ESP's efi/tools directory, adds the ability to launch a text-mode EFI shell from rEFInd. Note that the download link is to a 64-bit binary that must be renamed before rEFInd will recognize it.
• gptsync.efi—This program creates a hybrid MBR from your regular GPT disk. A hybrid MBR is a dangerous hack that enables Windows and OS X to coexist on a Macintosh disk. If you're using a UEFI-based PC, a hybrid MBR will be useless at best, so you shouldn't create one, and it's safest to not install gptsync.efi. If you're using a hybrid MBR to enable dual-booting Windows and OS X on a Mac, though, placing this program file in the ESP's or Mac boot partition's efi/tools directory will enable you to regenerate your hybrid MBR should some other tool convert the MBR to a standard protective MBR. You can obtain the file from the original rEFIt package.
• Drivers—You can install drivers to extend the capabilities of the EFI. rEFInd ships with filesystem drivers for ext2fs and ReiserFS, which can enable you to boot a Linux kernel with EFI stub support from an ext2fs, ext3fs, or ReiserFS partition. (rEFInd also provides ISO-9660 and HFS+ drivers.) You can find additional drivers from other sources, although they're still on the scarce side. See the Using EFI Drivers page for more on this topic.

I've seen links to other versions of these tools from time to time on the Web, so if you try one of these programs and it crashes or behaves strangely, try performing a Web search; you may turn up something that works better for you than the one to which I've linked.

copyright © 2012 by Roderick W. Smith

This document is licensed under the terms of the GNU Free Documentation License (FDL), version 1.3.

If you have problems with or comments about this Web page, please e-mail me at rodsmith@rodsbooks.com. Thanks.

Go to the main rEFInd page

Learn how to use rEFInd

Return to my main Web page.