X-Git-Url: https://code.delx.au/refind/blobdiff_plain/4de918f70e9382d26cc9f2047a3c1fb1b7ca12a1..c1935b0f6d9272cfa51e9a6c1e342c252ea41b1f:/docs/refind/installing.html diff --git a/docs/refind/installing.html b/docs/refind/installing.html index c68268f..4fc7bb7 100644 --- a/docs/refind/installing.html +++ b/docs/refind/installing.html @@ -15,7 +15,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com

Originally written: 3/14/2012; last Web page update: -5/15/2012, referencing rEFInd 0.3.5

+12/5/2012, referencing rEFInd 0.5.0

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!

@@ -92,14 +92,18 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com

Important: A rEFInd zip file, when uncompressed, creates a directory called refind-version, where version is the version number. This directory includes a subdirectory called refind that holds the boot loader, along with another that holds documentation, as well as miscellaneous files in refind-version itself. When I refer to "the refind directory" on this page, I mean the directory with that precise name, not the refind-version directory that is its parent.

-

Once you've uncompressed a rEFInd binary zip file, you must install it to your computer's ESP (or conceivably to some other location). The details of how you do this depend on your OS and your computer (UEFI-based PC vs. Macintosh). The upcoming sections provide details. For Linux and Mac OS X, you can use the installation script, install.sh, which provides easy one-command installation on most systems. Occasionally this script will fail, though, so I also provide explicit instructions for Linux and Mac OS X. Installation under Windows also must be done manually. In some cases, you'll have to deviate from the default naming conventions, as described in a section on this topic. If you're upgrading rEFInd, see the section on upgrading. Finally, I describe how to install some additional components you might find useful.

+

Once you've uncompressed a rEFInd binary zip file, you must install it to your computer's ESP (or conceivably to some other location). The details of how you do this depend on your OS and your computer (UEFI-based PC vs. Macintosh). The upcoming sections provide details. For Linux and Mac OS X, you can use the installation script, install.sh, which provides easy one-command installation on most systems. Occasionally this script will fail, though, so I also provide explicit instructions for Linux and Mac OS X. Installation under Windows also must be done manually. In some cases, you'll have to deviate from the default naming conventions, as described in a section on this topic. If you're upgrading rEFInd, see the section on upgrading. Finally, I describe how to install some additional components you might find useful. Note that this page describes installing the main rEFInd program; if you want to use the EFI filesystem drivers included with rEFInd, you should consult the page on using drivers with rEFInd.

Installing rEFInd Using install.sh under Linux or Mac OS X

Warning: If you're using a Macintosh, you should run install.sh from Mac OS X rather than from Linux. If run from Linux, rEFInd is unlikely to be fully installed. Worse, it's conceivable that running install.sh from Linux will damage your firmware, requiring that it be re-flashed. The reason is that Apple uses non-standard methods to enable a boot loader, and the Linux functions in install.sh assume standard EFI installation methods.

-

If you're using Linux or Mac OS X, the easiest way to install rEFInd is to use the install.sh script. Under Linux, this script installs rEFInd to your disk's ESP. Under Mac OS X, the script installs rEFInd to your current OS X boot partition by default; but you can install to your ESP instead by passing the script the esp option.

+

If you're using Linux or Mac OS X, the easiest way to install rEFInd is to use the install.sh 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 EFI mode to Linux on a UEFI-based PC, install.sh will probably do the right thing, so you can get by with the quick instructions. If your setup is unusual, though, or if you want to create a USB flash drive with rEFInd on it, you should read the extra instructions for this utility.

+ +

Quick install.sh Instructions

+ +

Under Linux, the install.sh script installs rEFInd to your disk's ESP. Under Mac OS X, the script installs rEFInd to your current OS X boot partition by default; but you can install to your ESP instead by passing the script the --esp option.

Before running this script under Linux, you should ensure that your ESP is mounted at /boot or /boot/efi, as described in more detail in the Installing rEFInd Manually Using Linux section. (If you installed Linux in EFI mode, chances are your ESP is properly mounted.) This precaution isn't necessary under OS X.

@@ -138,7 +142,13 @@ on some systems!! Installation has completed successfully. -

In either case, the details of the output differ depending on your existing configuration and how you ran the program. Some details that can affect how the script runs include the following:

+

