]> code.delx.au - refind/blob - docs/refind/linux.html
Version 0.10.0 release.
[refind] / 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 <meta name="viewport" content="width=device-width, initial-scale=1">
12
13 <body>
14 <h1>The rEFInd Boot Manager:<br />Methods of Booting Linux</h1>
15
16 <p class="subhead">by Roderick W. Smith, <a
17 href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
18
19 <p>Originally written: 3/19/2012; last Web page update:
20 11/8/2015, referencing rEFInd 0.10.0</p>
21
22
23 <p>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>
24
25 <table border="1">
26 <tr>
27 <td>Donate $1.00</td>
28 <td>Donate $2.50</td>
29 <td>Donate $5.00</td>
30 <td>Donate $10.00</td>
31 <td>Donate $20.00</td>
32 <td>Donate another value</td>
33 </tr>
34 <tr>
35
36 <td>
37 <form action="https://www.paypal.com/cgi-bin/webscr" method="post">
38 <input type="hidden" name="cmd" value="_donations">
39 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
40 <input type="hidden" name="lc" value="US">
41 <input type="hidden" name="no_note" value="0">
42 <input type="hidden" name="currency_code" value="USD">
43 <input type="hidden" name="amount" value="1.00">
44 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
45 <input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
46 <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!">
47 <img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
48 </form>
49 </td>
50
51 <td>
52 <form action="https://www.paypal.com/cgi-bin/webscr" method="post">
53 <input type="hidden" name="cmd" value="_donations">
54 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
55 <input type="hidden" name="lc" value="US">
56 <input type="hidden" name="no_note" value="0">
57 <input type="hidden" name="currency_code" value="USD">
58 <input type="hidden" name="amount" value="2.50">
59 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
60 <input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
61 <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!">
62 <img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
63 </form>
64 </td>
65
66
67 <td>
68 <form action="https://www.paypal.com/cgi-bin/webscr" method="post">
69 <input type="hidden" name="cmd" value="_donations">
70 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
71 <input type="hidden" name="lc" value="US">
72 <input type="hidden" name="no_note" value="0">
73 <input type="hidden" name="currency_code" value="USD">
74 <input type="hidden" name="amount" value="5.00">
75 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
76 <input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
77 <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!">
78 <img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
79 </form>
80 </td>
81
82 <td>
83 <form action="https://www.paypal.com/cgi-bin/webscr" method="post">
84 <input type="hidden" name="cmd" value="_donations">
85 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
86 <input type="hidden" name="lc" value="US">
87 <input type="hidden" name="no_note" value="0">
88 <input type="hidden" name="currency_code" value="USD">
89 <input type="hidden" name="amount" value="10.00">
90 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
91 <input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
92 <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!">
93 <img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
94 </form>
95 </td>
96
97 <td>
98 <form action="https://www.paypal.com/cgi-bin/webscr" method="post">
99 <input type="hidden" name="cmd" value="_donations">
100 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
101 <input type="hidden" name="lc" value="US">
102 <input type="hidden" name="no_note" value="0">
103 <input type="hidden" name="currency_code" value="USD">
104 <input type="hidden" name="amount" value="20.00">
105 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
106 <input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
107 <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!">
108 <img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
109 </form>
110 </td>
111
112 <td>
113 <form action="https://www.paypal.com/cgi-bin/webscr" method="post">
114 <input type="hidden" name="cmd" value="_donations">
115 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
116 <input type="hidden" name="lc" value="US">
117 <input type="hidden" name="no_note" value="0">
118 <input type="hidden" name="currency_code" value="USD">
119 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
120 <input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
121 <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!">
122 <img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
123 </form>
124 </td></tr>
125 </table>
126
127 <hr />
128
129 <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>
130
131 <hr />
132
133 <div style="float:right; width:55%">
134
135 <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>
136
137 </div>
138
139 <div class="navbar">
140
141 <h4 class="tight">Contents</h4>
142
143 <ul>
144
145 <li class="tight"><a href="#traditional">Using a Traditional Linux Boot Loader</li>
146
147 <li class="tight"><a href="#quickstart">Using the EFI Stub Loader: Three Configuration Options</a>
148
149 <ul>
150
151 <li class="tight"><a href="#easiest">For Those With Foresight or Luck: The Easiest Method</a></li>
152
153 <li class="tight"><a href="#testing">Preparing a Test Configuration</a></li>
154
155 <li class="tight"><a href="#reconfigure">If You Need to Reconfigure Your Partitions....</a></li>
156
157 </ul></li>
158
159 <li class="tight"><a href="#efistub">EFI Stub Loader Support Technical Details</a></li>
160
161 </ul>
162
163 </div>
164
165 <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>
166
167 <a name="traditional">
168 <h2>Using a Traditional Linux Boot Loader</h2>
169 </a>
170
171 <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>, <a href="http://www.rodsbooks.com/efi-bootloaders/grub2.html">GRUB 2</a>, and <a href="http://www.rodsbooks.com/efi-bootloaders/syslinux.html">SYSLINUX</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 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).</p>
172
173 <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>
174
175 <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>
176
177 <a name="quickstart">
178 <h2>Using the EFI Stub Loader: Three Configuration Options</h2>
179 </a>
180
181 <p>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 <a href="#easiest">easiest method</a> for those with compatible partition and filesystem layouts, a <a href="#testing">quick test configuration</a> for those without such a layout, and <a href="#reconfigure">a long-term setup</a> for those without the ideal setup.</p>
182
183 <a name="easiest">
184 <h3>For Those With Foresight or Luck: The Easiest Method</h3>
185 </a>
186
187 <p>This method requires that your <tt>/boot</tt> directory, whether it's on a separate partition or is a regular directory in your root (<tt>/</tt>) filesystem, be readable by the EFI. At the moment, all EFI implementations can read FAT and Macs can read HFS+. By using <a href="drivers.html">drivers,</a> 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 <tt>/boot</tt>, 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 <tt>/boot</tt> partition. You must also have a 3.3.0 or later Linux kernel with EFI stub support, of course.</p>
188
189 <p>If you installed rEFInd 0.6.0 or later with its <tt>refind-install</tt> (formerly <tt>install.sh</tt>) 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:
190
191 <ul>
192
193 <li>Copy the relevant driver file for your filesystem and architecture to
194 the <tt>drivers</tt> or <tt>drivers_<tt class="variable">arch</tt></tt>
195 subdirectory of the rEFInd installation directory on the EFI System
196 Partition (ESP). You may need to create this subdirectory, too.</li>
197
198 <li>Create a <tt>refind_linux.conf</tt> file in your <tt>/boot</tt>
199 directory. The <tt>mkrlconf</tt> script that comes with rEFInd
200 should do this job, or you can do it manually as described <a
201 href="#efistub">later.</a> Starting with version 0.6.12, rEFInd can
202 create minimal boot options from <tt>/etc/fstab</tt>, if <tt>/boot</tt>
203 is <i>not</i> a separate partition, so a <tt>refind_linux.conf</tt>
204 file may not be strictly necessary. Version 0.9.0 also adds the ability
205 to identify the root (<tt>/</tt>) partition via the <a
206 href="http://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable
207 Partitions Spec,</a> if your disk uses the appropriate type codes. A
208 <tt>refind_linux.conf</tt> file remains desirable, though, and is
209 necessary in some situations.</li>
210
211 </ul>
212
213 <p>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 <a href="#reconfigure">maintenance-free setup</a> section. If you have problems, you may need to adjust the <tt>refind_linux.conf</tt> file, as described in the <a href="#efistub">detailed configuration section.</a></p>
214
215 <a name="testing">
216 <h3>Preparing a Test Configuration</h3>
217 </a>
218
219 <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 since version 17, Ubuntu since 12.10, and most 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>
220
221 <ol>
222
223 <li>Copy your kernel file (<tt>vmlinuz-*</tt>) and matching initial RAM
224 disk file (<tt>init*</tt>) from <tt>/boot</tt> to a subdirectory of
225 <tt>EFI</tt> on your ESP. Your distribution's directory there should
226 work fine. For instance, typing <tt class="userinput">cp
227 /boot/vmlinuz-4.2.5-300.fc23.x86_64
228 /boot/initramfs-4.2.5-300.fc23.x86_64.img /boot/efi/EFI/fedora</tt> might
229 do the trick on a Fedora system, although you'll probably have to
230 adjust the version numbers. Note that the filename forms vary from one
231 distribution to another, so don't worry if yours look different from
232 these. Be sure that you match up the correct files by version number,
233 though.</li>
234
235 <li>Copy the <tt>/boot/refind_linux.conf</tt> file to the same directory to
236 which you copied your kernel. If this file doesn't exist, create it by
237 running (as <tt>root</tt>) the <tt>mkrlconf</tt> script that came
238 with rEFInd. This step may not be strictly necessary if <tt>/boot</tt>
239 is an ordinary directory on your root (<tt>/</tt>) partition.</li>
240
241 <li>Reboot. You should now see a new entry for launching the Linux kernel
242 that you copied. Try the option. If it works, great. If not, you may
243 need to adjust your <tt>refind_linux.conf</tt> file. See the <a
244 href="#efistub">detailed configuration section</a> for a description of
245 this file's format. If the kernel begins to boot but complains that it
246 couldn't find its root filesystem, double-check the version numbers on
247 your kernel and initial RAM disk file, and check the <tt>root=</tt>
248 option in <tt>refind_linux.conf</tt>.</li>
249
250 </ol>
251
252 <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>
253
254 <a name="reconfigure">
255 <h3>If You Need to Reconfigure Your Partitions....</h3>
256 </a>
257
258 <p>If your <tt>/boot</tt> 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 <a href="#easiest">easiest solution.</a> 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 <tt>root</tt>, or precede each of these commands with <tt>sudo</tt>:</p>
259
260 <ol>
261
262 <li>Begin with your ESP mounted at <tt>/boot/efi</tt>, which is the most
263 common location. If it's not mounted there, type <tt
264 class="userinput">mount /dev/sda1 /boot/efi</tt> to do so (adjusting
265 <tt>/dev/sda1</tt>, if necessary), or mount it elsewhere and adjust the
266 paths in the following procedure as necessary.</li>
267
268 <li>Check the size of the ESP by typing <tt class="userinput">df -h
269 /boot/efi</tt>. The ESP must be large enough to hold several Linux
270 kernels and initial RAM disk files&mdash;100MiB at a bare minimum, and
271 preferably 200&ndash;500MiB.</li>
272
273 <li>Check your <tt>/boot</tt> directory to be sure it contains no links or
274 other files that rely on Unix/Linux-style permissions or ownership. If
275 it does, don't proceed, or at least research these files further to
276 determine if you can work around the need for such permissions and
277 ownership.</li>
278
279 <li>Type <tt class="userinput">cp -r /boot/* /boot/efi</tt>. You'll see an
280 error message about being unable to copy <tt>/boot/efi</tt> into
281 itself. Ignore this.</li>
282
283 <li>Type <tt class="userinput">umount /boot/efi</tt>.</li>
284
285 <li>Edit <tt>/etc/fstab</tt> and change the mount point for
286 <tt>/boot/efi</tt> to <tt>/boot</tt>. If the ESP isn't present in
287 <tt>/etc/fstab</tt>, you must create an entry for it, with a mount
288 point of <tt>/boot</tt>.</li>
289
290 <li>Type <tt class="userinput">mount -a</tt> to re-mount everything,
291 including <tt>/boot</tt>. Check that your normal <tt>/boot</tt> files
292 are all present, along with the new <tt>/boot/EFI</tt> directory, which
293 holds what used to be <tt>/boot/efi/EFI</tt>. If something seems to be
294 missing (other than <tt>/boot/efi</tt> with a lowercase <tt>efi</tt>),
295 then you should try to correct the problem.</li>
296
297 <li>If it doesn't already exist, create a file called
298 <tt>/boot/refind_linux.conf</tt> and populate it with kernel options,
299 as described <a href="#refind_linux">later.</a> If this file doesn't
300 already exist, the easiest way to create it is to run the
301 <tt>mkrlconf</tt> script that comes with rEFInd 0.5.1 and
302 later.</li>
303
304 <li>Check your <tt>refind.conf</tt> file (presumably in
305 <tt>/boot/EFI/refind</tt>) to be sure that the
306 <tt>scan_all_linux_kernels</tt> line is uncommented. If it's not,
307 uncomment that line.</li>
308
309 <li>Optionally, type <tt class="userinput">cp
310 /boot/EFI/refind/icons/os_<i>name</i>.icns /boot/.VolumeIcon.icns</tt>
311 to give loaders in <tt>/boot</tt> an icon for your distribution.</li>
312
313 <li>Reboot to test that this configuration works.</li>
314
315 </ol>
316
317 <p>Recall that in step #4, you <i>copied</i> the contents of <tt>/boot</tt> (as a safety measure), but you did not move them. Therefore, you ended up with two copies of your kernels and other <tt>/boot</tt> directory contents, with one copy hiding the other when you mounted the ESP at <tt>/boot</tt>. Once you've booted successfully and are sure all is working well, you can recover some disk space by unmounting <tt>/boot</tt> and deleting the contents of the underlying <tt>/boot</tt> directory on your root (<tt>/</tt>) filesystem. Be sure that the <tt>/boot</tt> partition is unmounted before you do this, though! Also, be sure to leave the <tt>/boot</tt> directory itself in place, even if it has no contents; the directory is needed as a mount point for the <tt>/boot</tt> partition. Note that GRUB 2 may stop working if you delete its files from the root filesystem's <tt>/boot/grub</tt> directory, so if you want to keep GRUB around, you should re-install it with the separate <tt>/boot</tt> partition mounted.</p>
318
319 <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>
320
321 <p>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 <tt>/boot</tt> 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&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>
322
323 <p>If your distribution already uses a separate <tt>/boot</tt> 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 <tt>/etc/fstab</tt> to ensure that the computer mounts the new filesystem when you boot. 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>
324
325 <a name="efistub">
326 <h2>EFI Stub Loader Support Technical Details</h2>
327 </a>
328
329 <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>
330
331 <p>With all versions of rEFInd, you can create manual boot loader stanzas
332 in the <tt>refind.conf</tt> file to identify a Linux kernel and to pass it
333 all the options it needs. This approach is effective and flexible, but it
334 requires editing a single configuration file for all the OSes you want to
335 define in this way. If a computer boots two different Linux distributions,
336 and if both were to support rEFInd, problems might arise as each one tries
337 to modify its own rEFInd configuration; or the one that controls rEFInd
338 might set inappropriate options for another distribution. This is a problem
339 that's been a minor annoyance for years under BIOS, since the same
340 potential for poor configuration applies to LILO, GRUB Legacy, and GRUB 2
341 on BIOS. The most reliable solution under BIOS is to chainload one boot
342 loader to another. The same solution is possible under EFI, but rEFInd
343 offers another possibility.</p>
344
345 <p>rEFInd supports semi-automatic Linux EFI stub loader detection. This
346 feature works as part of the standard boot loader scan operation, but it
347 extends it as follows:</p>
348
349 <ol>
350
351 <li>rEFInd looks for boot loaders whose names include the strings
352 <tt>bzImage</tt> or <tt>vmlinuz</tt>. For instance,
353 <tt>bzImage-3.19.0.efi</tt> or <tt>vmlinuz-4.2.0</tt> would match, and
354 trigger subsequent steps in this procedure. The
355 <tt>scan_all_linux_kernels</tt> option in <tt>refind.conf</tt> controls
356 the scanning for kernels whose names do not end in <tt>.efi</tt>; if
357 this option is set to <tt>false</tt>, kernel filenames must end in
358 <tt>.efi</tt> to be picked up by rEFInd. This option is set to
359 <tt>true</tt> by default, but you can change it if you don't want to
360 scan all Linux kernels.</li>
361
362 <li>If a file's name ends in <tt>.efi.signed</tt>, any other file with an
363 otherwise-identical name that <i>lacks</i> this extension is excluded.
364 This peculiar rule exists because Ubuntu delivers two
365 copies of every kernel, one with and one without this extension. The
366 one with the extension is signed with a Secure Boot key; the one
367 without it is not so signed. Thus, if both files are present, the one
368 without the key won't boot on a computer with Secure Boot active, and
369 either will boot if Secure Boot is inactive. Thus, rEFInd excludes the
370 redundant (unsigned) file in order to help keep the list of boot
371 options manageable.</li>
372
373 <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>
374
375 <li>rEFInd looks for an initial RAM disk in the same directory as the
376 kernel file. A matching initial RAM disk has a name that begins with
377 <tt>init</tt> and that includes the same version string as the kernel.
378 The version string is defined as the part of the filename from the
379 first digit to the last digit, inclusive. Note that the version string
380 can include non-digits. For instance, the version string for
381 <tt>bzImage-3.19.0.efi</tt> is <tt>3.19.0</tt>, which matches
382 <tt>initramfs-3.19.0.bz</tt>; and
383 <tt>vmlinuz-4.2.5-300.fc23.x86_64</tt>'s version string is
384 <tt>4.2.5-300.fc23.x86_64</tt>, which matches
385 <tt>initrd-4.2.5-300.fc23.x86_64.img</tt>. Many other matches are
386 possible. If an initial RAM disk is identified, rEFInd passes a
387 suitable <tt>initrd=</tt> option to the kernel when it boots.</li>
388
389 <li>rEFInd looks for a file called <tt>refind_linux.conf</tt> in the same
390 directory as the kernel file. It consists of a series of lines,
391 each of which consists of a label followed by a series of kernel
392 options. The first line sets default options, and subsequent lines set
393 options that are accessible from the main menu tag's submenu screen. If
394 you installed rEFInd with the <tt>refind-install</tt>
395 script, that script created a sample <tt>refind_linux.conf</tt> file,
396 customized for your computer, in <tt>/boot</tt>. This file will work
397 without changes on many installations, but you may need to tweak it for
398 some.</li>
399
400 <li>If rEFInd can't find a <tt>refind_linux.conf</tt> file in the directory
401 that holds the kernel, the program looks for a file called
402 <tt>/etc/fstab</tt> on the partition that holds the kernel. If this
403 standard Linux file is present, rEFInd uses it to identify the root
404 (<tt>/</tt>) filesystem and creates two sets of Linux kernel boot
405 options: One set launches the kernel normally, but with minimal
406 options, and the other set launches the kernel into single-user mode.
407 This step can get a computer to boot without any rEFInd-specific
408 configuration files, aside from <tt>refind.conf</tt> in rEFInd's own
409 directory, but only if <tt>/boot</tt> is not a separate partition. The
410 intent is to facilitate the use of rEFInd as an emergency boot manager
411 or to help users who must install rEFInd from OS X or Windows. Note
412 that rEFInd uses <tt>/etc/fstab</tt> only if <tt>refind_linux.conf</tt>
413 is <i>not</i> found.</li>
414
415 <li>If rEFInd can't find a <tt>refind_linux.conf</tt> file or an
416 <tt>/etc/fstab</tt> file, it tries to identify the Linux root
417 (<tt>/</tt> filesystem by looking for a partition with a GUID type code
418 matching that specified for the root (<tt>/</tt>) filesystem in the <a
419 href="http://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Freedesktop.org
420 Discoverable Partitions Specification.</a> These type codes are as yet
421 seldom used, but if and when they become common, they should help a lot
422 for situations similar to those of the preceding case, but when a
423 separate <tt>/boot</tt> partition is used.</li>
424
425 </ol>
426
427 <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 directory that holds kernels; or if <tt>fold_linux_kernels</tt> is set to <tt>false</tt>, one menu entry for each kernel. Each entry will implement as many options as there are lines in the <tt>refind_linux.conf</tt> file (multiplied by the number of kernels, if <tt>fold_linux_kernels</tt> is <tt>true</tt>). 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>
428
429 <p>As an example, consider the following (partial) file listing:</p>
430
431 <pre class="listing">
432 $ <b>ls -l /boot/vmlin*</b>
433 total 17943
434 -rw-r--r-- 1 root root 5271984 Aug 7 10:18 /boot/vmlinuz-3.16.7-24-default
435 -rw-r--r-- 1 root root 5271536 Oct 23 17:25 /boot/vmlinuz-3.16.7-29-default
436 </pre>
437
438 <p>When rEFInd scans this directory, it will discover two kernels in <tt>/boot</tt>. Assuming <tt>fold_linux_kernels</tt> is its default of <tt>true</tt>, rEFInd will create one main-menu tag for these two kernels. A <tt>refind_linux.conf</tt> file in this directory should contain a list of labels and options:</p>
439
440 <a name="refind_linux">
441 <pre class="listing">
442 "Boot with standard options" "ro root=UUID=084f544a-7559-4d4b-938a-b920f59edc7e splash=silent quiet showopts "
443 "Boot to single-user mode" "ro root=UUID=084f544a-7559-4d4b-938a-b920f59edc7e splash=silent quiet showopts single"
444 "Boot with minimal options" "ro root=UUID=084f544a-7559-4d4b-938a-b920f59edc7e"
445 # This line is a comment
446 </pre>
447 </a>
448
449 <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>
450
451 <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 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:</p>
452
453 <br /><center><img src="automatic-submenu.png" align="center"
454 width="622" height="210" alt="rEFInd can load Linux boot options from
455 a refind_linux.conf file in the Linux kernel's directory."
456 border=2></center><br />
457
458 <p>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 <tt>refind_linux.conf</tt>. Subsequent kernels (just one in this example) appear below it, with the same labels preceded by the kernel filename. If you were to set <tt>fold_linux_kernels false</tt>, each kernel would get its own entry on the main menu, and each one's submenu would enable options for launching it alone.</p>
459
460 <p>To assist in initial configuration, rEFInd's <tt>refind-install</tt> script creates a sample <tt>refind_linux.conf</tt> file in <tt>/boot</tt>. This sample file defines three entries, the first two of which use the default GRUB options defined in <tt>/etc/default/grub</tt> 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 <tt>mkrlconf</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>
461
462 <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>
463
464 <ul>
465
466 <li>Your kernels must be compiled with EFI stub loader support. (This is
467 almost always true of distribution-provided kernels these days.)</li>
468
469 <li>You can't set a submenu option to boot via a different boot loader,
470 such as ELILO or GRUB; all the submenu options apply to a single boot
471 loader&mdash;that is, a single kernel. (rEFInd will still detect other
472 boot loaders and provide separate main-menu tags for them,
473 though.) Folded kernel entries are an exception to this rule.</li>
474
475 <li>All the kernels in a given directory use the same
476 <tt>refind_linux.conf</tt> file. If you need to set different options
477 for different kernels, you'll need to place those kernels in different
478 directories.</li>
479
480 <li>You must place your kernels in a directory other than the one that
481 holds the main rEFInd <tt>.efi</tt> file. This is because rEFInd does
482 not scan its own directory for boot loaders.</li>
483
484 </ul>
485
486 <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 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 (<tt>/</tt>) partition or from a <tt>/boot</tt> partition.</p>
487
488 <p>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>
489
490 <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>
491
492 <p>On the whole, auto-detecting kernels and passing boot options using <tt>refind_linux.conf</tt> 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 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.)</p>
493
494 <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>
495
496 <hr/>
497
498 <p>copyright &copy; 2012&ndash;2015 by Roderick W. Smith</p>
499
500 <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>
501
502 <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>
503
504 <p><a href="index.html">Go to the main rEFInd page</a></p>
505
506 <p><a href="secureboot.html">Learn how to manage Secure Boot</a></p>
507
508 <p><a href="http://www.rodsbooks.com/">Return</a> to my main Web page.</p>
509 </body>
510 </html>