]> code.delx.au - refind/blob - docs/refind/linux.html
Version 0.2.5 release. Additional icon-management changes.
[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 <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: 4/9/2012, referencing rEFInd 0.2.5</p>
18
19
20 <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>
21
22 <table border="1">
23 <tr>
24 <td>Donate $1.00</td>
25 <td>Donate $2.50</td>
26 <td>Donate $5.00</td>
27 <td>Donate $10.00</td>
28 <td>Donate another value</td>
29 </tr>
30 <tr>
31 <td><form name="_xclick" action="https://www.paypal.com/cgi-bin/webscr" method="post">
32 <input type="hidden" name="cmd" value="_xclick">
33 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
34 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
35 <input type="hidden" name="currency_code" value="USD">
36 <input type="hidden" name="amount" value="1.00">
37 <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!">
38 </form>
39
40 </td>
41 <td><form name="_xclick" action="https://www.paypal.com/cgi-bin/webscr" method="post">
42 <input type="hidden" name="cmd" value="_xclick">
43 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
44 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
45 <input type="hidden" name="currency_code" value="USD">
46 <input type="hidden" name="amount" value="2.50">
47 <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!">
48 </form>
49
50 </td>
51 <td><form name="_xclick" action="https://www.paypal.com/cgi-bin/webscr" method="post">
52 <input type="hidden" name="cmd" value="_xclick">
53 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
54 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
55 <input type="hidden" name="currency_code" value="USD">
56 <input type="hidden" name="amount" value="5.00">
57 <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!">
58 </form>
59
60 </td>
61 <td><form name="_xclick" action="https://www.paypal.com/cgi-bin/webscr" method="post">
62 <input type="hidden" name="cmd" value="_xclick">
63 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
64 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
65 <input type="hidden" name="currency_code" value="USD">
66 <input type="hidden" name="amount" value="10.00">
67 <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!">
68 </form>
69
70 </td>
71 <td>
72 <form action="https://www.paypal.com/cgi-bin/webscr" method="post">
73 <input type="hidden" name="cmd" value="_donations">
74 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
75 <input type="hidden" name="lc" value="US">
76 <input type="hidden" name="no_note" value="0">
77 <input type="hidden" name="currency_code" value="USD">
78 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
79 <input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
80 <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!">
81 <img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
82 </form>
83 </td></tr>
84 </table>
85
86 <hr />
87
88 <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>
89
90 <hr />
91
92 <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>
93
94 <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. Specifically, you can use a traditional Linux boot loader or configure an EFI stub loader.</p>
95
96 <h2>Using a Traditional Linux Boot Loader</h2>
97
98 <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 as EFI programs that are independent of the Linux kernel, but that 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>
99
100 <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>
101
102 <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>
103
104 <h2>Using the EFI Stub Loader</h2>
105
106 <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>
107
108 <p>With all versions of rEFInd, you can create manual boot loader stanzas
109 in the <tt>refind.conf</tt> file to identify a Linux kernel and to pass it
110 all the options it needs. This approach is effective and flexible, but it
111 requires editing a single configuration file for all the OSes you want to
112 define in this way. If a computer boots two different Linux distributions,
113 and if both were to support rEFInd, problems might arise as each one tries
114 to modify its own rEFInd configuration; or the one that controls rEFInd
115 might set inappropriate options for another distribution. This is a problem
116 that's been a minor annoyance for years under BIOS, since the same
117 potential for poor configuration applies to LILO, GRUB Legacy, and GRUB 2
118 on BIOS. The most reliable solution there is to chainload one boot loader
119 to another. The same solution is possible under EFI, but rEFInd offers
120 another possibility.</p>
121
122 <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>
123
124 <ol>
125
126 <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 (or other boot loader partition)!</li>
127
128 <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>
129
130 <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>
131
132 <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. For the moment, rEFInd still supports the <tt>linux.conf</tt> filename as a backup to <tt>refind_linux.conf</tt>, but <tt>linux.conf</tt> is now officially deprecated as a rEFInd configuration file, so you should rename your <tt>linux.conf</tt> file to <tt>refind_linux.conf</tt> if you're upgrading.</p>
133
134 <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>
135
136 </ol>
137
138 <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>
139
140 <p>As an example, consider the following file configuration:</p>
141
142 <pre class="listing">
143 $ <b>ls -l /boot/efi/EFI/ubuntu/</b>
144 total 17943
145 -rwxr-xr-x 1 root root 4781632 2012-03-18 12:01 bzImage-3.3.0.efi
146 -rwxr-xr-x 1 root root 131072 2011-10-14 04:10 grubx64.EFI
147 -rwxr-xr-x 1 root root 13459936 2012-03-18 12:02 initrd.img-3.3.0
148 -rwxr-xr-x 1 root root 266 2012-03-26 19:39 refind_linux.conf
149 </pre>
150
151 <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>
152
153 <pre class="listing">
154 "Boot with defaults" "root=/dev/sda3 ro quiet splash vt.handoff=7"
155 "Boot into single-user mode" "root=UUID=1cd95082-bce0-494c-a290-d2e642dd82b7 ro single"
156 "Boot without graphics" "root=UUID=1cd95082-bce0-494c-a290-d2e642dd82b7 ro"
157 # "Boot alternate install" "root=/dev/sdb9 ro quiet splash vt.handoff=7"
158 </pre>
159
160 <p>Ordinarily, both fields in this file must be enclosed in quotes. 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>
161
162 <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>
163
164 <br /><center><img src="automatic-submenu.png" align="center"
165 width="376" height="279" alt="rEFInd can load Linux boot options from
166 a refind_linux.conf file in the Linux kernel's directory."
167 border=2></center><br />
168
169 <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>
170
171 <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>
172
173 <ul>
174
175 <li>Your kernels must be compiled with EFI stub loader support.</li>
176
177 <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&mdash;that is, a single kernel. (rEFInd will still detect other boot loaders and provide separate main-menu tags for them, though.)</li>
178
179 <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>
180
181 <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>
182
183 <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>
184
185 </ul>
186
187 <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>
188
189 <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>
190
191 <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>
192
193 <hr/>
194
195 <p>copyright &copy; 2012 by Roderick W. Smith</p>
196
197 <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>
198
199 <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>
200
201 <p><a href="index.html">Go to the main rEFInd page</a></p>
202
203 <p><a href="revisions.html">Learn about rEFInd's history</a></p>
204
205 <p><a href="http://www.rodsbooks.com/">Return</a> to my main Web page.</p>
206 </body>
207 </html>