In either case, the details of the output differ depending on your existing configuration and how you ran the program. Unless you see an obvious warning or error, you shouldn't be concerned about minor deviations from these examples. If you run into such a situation, or if you want to install in an unusual way, read on....

+ + +

Extra install.sh Instructions

+ + +

Some details that can affect how the script runs include the following:

In any event, you should peruse the script's output to ensure that everything looks OK. install.sh displays error messages when it encounters errors, such as if the ESP is mounted read-only or if you run out of disk space. You may need to correct such problems manually and re-run the script. In some cases you may need to fall back on manual installation, which gives you better control over details such as which partition to use for installation.

@@ -198,16 +247,20 @@ Filesystem 1K-blocks Used Available Use% Mounted on
    -
  1. Type cp -r refind /boot/efi/EFI/ from the refind-version directory in which the refind directory exists. This copies all the files that rEFInd needs to work.
    2. +
  2. Type cp -r refind /boot/efi/EFI/ from the refind-version directory in which the refind directory exists. This copies all the files that rEFInd needs to work. Note that this includes all of rEFInd's drivers.
  3. Type cd /boot/efi/EFI/refind to change into rEFInd's new directory on the ESP.
  4. Type rm refind_ia32.efi to remove the IA32 binary if you're using an x86-64 (64-bit) system; or type rm refind_x64.efi to remove the x86-64 binary if you're using an x86 (32-bit) system. You can optionally rename the binary you keep as refind.efi, but this isn't required. (Note that you must keep the version that's the correct bit width for your EFI; if you've installed a 32-bit Linux on a 64-bit PC with a 64-bit EFI, you'd keep refind_x64.efi.
    5. +
  5. Optionally, type rm -r drivers_ia32 to remove the x86 drivers from an x86-64 system, or rm -r drivers_x64 to remove the x86-64 drivers from a 32-bit x86 system. You may also want to remove some or all of the drivers for the architecture you are using; if you don't need them, they'll slow down the start process. See the page on drivers for more on this topic.
    6. +
  6. Rename the configuration file by typing mv refind.conf-sample refind.conf. Consult the Editing the rEFInd Configuration File page for information on how to adjust your options.
    7. +

    Weird: A bug exists in some Lenovo computers (and perhaps in some others, too) that causes the firmware's boot manager to refuse to boot any boot loader that doesn't have the name Windows Boot Manager or Red Hat Enterprise Linux. If you have such a system, you must pass one of those names (in quotes) rather than rEFInd to efibootmgr via its -L option. This bug was reported to Lenovo in mid-November 2012, so with any luck updated firmware without this bug will be available later this year or early in 2013. I can make no promises about this, though.

    + -
  7. On a UEFI-based system, type efibootmgr -c -l \\EFI\\refind\\refind_x64.efi -L rEFInd to add rEFInd to your EFI's list of available boot loaders, which it stores in NVRAM. (Adjust the path to the binary as required if you install somewhere else.) You may need to install this program on some systems; it's a standard part of most distributions' repositories.
    8. +
  8. On a UEFI-based system, type efibootmgr -c -l \\EFI\\refind\\refind_x64.efi -L rEFInd to add rEFInd to your EFI's list of available boot loaders, which it stores in NVRAM. Adjust the path to the binary as required if you install somewhere else. You may also need to include additional options if your ESP isn't on /dev/sda1 or if your configuration is otherwise unusual; consult the efibootmgr man page for details. You may need to install this program on some systems; it's a standard part of most distributions' repositories.
    9.
  9. If other boot loaders are already installed, you can use efibootmgr to adjust their boot order. For instance, efibootmgr -o 3,7,2 sets the firmware to try boot loader #3 first, followed by #7, followed by #2. (The program should have displayed a list of boot loaders when you added yours in the preceding step.) Place rEFInd's number first to set it as the default boot program.
    10. @@ -268,6 +321,15 @@ $ ioreg -l -p IODeviceTree | grep firmware-abi 64-bit EFI or sudo rm /efi/refind/refind_x64.efi on a Mac with a 32-bit EFI. +
  10. Optionally, remove the drivers directory for the architecture you're + not using—/efi/refind/drivers_ia32 or + /efi/refind/drivers_x64, as appropriate. You may also want to + remove some or all of the drivers for the architecture you are using; + if you don't need them, they'll slow down the start process. See the page on drivers for more on this topic. Note + that Apple's firmware includes its own HFS+ driver, so the HFS+ driver + provided with rEFInd is useless on Macs.
    11. +
  11. If this is your first installation, type sudo mv /efi/refind/refind.conf-sample /efi/refind/refind.conf (adjusting the path as necessary) to rename the sample configuration @@ -292,6 +354,12 @@ $ ioreg -l -p IODeviceTree | grep firmware-abi unless you're certain you do not have an Advanced Format hard disk.
    12. +
  12. If you don't want to reboot immediately after installing rEFInd, you + may optionally unmount the ESP by typing sudo + umount /dev/disk0s1 or sudo umount + /Volumes/esp. This step isn't strictly required, but if you want + to keep the ESP out of your directory tree, it can be useful.
    13. +

