code.delx.au - refind/blob - docs/refind/linux.html

   1 <?xml version="1.0" encoding="utf-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   3   "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   4
   5 <html xmlns="http://www.w3.org/1999/xhtml">
   6 <head>
   7   <title>The rEFInd Boot Manager: Methods of Booting Linux</title>
   8   <link href="../Styles/styles.css" rel="stylesheet" type="text/css" />
   9 </head>
  10
  11 <body>
  12 <h1>The rEFInd Boot Manager:<br />Methods of Booting Linux</h1>
  13
  14 <p class="subhead">by Roderick W. Smith, <a
  15 href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
  16
  17 <p>Originally written: 3/19/2012; last Web page update:
  18 12/11/2012, referencing rEFInd 0.5.1</p>
  19
  20
  21 <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>
  22
  23 <table border="1">
  24 <tr>
  25 <td>Donate $1.00</td>
  26 <td>Donate $2.50</td>
  27 <td>Donate $5.00</td>
  28 <td>Donate $10.00</td>
  29 <td>Donate another value</td>
  30 </tr>
  31 <tr>
  32 <td><form name="_xclick" action="https://www.paypal.com/cgi-bin/webscr" method="post">
  33 <input type="hidden" name="cmd" value="_xclick">
  34 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
  35 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
  36 <input type="hidden" name="currency_code" value="USD">
  37 <input type="hidden" name="amount" value="1.00">
  38 <input type="image" src="http://www.paypal.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="Make payments with PayPal - it's fast, free and secure!">
  39 </form>
  40
  41 </td>
  42 <td><form name="_xclick" action="https://www.paypal.com/cgi-bin/webscr" method="post">
  43 <input type="hidden" name="cmd" value="_xclick">
  44 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
  45 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
  46 <input type="hidden" name="currency_code" value="USD">
  47 <input type="hidden" name="amount" value="2.50">
  48 <input type="image" src="http://www.paypal.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="Make payments with PayPal - it's fast, free and secure!">
  49 </form>
  50
  51 </td>
  52 <td><form name="_xclick" action="https://www.paypal.com/cgi-bin/webscr" method="post">
  53 <input type="hidden" name="cmd" value="_xclick">
  54 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
  55 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
  56 <input type="hidden" name="currency_code" value="USD">
  57 <input type="hidden" name="amount" value="5.00">
  58 <input type="image" src="http://www.paypal.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="Make payments with PayPal - it's fast, free and secure!">
  59 </form>
  60
  61 </td>
  62 <td><form name="_xclick" action="https://www.paypal.com/cgi-bin/webscr" method="post">
  63 <input type="hidden" name="cmd" value="_xclick">
  64 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
  65 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
  66 <input type="hidden" name="currency_code" value="USD">
  67 <input type="hidden" name="amount" value="10.00">
  68 <input type="image" src="http://www.paypal.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="Make payments with PayPal - it's fast, free and secure!">
  69 </form>
  70
  71 </td>
  72 <td>
  73 <form action="https://www.paypal.com/cgi-bin/webscr" method="post">
  74 <input type="hidden" name="cmd" value="_donations">
  75 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
  76 <input type="hidden" name="lc" value="US">
  77 <input type="hidden" name="no_note" value="0">
  78 <input type="hidden" name="currency_code" value="USD">
  79 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
  80 <input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
  81 <input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
  82 <img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
  83 </form>
  84 </td></tr>
  85 </table>
  86
  87 <hr />
  88
  89 <p>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 <a href="index.html">main page.</a></p>
  90
  91 <hr />
  92
  93 <p>Windows and Mac OS X both provide relatively simple EFI boot loader programs. Launch them, and if they're launched from the correct locations and have the correct files in place, they'll boot their respective OSes. This makes rEFInd's job easy; it just locates the boot loader program files and runs them.</p>
  94
  95 <p>Under Linux, by contrast, things can get complicated. As detailed on my <a href="http://www.rodsbooks.com/efi-bootloaders/index.html">Managing EFI Boot Loaders for Linux</a> 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 <a href="#traditional">traditional Linux boot loaders.</a> It works even better with the Linux EFI stub loader, so I provide <a href="#quickstart">instructions on starting with it.</a> For those interested in manual configuration, I also provide <a href="#efistub">detailed instructions</a> on how the EFI stub support works and how to configure it.</p>
  96
  97 <a name="traditional">
  98 <h2>Using a Traditional Linux Boot Loader</h2>
  99 </a>
 100
 101 <p>I consider <a href="http://www.rodsbooks.com/efi-bootloaders/elilo.html">ELILO,</a> <a href="http://www.rodsbooks.com/efi-bootloaders/grub_legacy.html">GRUB Legacy,</a> and <a href="http://www.rodsbooks.com/efi-bootloaders/grub2.html">GRUB 2</a> 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 three 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).</p>
 102
 103 <p>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.</p>
 104
 105 <p>If you prefer, you can disable automatic scanning and create an entry in <tt>refind.conf</tt> for your distribution, as described on the <a href="configfile.html">Configuring the Boot Manager</a> page. This method is harder to set up but can be preferable if you want to customize your options.</p>
 106
 107 <a name="quickstart">
 108 <h2>Using the EFI Stub Loader: A Quick Setup Guide</h2>
 109 </a>
 110
 111 <p>The EFI stub loader is basic and reliable, but it requires some setup to use it. I describe both <a href="#testing">a quick test configuration</a> and <a href="#longterm">a long-term setup.</a></p>
 112
 113 <a name="testing">
 114 <h3>Testing the EFI Stub Loader</h3>
 115 </a>
 116
 117 <p>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. (Fedora 17, Ubuntu 12.10, and probably other 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:</p>
 118
 119 <ol>
 120
 121 <li>Copy your kernel file (<tt>vmlinuz-*</tt>) and matching initial RAM
 122     disk file (<tt>init*</tt>) from <tt>/boot</tt> to a subdirectory of
 123     <tt>EFI</tt> on your ESP. Your distribution's directory there should
 124     work fine. For instance, typing <tt class="userinput">cp
 125     /boot/vmlinuz-3.6.7-4.fc17.x86_64
 126     /boot/initramfs-3.6.7-4.fc17.x86_64.img /boot/efi/EFI/redhat</tt> might
 127     do the trick on a Fedora system, although you'll probably have to
 128     adjust the version numbers. Note that the filename forms vary from one
 129     distribution to another, so don't worry if yours look different from
 130     these. Be sure that you match up the correct files by version number,
 131     though.</li>
 132
 133 <li>Copy the <tt>/boot/refind_linux.conf</tt> file to the same directory to
 134     which you copied your kernel. If this file doesn't exist, create it by
 135     running (as <tt>root</tt>) the <tt>mkrlconf.sh</tt> script that came
 136     with rEFInd.</li>
 137
 138 <li>Reboot. You should now see a new entry for launching the Linux kernel
 139     that you copied. Try the option. If it works, great. If not, you may
 140     need to adjust your <tt>refind_linux.conf</tt> file. See the <a
 141     href="#efistub">detailed configuration section</a> for a description of
 142     this file's format. If the kernel begins to boot but complains that it
 143     couldn't find its root filesystem, double-check the version numbers on
 144     your kernel and initial RAM disk file, and check the <tt>root=</tt>
 145     option in <tt>refind_linux.conf</tt>.</li>
 146
 147 </ol>
 148
 149 <p>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 <tt>/boot</tt> directory, where most Linux distributions place their kernels.</p>
 150
 151 <a name="longterm">
 152 <h3>Configuring a Maintenance-Free Setup</h3>
 153 </a>
 154
 155 <p>The ideal configuration for use of the EFI stub loader involves giving rEFInd the ability to load your kernels directly from <tt>/boot</tt>. The main obstacle to doing so is that this directory is frequently on an XFS, JFS, Btrfs, or ext4 filesystem that the EFI can't read, or it's tucked away in an LVM or RAID configuration that the EFI can't read. 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). If you're currently booting via GRUB 2, it is likely to cease working when you try this, although GRUB should be recoverable by re-installing it. (On the other hand, GRUB will become redundant once this method of booting starts working so you might prefer to remove it completely.) You should perform the following steps as <tt>root</tt>, or precede each of these commands with <tt>sudo</tt>:</p>
 156
 157 <ol>
 158
 159 <li>Begin with your ESP mounted at <tt>/boot/efi</tt>, which is the most
 160     common location. If it's not mounted there, type <tt
 161     class="userinput">mount /dev/sda1 /boot/efi</tt> to do so (adjusting
 162     <tt>/dev/sda1</tt>, if necessary), or mount it elsewhere and adjust the
 163     paths in the following procedure as necessary.</li>
 164
 165 <li>Check the size of the ESP by typing <tt class="userinput">df -h
 166     /boot/efi</tt>. The ESP must be large enough to hold several Linux
 167     kernels and initial RAM disk files&mdash;100MiB at a bare minimum, and
 168     preferably 200&ndash;500MiB.</li>
 169
 170 <li>Check your <tt>/boot</tt> directory to be sure it contains no links or
 171     other files that rely on Unix/Linux-style permissions or ownership. If
 172     it does, don't proceed, or at least research these files further to
 173     determine if you can work around the need for such permissions and
 174     ownership.</li>
 175
 176 <li>Type <tt class="userinput">mv /boot/* /boot/efi</tt>. You'll see an
 177     error message about being unable to move <tt>/boot/efi</tt> into
 178     itself. Ignore this.</li>
 179
 180 <li>Type <tt class="userinput">umount /boot/efi</tt>.</li>
 181
 182 <li>Edit <tt>/etc/fstab</tt> and change the mount point for
 183     <tt>/boot/efi</tt> to <tt>/boot</tt>. If the ESP isn't present in
 184     <tt>/etc/fstab</tt>, you must create an entry for it, with a mount
 185     point of <tt>/boot</tt>.</li>
 186
 187 <li>Type <tt class="userinput">mount -a</tt> to re-mount everything,
 188     including <tt>/boot</tt>. Check that your normal <tt>/boot</tt> files
 189     are all present, along with the new <tt>/boot/EFI</tt> directory, which
 190     holds what used to be <tt>/boot/efi/EFI</tt>. If something seems to be
 191     missing (other than <tt>/boot/efi</tt> with a lowercase <tt>efi</tt>),
 192     then you should try to correct the problem.</li>
 193
 194 <li>If it doesn't already exist, create a file called
 195     <tt>/boot/refind_linux.conf</tt> and populate it with kernel options,
 196     as described <a href="#refind_linux">later.</a> If this file doesn't
 197     already exist, the easiest way to create it is to run the
 198     <tt>mkrlconf.sh</tt> script that comes with rEFInd 0.5.1 and
 199     later.</li>
 200
 201 <li>Check your <tt>refind.conf</tt> file (presumably in
 202     <tt>/boot/EFI/refind</tt>) to be sure that the
 203     <tt>scan_all_linux_kernels</tt> line is uncommented. If it's not,
 204     uncomment that line.</li>
 205
 206 <li>Optionally, type <tt class="userinput">cp
 207     /boot/EFI/refind/icons/os_<i>name</i>.icns /boot/.VolumeIcon.icns</tt>
 208     to give loaders in <tt>/boot</tt> an icon for your distribution.</li>
 209
 210 <li>Reboot to test that this configuration works.</li>
 211
 212 </ol>
 213
 214 <p>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.</p>
 215
 216 <p>For these reasons, a variant of this procedure may be desirable. Most of the steps are similar, but in this variant, you create a separate <tt>/boot</tt> partition that's independent of the ESP. This partition can use FAT, HFS+, ReiserFS, ext2fs, ext3fs; but if you use any of the last four filesystems (three 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&ndash;500MiB). Mount your new <tt>/boot</tt> partition at a temporary location, copy or move the current <tt>/boot</tt> files into it, unmount it, and add it to <tt>/etc/fstab</tt> as <tt>/boot</tt>.</p>
 217
 218
 219 <p>If your distribution already uses a separate <tt>/boot</tt> partition (as Fedora 17 does by default), but if it uses ext4fs or some other unsuitable filesystem, you can back it up, create a fresh FAT, HFS+, ReiserFS, ext2, or ext3 filesystem on it, and restore the original files. If you use a separate non-ESP <tt>/boot</tt> partition, you'll probably want to continue mounting the ESP at <tt>/boot/efi</tt>.</p>
 220
 221 <a name="efistub">
 222 <h2>EFI Stub Loader Support Technical Details</h2>
 223 </a>
 224
 225 <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>
 226
 227 <p>With all versions of rEFInd, you can create manual boot loader stanzas
 228 in the <tt>refind.conf</tt> file to identify a Linux kernel and to pass it
 229 all the options it needs. This approach is effective and flexible, but it
 230 requires editing a single configuration file for all the OSes you want to
 231 define in this way. If a computer boots two different Linux distributions,
 232 and if both were to support rEFInd, problems might arise as each one tries
 233 to modify its own rEFInd configuration; or the one that controls rEFInd
 234 might set inappropriate options for another distribution. This is a problem
 235 that's been a minor annoyance for years under BIOS, since the same
 236 potential for poor configuration applies to LILO, GRUB Legacy, and GRUB 2
 237 on BIOS. The most reliable solution under BIOS is to chainload one boot
 238 loader to another. The same solution is possible under EFI, but rEFInd
 239 offers another possibility.</p>
 240
 241 <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>
 242
 243 <ol>
 244
 245 <li>rEFInd looks for boot loaders whose names include the strings
 246     <tt>bzImage</tt> or <tt>vmlinuz</tt> and that end in <tt>.efi</tt>. For
 247     instance, <tt>bzImage-3.3.0.efi</tt> or <tt>vmlinuz-3.3.0-fc17.efi</tt>
 248     would match, and trigger subsequent steps in this procedure. Beginning
 249     with version 0.3.0, if you uncomment the
 250     <tt>scan_all_linux_kernels</tt> option in <tt>refind.conf</tt>, rEFInd
 251     will also scan for kernels <i>without</i> a <tt>.efi</tt> filename
 252     extension. This option is uncommented by default, but if you comment it
 253     out, delete it, or change it to read <tt>scan_all_linux_kernels 0</tt>,
 254     rEFInd won't scan for kernels that lack <tt>.efi</tt> filename
 255     extensions.</li>
 256
 257 <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>
 258
 259 <li>rEFInd looks for an initial RAM disk in the same directory as the
 260     kernel file. A matching initial RAM disk has a name that begins with
 261     <tt>init</tt> and that includes the same version string as the kernel.
 262     The version string is defined as the part of the filename from the
 263     first digit to the last digit, inclusive. Note that the version string
 264     can include non-digits. For instance, the version string for
 265     <tt>bzImage-3.3.0.efi</tt> is <tt>3.3.0</tt>, which matches
 266     <tt>initramfs-3.3.0.bz</tt>; and <tt>vmlinuz-3.3.0-fc17.efi</tt>'s
 267     version string is <tt>3.3.0-fc17</tt>, which matches
 268     <tt>initrd-3.3.0-fc17.img</tt>. Many other matches are possible. If an
 269     initial RAM disk is identified, rEFInd passes a suitable
 270     <tt>initrd=</tt> option to the kernel when it boots.</li>
 271
 272 <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 rEFInd's <tt>linux.conf</tt> file to <tt>refind_linux.conf</tt> if you're upgrading.</p>
 273
 274 <li>rEFInd looks for a file called <tt>refind_linux.conf</tt> in the same
 275     directory as the kernel file. This file is a practical requirement for
 276     booting from an auto-detected kernel. It consists of a series of lines,
 277     each of which consists of a label followed by a series of kernel
 278     options. The first line sets default options, and subsequent lines set
 279     options that are accessible from the main menu tag's submenu screen. If
 280     you installed rEFInd 0.5.1 or later with the <tt>install.sh</tt>
 281     script, that script created a sample <tt>refind_linux.conf</tt> file,
 282     customized for your computer, in <tt>/boot</tt>. This file will work
 283     without changes on many installations, but you may need to tweak it for
 284     some.</li>
 285
 286 </ol>
 287
 288 <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 subdirectories on the ESP, on EFI-accessible <tt>/boot</tt> partitions, or in <tt>/boot</tt> directories on EFI-accessible Linux root (<tt>/</tt>) partitions. rEFInd will detect these 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>
 289
 290 <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>
 291
 292 <p>As an example, consider the following file configuration:</p>
 293
 294 <pre class="listing">
 295 $ <b>ls -l /boot/efi/EFI/ubuntu/</b>
 296 total 17943
 297 -rwxr-xr-x 1 root root  4781632 2012-03-18 12:01 bzImage-3.3.0.efi
 298 -rwxr-xr-x 1 root root   131072 2011-10-14 04:10 grubx64.EFI
 299 -rwxr-xr-x 1 root root 13459936 2012-03-18 12:02 initrd.img-3.3.0
 300 -rwxr-xr-x 1 root root      266 2012-03-26 19:39 refind_linux.conf
 301 </pre>
 302
 303 <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>
 304
 305 <a name="refind_linux">
 306 <pre class="listing">
 307 "Boot with defaults"         "root=/dev/sda3 ro quiet splash vt.handoff=7"
 308 "Boot into single-user mode" "root=UUID=1cd95082-bce0-494c-a290-d2e642dd82b7 ro single"
 309 "Boot without graphics"      "root=UUID=1cd95082-bce0-494c-a290-d2e642dd82b7 ro"
 310 # "Boot alternate install"   "root=/dev/sdb9 ro quiet splash vt.handoff=7"
 311 </pre>
 312 </a>
 313
 314 <p>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 <tt>"root=/dev/sdb9 my_opt=""this is it"""</tt>, which passes <tt>root=/dev/sdb9 my_opt="this is it"</tt> 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 (<tt>#</tt>), as in the fourth line in this example.</p>
 315
 316 <p>In the preceding example, the first line sets the options that rEFInd passes to the kernel by default (along with the name of the <tt>initrd.img-3.3.0</tt> 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:</p>
 317
 318     <br /><center><img src="automatic-submenu.png" align="center"
 319     width="376" height="279" alt="rEFInd can load Linux boot options from
 320     a refind_linux.conf file in the Linux kernel's directory."
 321     border=2></center><br />
 322
 323 <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>
 324
 325 <p>To assist in initial configuration, rEFInd's <tt>install.sh</tt> script creates a sample <tt>refind_linux.conf</tt> file in <tt>/boot</tt>. This sample file defines two entries that use the default GRUB options defined in <tt>/etc/default/grub</tt>. 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 <tt>mkrlconf.sh</tt> script that comes with rEFInd. If you pass it the <tt>--force</tt> option, it will overwrite the existing <tt>/boot/refind_linux.conf</tt> file; otherwise it will create the file only if one doesn't already exist.</p>
 326
 327 <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>
 328
 329 <ul>
 330
 331 <li>Your kernels must be compiled with EFI stub loader support.</li>
 332
 333 <li>You can't set a submenu option to boot via a different boot loader,
 334     such as ELILO or GRUB; all the submenu options apply to a single boot
 335     loader&mdash;that is, a single kernel. (rEFInd will still detect other
 336     boot loaders and provide separate main-menu tags for them,
 337     though.)</li>
 338
 339 <li>If an installation includes two or more kernel files, each one receives
 340     its own main-menu entry; you can't combine them together in one menu
 341     item. This is essentially a corollary of the preceding limitation. The
 342     result can be an overburdened main menu if your system has many
 343     kernels.</li>
 344
 345 <li>All the kernels in a given directory use the same
 346     <tt>refind_linux.conf</tt> file. If you need to set different options
 347     for different kernels, you'll need to place those kernels in different
 348     directories.</li>
 349
 350 <li>You must place your kernels in a directory other than the one that
 351     holds the main rEFInd <tt>.efi</tt> file. This is because rEFInd does
 352     not scan its own directory for boot loaders.</li>
 353
 354 </ul>
 355
 356 <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>
 357
 358 <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>
 359
 360 <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>
 361
 362 <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>
 363
 364 <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>
 365
 366 <hr/>
 367
 368 <p>copyright &copy; 2012 by Roderick W. Smith</p>
 369
 370 <p>This document is licensed under the terms of the <a href="FDL-1.3.txt">GNU Free Documentation License (FDL), version 1.3.</a></p>
 371
 372 <p>If you have problems with or comments about this Web page, please e-mail me at <a href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com.</a> Thanks.</p>
 373
 374 <p><a href="index.html">Go to the main rEFInd page</a></p>
 375
 376 <p><a href="secureboot.html">Learn how to manage Secure Boot</a></p>
 377
 378   <p><a href="http://www.rodsbooks.com/">Return</a> to my main Web page.</p>
 379 </body>
 380 </html>