The rEFInd Boot Manager:
Methods of Booting Linux

by Roderick W. Smith,

Originally written: 3/19/2012; last Web page update: 10/22/2017, referencing rEFInd 0.11.2

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

Windows and Mac OS X both provide relatively simple EFI boot loader programs. Launch them, and they'll boot their respective OSes. This makes rEFInd's job easy; it just locates the boot loader program files and runs them.

Under Linux, by contrast, things can get complicated. As detailed on my Managing EFI Boot Loaders for Linux page, several different EFI boot loaders for Linux exist, and all of them require configuration. If you're lucky, your distribution will have set up a Linux boot loader in a sensible way, in which case rEFInd should detect it and it will work as easily as a Windows or Mac OS X boot loader. If you're not lucky, though, you may need to configure it further. rEFInd offers options to help out with this task. Naturally, rEFInd supports traditional Linux boot loaders. It works even better with the Linux EFI stub loader, so I provide instructions on starting with it. For those interested in manual configuration, I also provide detailed instructions on how the EFI stub support works and how to configure it.

Using a Traditional Linux Boot Loader

I consider ELILO, GRUB Legacy, GRUB 2, and SYSLINUX to be traditional Linux boot loaders. These programs all exist independent of the Linux kernel, but they can load a kernel and hand off control to it. All four programs have their own configuration files that reside in the same directory as the boot loader itself (or optionally elsewhere, in the case of GRUB 2).

Ordinarily, rEFInd will detect these traditional boot loaders and provide main menu entries for them. If the boot loader exists in a directory with a name that matches a Linux distribution's icon filename, you'll automatically get a distribution-specific icon to refer to the boot loader.

If you prefer, you can disable automatic scanning and create an entry in refind.conf for your distribution, as described on the Configuring the Boot Manager page. This method is harder to set up but can be preferable if you want to customize your options.

Using the EFI Stub Loader: Three Configuration Options

The EFI stub loader is basic and reliable, but it requires some setup to use it on some computers. It also requires that you run a kernel with the same bit width as your EFI. In most cases, this means running a 64-bit kernel, since 32-bit EFI-based computers are so rare. I describe three methods of using the EFI stub loader: an easiest method for those with compatible partition and filesystem layouts, a quick test configuration for those without such a layout, and a long-term setup for those without the ideal setup. In most cases, the first (easiest) method works fine, thanks to rEFInd's filesystem drivers and rEFInd features intended to help launch a kernel with minimal user configuration.

For Those With Foresight or Luck: The Easiest Method

This method requires that your /boot directory, whether it's on a separate partition or is a regular directory in your root (/) filesystem, be readable by the EFI. At the moment, all EFI implementations can read FAT and Macs can read HFS+. By using drivers, you can make any EFI read HFS+, ISO-9660, ReiserFS, ext2fs, ext3fs, ext4fs, Btrfs, or other filesystems. Thus, if you use any of these filesystems on a regular partition (not an LVM or RAID configuration) that holds your kernels in /boot, you qualify for this easy method. The default partition layouts used by Ubuntu, Fedora, and many other distributions qualify, because they use one of these filesystems (usually ext4fs) in a normal partition or on a separate /boot partition. You must also have a 3.3.0 or later Linux kernel with EFI stub support, of course.