When you reboot, your Mac should bring up the rEFInd menu, and should continue to do so thereafter. If you make changes that break this association, you can re-run the bless command (if necessary, restoring the rEFInd files first). This might be necessary after installing system updates from Apple or if you upgrade rEFInd to a newer version.

@@ -304,6 +372,8 @@ $ ioreg -l -p IODeviceTree | grep firmware-abi

Installing rEFInd Manually Using Windows

+

Warning: Windows 8 implements a fast shutdown feature that helps speed up shutdown and startup operations on a single-boot computer. Unfortunately, this feature can cause filesystem corruption if it's used on a multi-boot computer. You can disable the feature by launching an Administrator Command Prompt window and typing powercfg /h off in it.

+

To install rEFInd under Windows, you must first find a way to access the ESP, which Windows normally hides from view. One way to accomplish this goal, and to proceed forward once the ESP is accessible, is as follows:

    @@ -322,6 +392,8 @@ $ ioreg -l -p IODeviceTree | grep firmware-abi
  1. Type del refind_ia32.efi to delete the unused 32-bit version of rEFInd. (Windows only supports EFI boots on 64-bit EFI implementations and in 64-bit versions of Windows.)
    2. +
  2. Optionally type rd /s drivers_ia32 to delete the drivers_ia32 directory and its contents. You may also want to selectively delete some of the drivers in the drivers_x64 directory, depending on your needs. Unnecessary drivers may slow the rEFInd start process. See the page on drivers for more on this topic.
    3. +
  3. Type rename refind.conf-sample refind.conf to rename rEFInd's configuration file.
  4. Type bcdedit /set {bootmgr} path \EFI\refind\refind_x64.efi to set rEFInd as the default EFI boot program. Note that {bootmgr} is entered as such; that's not a notation for a variable.
    5. @@ -400,6 +472,8 @@ $ ioreg -l -p IODeviceTree | grep firmware-abi

    In all cases, if the new version includes new or altered configuration file options, you may need to manually update your configuration file. Alternatively, if you've used the default configuration file, you can replace your working refind.conf with refind.conf-sample from the rEFInd zip file. (When using install.sh, this file will be copied to rEFInd's installation directory under its original name, so you can rename it within that directory to replace the old file.

    +

    If you're upgrading to rEFInd from rEFIt, you can simply run the install.sh script as described earlier or perform a manual installation. Once installed, rEFInd will take over boot manager duties. You'll still be able to launch rEFIt from rEFInd; a rEFIt icon will appear in rEFInd's menu. You can eliminate this option by removing the rEFIt files, which normally reside in /EFI/refit.

    +

    Installing Additional Components

     @@ -408,13 +482,17 @@ $ ioreg -l -p IODeviceTree | grep firmware-abi

    I've seen links to other versions of these tools from time to time on the Web, so if you try one of these programs and it crashes or behaves strangely, try performing a Web search; you may turn up something that works better for you than the one to which I've linked.

    + +

    Fixing a Sluggish Macintosh Boot

    +     + +

    I've received a few reports of a sluggish boot process (a delay of about 30 seconds before starting rEFInd) on some Macs after installing rEFInd. I've been unable to replicate this problem myself, and its true cause remains mysterious to me. I have found a Web forum post describing a possible fix. Be aware, though, that this procedure involves using the efibootmgr utility on Macs, which has been known to damage the firmware on some Macs. Other reports indicate that this problem has been fixed with 3.3.0 and later kernels. Thus, I present this information cautiously and with a strong "use at your own risk" warning. If you care to proceed, I recommend you update your Linux kernel to the latest possible version and then proceed as follows:

    + +
      + +
    1. Boot into Linux.
      2. + +
    2. Type efibootmgr as root to obtain a list of your boot loader entries. Each entry includes a boot number, as in Boot0003 or Boot0027.
      3. + +
    3. Remove all of the boot loader entries except rEFInd's by using efibootmgr's -b bootnum option to specify the boot entry and -B to delete it. For instance, typing efibootmgr -b 0027 -B as root deletes boot entry Boot0027. Issue a separate efibootmgr command for each boot entry.
      4. + +
    4. Re-install rEFInd using the install script. It's unclear from the original post if this meant installing from Linux or from OS X.
      5. + +
    + + +

    Uninstalling rEFInd

    +     + +

    If you decide you don't want to keep rEFInd, you can uninstall it. Doing so is a matter of removing the rEFInd files from your ESP (or from your OS X boot partition, if you installed the program there). In Linux, a command like the following, typed as root, should do the trick:

    + +
    +# rm -r /boot/efi/EFI/refind
