<link href="../Styles/styles.css" rel="stylesheet" type="text/css" />
</head>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+
<body>
<h1>The rEFInd Boot Manager:<br />Configuring the Boot Manager</h1>
href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
<p>Originally written: 3/14/2012; last Web page update:
-12/8/2014, referencing rEFInd 0.8.4</p>
+7/21/2015, referencing rEFInd 0.9.0</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>
<li class="tight"><a href="#adjusting">Adjusting the Global Configuration</a></li>
-<li class="tight"><a href="#stanzas">Creating OS Stanzas</a></li>
+<li class="tight"><a href="#stanzas">Creating Manual Boot Stanzas</a></li>
<li class="tight"><a href="#submenu">Creating Submenu Entries</a></li>
<p>As a special case, rEFInd assigns icons to the Windows and OS X boot loaders based on their conventional locations, so they get suitable icons even if they don't follow these rules.</p>
-<p>In addition to the main OS tag icon, you can set the <i>badge</i> icon for a volume by creating a file called <tt>.VolumeBadge.icns</tt> or <tt>.VolumeBadge.png</tt> in the root directory of a partition. If present, it replaces the disk-type icons that are overlaid on the main OS icon. If you use this feature, the badge is applied to all the boot loaders read from the disk, not just those stored in the root directory or the Apple boot loader location. You could use this feature to set a custom badge for different specific disks or to help differentiate multiple OS X installations on one computer. If you don't want any badges, you can replace the three badge icons in the rEFInd <tt>icons</tt> subdirectory (<tt>vol_external.icns</tt>, <tt>vol_internal.icns</tt>, and <tt>vol_optical.icns</tt>) with a completely transparent badge. The <tt>transparent.icns</tt> file in the rEFInd <tt>icons</tt> directory may be used for this purpose.</p>
+<p>In addition to the main OS tag icon, you can set the <i>badge</i> icon for a volume by creating a file called <tt>.VolumeBadge.icns</tt> or <tt>.VolumeBadge.png</tt> in the root directory of a partition. If present, it replaces the disk-type icons that are overlaid on the main OS icon. If you use this feature, the badge is applied to all the boot loaders read from the disk, not just those stored in the root directory or the Apple boot loader location. You could use this feature to set a custom badge for different specific disks or to help differentiate multiple OS X installations on one computer. If you don't want any badges, you can add the <tt>badges</tt> option to <tt>hideui</tt> in <tt>refind.conf</tt>. Alternatively, or to hide just certain types of badges, you can replace the four badge icons in the rEFInd <tt>icons</tt> subdirectory (<tt>vol_external.png</tt>, <tt>vol_internal.png</tt>, <tt>vol_optical.png</tt>, and <tt>vol_net.png</tt>) with a completely transparent badge. The <tt>transparent.png</tt> file in the rEFInd <tt>icons</tt> directory may be used for this purpose.</p>
<p>The default icon sizes are 128x128 pixels for OS icons, 48x48 pixels for the second-row tools, and 32x32 pixels for badges. You can change the sizes of the big OS icons and the small tool icons with the <tt>big_icon_size</tt> and <tt>small_icon_size</tt> tokens in <tt>refind.conf</tt>, as noted in <a href="#table1">Table 1.</a> The size of the disk-type badges is 1/4 the size of OS icons.</p>
</tr>
<tr>
<td><tt>hideui</tt></td>
- <td><tt>banner</tt>, <tt>label</tt>, <tt>singleuser</tt>, <tt>safemode</tt>, <tt>hwtest</tt>, <tt>arrows</tt>, <tt>hints</tt>, <tt>editor</tt>, or <tt>all</tt></td>
- <td>Removes the specified user interface features. <tt>banner</tt> removes the banner graphic or background image, <tt>label</tt> removes the text description of each tag and the countdown timer, <tt>singleuser</tt> removes the single-user option from the OS X sub-menu, <tt>safemode</tt> removes the option to boot to safe mode from the OS X sub-menu, <tt>hwtest</tt> removes the Macintosh hardware test option, <tt>arrows</tt> removes the arrows to the right or left of the OS tags when rEFInd finds too many OSes to display simultaneously, <tt>hints</tt> removes the brief description of what basic keypresses do, <tt>editor</tt> disables the options editor, and <tt>all</tt> removes all of these options. You can specify multiple parameters with this option. The default is to set none of these values.</td>
+ <td><tt>banner</tt>, <tt>label</tt>, <tt>singleuser</tt>, <tt>safemode</tt>, <tt>hwtest</tt>, <tt>arrows</tt>, <tt>hints</tt>, <tt>editor</tt>, <tt>badges</tt>, or <tt>all</tt></td>
+ <td>Removes the specified user interface features. <tt>banner</tt> removes the banner graphic or background image, <tt>label</tt> removes the text description of each tag and the countdown timer, <tt>singleuser</tt> removes the single-user option from the OS X sub-menu, <tt>safemode</tt> removes the option to boot to safe mode from the OS X sub-menu, <tt>hwtest</tt> removes the Macintosh hardware test option, <tt>arrows</tt> removes the arrows to the right or left of the OS tags when rEFInd finds too many OSes to display simultaneously, <tt>hints</tt> removes the brief description of what basic keypresses do, <tt>editor</tt> disables the options editor, <tt>badges</tt> removes the device-type badges from the OS tags, and <tt>all</tt> removes all of these features. You can specify multiple parameters with this option. The default is to set none of these values.</td>
</tr>
<tr>
<td><tt>icons_dir</tt></td>
<tr>
<td><tt>also_scan_dirs</tt></td>
<td>directory path(s)</td>
- <td>Adds the specified directory or directories to the directory list that rEFInd scans for EFI boot loaders when <tt>scanfor</tt> includes the <tt>internal</tt>, <tt>external</tt>, or <tt>optical</tt> options. Directories are specified relative to the filesystem's root directory. You may precede a directory path with a volume name and colon, as in <tt>somevol:/extra/path</tt>, to restrict the extra scan to a single volume. A volume number, preceded by <tt>fs</tt>, can be used for volumes that lack names, as in <tt>fs1:/extra/path</tt>. If you don't specify a volume name or number, this option is applied to <i>all</i> the filesystems that rEFInd scans. If a specified directory doesn't exist, rEFInd ignores it (no error results). The default value is <tt>boot</tt>, which is useful for locating Linux kernels when you have an EFI driver for your Linux root (<tt>/</tt>) filesystem. To add to, rather than replace, the default value, specify <tt>+</tt> as the first item in the list, as in <tt>also_scan_dirs +,loaders</tt>.</td>
+ <td>Adds the specified directory or directories to the directory list that rEFInd scans for EFI boot loaders when <tt>scanfor</tt> includes the <tt>internal</tt>, <tt>external</tt>, or <tt>optical</tt> options. Directories are specified relative to the filesystem's root directory. You may precede a directory path with a volume name and colon, as in <tt>somevol:/extra/path</tt>, to restrict the extra scan to a single volume. A volume number, preceded by <tt>fs</tt>, can be used for volumes that lack names, as in <tt>fs1:/extra/path</tt>. (<i>This usage is deprecated.</i>) If you don't specify a volume name or number, this option is applied to <i>all</i> the filesystems that rEFInd scans. If a specified directory doesn't exist, rEFInd ignores it (no error results). The default value is <tt>boot</tt>, which is useful for locating Linux kernels when you have an EFI driver for your Linux root (<tt>/</tt>) filesystem. To add to, rather than replace, the default value, specify <tt>+</tt> as the first item in the list, as in <tt>also_scan_dirs +,loaders</tt>.</td>
</tr>
<tr>
<td><tt>dont_scan_volumes</tt> or <tt>don't_scan_volumes</tt></td>
<tr>
<td><tt>dont_scan_dirs</tt> or <tt>don't_scan_dirs</tt></td>
<td>directory path(s)</td>
- <td>Adds the specified directory or directories to a directory "blacklist"—these directories are <i>not</i> scanned for boot loaders. You may optionally precede a directory path with a volume name and a colon to limit the blacklist to that volume; otherwise all volumes are affected. For instance, <tt>EFI/BOOT</tt> prevents scanning the <tt>EFI/BOOT</tt> directory on <i>all</i> volumes, whereas <tt>ESP:EFI/BOOT</tt> blocks scans of <tt>EFI/BOOT</tt> on the volume called <tt>ESP</tt> but not on other volumes. You can use a filesystem number, as in <tt>fs0</tt>, in place of a volume name. This token may be useful to keep duplicate boot loaders out of the menu; or to keep drivers or utilities out of the boot menu, if you've stored them in a subdirectory of <tt>EFI</tt>. This option takes precedence over <tt>also_scan_dirs</tt>; if a directory appears in both lists, it will <i>not</i> be scanned. To add directories to the default list rather than replace the list, specify <tt>+</tt> as the first option, as in <tt>dont_scan_dirs + EFI/dontscan</tt>. The default for this token is <tt>EFI/tools, EFI/tools/memtest86, EFI/tools/memtest, EFI/memtest86, EFI/memtest, com.apple.recovery.boot</tt>.</td>
+ <td>Adds the specified directory or directories to a directory "blacklist"—these directories are <i>not</i> scanned for boot loaders. You may optionally precede a directory path with a volume name and a colon to limit the blacklist to that volume; otherwise all volumes are affected. For instance, <tt>EFI/BOOT</tt> prevents scanning the <tt>EFI/BOOT</tt> directory on <i>all</i> volumes, whereas <tt>ESP:EFI/BOOT</tt> blocks scans of <tt>EFI/BOOT</tt> on the volume called <tt>ESP</tt> but not on other volumes. You can use a filesystem number, as in <tt>fs0</tt>, in place of a volume name. (<i>The use of filesystem numbers is deprecated.</i>) This token may be useful to keep duplicate boot loaders out of the menu; or to keep drivers or utilities out of the boot menu, if you've stored them in a subdirectory of <tt>EFI</tt>. This option takes precedence over <tt>also_scan_dirs</tt>; if a directory appears in both lists, it will <i>not</i> be scanned. To add directories to the default list rather than replace the list, specify <tt>+</tt> as the first option, as in <tt>dont_scan_dirs + EFI/dontscan</tt>. The default for this token is <tt>EFI/tools, EFI/tools/memtest86, EFI/tools/memtest, EFI/memtest86, EFI/memtest, com.apple.recovery.boot</tt>.</td>
</tr>
<tr>
<td><tt>dont_scan_files</tt> or <tt>don't_scan_files</tt></td>
<tr>
<td><tt>scan_all_linux_kernels</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 uncommented or set to <tt>true</tt>, <tt>on</tt>, or <tt>1</tt>, causes rEFInd to add Linux kernels (files with names that begin with <tt>vmlinuz</tt> or <tt>bzImage</tt>) to the list of EFI boot loaders, even if they lack <tt>.efi</tt> filename extensions. This simplifies use of rEFInd on most Linux distributions, which usually provide kernels with EFI stub loader support but don't give those kernels names that end in <tt>.efi</tt>. Of course, the kernels must still be stored on a filesystem that rEFInd can read, and in a directory that it scans. (<a href="drivers.html">Drivers</a> and the <tt>also_scan_dirs</tt> options can help with those issues.) As of version 0.5.0, this option is enabled in the default configuration file. The program default remains to not scan for such kernels, though, so you can delete or uncomment this option to keep them from appearing in your boot menu. Passing <tt>false</tt>, <tt>off</tt>, or <tt>0</tt> causes these kernels to not be scanned. (This could be useful if you want to override a setting of <tt>scan_all_linux_kernels</tt> in an included secondary configuration file.)</td>
+ <td>When uncommented or set to <tt>true</tt>, <tt>on</tt>, or <tt>1</tt>, causes rEFInd to add Linux kernels (files with names that begin with <tt>vmlinuz</tt> or <tt>bzImage</tt>) to the list of EFI boot loaders, even if they lack <tt>.efi</tt> filename extensions. This simplifies use of rEFInd on most Linux distributions, which usually provide kernels with EFI stub loader support but don't give those kernels names that end in <tt>.efi</tt>. Of course, the kernels must still be stored on a filesystem that rEFInd can read, and in a directory that it scans. (<a href="drivers.html">Drivers</a> and the <tt>also_scan_dirs</tt> options can help with those issues.) As of version 0.8.3, this option is enabled by default; to disable this feature, you must uncomment this token and set it to <tt>false</tt> or one of its synonyms (<tt>off</tt> or <tt>0</tt>).</td>
+</tr>
+<tr>
+ <td><tt>fold_linux_kernels</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 uncommented or set to <tt>true</tt>, <tt>on</tt>, or <tt>1</tt>, causes rEFInd to "fold" all Linux kernels in a given directory into a single main-menu icon. Selecting that icon launches the most recent kernel. To launch an older kernel, you must press F2 or Insert; older kernels appear on the resulting submenu display. If you prefer to see all your kernels in the main menu, set this option to <tt>false</tt>, <tt>off</tt>, or <tt>0</tt>. Note that this option is new with version 0.9.0, which changes the default behavior; earlier versions of rEFInd behaved as if <tt>fold_linux_kernels false</tt> was set.</td>
</tr>
<tr>
<td><tt>max_tags</tt></td>
<p>This example sets a timeout of 5 seconds; loads a custom graphic file called <tt>custom.bmp</tt> from the directory in which the rEFInd binary resides; scans the <tt>drivers</tt> and <tt>EFI/tools/drivers</tt> directories for EFI drivers; uses manual boot loader configuration but also scans for external EFI boot loaders and EFI boot loaders on optical discs; and sets the default boot loader to the first loader found that includes the string <tt>elilo</tt>. Of course, since this file specifies use of manual boot loader configuration, it's not complete; you'll need to add at least one OS stanza to be able to boot from anything but an external disk or optical drive, as described shortly.</p>
<a name="stanzas">
-<h2>Creating OS Stanzas</h2>
+<h2>Creating Manual Boot Stanzas</h2>
</a>
-<p>OS stanzas in rEFInd are similar to those in GRUB Legacy, GRUB 2, or ELILO. You can use them to add EFI boot loaders to those that are auto-detected. rEFInd does not yet support manual boot stanzas for BIOS-mode boot loaders. You also cannot modify the auto-detected options; if you just want to tweak one OS's configuration, you have several options, none of which is ideal:</p>
+<p class="sidebar"><b>Note:</b> Don't create manual boot stanzas unless you need to do so! Many people try to create them when rEFInd's auto-detection mechanisms will do the job just as well and with less hassle and chance of error. (Note that you can pass kernel options to a Linux kernel in the <tt>/boot/refind_linux.conf</tt> file; see the <a href="linux.html">Methods of Booting Linux</a> page for details.) Efforts to create manual boot stanzas when auto-detection can do the job just create pointless work for yourself!</p>
+
+<p>Manual boot stanzas in rEFInd are similar to those in GRUB Legacy, GRUB 2, or ELILO. You can use them to add EFI boot loaders to those that are auto-detected. rEFInd does not yet support manual boot stanzas for BIOS-mode boot loaders. You also cannot modify the auto-detected options; if you just want to tweak one OS's configuration, you have several options:</p>
<ul>
+<li>You can use the <tt>dont_scan_volumes</tt>, <tt>dont_scan_dirs</tt>, or <tt>dont_scan_files</tt> options in <tt>refind.conf</tt> to hide the tag you want to modify, then create a manual boot stanza to replace it.</li>
+
<li>You can move or rename the boot loader file for the boot loader you want to tweak.</li>
<li>You can disable all auto-detection options and add manual configurations for all your boot loaders, even those that work fine when auto-detected.</li>
}
</pre>
-<p>The main menu item for this entry won't look different with the submenus defined than without them; but if you press the Insert key, you'll see the submenu items:</p>
+<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="372"
- height="272" alt="Manually defining submenus enables you to customize
+ <br /><center><img src="manual-submenu.png" align="center" width="403"
+ height="411" 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>
<hr />
-<p>copyright © 2012–2014 by Roderick W. Smith</p>
+<p>copyright © 2012–2015 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>