href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
<p>Originally written: 3/14/2012; last Web page update:
-8/7/2013, referencing rEFInd 0.7.3</p>
+2/8/2015, referencing rEFInd 0.8.6</p>
-<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>
+<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>
<table border="1">
<tr>
<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 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) 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>
<li class="tight"><a href="#hiding">Hiding and Displaying EFI Boot Loaders</li>
+<li class="tight"><a href="#icons">Setting OS Icons</li>
+
<li class="tight"><a href="#adjusting">Adjusting the Global Configuration</a></li>
<li class="tight"><a href="#stanzas">Creating OS Stanzas</a></li>
<p>Another way to hide a boot loader is to move it into rEFInd's own directory. In order to keep rEFInd from showing up in its own menu, it ignores boot loaders in its own directory. This obviously includes the rEFInd binary file itself, but also anything else you might store there.</p>
-<p>In addition to hiding boot loaders, you can adjust their icons. You can do this in any of five ways for auto-detected boot loaders:</p>
+<p>You can also use the <tt>dont_scan_volumes</tt>, <tt>dont_scan_dirs</tt>, and <tt>dont_scan_files</tt> tokens in <tt>refind.conf</tt> to hide entire volumes, directories, and individual files, respectively. Note that <tt>dont_scan_volumes</tt> works with both EFI and legacy scans, whereas the other two options make sense for hiding only EFI-mode boot loaders.</p>
+
+<a name="icons">
+<h2>Setting OS Icons</h2>
+</a>
+
+<p>In addition to hiding boot loaders, you can adjust their icons. You can do this in any of seven ways for auto-detected boot loaders:</p>
<ul>
-<li>You can name an icon file after your boot loader, but with an extension of <tt>.icns</tt> or <tt>.png</tt> for ICNS-format and PNG-format icons, respectively. For instance, if you're using <tt class="variable">loader</tt><tt>.efi</tt>, you would name the icon file <tt class="variable">loader</tt><tt>.icns</tt>. (If you use the <tt>scan_all_linux_kernels</tt> option, you can give an icon for a Linux kernel without a <tt>.efi</tt> extension a name based on the kernel name but with a <tt>.icns</tt> or <tt>.png</tt> extension—for instance, <tt>bzImage-3.
6.9.png</tt> will serve as the icon for the <tt>bzImage-3.6.9</tt> kernel.) These icon files should be 128x128 images in <a href="http://en.wikipedia.org/wiki/Apple_Icon_Image_format">Apple's ICNS</a> or <a href="http://en.wikipedia.org/wiki/Portable_Network_Graphics">Portable Network Graphics (PNG)</a> format, depending on the filename extension.</li>
+<li>You can name an icon file after your boot loader, but with an extension of <tt>.icns</tt> or <tt>.png</tt> for ICNS-format and PNG-format icons, respectively. For instance, if you're using <tt class="variable">loader</tt><tt>.efi</tt>, you would name the icon file <tt class="variable">loader</tt><tt>.icns</tt>. (If you use the <tt>scan_all_linux_kernels</tt> option, you can give an icon for a Linux kernel without a <tt>.efi</tt> extension a name based on the kernel name but with a <tt>.icns</tt> or <tt>.png</tt> extension—for instance, <tt>bzImage-3.
13.6.png</tt> will serve as the icon for the <tt>bzImage-3.13.6</tt> kernel.) These icon files should be in <a href="http://en.wikipedia.org/wiki/Apple_Icon_Image_format">Apple's ICNS</a> or <a href="http://en.wikipedia.org/wiki/Portable_Network_Graphics">Portable Network Graphics (PNG)</a> format, depending on the filename extension.</li>
-<li>If you're booting OS X from its standard boot loader, or if you place a boot loader file for any OS in the root directory of a partition, you can create a file called <tt>.VolumeIcon.icns</tt> or <tt>.VolumeIcon.png</tt> that holds an icon file. OS X uses the <tt>.VolumeIcon.icns</tt> file for its volume icons, so rEFInd picks up these icons automatically, provided they include 128x128 bitmaps.</li>
+<li>If you're booting OS X from its standard boot loader, or if you place a boot loader file for any OS in the root directory of a partition, you can create a file called <tt>.VolumeIcon.icns</tt> or <tt>.VolumeIcon.png</tt> that holds an icon file. OS X uses the <tt>.VolumeIcon.icns</tt> file for its volume icons, so rEFInd picks up these icons automatically, provided they include appropriate bitmaps.</li>
<li>You can place a boot loader in a directory with a name that matches one of rEFInd's standard icons, which take names of the form <tt>os_<tt class="variable">name</tt>.icns</tt> or <tt>os_<tt class="variable">name</tt>.png</tt>. To use such an icon, you would place the boot loader in the directory called <tt class="variable">name</tt>.</li>
<li>You can give the filesystem from which the boot loader is loaded a name that matches the OS name component of the icon filename. For instance, if you call your boot filesystem <tt>CentOS</tt>, it matches the <tt>os_centos.icns</tt> icon. This match is performed on a word-by-word basis within the name, with "words" being delimited by spaces, dashes (<tt>-</tt>), and underscores (<tt>_</tt>). Thus, a volume called <tt>Debian-boot</tt> will match <tt>os_debian.icns</tt> or <tt>os_boot.icns</tt>.</li>
-<li>Certain boot loaders have hard-coded icons associated with them. For instance, filenames beginning with <tt>vmlinuz</tt> or <tt>bzImage</tt> acquire Linux "Tux" icons and the <tt>bootmgfw.efi</tt> loader acquires a Windows icon. For the most part, these are the associations you want to overcome with the preceding rules, but sometimes renaming a boot loader to a more conventional name is the better approach.</li>
+<li>You can give the GPT partition from which the boot loader is loaded a name that matches the OS name component of the icon filename. This works much like the previous method, except that you'd use a tool like <tt>gdisk</tt> or <tt>parted</tt> to set the partition's name, rather than <tt>tune2fs</tt> or GParted to set the filesystem's name.</li>
+
+<li>rEFInd attempts to guess the Linux distribution based on data in the <tt>/etc/os-release</tt> file. This file will only be accessible if a separate <tt>/boot</tt> partition is <i>not</i> used, though. Manually adjusting the <tt>os-release</tt> file to change an OS icon in rEFInd is <i>not</i> recommended.</li>
+
+<li>Certain boot loaders have hard-coded icons associated with them. For instance, filenames beginning with <tt>vmlinuz</tt> or <tt>bzImage</tt> acquire Linux "Tux" icon and the <tt>bootmgfw.efi</tt> loader acquires a Windows icon. Fedora and Red Hat kernels can be identified by the presence of <tt>.fc</tt> or <tt>.el</tt> strings in their filenames, and so acquire suitable icons automatically. For the most part, these are the associations you want to overcome with the preceding rules, but sometimes renaming a boot loader to a more conventional name is the better approach. Renaming a locally-compiled kernel so that it acquires a Fedora or Red Hat icon is reasonable, but I don't recommend renaming precompiled kernels unless you also manually copy them to the ESP.</li>
</ul>
<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. This icon file must include a 32x32 bitmap. 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>
<a name="adjusting">
<h2>Adjusting the Global Configuration</h2>
</a>
-<p>You can adjust many of rEFInd's options by editing its <tt>refind.conf</tt> file. You can use any text editor you like for the job, 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 I've not tried that myself.) 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 for rEFInd to read the changed configuration file.</p>
+<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>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>
<p>Global configuration file options consist of a name token followed by one or more parameters, as in:</p>
<tr>
<td><tt>timeout</tt></td>
<td>numeric value</td>
- <td>Sets the timeout period in seconds. If <tt>0</tt>, the timeout is disabled—rEFInd waits indefinitely for user input.</td>
+ <td>Sets the timeout period in seconds. If <tt>0</tt>, the timeout is disabled—rEFInd waits indefinitely for user input. If <tt>-1</tt>, rEFInd will normally boot immediately to the default selection; however, if a shortcut key (for instance, <tt>W</tt> for Windows) is pressed, that system will boot instead. If any other key is pressed, the menu will show with no timeout.</td>
</tr>
<tr>
<td><tt>screensaver</tt></td>
<td>numeric value</td>
- <td>Sets the number of seconds of inactivity before the screen blanks to prevent burn-in. The display returns after most keypresses (unfortunately, not including modifiers such as Shift, Control, Alt, or Option). The default is <tt>0</tt>, which disables this feature.</td>
+ <td>Sets the number of seconds of inactivity before the screen blanks to prevent burn-in. The display returns after most keypresses (unfortunately, not including modifiers such as Shift, Control, Alt, or Option). The default is <tt>0</tt>, which disables this feature. Setting this token to <tt>-1</tt> causes a blank display until the <tt>timeout</tt> value passes or you press a key.</td>
</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>
<td>directory name</td>
- <td>Specifies a directory in which custom icons may be found. This directory should contain files with the same names as the files in the standard <tt>icons</tt> directory. The directory name is specified relative to the directory in which the rEFInd binary resides. The standard <tt>icons</tt> directory is searched if an icon can't be found in the one specified by <tt>icons_dir</tt>, so you can use this location to redefine just some icons.</td>
+ <td>Specifies a directory in which custom icons may be found. This directory should contain files with the same names as the files in the standard <tt>icons</tt> directory. The directory name is specified relative to the directory in which the rEFInd binary resides. The standard <tt>icons</tt> directory is searched if an icon can't be found in the one specified by <tt>icons_dir</tt>, so you can use this location to redefine just some icons. Note that if no icons directory is found (either <tt>icons</tt> or one specified by <tt>icons_dir</tt>), rEFInd switches to text-only mode, as if <tt>textonly</tt> had been specified.</td>
</tr>
<tr>
<td><tt>banner</tt></td>
<td>filename</td>
<td>Specifies a custom banner file to replace the rEFInd banner image. The file should be a BMP or PNG image with a color depth of 24, 8, 4, or 1 bits. The file path is relative to the directory where the rEFInd binary is stored.</td>
</tr>
+<tr>
+ <td><tt>banner_scale</tt></td>
+ <td><tt>noscale</tt> or <tt>fillscreen</tt></td>
+ <td>Tells rEFInd whether to display banner images pixel-for-pixel (<tt>noscale</tt>) or to scale banner images to fill the screen (<tt>fillscreen</tt>). The former is the default.</td>
+</tr>
+<tr>
+ <td><tt>big_icon_size</tt></td>
+ <td>numeric value (at least <tt>32</tt>)</td>
+ <td>Sets the size of big icons (those used for OSes on the first row). All icons are square, so only one value is specified. If icon files don't contain images of the specified size, the available images are scaled to this size. The disk-type badge size is set indirectly by this token; badges are 1/4 the size of big icons. The default value is <tt>128<tt>.</td>
+</tr>
+<tr>
+ <td><tt>small_icon_size</tt></td>
+ <td>numeric value (at least <tt>32</tt>)</td>
+ <td>Sets the size of small icons (those used for tools on the second row). All icons are square, so only one value is specified. If icon files don't contain images of the specified size, the available images are scaled to this size. The default value is <tt>128<tt>.</td>
+</tr>
<tr>
<td><tt>selection_big</tt></td>
<td>filename</td>
</tr>
<tr>
<td><tt>showtools</tt></td>
- <td><tt>shell</tt>, <tt>gptsync</tt>, <tt>apple_recovery</tt>, <tt>mok_tool</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>
gptsync</tt> launches a tool that creates a hybrid MBR, <tt>apple_recovery</tt> boots the OS X Recovery HD, <tt>mok_tool</tt> launches a tool to manage Machine Owner Keys (MOKs) on systems with Secure Boot active, <tt>about</tt> displays information about the program, <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, apple_recovery, mok_tool, about, shutdown, reboot, firmware</tt>. Note that the <tt>shell</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 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>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>
</tr>
<tr>
<td><tt>font</tt></td>
</tr>
<tr>
<td><tt>textonly</tt></td>
- <td>none or <tt>0</tt></td>
- <td>rEFInd defaults to a graphical mode; however, if you prefer to do without the flashy graphics, you can run it in text mode by including this option. Passing any option but <tt>0</tt> causes text mode to be used; passing a <tt>0</tt> causes graphics mode to be used. (This could be useful if you want to override a text-mode setting in an included secondary configuration file.)</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>rEFInd defaults to a graphical mode; however, if you prefer to do without the flashy graphics, you can run it in text mode by including this option (alone or with <tt>true</tt>, <tt>on</tt>, or <tt>1</tt>). Passing <tt>false</tt>, <tt>off</tt>, or <tt>0</tt> causes graphics mode to be used. (This could be useful if you want to override a text-mode setting in an included secondary configuration file.) Text-only mode is implicitly set if rEFInd cannot find either a subdirectory called <tt>icons</tt> or a subdirectory named by <tt>icons_dir</tt>.</td>
</tr>
<tr>
<td><tt>textmode</tt></td>
<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>Ordinarily, rEFInd clears the screen and displays basic boot information when launching any OS but Mac OS X. For OS X, the default behavior is to clear the screen to the default background color and display no information. You can specify the simpler Mac-style behavior by specifying the OSes or boot loaders you want to work this way with this option. (OSes that should use text-mode displays should be omitted from this list.) Note that this option doesn't affect what the boot loader does; it may display graphics, text, or nothing at all. Thus, the effect of this option is likely to last for just a fraction of a second. On at least one firmware (used on some Gigabyte boards), setting <tt>use_graphics_for linux</tt> is required to avoid a system hang when launching Linux via its EFI stub loader.</td>
+ <td>Ordinarily, rEFInd clears the screen and displays basic boot information when launching any OS but Mac OS X. For OS X, the default behavior is to clear the screen to the default background color and display no information. You can specify the simpler Mac-style behavior by specifying the OSes or boot loaders you want to work this way with this option. (OSes that should use text-mode displays should be omitted from this list.) Note that this option doesn't affect what the boot loader does; it may display graphics, text, or nothing at all. Thus, the effect of this option is likely to last for just a fraction of a second. On at least one firmware (used on some Gigabyte boards), setting <tt>use_graphics_for linux</tt> is required to avoid a system hang when launching Linux via its EFI stub loader. To add to the default list, specify <tt>+</tt> as the first option, as in <tt>use_graphics_for + windows</tt>.</td>
</tr>
<tr>
<td><tt>scan_driver_dirs</tt></td>
</tr>
<tr>
<td><tt>scanfor</tt></td>
- <td><tt>internal</tt>, <tt>external</tt>, <tt>optical</tt>, <tt>hdbios</tt>, <tt>biosexternal</tt>, <tt>cd</tt>, and <tt>manual</tt></td>
- <td>Tells rEFInd what methods to use to locate boot loaders. The <tt>internal</tt>, <tt>external</tt>, and <tt>optical</tt> parameters tell rEFInd to scan for EFI boot loaders on internal, external, and optical (CD, DVD, and Blu-ray) devices, respectively. The <tt>hdbios</tt>, <tt>biosexternal</tt>, and <tt>cd</tt> parameters are similar, but scan for BIOS boot loaders. (Note that the BIOS options scan more thoroughly and actively on Macs than on UEFI-based PCs; for the latter, only options in the firmware's boot list are scanned, as described on the <a href="using.html">Using rEFInd</a> page.) The <tt>manual</tt> parameter tells rEFInd to scan the configuration file for manual settings. You can specify multiple parameters to have the program scan for multiple boot loader types. When you do so, the order determines the order in which the boot loaders appear in the menu. The default is <tt>internal, external, optical, manual</tt> on most systems, but <tt>internal, hdbios, external, biosexternal, optical, cd, manual</tt> on Macs.</td>
+ <td><tt>internal</tt>, <tt>external</tt>, <tt>optical</tt>, <tt>netboot</tt>, <tt>hdbios</tt>, <tt>biosexternal</tt>, <tt>cd</tt>, and <tt>manual</tt></td>
+ <td>Tells rEFInd what methods to use to locate boot loaders. The <tt>internal</tt>, <tt>external</tt>, and <tt>optical</tt> parameters tell rEFInd to scan for EFI boot loaders on internal, external, and optical (CD, DVD, and Blu-ray) devices, respectively. The <tt>netboot</tt> option relies on the presence of the <tt>ipxe.efi</tt> and <tt>ipxe_discover.efi</tt> program files in the <tt>EFI/tools</tt> directory to assist with network (Preboot Execution Environment, or PXE) booting. Note that <tt>netboot</tt> is experimental. See the <tt>BUILDING.txt</tt> file for information on building the necessary binaries. The <tt>hdbios</tt>, <tt>biosexternal</tt>, and <tt>cd</tt> parameters are similar, but scan for BIOS boot loaders. (Note that the BIOS options scan more thoroughly and actively on Macs than on UEFI-based PCs; for the latter, only options in the firmware's boot list are scanned, as described on the <a href="using.html">Using rEFInd</a> page.) The <tt>manual</tt> parameter tells rEFInd to scan the configuration file for manual settings. You can specify multiple parameters to have the program scan for multiple boot loader types. When you do so, the order determines the order in which the boot loaders appear in the menu. The default is <tt>internal, external, optical, manual</tt> on most systems, but <tt>internal, hdbios, external, biosexternal, optical, cd, manual</tt> on Macs.</td>
+</tr>
+<tr>
+ <td><tt>uefi_deep_legacy_scan</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>Tells rEFInd how aggressively to scan for BIOS/CSM/legacy boot loaders on UEFI-based PCs. Ordinarily or if this option is set to <tt>false</tt>, <tt>off</tt>, or <tt>0</tt>, rEFInd presents only those options that were available in the NVRAM when it launched. When uncommented with no option or with <tt>true</tt>, <tt>on</tt>, or <tt>1</tt> set, rEFInd adds every possible BIOS-mode boot device (of types specified by <tt>scanfor</tt>) as a BIOS/CSM/legacy boot option. This latter behavior is sometimes required to detect USB flash drives or hard disks beyond the first one.</td>
</tr>
<tr>
<td><tt>scan_delay</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.</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>
</tr>
<tr>
<td><tt>dont_scan_volumes</tt> or <tt>don't_scan_volumes</tt></td>
- <td>filesystem label(s)</td>
- <td>Adds the specified volume or volumes to a volume "blacklist"—these filesystems are <i>not</i> scanned for EFI boot loaders. This may be useful to keep unwanted EFI boot entries, such as for a Macintosh recovery partition, from appearing on the main list of boot loaders. The default value is <tt>Recovery HD</tt>, to keep the Mac recovery volume from appearing. (It should get its own tools icon instead—see the <tt>showtools</tt> token.)</td>
+ <td>filesystem or partition label(s)</td>
+ <td>Adds the specified volume or volumes to a volume "blacklist"—these filesystems are <i>not</i> scanned for EFI boot loaders. This may be useful to keep unwanted EFI boot entries, such as for a Macintosh recovery partition, from appearing on the main list of boot loaders. The default value is <tt>LRS_ESP</tt>, to keep the Lenovo Windows recovery volume from appearing. (This volume should get its own tools icon instead—see the <tt>showtools</tt> token.) You can use <tt>dont_scan_volumes</tt> to hide disks or partitions from legacy-mode scans, too. In this case, you can enter any part of the description that appears beneath the icons to hide entries that include the string you specify.</td>
</tr>
<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.</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>
</tr>
<tr>
<td><tt>dont_scan_files</tt> or <tt>don't_scan_files</tt></td>
<td>filename(s)</td>
- <td>Adds the specified filename or filenames to a filename "blacklist"—these files are <i>not</i> included as boot loader options even if they're found on the disk. This is useful to exclude support programs (such as <tt>shim.efi</tt> and <tt>MokManager.efi</tt>) and drivers from your OS list. The default value is <tt>shim.efi, shim-fedora.efi, PreLoader.efi, TextMode.efi, ebounce.efi, GraphicsConsole.efi, MokManager.efi, HashTool.efi, HashTool-signed.efi</tt>.</td>
+ <td>Adds the specified filename or filenames to a filename "blacklist"—these files are <i>not</i> included as boot loader options even if they're found on the disk. This is useful to exclude support programs (such as <tt>shim.efi</tt> and <tt>MokManager.efi</tt>) and drivers from your OS list. The default value is <tt>shim.efi, shim-fedora.efi, shimx64.efi, PreLoader.efi, TextMode.efi, ebounce.efi, GraphicsConsole.efi, MokManager.efi, HashTool.efi, HashTool-signed.efi</tt>. You can add a pathname and even a volume specification, as in <tt>ESP:/EFI/BOOT/backup.efi, /boot/vmlinuz-bad</tt>, to block the boot loaders only in those specified locations. To add files to the default list rather than replace the list, specify <tt>+</tt> as the first option, as in <tt>dont_scan_files + badloader.efi</tt>.</td>
+</tr>
+<tr>
+ <td><tt>windows_recovery_files</tt></td>
+ <td>filename(s)</td>
+ <td>Adds the specified filename or filenames to list that will be recognized as Windows recovery tools and presented as such on the second row, if <tt>windows_recovery</tt> is among the options to <tt>showtools</tt>. The filename must include a complete path and may optionally include a filesystem label, as in <tt>LRS_EFI:\EFI\Microsoft\Boot\LrsBootmgr.efi</tt>. Whatever you specify here is added to the <tt>dont_scan_files</tt> list. The default value is <tt>EFI\Microsoft\Boot\LrsBootmgr.efi</tt>. If you specify <tt>+</tt> as the first option, the following options will be added to the default rather than replace it.</td>
</tr>
<tr>
<td><tt>scan_all_linux_kernels</tt></td>
- <td>none or <tt>0</tt></td>
- <td>When set, 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. The hope is that this will simplify use of rEFInd on distributions that provide kernels with EFI stub loader support but that 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.) Note that this option can cause unwanted files to be improperly detected and given loader tags, such as older kernels without EFI stub loader support. Versions of rEFInd prior to 0.5.0 left this option commented out in the <tt>refind.conf-sample</tt> file, but 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 any option but <tt>0</tt> causes scans for all kernels to occur; passing a <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>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>
+</tr>
+<tr>
+ <td><tt>max_tags</tt></td>
+ <td>numeric (integer) value</td>
+ <td>Limits the number of tags that rEFInd will display at one time. If rEFInd discovers more loaders than this value, they're shown in a scrolling list. The default value is <tt>0</tt>, which imposes no limit.</td>
</tr>
<tr>
<td><tt>default_selection</tt></td>
- <td>a substring of a boot loader's title; or a numeric position</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 most recent 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.</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>include</tt></td>
<h2>Creating OS 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 configuration options to those that are auto-detected. You cannot modify the auto-detected options, though; if you just want to tweak one OS's configuration, you have several options, none of which is ideal:</p>
+<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>
<ul>
</tr>
<tr>
<td><tt>volume</tt></td>
- <td>filesystem label</td>
- <td>Sets the volume that's used for subsequent file accesses (by <tt>icon</tt> and <tt>loader</tt>, and by implication by <tt>initrd</tt> if <tt>loader</tt> follows <tt>volume</tt>). You pass this token a filesystem's label or a volume number. A filesystem label is typically displayed under the volume's icon in file managers and that rEFInd displays on its menu at the end of the boot prompt string. If this label isn't unique, the first volume with the specified label is used. The matching is nominally case-insensitive, but on some EFIs it's case-sensitive. If a filesystem has no label, you can use a volume number followed by a colon, such as <tt>0:</tt> to refer to the first filesystem or <tt>1:</tt> to refer to the second. The assignment of numbers is arbitrary and may not be consistent across boots, though. It might change if you insert an optical disc or plug in a USB flash drive, for instance. If this option is not set, the volume defaults to the one from which rEFInd launched.</td>
+ <td>filesystem label, partition label, GUID value, or filesystem number</td>
+ <td>Sets the volume that's used for subsequent file accesses (by <tt>icon</tt> and <tt>loader</tt>, and by implication by <tt>initrd</tt> if <tt>loader</tt> follows <tt>volume</tt>). You pass this token a filesystem's label, a partition's label, a partition's GUID, or a volume number. A filesystem or partition label is typically displayed under the volume's icon in file managers and rEFInd displays it on its menu at the end of the boot prompt string. If this label isn't unique, the first volume with the specified label is used. The matching is nominally case-insensitive, but on some EFIs it's case-sensitive. If a filesystem has no label, you can use a partition GUID number. You can also use a volume number followed by a colon, such as <tt>0:</tt> to refer to the first filesystem or <tt>1:</tt> to refer to the second. The assignment of numbers is arbitrary and may not be consistent across boots, though. It might change if you insert an optical disc or plug in a USB flash drive, for instance. If this option is not set, the volume defaults to the one from which rEFInd launched.</td>
</tr>
<tr>
<td><tt>loader</tt></td>
<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 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.</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 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 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 <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>
<hr />
-<p>copyright © 2012–2013 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>