+
    + +

    This example assumes that your ESP is mounted at /boot/efi and that rEFInd is installed in EFI/refind on that partition. If you've mounted your ESP elsewhere, or installed rEFInd elsewhere, you should adjust the command appropriately.

    + +

    The same procedure works in OS X, with the caveat that the ESP isn't normally mounted in OS X and rEFInd is installed to the OS X boot partition by default. You'll also need to use sudo to acquire root privileges. Thus, you'd probably use a command like the following in OS X:

    + +
    +$ sudo rm -r /EFI/refind
+
    + +

    Many variants of both of these commands are possible on both OS X and Linux. For instance, you'd probably use sudo on Ubuntu; and if you installed rEFInd to your ESP on a Mac, you'd need to first mount the ESP and include its path in the rm command.

    + +

    From Windows, you must reverse the directions for installing in Windows—type mountvol S: /S to mount your ESP as S:, then navigate to the S:\EFI directory and delete the refind subdirectory.

    + +

    In any of these cases, when the computer boots and cannot find the rEFInd files, it should move on to the next boot loader in its list. In my experience, some EFI firmware implementations remove boot loaders they can't find from their NVRAM lists, so nothing else will be required, provided you have another working boot loader in your firmware's list. If your firmware doesn't automatically clean up its NVRAM entries, rEFInd's entry will do little harm; however, you can delete it with the efibootmgr utility in Linux:

    + +
    +# efibootmgr --verbose
+Timeout: 10 seconds
+BootOrder: 0000,0007
+Boot0000* rEFInd	HD(2,1b8,64000,f1b7598e-baa8-16ea-4ef6-3ff3b606ac1e)File(\EFI\refind\refind.efi)
+Boot0007* CD/DVD Drive	BIOS(3,0,00)PATA: HP DVD Writer 1040r     .
+# efibootmgr --delete-bootnum --bootnum 0000
+Timeout: 10 seconds
+BootOrder: 0007
+Boot0007* CD/DVD Drive
    + +

    Warning: As noted earlier, efibootmgr has been linked to firmware corruption on some Macs, at least with pre-3.0 Linux kernels. Therefore, I don't recommend using efibootmgr on Macs.

    + +

    This example shows use of efibootmgr's --verbose (-v) option to display boot loaders so as to identify which one is rEFInd, followed by --delete-bootnum (-B) to delete a boot program and --bootnum (-b) to identify which one to delete. Of course, in this example there's not much else left, so you'd presumably want to install another boot loader at this point! If you already have another one installed, you may want to check the BootOrder line to determine which one will take precedence when you reboot. If you don't like what it shows, you can adjust it with the --bootorder (-o) option; consult efibootmgr's man page for details.

    + +

    If you're not using Linux, you may be able to find a utility that serves a similar function. The OS X bless utility (or its GUI equivalent, the Startup Disk item in System Preferences) should do the trick; but Macs pick up standard OS X boot loaders when they boot and find that a configured non-standard boot loader is missing, so this shouldn't be necessary on Macs. Under Windows, the bcdedit command, described in the section on installing rEFInd under Windows, may work, although I've not attempted this.

    +

    copyright © 2012 by Roderick W. Smith