</head>
<body>
- <h1>The rEFInd Boot Manager:<br />Methods of Booting Linux</h1>
+<h1>The rEFInd Boot Manager:<br />Methods of Booting Linux</h1>
-
<p class="subhead">by Roderick W. Smith, <a
+<p class="subhead">by Roderick W. Smith, <a
href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
- <p>Originally written: 3/19/2012; last Web page update: 3/23/2012, referencing rEFInd 0.2.2</p>
+<p>Originally written: 3/19/2012; last Web page update:
+6/23/2012, referencing rEFInd 0.4.4</p>
<p>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!</p>
<h2>Using the EFI Stub Loader</h2>
-<p>The Linux <a href="http://www.rodsbooks.com/efi-bootloaders/efistub.html">EFI stub loader</a> 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 (<tt>/</tt>) 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. For this reason, rEFIt, rEFInd's parent program, could not boot a Linux kernel with EFI stub support. rEFInd, however, goes a little further....</p>
-
-<p>With all versions of rEFInd, you can create manual boot loader stanzas in the <tt>refind.conf</tt> 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. 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 there is to chainload one boot loader to another. The same solution is possible under EFI, but rEFInd offers another possibility.</p>
+<p>The Linux <a href="http://www.rodsbooks.com/efi-bootloaders/efistub.html">EFI stub loader</a> 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 (<tt>/</tt>) 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.</p>
+
+<p>With all versions of rEFInd, you can create manual boot loader stanzas
+in the <tt>refind.conf</tt> 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 there is to chainload one boot loader
+to another. The same solution is possible under EFI, but rEFInd offers
+another possibility.</p>
<p>rEFInd 0.2.1 and later 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:</p>
<ol>
-<li>rEFInd looks for boot loaders whose names include the strings <tt>bzImage</tt> or <tt>vmlinuz</tt> and that end in <tt>.efi</tt>. For instance, <tt>bzImage-3.3.0.efi</tt> or <tt>vmlinuz-3.3.0-fc17.efi</tt> would match, and trigger subsequent steps in this procedure. Note that to use this system, you <i>must</i> give your kernel file a <tt>.efi</tt> extension, at least on the ESP!</li>
-
-<div class="sidebar">
-
-<p>A kernel whose filename lacks a version string matches an initial RAM disk that also lacks a version string in its filename. Note that you can reliably use only <i>one</i> kernel and initial RAM disk per directory that lack version numbers in their filenames.</p>
-
-</div>
-
-<li>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 <tt>init</tt> 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 <tt>bzImage-3.3.0.efi</tt> is <tt>3.3.0</tt>, which matches <tt>initramfs-3.3.0.bz</tt>; and <tt>vmlinuz-3.3.0-fc17.efi</tt>'s version string is <tt>3.3.0-fc17</tt>, which matches <tt>initrd-3.3.0-fc17.img</tt>. Many other matches are possible. If an initial RAM disk is identified, rEFInd passes a suitable <tt>initrd=</tt> option to the kernel when it boots.</li>
-
-<li>rEFInd looks for a file called <tt>linux.conf</tt> in the same directory as the kernel file. This file is a practical requirement for booting from an auto-detected kernel. 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.</li>
+<li>rEFInd looks for boot loaders whose names include the strings
+ <tt>bzImage</tt> or <tt>vmlinuz</tt> and that end in <tt>.efi</tt>. For
+ instance, <tt>bzImage-3.3.0.efi</tt> or <tt>vmlinuz-3.3.0-fc17.efi</tt>
+ would match, and trigger subsequent steps in this procedure. Beginning
+ with version 0.3.0, if you uncomment the
+ <tt>scan_all_linux_kernels</tt> option in <tt>refind.conf</tt>, rEFInd
+ will also scan for kernels <i>without</i> a <tt>.efi</tt> filename
+ extension. This option is not the default, though, because it can pick
+ up old kernels that lack EFI stub loader support and even non-kernel
+ files.</li>
+
+<p class="sidebar">A kernel whose filename lacks a version string matches an initial RAM disk that also lacks a version string in its filename. Note that you can reliably use only <i>one</i> kernel and initial RAM disk per directory that lack version numbers in their filenames.</p>
+
+<li>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
+ <tt>init</tt> 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
+ <tt>bzImage-3.3.0.efi</tt> is <tt>3.3.0</tt>, which matches
+ <tt>initramfs-3.3.0.bz</tt>; and <tt>vmlinuz-3.3.0-fc17.efi</tt>'s
+ version string is <tt>3.3.0-fc17</tt>, which matches
+ <tt>initrd-3.3.0-fc17.img</tt>. Many other matches are possible. If an
+ initial RAM disk is identified, rEFInd passes a suitable
+ <tt>initrd=</tt> option to the kernel when it boots.</li>
+
+<p class="sidebar">rEFInd 0.2.1 and 0.2.2 used a filename of <tt>linux.conf</tt> to hold Linux kernel options; however, the Linux kernel developers plan to use this name themselves, so I've switched to <tt>refind_linux.conf</tt> as of rEFInd 0.2.3. Through version 0.4.2, rEFInd still supported the <tt>linux.conf</tt> filename as a backup to <tt>refind_linux.conf</tt>, but as of version 0.4.3, <tt>linux.conf</tt> no longer works, so you should rename your <tt>linux.conf</tt> file to <tt>refind_linux.conf</tt> if you're upgrading.</p>
+
+<li>rEFInd looks for a file called <tt>refind_linux.conf</tt> in the same
+ directory as the kernel file. This file is a practical requirement for
+ booting from an auto-detected kernel. 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.</li>
</ol>
-<p>The intent of this system is that distribution maintainers can place their kernels, initial RAM disks, and a <tt>linux.conf</tt> file in their own subdirectory on the ESP. rEFInd will detect their kernels and create one main menu entry for each kernel. Each entry will implement as many options as there are lines in the <tt>linux.conf</tt> file. In this way, two or more distributions can each maintain their boot loader entries, without being too concerned for who maintains rEFInd as a whole.</p>
+<p>The intent of this system is that distribution maintainers can place their kernels, initial RAM disks, and a <tt>refind_linux.conf</tt> file in their own subdirectory on the ESP. rEFInd will detect their kernels and create one main menu entry for each kernel. Each entry will implement as many options as there are lines in the <tt>refind_linux.conf</tt> file. 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.</p>
+
+<p>The <tt>scan_all_linux_kernels</tt> option is intended to help users and distribution maintainers when rEFInd is used in conjunction with a Linux filesystem driver for EFI or when the ESP is mounted as the Linux <tt>/boot</tt> partition. In these cases, if all the kernels in Linux's <tt>/boot</tt> directory include EFI stub loader support, rEFInd will automatically detect and use kernels installed in the usual way, such as via an automatic system update. You won't even need to move or rename your kernels. You will need to set up a <tt>refind_linux.conf</tt> file and you may need to install a driver or set the <tt>also_scan_dirs</tt> option in <tt>refind.conf</tt>; but these are one-time requirements. Set up in this way, ongoing maintenance to handle kernel updates drops to zero!</p>
<p>As an example, consider the following file configuration:</p>
-rwxr-xr-x 1 root root 4781632 2012-03-18 12:01 bzImage-3.3.0.efi
-rwxr-xr-x 1 root root 131072 2011-10-14 04:10 grubx64.EFI
-rwxr-xr-x 1 root root 13459936 2012-03-18 12:02 initrd.img-3.3.0
--rwxr-xr-x 1 root root 266 2012-03-18 19:39 linux.conf
+-rwxr-xr-x 1 root root 266 2012-03-26 19:39 refind_linux.conf
</pre>
-<p>When rEFInd scans this directory, it will find two EFI boot loaders in <tt>EFI/ubuntu</tt>: <tt>grubx64.EFI</tt> and <tt>bzImage-3.3.0.efi</tt>. rEFInd will create two main-menu tags for these two loaders, one of which will launch Ubuntu's standard GRUB and the other of which will launch the 3.3.0 kernel file directly. The <tt>linux.conf</tt> file contains a list of labels and options:</p>
+<p>When rEFInd scans this directory, it will find two EFI boot loaders in <tt>EFI/ubuntu</tt>: <tt>grubx64.EFI</tt> and <tt>bzImage-3.3.0.efi</tt>. rEFInd will create two main-menu tags for these two loaders, one of which will launch Ubuntu's standard GRUB and the other of which will launch the 3.3.0 kernel file directly. The <tt>refind_linux.conf</tt> file contains a list of labels and options:</p>
<pre class="listing">
"Boot with defaults" "root=/dev/sda3 ro quiet splash vt.handoff=7"
<br /><center><img src="automatic-submenu.png" align="center"
width="376" height="279" alt="rEFInd can load Linux boot options from
- a linux.conf file in the Linux kernel's directory."
+ a refind_linux.conf file in the Linux kernel's directory."
border=2></center><br />
-<p>Note that the first entry shown here takes a name that's set in rEFInd rather than the one specified in the <tt>linux.conf</tt> file. The remaining names match those specified in the file, though.</p>
+<p>Note that the first entry shown here takes a name that's set in rEFInd rather than the one specified in the <tt>refind_linux.conf</tt> file. The remaining names match those specified in the file, though.</p>
<p>From a user's perspective, the submenus defined in this way work just like submenus defined via the <tt>submenuentry</tt> options in <tt>refind.conf</tt>, 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:</p>
<li>Your kernels must be compiled with EFI stub loader support.</li>
-<li>You can't set an option to boot via a different boot loader, such as ELILO or GRUB; all the options apply to a single boot loader—that is, a single kernel.</li>
+<li>You can't set a submenu option to boot via a different boot loader,
+ such as ELILO or GRUB; all the submenu options apply to a single boot
+ loader—that is, a single kernel. (rEFInd will still detect other
+ boot loaders and provide separate main-menu tags for them,
+ though.)</li>
-<li>If an installation includes two or more kernel files, each one receives its own main-menu entry; you can't combine them together in one menu item. This is essentially a corollary of the preceding limitation. The result can be an overburdened main menu if your system has many kernels.</li>
+<li>If an installation includes two or more kernel files, each one receives
+ its own main-menu entry; you can't combine them together in one menu
+ item. This is essentially a corollary of the preceding limitation. The
+ result can be an overburdened main menu if your system has many
+ kernels.</li>
-<li>All the kernels in a given directory use the same <tt>linux.conf</tt> file. If you need to set different options for different kernels, you'll need to place those kernels in different directories.</li>
+<li>All the kernels in a given directory use the same
+ <tt>refind_linux.conf</tt> file. If you need to set different options
+ for different kernels, you'll need to place those kernels in different
+ directories.</li>
-<li>You must place your kernels in a directory other than the one that holds the main rEFInd <tt>.efi</tt> file. This is because rEFInd does not scan its own directory for boot loaders.</li>
+<li>You must place your kernels in a directory other than the one that
+ holds the main rEFInd <tt>.efi</tt> file. This is because rEFInd does
+ not scan its own directory for boot loaders.</li>
</ul>
-<p>On the whole, this method of configuration 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 <tt>linux.conf</tt> file, then any rEFInd 0.2.1 or later installation 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.)</p>
+<p>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 <a href="drivers.html">EFI drivers,</a> though, you can place your kernel on any filesystem for which an EFI driver exists. This list is currently rather limited (ext2fs/ext3fs, ReiserFS, ISO-9660, and HFS+), but even just one or two options might help a lot if you've got an undersized ESP or if copying your kernel file to the ESP is a hassle you'd rather avoid.</p>
+
+<p>Beginning with version 0.3.1, rEFInd sorts boot loader entries <i>within each directory</i> 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 <tt>default_selection</tt>, 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 <tt>default_selection</tt> in this way. If you <i>don't</i> want the latest kernel to become the default, you can use <tt>touch</tt> to give the desired kernel (or other boot loader) in the directory a more recent time stamp, or you can set <tt>default_selection</tt> 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 <a href="http://en.wikipedia.org/wiki/Coordinated_Universal_Time">Coordinated Universal Time (UTC)</a>. 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.</p>
+
+<p class="sidebar"><b>Tip for distribution maintainers:</b> If you maintain an <tt>EFI/<tt class="variable">distname</tt></tt> directory for your kernels, you can place your version of rEFInd in a directory called <tt>EFI/<tt class="variable">distname</tt>/refind</tt>. This will avoid collisions with duplicate rEFInd installations from other distributions.</p>
+
+<p>On the whole, this method of configuration 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 <tt>refind_linux.conf</tt> file, then any rEFInd 0.2.3 or later installation 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.)</p>
-<p>For end users, this method is simpler than maintaining manual configurations in <tt>refind.conf</tt> (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 <tt>linux.conf</tt> in your kernel's directory. You will, however, have to adjust <tt>linux.conf</tt> if you make certain changes, such as if your root directory identifier changes.</p>
+<p>For end users, this method is simpler than maintaining manual configurations in <tt>refind.conf</tt> (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 <tt>refind_linux.conf</tt> in your kernel's directory. You will, however, have to adjust <tt>refind_linux.conf</tt> if you make certain changes, such as if your root directory identifier changes.</p>
<hr/>