0.10.3 (?/??/2016):
-------------------
+- Tightened exclusion of shell binary filenames from boot loader scan.
+ Previously, any filename containing the substring "shell" was excluded
+ from scans. Now it's tighter; only files matching one of the filenames in
+ the constant SHELL_NAMES in main.c are excluded. This change will enable
+ programs with names that include "shell", but that aren't in rEFInd's
+ SHELL_NAMES list, such as "shelly.efi", to be shown in the rEFInd main
+ menu.
+
- Fixed bug in NTFS driver that caused it to hang (and thus hang the
computer) in some situations, particularly when a file on an NTFS volume
had many fragments and when the computer's CSM was activated. (Fix
Instead of searching for the string \fBrefind\fR in \fIefibootmgr\fR output
as a way to identify rEFInd, search for the string \fBname\fR.
+.SH "RETURN VALUES"
+
+\fIrefind-mkdefault\fR returns the following values:
+
+.TP
+.B 0
+The script completed successfully, which can mean either that no change was
+necessary or that the call to \fIefibootmgr\fR returned a success code.
+
+.TP
+.B 1
+EFI boot order variables are available, and a rEFInd entry was found, but
+the call to \fIefibootmgr\fR returned a failure code.
+
+.TP
+.B 2
+EFI boot entries are not available. This condition is often an indication of
+a buggy EFI or badly damaged NVRAM contents.
+
+.TP
+.B 3
+No rEFInd entry could be found in the list of boot options, and so
+no changes were made to the boot order list.
+
.SH "LIMITATIONS"
.TP
<p>Most EFIs provide their own build-in boot managers. These tools are primitive, and in some cases they can be difficult to reach, but they can be useful if you need to bypass a new system default in order to boot an OS that has the tools you need to control the boot process.</p>
-<p>On Macs, holding the Option key (or Alt with a PC keyboard) brings up the Mac's boot manager. Typically, the Esc key, Enter key, or a function key (usually F8 or above) does the job on UEFI-based PCs. Some computers provide a prompt for what key to use to access the boot menu, but this isn't always true. Sometimes the keyboard is disabled in the early stages of the boot process by default—part of a strategy to speed up system boots. Disabling a "fast start" feature in the firmware may work around this problem. Getting into the firmware can be a challenge on such computers, though. Microsoft provides a way to do this in Windows 8 and later; see <a href="https://support.lenovo.com/us/en/documents/ht081446">this Lenovo page</a> for documentation on how to use this feature. (The same procedure works on any brand of computer.)</p>
+<p>On Macs, holding the Option key (or Alt with a PC keyboard) brings up the Mac's boot manager. Typically, the Esc key, Enter key, or a function key (usually F8 or above) does the job on UEFI-based PCs. Some computers provide a prompt for what key to use to access the boot menu, but this isn't always true. Sometimes the keyboard is disabled in the early stages of the boot process by default—part of a strategy to speed up system boots. Disabling a "fast start" feature in the firmware may work around this problem. Getting into the firmware can be a challenge on such computers, though. Microsoft provides a way to do this in Windows 8 and later; see <a href="http://www.howtogeek.com/126016/three-ways-to-access-the-windows-8-boot-options-menu/">this How-To Geek article</a> for documentation on how to use this feature.</p>
<p>Once you've found the built-in boot manager, you'll see its display, which is typically a text-mode listing of boot options. On UEFI-based PCs, the user interface is typically similar to the one used in years past on BIOS-based computers to select the boot device; it's simply been upgraded to include the descriptions held in NVRAM for specific boot loaders. (In fact, prompts are often outdated and misleading; as in the below example, they may refer to "boot devices," when in fact most of the options are EFI boot loader programs, not hardware devices.) As an example, an ASUS P8 H77-I's boot manager looks like this:</p>
Boot0081* Mac OS X Vendor(99e275e7-75a0-4b37-a2e6-c5385e6c00cb,)-.o. .-.e.e. .-.f. .e.f.i.-.a.p.p.l.e.-.p.a.y.l.o.a.d.0.-.d.a.t.a...
Boot0085* ubuntu HD(1,800,113000,2491a00e-2a89-4dc4-af21-34c436c8f88a)File(EFI\Ubuntu\grubx64.efi)</pre>
-<p>Much of this output looks like gibberish, and is useful only for very advanced diagnostics. Note, however, the part of each line that specifies a filename, in parentheses after <tt>File</tt>—this information can help disambiguate a misleading or redundant name.</p>
+<p>Much of this output looks like gibberish, and is useful only for very advanced diagnostics. Note, however, the part of most lines that specifies a filename, in parentheses after <tt>File</tt>—this information can help disambiguate a misleading or redundant name.</p>
<p>To adjust the boot order, you must identify the rEFInd entry and then use the <tt>-o</tt> option to <tt>efibootmgr</tt> to adjust the order:</p>
</ol>
-<p class="sidebar"><b>Tip:</b> If you install the EFI shell in the <tt>EFI/tools/shell.efi</tt> or <tt>EFI/tools/shellx64.efi</tt> (on x86-64 systems; <tt>EFI/TOOLS/shellia32.efi</tt> on IA-32 systems) on your hard disk's ESP, rEFInd will detect it and enable you to boot it from rEFInd. If you also register the shell with the firmware's boot manager, you'll be able to launch it that way without using the USB flash drive.</p>
+<p class="sidebar"><b>Tip:</b> If you install the EFI shell as <tt>EFI/tools/shell.efi</tt> or <tt>EFI/tools/shellx64.efi</tt> (on x86-64 systems; <tt>EFI/TOOLS/shellia32.efi</tt> on IA-32 systems) on your hard disk's ESP, rEFInd will detect it and enable you to boot it from rEFInd. If you register the shell with the firmware's boot manager, you'll be able to launch it that way without using a USB flash drive.</p>
<p>With any luck, rEFInd will be restored as the default boot manager at this point. As with most of the methods described on this page, this procedure will do nothing to prevent future boot coups, so you may need to repeat the process in the future.</p>
<li><a href="refind-install.html"><tt>refind-install</tt></a>—This Linux and OS X script installs rEFInd with minimal fuss.</li>
+ <li><a href="refind-mkdefault.html"><tt>refind-mkdefault</tt></a>—This Linux script makes rEFInd the default boot program with minimal fuss.</li>
+
</ul></li>
</ul>
<p class="sidebar"><b>Note:</b> If you're using a Macintosh, it's best to install rEFInd from OS X, if possible. In the past, the Mac's firmware was quirky enough that the Linux tools didn't always work reliably. The matter seems to have improved with recent versions of Linux tools, but I can't guarantee success if you use Linux for this task. There is one significant issue with OS X 10.11, though (see the next Warning sidebar).</p>
-<p>If you're using Linux or Mac OS X, the easiest way to install rEFInd is to use the <tt>refind-install</tt> script. This script automatically copies rEFInd's files to your ESP or other target location and makes changes to your firmware's NVRAM settings so that rEFInd will start the next time you boot. If you've booted to OS X or in non-Secure-Boot EFI mode to Linux on a UEFI-based PC, <tt>refind-install</tt> will probably do the right thing, so you can get by with the quick instructions. If your setup is unusual, if your computer uses Secure Boot, or if you want to create a USB flash drive with rEFInd on it, you should read the <a href="#extra_installsh">extra instructions</a> for this utility.</p>
+<p>If you're using Linux or Mac OS X, the easiest way to install rEFInd is to use the <tt>refind-install</tt> script. This script automatically copies rEFInd's files to your ESP or other target location and makes changes to your firmware's NVRAM settings so that rEFInd will start the next time you boot. If you've booted to OS X or in non-Secure-Boot EFI mode to Linux on a UEFI-based PC, <tt>refind-install</tt> will probably do the right thing, so you can get by with the quick instructions. If your setup is unusual, if your computer uses Secure Boot, or if you want to create a USB flash drive with rEFInd on it, you should read the <a href="refind-install.html">man page</a> for this utility.</p>
<p class="sidebar"><b>Warning:</b> OS X 10.11 ("El Capitan") implements a new feature called System Integrity Protection (SIP; aka "rootless" or "CSR"). When enabled, SIP prevents the final step of rEFInd installation—registering the boot loader with the firmware. Thus, to install rEFInd, you must either disable SIP or perform the installation from something other than your regular OS X installation. The <a href="sip.html">rEFInd and System Integrity Protection</a> page of this document describes the options.</p>
:param label:
String used to identify rEFInd entry in efibootmgr output
:returns:
- True if order adjusted, False otherwise
+ * -1 if order already OK
+ * 0 if order adjusted
+ * 3 if label was not found in available entries
"""
first_refind_number = i = -1
- changed_order = False
+ retval = 0
found_first_refind = ""
show_multiple_warning = True
for entry in boot_order:
found_first_refind = entry
first_refind_number = i
if first_refind_number == -1:
- if add_unordered_entry(boot_entries, boot_order, label):
- changed_order = True
- else:
+ if not add_unordered_entry(boot_entries, boot_order, label):
print("{} was not found in the boot options list!".format(label))
print("You should create a {} entry with efibootmgr or by re-installing".format(label))
print("(with refind-install, for example)")
+ retval = 3
elif first_refind_number == 0:
print("{} is already the first entry".format(label))
+ retval = -1
elif first_refind_number > 0:
del boot_order[first_refind_number]
boot_order.insert(0, found_first_refind)
- changed_order = True
print("{} is not the first boot entry; adjusting....".format(label))
- return changed_order
+ return retval
def save_changes(boot_order):
:param boot_order:
List of boot numbers as strings, in boot order
:returns:
- True if there were no problems, False otherwise
+ 0 if there were no problems, 1 otherwise
"""
+ retval = 0
order_string = ",".join(boot_order)
command = "efibootmgr -o {}".format(order_string)
print("Setting a boot order of {}".format(order_string))
Popen(shlex.split(command), stdout=PIPE).communicate()[0]
except:
print("An error occurred setting the new boot order!")
+ retval = 1
+ return retval
def main():
print("This program must be run as root (or via sudo); exiting!")
return(1)
- problems = False
retval = 0
boot_entries, boot_order = discover_data()
if boot_entries == {}:
- problems = True
print("No EFI boot entries are available. This may indicate a firmware problem.")
+ retval = 2
if boot_order == []:
- problems = True
print("The EFI BootOrder variable is not available. This may indicate a firmware")
print("problem.")
- if (not problems and
- set_refind_first(boot_entries, boot_order, args.label)):
- save_changes(boot_order)
+ if (retval == 0):
+ changed = set_refind_first(boot_entries, boot_order, args.label)
+ if (changed == 0):
+ retval = save_changes(boot_order)
+ else:
+ print("No changes saved.")
+ if changed > 0:
+ retval = changed
else:
- if problems:
- retval = 1
print("No changes saved.")
return(retval)
MyStriCmp(Extension, L".icns") ||
MyStriCmp(Extension, L".png") ||
(MyStriCmp(DirEntry->FileName, FALLBACK_BASENAME) && (MyStriCmp(Path, L"EFI\\BOOT"))) ||
- StriSubCmp(L"shell", DirEntry->FileName) ||
+ FilenameIn(Volume, Path, DirEntry->FileName, SHELL_NAMES) ||
IsSymbolicLink(Volume, Path, DirEntry) || /* is symbolic link */
HasSignedCounterpart(Volume, Path, DirEntry->FileName) || /* a file with same name plus ".efi.signed" is present */
- FilenameIn(Volume, Path, DirEntry->FileName, GlobalConfig.DontScanFiles))
+ FilenameIn(Volume, Path, DirEntry->FileName, GlobalConfig.DontScanFiles)) {
continue; // skip this
+ }
if (Path)
SPrint(FileName, 255, L"\\%s\\%s", Path, DirEntry->FileName);