href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
<p>Originally written: 3/14/2012; last Web page update:
-7/26/2015, referencing rEFInd 0.9.0</p>
+11/1/2015, referencing rEFInd 0.9.3</p>
<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>
<td>a substring of a boot loader's title, or a numeric position; optionally followed by two times in <tt class="variable">HH:MM</tt> format</td>
<td>Sets the default boot OS based on the loader's title, which appears in the main menu beneath the icons when you select the loader. You can enter any substring of the title as the <tt>default_selection</tt>, so long as it's two or more characters in length. It's best to use a unique substring, since rEFInd stops searching when it finds the first match. Because rEFInd sorts entries within a directory in descending order by file modification time, if you specify a directory (or volume name, for loaders in a partition's root directory) as the <tt>default_selection</tt>, the newest loader in that directory will be the default. One-character entries are matched against the first character of the title, except for digits, which refer to the numeric order of the boot loader entries. If you specify a comma-delimited list of names <i><b>in quotation marks,</b></i> rEFInd will search on these in turn until it finds a match. For instance, <tt>default_selection "alpha,beta"</tt> will launch <tt>alpha</tt> if it's available, and <tt>beta</tt> if <tt>alpha</tt> is not available but <tt>beta</tt> is. If the <i>first</i> item in such a list is a plus sign (<tt>+</tt>), that refers to the item that rEFInd launched the last time it ran. You may optionally follow the match string by two times, in 24-hour format, in which case the entry applies only between those two times. For instance, <tt>default_selection Safety 1:30 2:30</tt> boots the entry called <tt>Safety</tt> by default between the hours of 1:30 and 2:30. These times are specified in whatever format the motherboard clock uses (local time or UTC). If the first value is larger than the second, as in <tt>23:00 1:00</tt>, it is interpreted as crossing midnight—11:00 PM to 1:00 AM in this example. The last <tt>default_selection</tt> setting takes precedence over preceding ones <i>if</i> the time value matches. Thus, you can set a main <tt>default_selection</tt> without a time specification and then set one or more others to override the main setting at specific times. If you do not specify a <tt>default_selection</tt>, rEFInd attempts to boot the previously-booted entry, or the first entry if there's no record of that or if the previously-booted entry can't be found.</td>
</tr>
+<tr>
+ <td><tt>enable_and_lock_vmx</tt></td>
+ <td>none or one of <tt>true</tt>, <tt>on</tt>, <tt>1</tt>, <tt>false</tt>, <tt>off</tt>, or <tt>0</tt></td>
+ <td>When set to <tt>true</tt> or a synonym, enable the CPU's VMX bit and lock the MSR. This configuration is necessary for some hypervisors (notably Microsoft's Hyper-V) to function properly. Activating it on other CPUs will, at best, have no effect, and could conceivably crash the computer, so enable it at your own risk! If your firmware supports activating these features, you should use it instead; this option is provided for users whose firmware does not provide this functionality. (Many Macs lack this configurability, for instance.) The default is <tt>false</tt>.</td>
+</tr>
+<tr>
+ <td><tt>spoof_osx_version</tt></td>
+ <td>string (<tt>10.9</tt> suggested)</td>
+ <td>On some Macs, this option causes rEFInd to tell the firmware that the specified version of OS X is being launched, even when another OS is selected. The effect is that the firmware may initialize hardware differently, which may have beneficial (or detrimental) results. If your Mac's video output isn't working normally, this option may help. On the other hand, keyboards and mice are known to sometimes stop functioning if this option is used, so you shouldn't use it unnecessarily. This option has no effect on non-Apple hardware. The default is to not use this feature.</td>
+</tr>
<tr>
<td><tt>include</tt></td>
<td>filename</td>
disabled
}
-menuentry Gentoo {
- icon \EFI\refind\icons\os_gentoo.icns
- volume G_KERNELS
- loader \kernels\bzImage-3.3.0-rc7
- initrd \kernels\initrd-3.3.0-rc7.img
+menuentry Arch {
+ icon /EFI/refind/icons/os_arch.png
+ volume ARCHBOOT
+ loader /vmlinuz-linux
+ initrd /initramfs-linux.img
options "root=/dev/sda3 ro"
}
menuentry "Windows via shell script" {
- icon \EFI\refind\icons\os_win.icns
+ icon \EFI\refind\icons\os_win.png
loader \EFI\tools\shell.efi
options "fs0:\EFI\tools\launch_windows.nsh"
}
</pre>
-<p>This example sets up three entries: one for Ubuntu Linux, one for Gentoo Linux, and one to launch a shell script. Note that the first two entries use different directory separators, simply to demonstrate the fact that it's possible. The Ubuntu entry sets no icon, since rEFInd will note that the boot loader is stored in the <tt>ubuntu</tt> directory, and it will automatically find the appropriate Ubuntu icon (<tt>os_ubuntu.icns</tt>). This option is, however, disabled, so no matching icon will appear when you reboot unless you first comment out or delete the <tt>disabled</tt> line.</p>
+<p>This example sets up three entries: one for Ubuntu Linux, one for Arch Linux, and one to launch a shell script. Note that the final entry uses different directory separators from the first two, simply to demonstrate the fact that it's possible. (The form of directory separators in <tt>options</tt> lines is important, though, because the program being launched may expect a particular directory separator character.) The Ubuntu entry sets no icon, since rEFInd will note that the boot loader is stored in the <tt>ubuntu</tt> directory, and it will automatically find the appropriate Ubuntu icon (<tt>os_ubuntu.png</tt>). This option is, however, disabled, so no matching icon will appear when you reboot unless you first comment out or delete the <tt>disabled</tt> line.</p>
<p class="sidebar"><b>Tip:</b> Under Linux, you can learn a filesystem's label by using <tt>blkid</tt>, as in <tt class="userinput">blkid /dev/sda1</tt>. The filesystem's label, if set, is identified by the keyword <tt>LABEL</tt> in the output. Some versions also return the partition's label and partition GUID (referred to as <tt>PARTUUID</tt> by <tt>blkid</tt>). You can obtain the partition's name and unique GUID using <tt>sgdisk</tt>, as in <tt class="userinput">sgdisk -i 1 /dev/sda</tt> to find the data on <tt>/dev/sda1</tt>.</p>
-<p>The Gentoo entry begins with an icon specification to be sure that the icon is loaded from the same volume as rEFInd. (If the icon were stored on the same filesystem as the kernel, you'd place the <tt>icon</tt> line after the <tt>volume</tt> line.) This entry uses the <tt>volume</tt> token to tell rEFInd to load the kernel and initial RAM disk file from the filesystem or partition called <tt>G_KERNELS</tt>. It passes the filename for an initial RAM disk using the <tt>initrd</tt> line and free-form options using the <tt>options</tt> line. Note that the kernel filename does <i>not</i> include a <tt>.efi</tt> extension, which keeps rEFInd from picking up the kernel file in its auto-scans.</p>
+<p>The Arch entry begins with an icon specification to be sure that the icon is loaded from the same volume as rEFInd. (If the icon were stored on the same filesystem as the kernel, you'd place the <tt>icon</tt> line after the <tt>volume</tt> line.) This entry uses the <tt>volume</tt> token to tell rEFInd to load the kernel and initial RAM disk file from the filesystem or partition called <tt>ARCHBOOT</tt>. It passes the filename for an initial RAM disk using the <tt>initrd</tt> line and free-form options using the <tt>options</tt> line.</p>
<p>The <tt>Windows via shell script</tt> entry may seem puzzling, but its purpose is to launch an OS (Windows in this case) after performing additional pre-boot initialization, which is handled by an EFI shell script. This works because you can pass the name of a shell script to an EFI shell—the script is named on the stanza's <tt>options</tt> line, using EFI file notation. The shell script, in turn, does whatever it needs to do and then launches the OS's boot loader:</p>
<pre class="listing">mm 0003003E 8 -pci
fs0:\EFI\Microsoft\Boot\bootmgfw.efi</pre>
-<p>This example writes data to the computer's PCI bus via the EFI shell's <tt>mm</tt> command and then launches Windows. Chances are you won't need to engage in such operations, and I do <i>not</i> recommend you try this exact example unless you know what you're doing! This command was required to activate the video hardware
on a computer of a person with whom I corresponded prior to booting Windows, but such needs are rare. Another example of a similar approach can be found in <a href="http://forum.techinferno.com/diy-e-gpu-projects/printfriendly2367.htm">this forum thread.</a> A few pointers on finding addresses for your hardware can be found <a href="http://forum.techinferno.com/diy-e-gpu-projects/2367-macbook-pro-retina-15-gtx-560-ti-%40-th05-8.html#post36199">in this post.</a></p>
+<p>This example writes data to the computer's PCI bus via the EFI shell's <tt>mm</tt> command and then launches Windows. Chances are you won't need to engage in such operations, and I do <i>not</i> recommend you try this exact example unless you know what you're doing! This command was required to activate the video hardware
prior to booting Windows on a computer of a person with whom I corresponded, but such needs are rare. (Using the <tt>spoof_osx_version</tt> option in rEFInd 0.9.3 and later may also help with some such problems, at least on Macs.) Another example of a similar approach can be found in <a href="http://forum.techinferno.com/diy-e-gpu-projects/printfriendly2367.htm">this forum thread.</a> A few pointers on finding addresses for your hardware can be found <a href="http://forum.techinferno.com/diy-e-gpu-projects/2367-macbook-pro-retina-15-gtx-560-ti-%40-th05-8.html#post36199">in this post.</a></p>
-<p>You can combine these OS stanzas with the global <tt>refind.conf</tt> options presented earlier. The result would contain just two entries on the rEFInd boot menu (for Gentoo and Windows, since the Ubuntu entry is disabled), unless rEFInd found other boot options on an external or optical disk.</p>
+<p>You can combine these OS stanzas with the global <tt>refind.conf</tt> options presented earlier. The result would contain just two entries on the rEFInd boot menu (for Arch and Windows, since the Ubuntu entry is disabled), unless rEFInd found other boot options on an external or optical disk.</p>
<a name="submenu">
<h2>Creating Submenu Entries</h2>
</a>
-<p>As described on the <a href="using.html">Using rEFInd</a> page, rEFInd can present a menu of options for certain loader tags when you press the Insert, F2, or + key. rEFInd does this automatically when it detects Mac OS X or ELILO boot loaders, or when you set the OS type via the <tt>ostype</tt> option. The Mac OS X boot loader, in particular, accepts various options that you can use to boot in various ways.</p>
+<p>As described on the <a href="using.html">Using rEFInd</a> page, rEFInd can present a menu of options for certain loader tags when you press the Insert, F2, or + key. rEFInd does this automatically when it detects Mac OS X or ELILO boot loaders, when you set the OS type via the <tt>ostype</tt> option, or when booting a Linux kernel directly. The Mac OS X boot loader, in particular, accepts various options that you can use to boot in various ways.</p>
-<p>Sometimes, you might want to create your own custom submenu entries, and rEFInd
0.2.1 and later enable you to do this. To create a custom submenu, you use the <tt>submenuentry</tt> keyword <i>inside</i> a <tt>menuentry</tt> stanza. Normally, you'll set the submenu definitions <i>after</i> you've set the main menu options, since the submenu options take the main menu options as defult, and so the main options must be set first. Like a <tt>menuentry</tt> stanza, a <tt>submenuentry</tt> definition begins with the keyword, the name of the item, and an open curly brace (<tt>{</tt>). It continues until a close curly brace (<tt>}</tt>). A submenu definition can use the keywords described in <a href="#table3">Table 3.</a> Except as otherwise noted, using an option of a given name completely overrides the setting in the main stanza.</p>
+<p>Sometimes, you might want to create your own custom submenu entries, and rEFInd
enables you to do this. To create a custom submenu, you use the <tt>submenuentry</tt> keyword <i>inside</i> a <tt>menuentry</tt> stanza. Normally, you'll set the submenu definitions <i>after</i> you've set the main menu options, since the submenu options take the main menu options as defult, and so the main options must be set first. Like a <tt>menuentry</tt> stanza, a <tt>submenuentry</tt> definition begins with the keyword, the name of the item, and an open curly brace (<tt>{</tt>). It continues until a close curly brace (<tt>}</tt>). A submenu definition can use the keywords described in <a href="#table3">Table 3.</a> Except as otherwise noted, using an option of a given name completely overrides the setting in the main stanza.</p>
<table border="1" cellpadding="1" cellspacing="2" summary="Table 3: Submenu keywords in <tt>refind.conf</tt>"><a name="table3"><caption><b>Table 3: Submenu keywords in <tt>refind.conf</tt></b></caption></a>
<tr>
<p>The following menu entry illustrates the use of submenu entries. This is a variant of the second entry presented earlier:</p>
<pre class="listing">
-menuentry Gentoo {
- loader \EFI\linux\bzImage-3.3.0-rc7
- initrd \EFI\linux\initrd-3.3.0-rc7.img
+menuentry Arch {
+ icon /EFI/refind/icons/os_arch.png
+ loader /vmlinuz-linux
+ initrd /initramfs-linux.img
options "root=/dev/sda3 ro"
- icon \EFI\refind\icons\os_gentoo.icns
submenuentry "single-user mode" {
add_options "single"
}
- submenuentry "3.3.0 final release kernel" {
- loader \EFI\linux\bzImage-3.3.0
- initrd \EFI\linux\initrd-3.3.0.img
+ submenuentry "Use fallback initrd" {
+ initrd /initramfs-linux-fallback.img
}
- submenuentry "boot via ELILO" {
- loader \EFI\elilo\elilo.efi
+ submenuentry "boot via SYSLINUX" {
+ loader \EFI\syslinux\syslinux.efi
initrd
options
}
<p>The main menu item for this entry won't look different with the submenus defined than without them; but if you press the F2 or Insert key, you'll see the submenu items:</p>
- <br /><center><img src="manual-submenu.png" align="center" width="403"
- height="411" alt="Manually defining submenus enables you to customize
+ <br /><center><img src="manual-submenu.png" align="center" width="406"
+ height="214" alt="Manually defining submenus enables you to customize
your boot options." border=2></center><br />
-<p>The main menu item appears at the top of the list—<tt>Run bzImage-3.3.0-rc7</tt> in this example. The three submenus defined in this example's configuration file appear next, enabling you to launch in single-user mode, run the 3.3.0 release kernel, or boot via ELILO, respectively. Submenus also include an item called <tt>Return to Main Menu</tt> that does just as it says. (Alternatively, you can return to the main menu by pressing the Esc key.)</p>
+<p>The main menu item appears at the top of the list—<tt>Boot using default options</tt>. The three submenus defined in this example's configuration file appear next, enabling you to launch in single-user mode, boot the standard kernel with the fallback initrd file, or boot via SYSLINUX, respectively. Submenus also include an item called <tt>Return to Main Menu</tt> that does just as it says. (Alternatively, you can return to the main menu by pressing the Esc key.)</p>
<p>This example illustrates some of the things you can do with submenu entries:</p>
<li>You can add kernel options when booting via the EFI stub loader—to launch single-user mode, to add graphical boot options, or what have you.</li>
+<li>You can remove options. Note the empty <tt>initrd</tt> and <tt>options</tt> lines in the SYSLINUX entry, for example; these empty lines override the default entries, which are carried over to submenu entries by default.</li>
+
<li>You can change kernel options when booting via the EFI stub loader—to <i>remove</i> graphical boot options, to boot to a different root device, and so on.</li>
<li>You can change your kernel and/or initial RAM disk when booting via the EFI stub loader.</li>
-<li>You can give users a choice of boot loaders. In this example, the main option boots via the kernel stub loader, but the submenu gives users the chance to boot via ELILO instead. In fact, you could even boot two entirely different OSes from manually-defined submenu entries, although that could be confusing.</li>
+<li>You can give users a choice of boot loaders. In this example, the main option boots via the kernel stub loader, but the submenu gives users the chance to boot via SYSLINUX instead. In fact, you could even boot two entirely different OSes from manually-defined submenu entries, although that could be confusing.</li>
</ul>