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>
+4/24/2016, referencing rEFInd 0.10.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>
<input type="hidden" name="amount" value="1.00">
<input type="hidden" name="item_name" value="rEFInd Boot Manager">
<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
-<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!">
-<img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
+<input type="image" src="donate.png" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
</form>
</td>
<input type="hidden" name="amount" value="2.50">
<input type="hidden" name="item_name" value="rEFInd Boot Manager">
<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
-<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!">
-<img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
+<input type="image" src="donate.png" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
</form>
</td>
<input type="hidden" name="amount" value="5.00">
<input type="hidden" name="item_name" value="rEFInd Boot Manager">
<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
-<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!">
-<img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
+<input type="image" src="donate.png" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
</form>
</td>
<input type="hidden" name="amount" value="10.00">
<input type="hidden" name="item_name" value="rEFInd Boot Manager">
<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
-<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!">
-<img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
+<input type="image" src="donate.png" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
</form>
</td>
<input type="hidden" name="amount" value="20.00">
<input type="hidden" name="item_name" value="rEFInd Boot Manager">
<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
-<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!">
-<img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
+<input type="image" src="donate.png" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
</form>
</td>
<input type="hidden" name="currency_code" value="USD">
<input type="hidden" name="item_name" value="rEFInd Boot Manager">
<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
-<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!">
-<img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
+<input type="image" src="donate.png" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
</form>
</td></tr>
</table>
<div style="float:right; width:55%">
-<p>Many casual users will be able to use rEFInd without making changes to its settings; in its default configuration, the boot manager automatically detects all the EFI boot loader programs you have on your EFI System Partition (ESP) (or your OS X boot partition, in the case of Macs) and displays icons for them. On Macs, rEFInd also presents legacy BIOS boot options by default. Sometimes, though, you may want to tweak rEFInd's configuration. Sometimes you can obtain your desired results by adjusting the filenames of your boot loaders. Other times, you can edit rEFInd's configuration file, <tt>refind.conf</tt>, which resides in the same directory as its binary file (<tt>refind_x64.efi</tt> or whatever you've renamed it).</p>
+<p>Many casual users will be able to use rEFInd without making changes to its settings; in its default configuration, the boot manager automatically detects all the EFI boot loader programs you have on your EFI System Partition (ESP) (or your OS X boot partition, in the case of Macs) in conventional locations and displays icons for them. On Macs, rEFInd also presents legacy BIOS boot options by default. Sometimes, though, you may want to tweak rEFInd's configuration. Sometimes you can obtain your desired results by adjusting the filenames of your boot loaders. Other times, you can edit rEFInd's configuration file, <tt>refind.conf</tt>, which resides in the same directory as its binary file (<tt>refind_x64.efi</tt> or whatever you've renamed it).</p>
</div>
<h2>Adjusting the Global Configuration</h2>
</a>
-<p>You can adjust many of rEFInd's options by editing its configuration file. This file is called <tt>refind.conf</tt> by default; but you can use another filename by passing <tt>-c <tt class="variable">filename</tt></tt> as an option, as in <tt>refind_x64.efi -c myrefind.conf</tt> to use <tt>myrefind.conf</tt> in rEFInd's main directory. You can specify a configuration file in another directory, but to do so, you <i>must</i> use backslashes as directory separators, as in <tt>-c \EFI\other\refind.conf</tt>. This feature is intended for users who want to have rEFInd appear in its own menu, with the version launched in this way behaving differently from the original—for instance, to have a secondary rEFInd that provides boot options hidden by the main one. In this scenario, the default <tt>refind.conf</tt> would have a <a href="#stanzas">manual boot stanza</a> defining the new rEFInd instance, including its <tt>-c</tt> option.</p>
+<p class="sidebar">You can tell rEFInd to use any configuration filename by passing <tt>-c <tt class="variable">filename</tt></tt> as an option, as in <tt>refind_x64.efi -c myrefind.conf</tt> to use <tt>myrefind.conf</tt> in rEFInd's main directory. You can specify a configuration file in another directory, but to do so, you <i>must</i> use backslashes as directory separators, as in <tt>-c \EFI\other\refind.conf</tt>. This feature is intended for users who want to have rEFInd appear in its own menu, with the version launched in this way behaving differently from the original—for instance, to have a secondary rEFInd that provides boot options hidden by the main one. In this scenario, the default <tt>refind.conf</tt> would have a <a href="#stanzas">manual boot stanza</a> defining the new rEFInd instance, including its <tt>-c</tt> option.</p>
+
+<p>You can adjust many of rEFInd's options by editing its configuration file, which is called <tt>refind.conf</tt>. You must first find this file, though. It is located in the rEFInd directory. On a UEFI-based PC, this directory will be located on the <a href="http://en.wikipedia.org/wiki/EFI_System_partition">EFI System Partition (ESP),</a> which can be in any number of places:</p>
+
+<ul>
+
+<li>Under Linux, the ESP is usually mounted at <tt>/boot/efi</tt>, although some users, particularly in Arch and Gentoo, prefer to mount the ESP at <tt>/boot</tt>.</li>
+
+<li>Under OS X, the ESP is not mounted by default, so you must mount it yourself to access it. Since 0.9.3, rEFInd has provided a script called <tt>mountesp</tt>, which locates and mounts the ESP. Open a Terminal and type <tt class="userinput">sudo mountesp</tt> to mount the ESP. The program should tell you where it's mounted the ESP. It will remain mounted until you manually unmount it or until you reboot.</li>
+
+<li>Under Windows, the ESP is not mounted by default. You can do so manually by opening an Administrator Command Prompt window and typing <tt class="userinput">mountvol S: /S</tt> to mount it at <tt>S:</tt>. (You can change the drive letter if you like.) Note that you will be able to access the ESP only from this Administrator Command Prompt window.</li>
+
+</ul>
+
+<p>As a further twist, on Macs rEFInd can exist on its own partition or on the main OS X partition, depending on the version of rEFInd you've installed and the options you passed to the installation script. rEFInd has installed to the ESP by default since version 0.8.4. rEFInd typically lives on the ESP in the <tt>EFI/refind</tt> directory, or sometimes in <tt>EFI/BOOT</tt> or elsewhere. Thus, the rEFInd configuration file might be <tt>/boot/efi/EFI/refind/refind.conf</tt>, <tt>/boot/EFI/BOOT/refind.conf</tt>, <tt>/Volumes/ESP/EFI/refind/refind.conf</tt>, <tt>S:\EFI\refind\refind.conf</tt>, or something else, depending on your OS and mount point.</p>
<p>You can use any text editor you like to edit <tt>refind.conf</tt>, but be sure it saves the file in plain ASCII text, not in a word processing format. (In theory, a UTF-16 encoding should also work, but this has been poorly tested.) Note that the EFI shell includes its own editor. If you need to make a change before you launch an OS, you can launch a shell, change to the rEFInd directory, and type <b><tt>edit refind.conf</tt></b> to edit the file. This EFI editor is quite primitive, but it gets the job done. After editing, you'll need to reboot or re-launch rEFInd for rEFInd to read the changed configuration file.</p>
</tr>
<tr>
<td><tt>showtools</tt></td>
- <td><tt>shell</tt>, <tt>memtest</tt>, <tt>gdisk</tt>, <tt>gptsync</tt>, <tt>apple_recovery</tt>, <tt>mok_tool</tt>, <tt>netboot</tt>, <tt>about</tt>, <tt>exit</tt>, <tt>shutdown</tt>, <tt>reboot</tt>, and <tt>firmware</tt></td>
- <td>Specifies which tool tags to display on the second row. <tt>shell</tt> launches an EFI shell, <tt>memtest</tt> (or <tt>memtest86</tt>) launches the <a href="http://www.memtest86.com/download.htm">Memtest86</a> program, <tt>gdisk</tt> launches the partitioning tool of the same name, <tt>gptsync</tt> launches a tool that creates a hybrid MBR, <tt>apple_recovery</tt> boots the OS X Recovery HD, <tt>
windows_recovery</tt> boots a Windows recovery tool, <tt>mok_tool</tt> launches a tool to manage Machine Owner Keys (MOKs) on systems with Secure Boot active, <tt>netboot</tt> launches the network boot tool (iPXE), <tt>about</tt> displays information about rEFInd, <tt>exit</tt> terminates rEFInd, <tt>shutdown</tt> shuts down the computer (or reboots it, on some UEFI PCs), <tt>reboot</tt> reboots the computer, and <tt>firmware</tt> reboots the computer into the computer's own setup utility. The tags appear in the order in which you specify them. The default is <tt>shell, memtest, gdisk, apple_recovery, mok_tool, about, shutdown, reboot, firmware</tt>. Note that the <tt>shell</tt>, <tt>memtest</tt>, <tt>apple_recovery</tt>, and <tt>mok_tool</tt> options all require the presence of programs not included with rEFInd. The <tt>gptsync</tt> option requires use of a like-named program which, although it ships with rEFInd 0.6.9 and later, is not installed by default except under OS X. See the <a href="installing.html#addons">"Installing Additional Components"</a> section of the <a href="installing.html">Installing rEFInd</a> page for pointers to the shell, Memtest86, and <tt>gptsync</tt> programs. The <tt>apple_recovery</tt> option will appear only if you've got an Apple Recovery HD partition (which has a boot loader called <tt>com.apple.recovery.boot/boot.efi</tt>). The <tt>firmware</tt> option works only on computers that support this option; on other computers, the option is quietly ignored. See the <a href="secureboot.html">Secure Boot</a> page for information on Secure Boot and MOK management.</td>
+ <td><tt>shell</tt>, <tt>memtest</tt>, <tt>gdisk</tt>, <tt>gptsync</tt>, <tt>apple_recovery</tt>, <tt>csr_rotate</tt>, <tt>mok_tool</tt>, <tt>fwupdate</tt>, <tt>netboot</tt>, <tt>about</tt>, <tt>exit</tt>, <tt>shutdown</tt>, <tt>reboot</tt>, and <tt>firmware</tt></td>
+ <td>Specifies which tool tags to display on the second row. <tt>shell</tt> launches an EFI shell, <tt>memtest</tt> (or <tt>memtest86</tt>) launches the <a href="http://www.memtest86.com/download.htm">Memtest86</a> program, <tt>gdisk</tt> launches the partitioning tool of the same name, <tt>gptsync</tt> launches a tool that creates a hybrid MBR, <tt>apple_recovery</tt> boots the OS X Recovery HD, <tt>
csr_rotate</tt> rotates through System Integrity Protection (SIP) values specified by <tt>csr_values</tt>, <tt>windows_recovery</tt> boots a Windows recovery tool, <tt>mok_tool</tt> launches a tool to manage Machine Owner Keys (MOKs) on systems with Secure Boot active, <tt>fwupdate</tt> launches a firmware-update tool, <tt>netboot</tt> launches the network boot tool (iPXE), <tt>about</tt> displays information about rEFInd, <tt>exit</tt> terminates rEFInd, <tt>shutdown</tt> shuts down the computer (or reboots it, on some UEFI PCs), <tt>reboot</tt> reboots the computer, and <tt>firmware</tt> reboots the computer into the computer's own setup utility. The tags appear in the order in which you specify them. The default is <tt>shell, memtest, gdisk, apple_recovery, mok_tool, about, shutdown, reboot, firmware</tt>. Note that the <tt>shell</tt>, <tt>memtest</tt>, <tt>apple_recovery</tt>, and <tt>mok_tool</tt> options all require the presence of programs not included with rEFInd. The <tt>gptsync</tt> option requires use of a like-named program which, although it ships with rEFInd 0.6.9 and later, is not installed by default except under OS X. See the <a href="installing.html#addons">"Installing Additional Components"</a> section of the <a href="installing.html">Installing rEFInd</a> page for pointers to the shell, Memtest86, and <tt>gptsync</tt> programs. The <tt>apple_recovery</tt> option will appear only if you've got an Apple Recovery HD partition (which has a boot loader called <tt>com.apple.recovery.boot/boot.efi</tt>). The <tt>firmware</tt> option works only on computers that support this option; on other computers, the option is quietly ignored. See the <a href="secureboot.html">Secure Boot</a> page for information on Secure Boot and MOK management.</td>
</tr>
<tr>
<td><tt>font</tt></td>
<td>one or two integer values</td>
<td>Sets the video resolution used by rEFInd; takes <i>either</i> a width and a height <i>or</i> a single UEFI video mode number as options. For instance, <tt>resolution 1024 768</tt> sets the resolution to 1024x768. On UEFI systems, <tt>resolution 1</tt> sets video mode 1, the resolution of which varies from system to system. If you set a resolution that doesn't work on a UEFI-based system, rEFInd displays a message along with a list of valid modes. On an system built around EFI 1.<i>x</i> (such as a Mac), setting an incorrect resolution fails silently; you'll get the system's default resolution. You'll also get the system's default resolution if you set both resolution values to <tt>0</tt> or if you pass anything but two numbers. (Note that passing a resolution with an <tt>x</tt>, as in <tt>1024x768</tt>, will be interpreted as <i>one</i> option and so will cause the default resolution to be used.) If you get a higher resolution than you request, try commenting out or changing the <tt>textmode</tt> value, since it can force the system to use a higher graphics resolution than you specify with <tt>resolution</tt>. Also, be aware that it is possible to set a valid resolution for your video card that's invalid for your monitor. If you do this, your monitor will go blank until you've booted an OS that resets the video mode.</td>
</tr>
+<tr>
+ <td><tt>enable_touch</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>Enables support for touch screens (as on tablets). Note that not all tablets provide the necessary support. If this feature is enabled and the tablet supports it, touching an OS or tool should launch it or enter a submenu. In a submenu, it is currently not possible to select a specific item; any touch will launch the default submenu option.</td>
+</tr>
<tr>
<td><tt>use_graphics_for</tt></td>
<td><tt>osx</tt>, <tt>linux</tt>, <tt>elilo</tt>, <tt>grub</tt>, and <tt>windows</tt></td>
<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>csr_values</tt></td>
+ <td>List of hexadecimal values</td>
+ <td>Specifies values that may be set via the <tt>csr_rotate</tt> tool for Apple's System Integrity Protection (SIP). SIP stores values in NVRAM to set restrictions on what users (even <tt>root</tt>) may do in OS X 10.11. If you want to be able to control these restrictions in rEFInd, you must set the values you want to use here <i>and</i> set <tt>csr_rotate</tt> on the <tt>showtools</tt> line (which must also be uncommented). Note that values are specified in hexadecimal, with no leading <tt>0x</tt> or other hexadecimal indicator. SIP is described in more detail on many Web sites, such as <a href="http://osxarena.com/2015/10/guide-details-apples-system-integrity-protection-sip-for-hackintosh/">here</a> and <a href="http://www.idelta.info/archives/sip-rootless-internal-in-el-capitan/">here.</a></td>
+</tr>
<tr>
<td><tt>include</tt></td>
<td>filename</td>
</tr>
</table>
-<p>Prior to version 0.2.4, rEFInd supported a token called <tt>disable</tt>, whose function partially overlapped with <tt>hideui</tt>. Version 0.2.4 merges many of the features of these two tokens into <tt>hideui</tt> and creates the new <tt>showtools</tt> option, which provides the remaining functionality in a more flexible way.</p>
-
<p>As an example of rEFInd configuration, consider the following <tt>refind.conf</tt> file:</p>
<pre class="listing">
<p>As an example, consider the following entries:</p>
<pre class="listing">
-menuentry "Ubuntu Linux" {
+menuentry "Ubuntu" {
loader /EFI/ubuntu/grubx64.efi
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, 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 entire entry 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>
<h2>Adjusting the Default Boot Option</h2>
</a>
-<p>Just before launching an OS, rEFInd stores the description in the EFI variable <tt>PreviousBoot</tt> with a GUID of 36d08fa7-cf0b-42f5-8f14-68df73ed3740. The next time it launches, it reads that same variable and sets the default boot loader to that value, if it's still available and if the first item in <tt>default_selection</tt> in the <tt>refind.conf</tt> file is a plus sign (<tt>+</tt>).</p>
+<p>Just before launching an OS, rEFInd stores the description in the EFI variable <tt>PreviousBoot</tt> with a GUID of 36d08fa7-cf0b-42f5-8f14-68df73ed3740. The next time rEFInd launches, it reads that same variable and sets the default boot loader to that value, if it's still available and if the first item in <tt>default_selection</tt> in the <tt>refind.conf</tt> file is a plus sign (<tt>+</tt>).</p>
<p>Under Linux, the variable that rEFInd uses to store this information is accessible as <tt>/sys/firmware/efi/efivars/PreviousBoot-36d08fa7-cf0b-42f5-8f14-68df73ed3740</tt>. Thus, you can back up this value, modify it, and write it back out to adjust your next-booted OS. Getting this string just right can be a bit tricky, though, and if the kernel doesn't like its format, it will not let you modify the variable. If you try to modify the variable, be aware that it's stored in UTF-16 format. As with the <tt>default_selection</tt> token in <tt>refind.conf</tt>, you can enter any substring that uniquely identifies the entry you want to boot.</p>
<hr />
-<p>copyright © 2012–2015 by Roderick W. Smith</p>
+<p>copyright © 2012–2016 by Roderick W. Smith</p>
<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>