If you installed rEFInd 0.6.0 or later with its refind-install (formerly script from your regular Linux installation, chances are everything's set up; you should be able to reboot and see your Linux kernels as boot options. If you installed manually, from OS X, or from an emergency system, though, you may need to do a couple of things manually:

When you reboot, you should see rEFInd options for your Linux kernels. If they work, your job is done, although you might want to apply some of the tweaks described in the maintenance-free setup section. If you have problems, you may need to adjust the refind_linux.conf file, as described in the detailed configuration section.

Preparing a Test Configuration

If you're not sure you want to use the EFI stub loader in the long term, you can perform a fairly quick initial test of it. This procedure assumes that you have access to a 3.3.0 or later Linux kernel with EFI stub support compiled into it. (Most distributions ship with such kernels.) Creating this configuration poses no risk to your current boot options, provided you don't accidentally delete existing files. The procedure for a quick test is:

  1. Copy your kernel file (vmlinuz-*) and matching initial RAM disk file (init*) from /boot to a subdirectory of EFI on your ESP. Your distribution's directory there should work fine. For instance, typing cp /boot/vmlinuz-4.2.5-300.fc23.x86_64 /boot/initramfs-4.2.5-300.fc23.x86_64.img /boot/efi/EFI/fedora might do the trick on a Fedora system, although you'll probably have to adjust the version numbers. Note that the filename forms vary from one distribution to another, so don't worry if yours look different from these. Be sure that you match up the correct files by version number, though.
  2. Copy the /boot/refind_linux.conf file to the same directory to which you copied your kernel. If this file doesn't exist, create it by running (as root) the mkrlconf script that came with rEFInd. This step may not be strictly necessary if /boot is an ordinary directory on your root (/) partition.
  3. Reboot. You should now see a new entry for launching the Linux kernel that you copied. Try the option. If it works, great. If not, you may need to adjust your refind_linux.conf file. See the detailed configuration section for a description of this file's format. If the kernel begins to boot but complains that it couldn't find its root filesystem, double-check the version numbers on your kernel and initial RAM disk file, and check the root= option in refind_linux.conf.

You can continue to boot your computer with this type of configuration; however, the drawback is that you'll need to copy your kernel whenever it's updated. This can be a hassle. A better way is to configure you system so that the EFI, and therefore rEFInd, can read your Linux /boot directory, where most Linux distributions place their kernels. You do this by installing the appropriate EFI filesystem driver for the /boot (or root, /) filesystem.

If You Need to Reconfigure Your Partitions....

If your /boot directory happens to be on an XFS or JFS partition that the EFI can't read, or it's tucked away in an LVM or RAID configuration that the EFI can't read, you won't be able to use the easiest solution. Fortunately, this problem can be overcome with relatively little fuss. Several variant procedures are possible, but I begin by describing one that will almost always work, although it's got some important caveats (described at the end). You should perform the following steps as root, or precede each of these commands with sudo:

  1. Begin with your ESP mounted at /boot/efi, which is the most common location. If it's not mounted there, type mount /dev/sda1 /boot/efi to do so (adjusting /dev/sda1, if necessary), or mount it elsewhere and adjust the paths in the following procedure as necessary.
  2. Check the size of the ESP by typing df -h /boot/efi. The ESP must be large enough to hold several Linux kernels and initial RAM disk files—100MiB at a bare minimum, and preferably 200–500MiB.
  3. Check your /boot directory to be sure it contains no links or other files that rely on Unix/Linux-style permissions or ownership. If it does, don't proceed, or at least research these files further to determine if you can work around the need for such permissions and ownership.
  4. Type cp -r /boot/* /boot/efi. You'll see an error message about being unable to copy /boot/efi into itself. Ignore this.
  5. Type umount /boot/efi.
  6. Edit /etc/fstab and change the mount point for /boot/efi to /boot. If the ESP isn't present in /etc/fstab, you must create an entry for it, with a mount point of /boot.
  7. Type mount -a to re-mount everything, including /boot. Check that your normal /boot files are all present, along with the new /boot/EFI directory, which holds what used to be /boot/efi/EFI. If something seems to be missing (other than /boot/efi with a lowercase efi), then you should try to correct the problem.
  8. If it doesn't already exist, create a file called /boot/refind_linux.conf and populate it with kernel options, as described later. If this file doesn't already exist, the easiest way to create it is to run the mkrlconf script that comes with rEFInd 0.5.1 and later.
  9. Check your refind.conf file (presumably in /boot/EFI/refind) to be sure that the scan_all_linux_kernels line is uncommented. If it's not, uncomment that line.
  10. Optionally, type cp /boot/EFI/refind/icons/os_name.icns /boot/.VolumeIcon.icns to give loaders in /boot an icon for your distribution.
  11. Reboot to test that this configuration works.

Recall that in step #4, you copied the contents of /boot (as a safety measure), but you did not move them. Therefore, you ended up with two copies of your kernels and other /boot directory contents, with one copy hiding the other when you mounted the ESP at /boot. Once you've booted successfully and are sure all is working well, you can recover some disk space by unmounting /boot and deleting the contents of the underlying /boot directory on your root (/) filesystem. Be sure that the /boot partition is unmounted before you do this, though! Also, be sure to leave the /boot directory itself in place, even if it has no contents; the directory is needed as a mount point for the /boot partition. Note that GRUB 2 may stop working if you delete its files from the root filesystem's /boot/grub directory, so if you want to keep GRUB around, you should re-install it with the separate /boot partition mounted.

Once this task is done, updates to your kernel will automatically be stored in the root directory of your ESP, where rEFInd will automatically detect them. Thus, the boot configuration becomes maintenance-free. The procedure as just described has some drawbacks, though. By placing your kernels in the root directory of your ESP, you render them vulnerable to any other OS with which you might be dual-booting. Your ESP must also be large enough to hold all your kernels. If you dual-boot with multiple Linux distributions, they might conceivably overwrite each others' kernels, and distinguishing one from another becomes more difficult.

For these reasons, a variant of this procedure is desirable on some systems. Most of the steps are similar, but in this variant, you create a separate /boot partition that's independent of the ESP. This partition can use FAT, HFS+, ReiserFS, ext2fs, ext3fs, ext4fs, or Btrfs; but if you use any of the last six filesystems (five on Macs), you must install the matching EFI filesystem driver that ships with rEFInd. Creating the filesystem will normally require you to shrink an existing partition by a suitable amount (200–500MiB). Mount your new /boot partition at a temporary location, copy or move the current /boot files into it, unmount it, and add it to /etc/fstab as /boot.

If your distribution already uses a separate /boot partition, but if it uses XFS or some other unsuitable filesystem, you can back it up, create a fresh FAT, HFS+, ReiserFS, Btrfs, ext2, ext3, or ext4 filesystem on it, and restore the original files. You'll probably need to adjust the UUID value in /etc/fstab to ensure that the computer mounts the new filesystem when you boot. If you use a separate non-ESP /boot partition, you'll probably want to continue mounting the ESP at /boot/efi.

EFI Stub Loader Support Technical Details

The Linux EFI stub loader is a way to turn a Linux kernel into an EFI application. In a sense, the kernel becomes its own boot loader. This approach to booting Linux is very elegant in some ways, but as described on the page to which I just linked, it has its disadvantages, too. One challenge to booting in this way is that modern Linux installations typically require that the kernel be passed a number of options at boot time. These tell the kernel where the Linux root (/) filesystem is, where the initial RAM disk is, and so on. Without these options, Linux won't boot. These options are impossible for a generic boot loader to guess without a little help. It's possible to build a kernel with a default set of options, but this is rather limiting. Thus, rEFInd provides configuration options to help.

With all versions of rEFInd, you can create manual boot loader stanzas in the refind.conf file to identify a Linux kernel and to pass it all the options it needs. This approach is effective and flexible, but it requires editing a single configuration file for all the OSes you want to define in this way. If a computer boots two different Linux distributions, and if both were to support rEFInd, problems might arise as each one tries to modify its own rEFInd configuration; or the one that controls rEFInd might set inappropriate options for another distribution. This is a problem that's been a minor annoyance for years under BIOS, since the same potential for poor configuration applies to LILO, GRUB Legacy, and GRUB 2 on BIOS. The most reliable solution under BIOS is to chainload one boot loader to another. The same solution is possible under EFI, but rEFInd offers another possibility.

rEFInd supports semi-automatic Linux EFI stub loader detection. This feature works as part of the standard boot loader scan operation, but it extends it as follows:

  1. rEFInd looks for boot loaders whose names include the strings bzImage or vmlinuz. For instance, bzImage-3.19.0.efi or vmlinuz-4.2.0 would match, and trigger subsequent steps in this procedure. The scan_all_linux_kernels option in refind.conf controls the scanning for kernels whose names do not end in .efi; if this option is set to false, kernel filenames must end in .efi to be picked up by rEFInd. This option is set to true by default, but you can change it if you don't want to scan all Linux kernels.
  2. If a file's name ends in .efi.signed, any other file with an otherwise-identical name that lacks this extension is excluded. This peculiar rule exists because Ubuntu delivers two copies of every kernel, one with and one without this extension. The one with the extension is signed with a Secure Boot key; the one without it is not so signed. Thus, if both files are present, the one without the key won't boot on a computer with Secure Boot active, and either will boot if Secure Boot is inactive. Thus, rEFInd excludes the redundant (unsigned) file in order to help keep the list of boot options manageable.
  3. rEFInd looks for an initial RAM disk in the same directory as the kernel file. A matching initial RAM disk has a name that begins with init and that includes the same version string as the kernel. The version string is defined as the part of the filename from the first digit to the last digit, inclusive. Note that the version string can include non-digits. For instance, the version string for bzImage-3.19.0.efi is 3.19.0, which matches; and vmlinuz-4.2.5-300.fc23.x86_64's version string is 4.2.5-300.fc23.x86_64, which matches initrd-4.2.5-300.fc23.x86_64.img. Many other matches are possible. If an initial RAM disk is identified, rEFInd passes a suitable initrd= option to the kernel when it boots. There are two variants on this rule:
  4. rEFInd looks for a file called refind_linux.conf in the same directory as the kernel file. It consists of a series of lines, each of which consists of a label followed by a series of kernel options. The first line sets default options, and subsequent lines set options that are accessible from the main menu tag's submenu screen. If you installed rEFInd with the refind-install script, that script created a sample refind_linux.conf file, customized for your computer, in /boot. This file will work without changes on many installations, but you may need to tweak it for some. If the kernel options string includes the substring %v, rEFInd substitutes the kernel version number for that string. (If you need the actual string %v in your kernel options, use %%v instead; rEFInd will change this to %v.) This feature can be used to match an initial RAM disk file that requires special treatment, such as if you have multiple numbered kernels, each of which has two initial RAM disk files.
  5. If rEFInd can't find a refind_linux.conf file in the directory that holds the kernel, the program looks for a file called /etc/fstab on the partition that holds the kernel. If this standard Linux file is present, rEFInd uses it to identify the root (/) filesystem and creates two sets of Linux kernel boot options: One set launches the kernel normally, but with minimal options, and the other set launches the kernel into single-user mode. This step can get a computer to boot without any rEFInd-specific configuration files, aside from refind.conf in rEFInd's own directory, but only if /boot is not a separate partition. The intent is to facilitate the use of rEFInd as an emergency boot manager or to help users who must install rEFInd from OS X or Windows. Note that rEFInd uses /etc/fstab only if refind_linux.conf is not found.
  6. If rEFInd can't find a refind_linux.conf file or an /etc/fstab file, it tries to identify the Linux root (/) filesystem by looking for a partition with a GUID type code matching that specified for the root (/) filesystem in the Discoverable Partitions Specification. These type codes are as yet seldom used, but if and when they become common, they should help a lot for situations similar to those of the preceding case, but when a separate /boot partition is used.

The intent of this system is that distribution maintainers can place their kernels, initial RAM disks, and a refind_linux.conf file in their own subdirectories on the ESP, on EFI-accessible /boot partitions, or in /boot directories on EFI-accessible Linux root (/) partitions. rEFInd will detect these kernels and create one main menu entry for each directory that holds kernels; or if fold_linux_kernels is set to false, one menu entry for each kernel. Each entry will implement as many options as there are lines in the refind_linux.conf file (multiplied by the number of kernels, if fold_linux_kernels is true). In this way, two or more distributions can each maintain their boot loader entries, without being too concerned about who maintains rEFInd as a whole.

As an example, consider the following (partial) file listing:

$ ls -l /boot/vmlin*
total 17943
-rw-r--r-- 1 root root 5271984 Aug  7 10:18 /boot/vmlinuz-3.16.7-24-default
-rw-r--r-- 1 root root 5271536 Oct 23 17:25 /boot/vmlinuz-3.16.7-29-default

When rEFInd scans this directory, it will discover two kernels in /boot. Assuming fold_linux_kernels is its default of true, rEFInd will create one main-menu tag for these two kernels. A refind_linux.conf file in this directory should contain a list of labels and options:

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

Ordinarily, both fields in this file must be enclosed in quotes. If you have to pass an option that includes quotes, you can do so by doubling up on them, as in "root=/dev/sdb9 my_opt=""this is it""", which passes root=/dev/sdb9 my_opt="this is it" to the shell. You can include as much white space as you like between options. You can also place comments in the file, or remove an option by commenting it out with a leading hash mark (#), as in the fourth line in this example.

In the preceding example, the first line sets the options that rEFInd passes to the kernel by default (along with the name of the discovered initrd file, since its version string matches that of the kernel). The next two lines set options that you can obtain by pressing Insert, F2, or + on the main menu, as shown here:

rEFInd can load Linux boot options from
    a refind_linux.conf file in the Linux kernel's directory.

Note that in this example, the default kernel (the one with the most recent time stamp) appears first on the list, with the labels specified in refind_linux.conf. Subsequent kernels (just one in this example) appear below it, with the same labels preceded by the kernel filename. If you were to set fold_linux_kernels false, each kernel would get its own entry on the main menu, and each one's submenu would enable options for launching it alone.

To assist in initial configuration, rEFInd's refind-install script creates a sample refind_linux.conf file in /boot. This sample file defines three entries, the first two of which use the default GRUB options defined in /etc/default/grub and the last of which uses minimal options. The first entry boots normally and the second boots into single-user mode. If you want to create a new file, you can use the mkrlconf script that comes with rEFInd. If you pass it the --force option, it will overwrite the existing /boot/refind_linux.conf file; otherwise it will create the file only if one doesn't already exist.

From a user's perspective, the submenus defined in this way work just like submenus defined via the submenuentry options in refind.conf, or like the submenus that rEFInd creates automatically for Mac OS X or ELILO. There are, however, limitations in what you can accomplish with this method:

Ordinarily, a kernel booted in this way must reside on the ESP, or at least on another FAT partition. On a Macintosh, though, you can use HFS+ to house your kernel files. In fact, that may be necessary; my Mac Mini hangs when I try to boot a Linux kernel via an EFI stub loader from the computer's ESP, but it works fine when booting from an HFS+ partition. If you use EFI drivers, though, you can place your kernel on any filesystem for which an EFI driver exists. This list is currently good (ext2fs/ext3fs, ext4fs, ReiserFS, Btrfs, ISO-9660, HFS+, and NTFS in rEFInd, plus more from other sources), so chances are you'll be able to use this method to boot your kernel from your root (/) partition or from a /boot partition.

rEFInd sorts boot loader entries within each directory by time stamp, so that the most recent entry comes first. Thus, if you specify a directory name (or a volume label, for loaders stored in a volume's root directory) as the default_selection, rEFInd will make the most recent loader in the directory the default. This can obviate the need to adjust this configuration parameter when you add a new kernel; chances are you want the most recently-added kernel to be the default, and rEFInd makes it so when you set the default_selection in this way. If you don't want the latest kernel to become the default, you can use touch to give the desired kernel (or other boot loader) in the directory a more recent time stamp, or you can set default_selection to a value that uniquely identifies your desired default loader. One caveat you should keep in mind is that the EFI and Windows interpret the hardware clock as local time, whereas Mac OS X uses Coordinated Universal Time (UTC). Linux can work either way. Thus, time stamps for boot loaders can be skewed by several hours depending on the environment in which they were created or last modified.

On the whole, auto-detecting kernels and passing boot options using refind_linux.conf has a lot going for it. For distribution maintainers, if you place your Linux kernel files (with EFI stub support) on the ESP, with suitable filenames, matching initial RAM disk files, and a refind_linux.conf file, then rEFInd should detect your files, even if the user installs another distribution with another rEFInd that takes over from yours. (If the user, or this other rEFInd installation, disables auto-detection, this won't work.)

For end users, this method is simpler than maintaining manual configurations in refind.conf (or equivalents for ELILO or GRUB). To install a new kernel, you need only copy it and its initial RAM disk, under suitable names, to a scanned directory on the ESP. There's no need to touch any configuration file, provided you've already set up refind_linux.conf in your kernel's directory. You will, however, have to adjust refind_linux.conf if you make certain changes, such as if your root directory identifier changes.

copyright © 2012–2017 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 Thanks.

Go to the main rEFInd page

Learn how to manage Secure Boot

Return to my main Web page.