X-Git-Url: https://code.delx.au/refind/blobdiff_plain/2cc79ea9b33424d5fc32f15683adf7c956656b9b..63072e911e51d8960638fb086fc8ff0fe62ebc9d:/docs/refind/installing.html diff --git a/docs/refind/installing.html b/docs/refind/installing.html index 925c237..6f5d1e6 100644 --- a/docs/refind/installing.html +++ b/docs/refind/installing.html @@ -8,6 +8,8 @@ + +

The rEFInd Boot Manager:
Installing rEFInd

@@ -15,7 +17,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com

Originally written: 3/14/2012; last Web page update: -12/8/2014, referencing rEFInd 0.8.4

+11/8/2015, referencing rEFInd 0.10.0

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!

@@ -41,8 +43,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com

- -Donate with PayPal + @@ -56,8 +57,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com

- -Donate with PayPal + @@ -72,8 +72,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com

- -Donate with PayPal + @@ -87,8 +86,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com

- -Donate with PayPal + @@ -102,8 +100,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com

- -Donate with PayPal + @@ -116,8 +113,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com

- -Donate with PayPal + @@ -130,9 +126,9 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com

-

Don't be scared by the length of this page! Only portions of this page apply to any given user, and most people can install rEFInd from an RPM or Debian package in a matter of seconds or by using the install.sh script in minute or two.

+

Don't be scared by the length of this page! Only portions of this page apply to any given user, and most people can install rEFInd from an RPM or Debian package in a matter of seconds or by using the refind-install script in minute or two.

-

Once you've obtained a rEFInd binary file, you must install it to your computer's EFI System Partition (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. See the Contents sidebar to the left for links to specific installation procedures. For most Linux users, an RPM or Debian package is the best way to go. If your Linux system doesn't support these formats, though, or if you're running OS X, using the install.sh script can be a good way to go. If you're using Windows, you'll have to install manually.

+

Once you've obtained a rEFInd binary file, as described on the preceding page, you must install it to your computer's EFI System Partition (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. See the Contents sidebar to the left for links to specific installation procedures. For most Linux users, an RPM or Debian package is the best way to go. If your Linux system doesn't support these formats, though, or if you're running OS X, using the refind-install script can be a good way to go. If you're using Windows, you'll have to install manually.

@@ -146,15 +142,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com

  • Installing rEFInd using an RPM or Debian package file
  • -
  • Installing rEFInd Using install.sh under Linux or Mac OS X - -
  • +
  • Installing rEFInd Using refind-install under Linux or Mac OS X
  • Installing rEFInd Manually @@ -172,7 +160,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com

    -

    If you need to use one of these names, or something more exotic, you can do so in either of two ways: You can use the mvrefind.sh script to move your installation in one step, or you can move and rename your files manually.

    +

    If you need to use one of these names, or something more exotic, you can do so in either of two ways: You can use the mvrefind script to move your installation in one step, or you can move and rename your files manually.

    -

    Using mvrefind.sh

    +

    Using mvrefind

    -

    The easiest way to move a rEFInd installation, at least in Linux, is to use the mvrefind.sh script. If you installed from one of my RPM or Debian packages, this script should be installed in /usr/sbin, so you can use it like a regular Linux command; otherwise you'll need to install it to your path yourself or type its complete path. Either way, it works much like the Linux mv command, but you pass it the directory in which a rEFInd installation appears and a target location:

    +

    The easiest way to move a rEFInd installation, at least in Linux, is to use the mvrefind script. If you installed from one of my RPM or Debian packages, this script should be installed in /usr/sbin, so you can use it like a regular Linux command; otherwise you'll need to install it to your path yourself or type its complete path. Either way, it works much like the Linux mv command, but you pass it the directory in which a rEFInd installation appears and a target location:

    -# mvrefind.sh /boot/efi/EFI/BOOT /boot/efi/EFI/refind
    +# mvrefind /boot/efi/EFI/BOOT /boot/efi/EFI/refind
     

    This example moves rEFInd from /boot/efi/EFI/BOOT to /boot/efi/EFI/refind. It differs from mv in several ways: @@ -790,7 +643,7 @@ $ ioreg -l -p IODeviceTree | grep firmware-abi

    -

    The mvrefind.sh script is likely to be useful in resolving boot problems—if your system won't boot, you can try copying the installation to /boot/efi/EFI/BOOT, /boot/efi/EFI/Microsoft/Boot, and /boot/efi/EFI/refind in turn, testing the boot process after each attempt. (These filenames all assume your ESP is mounted at /boot/efi.) You could also copy a BIOS-mode install from /boot/efi/EFI/BOOT or /boot/efi/EFI/Microsoft/Boot to /boot/efi/EFI/refind to make it more robust against Windows repairs (assuming your firmware isn't broken).

    +

    The mvrefind script is likely to be useful in resolving boot problems—if your system won't boot, you can try copying the installation to /boot/efi/EFI/BOOT, /boot/efi/EFI/Microsoft/Boot, and /boot/efi/EFI/refind in turn, testing the boot process after each attempt. (These filenames all assume your ESP is mounted at /boot/efi.) You could also copy a BIOS-mode install from /boot/efi/EFI/BOOT or /boot/efi/EFI/Microsoft/Boot to /boot/efi/EFI/refind to make it more robust against Windows repairs (assuming your firmware isn't broken).

    Renaming Files Manually

    @@ -860,19 +713,24 @@ $ ioreg -l -p IODeviceTree | grep firmware-abi
  • In OS X, if you copy over the original file with the new one, you'll probably have to re-bless it to make it work.
  • -
  • Under Linux or OS X, you can re-run the install.sh script. In +
  • Under Linux or OS X, you can re-run the refind-install script. In most cases this works fine, but you'll end up with a duplicate of the icons directory (icons-backup, which holds the original icons, whereas icons holds the icons from the new package). Normally this just wastes some disk space; but if you've customized your icons, you'll need to copy your altered icons back. Under Linux, versions - 0.6.2 and later of install.sh search for rEFInd in several - locations on the ESP, and will upgrade whatever is found.
  • + 0.6.2 and later of refind-install search for rEFInd in several + locations on the ESP, and will upgrade whatever is found. The same is + true with versions 0.8.5 and later under OS X when installing to the + ESP. If you install to a location other than the ESP under OS X, be + sure to include the same option to refind-install + (--notesp or --ownhfs) to replace the original rather + than create a new installation to the ESP.
  • Under an RPM- or Debian-based Linux distribution, you can use your package system to install a newer version of the RPM or Debian package that I provide. This will upgrade the files in your Linux filesystem - and re-run the install.sh script, so as with the previous + and re-run the refind-install script, so as with the previous options, you'll waste a little disk space on duplicated icons, but the process should otherwise work quite well.
  • @@ -882,14 +740,14 @@ $ ioreg -l -p IODeviceTree | grep firmware-abi on how the package was created, though, this update might or might not install the update to the ESP; you might need to manually re-run the installation script. Consult your distribution's documentation for - details. My Ubuntu PPA will automatically run install.sh after + details. My Ubuntu PPA will automatically run refind-install after the package is installed. -

    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.)

    +

    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 refind-install, 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.

    +

    If you're upgrading to rEFInd from rEFIt, you can simply run the refind-install 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

    @@ -949,7 +807,7 @@ $ ioreg -l -p IODeviceTree | grep firmware-abi original rEFIt version of the program usually goes by the filename gptsync.efi, whereas the updated rEFInd version ships with an architecture code, as in gptsync_x64.efi or - gptsync_ia32.efi. The rEFInd install.sh script + gptsync_ia32.efi. The rEFInd refind-install script installs gptsync_arch.efi when run under OS X, but not when run on Linux. In addition to installing the program, you must edit refind.conf, uncomment the @@ -993,13 +851,21 @@ $ ioreg -l -p IODeviceTree | grep firmware-abi

    Fixing Macintosh Boot Problems

    -

    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, as well as some other Mac-specific peculiarities. I've been unable to replicate thess problems myself, and their true causes remains mysterious to me. I have found several possible solutions, though: using the fallback filename, moving rEFInd to an HFS+ volume, clearing NVRAM entries, and fixing wake problems.

    +

    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, as well as some other Mac-specific peculiarities. I've been unable to replicate thess problems myself, and their true causes remains mysterious to me. I have found several possible solutions, though: Using the --shortform option, using the fallback filename, moving rEFInd to an HFS+ volume, clearing NVRAM entries, fixing wake problems, and fixing a failure to find Linux.

    + + +

    Using the --shortform Option

    +
    + +

    Prior to version 0.8.5, these instructions and the refind-install script omitted the --shortform option from the bless command when installing rEFInd to the ESP. A rEFInd user, however, discovered that using the option eliminated the 30-second delay, so it is now the default with 0.8.5's refind-install, and is specified in the instructions. If you installed rEFInd 0.8.4 or earlier, you may want to re-install or re-bless rEFInd using this option.

    + +

    There is one caveat, though: The man page for bless notes that --shortform notes that its use can come "at the expense of boot time performance." Thus, it's not clear to me that this option might not actually create problems on some computers. (It's eliminated the boot delay on my 2014 MacBook Air and has no detrimental effect on an old 32-bit Mac Mini that's never had a boot delay problem, though.) Thus, if you have problems with rEFInd 0.8.5 or later, you might try running bless, as described in Installing rEFInd Manually Using OS X's step 8, but omit the --shortform option.

    Using the Fallback Filename

    -

    I've received a few reports that installing rEFInd to the ESP using the fallback filename (EFI/BOOT/bootx64.efi on most systems, or EFI/BOOT/bootia32.efi on very old Macs) can work around a sluggish boot problem. In fact, since version 0.8.4, the install.sh script copies the rEFInd binary to this name when run under OS X. If you installed manually to another name, though, renaming (and re-blessing) the installation is worth trying.

    +

    I've received a few reports that installing rEFInd to the ESP using the fallback filename (EFI/BOOT/bootx64.efi on most systems, or EFI/BOOT/bootia32.efi on very old Macs) can work around a sluggish boot problem. In fact, version 0.8.4's refind-install script copied the rEFInd binary to this name when run under OS X. (Version 0.8.5 switches to using --shortform with the more conventional EFI/refind/refind_x64.efi or EFI/refind/refind_ia32.efi name, as just noted.) If you installed to a name other than EFI/BOOT/BOOT{ARCH}, either manually or by using the 0.8.5 or later refind-install, renaming (and re-blessing) the installation is worth trying.

    Moving rEFInd to an HFS+ Volume

    @@ -1007,7 +873,7 @@ $ ioreg -l -p IODeviceTree | grep firmware-abi

    Most of the reports of sluggish Macintosh boots I've seen note that the user installed rEFInd to the ESP rather than to the OS X root partition. Some users have reported that re-installing rEFInd to the OS X root partition clears up the problem. This is obviously a straightforward solution to the problem, if it works. (This location is not an option when using WDE or OS X logical volumes.) Note that rEFInd can launch boot loaders that are stored on any partition that the EFI can read no matter where it's installed; therefore, you'll still be able to launch boot loaders stored on the ESP (or elsewhere) if you install it in this way.

    -

    A variant of this solution is to create a small (~100MiB) HFS+ volume to be used exclusively by rEFInd. You can then install rEFInd to that volume with the --ownhfs option to install.sh, as in ./install.sh --ownhfs /dev/disk0s6 if the volume is /dev/disk0s6. This approach has the advantage that it can be managed via OS X's own Startup Disk tool in System Preferences.

    +

    A variant of this solution is to create a small (~100MiB) HFS+ volume to be used exclusively by rEFInd. You can then install rEFInd to that volume with the --ownhfs option to refind-install, as in ./refind-install --ownhfs /dev/disk0s6 if the volume is /dev/disk0s6. This approach has the advantage that it can be managed via OS X's own Startup Disk tool in System Preferences.

    The biggest drawback to storing rEFInd on an HFS+ volume is that you won't be able to edit the rEFInd configuration file or move rEFInd-related binaries from an EFI shell if you install it in this way, since Apple's HFS+ driver for EFI is read-only. (The same is true of rEFInd's HFS+ driver, so it won't help you overcome this limitation.) You may also be limited in making changes to your rEFInd configuration from Linux or other OSes, too, since Linux's HFS+ drivers disable write support by default on volumes with an active journal. You can force write access by using the force option to mount; however, this procedure is noted as being risky in the Linux HFS+ documentation, so I don't recommend doing this on a regular basis on the OS X boot volume. This isn't as risky if you use a dedicated HFS+ rEFInd partition, though. You could even mount it as the Linux /boot partition, in which case it would also hold the Linux kernel and related files.

    @@ -1039,13 +905,33 @@ $ ioreg -l -p IODeviceTree | grep firmware-abi -

    Unfortunately, I lack a recent Mac and so can't investigate these issues myself, so I'm dependent upon others (mostly non-programmers) to offer workarounds. This is the type of problem that really requires hands-on interactive debugging sessions with the code to stand any chance of finding a better solution.

    +

    I've recently acquired a 2014 MacBook Air, but I haven't yet had the chance to try to reproduce this problem and find a workaround. It's on my to-do list, though.

    + +
    +

    Fixing a Failure to Find Linux

    +
    + +

    Some users report that rEFInd doesn't detect Linux, or won't boot it when it is found. Broadly speaking, there are two common causes of this problem:

    + + + +

    If you suspect that your hybrid MBR is damaged, you can try re-creating it with my GPT fdisk (gdisk) program. The GPT fdisk hybrid MBR documentation covers this procedure in detail. You can run gdisk from either OS X or Linux, although you may need to install it, particularly in OS X.

    + +

    If you suspect driver problems, you'll need to mount your ESP (as described in the manual OS X installation instructions), locate the rEFInd drivers_x64 directory, and adjust its contents. Make sure you have a driver for the filesystem that holds your Linux kernel. If you don't know what filesystem this is, it's probably ext4fs. rEFInd ships with several filesystem drivers, including one for ext4fs. You should also remove unnecessary filesystem drivers. I've seen several reports of one driver interfering with others' operation. The biggest culprit seems to be the HFS+ driver when used on Macs.

    + +

    Fixing Windows Boot Problems

    @@ -1115,33 +1001,58 @@ $ ioreg -l -p IODeviceTree | grep firmware-abi
      -
    1. You must first determine where rEFInd is installed. If you used the - default installation location, this will be /EFI/refind on - your main partition if you installed rEFInd 0.8.3 or earlier, or in - EFI/refind or EFI/BOOT on the ESP if you installed - rEFInd 0.8.4 with the default options. If you used the - --ownhfs option, rEFInd will be in the - System/Library/CoreServices directory on the volume you - specified.
    2. +
    3. You must first determine where rEFInd is installed. This can be any of + several locations: + +
        + +
      • If you installed rEFInd 0.8.3 or earlier with the default options, + or if you used the --notesp option with rEFInd 0.8.4 or + later, it will be /EFI/refind on your main partition
      • + +
      • If you installed rEFInd 0.8.4 or later with the default options, or + if you used the --esp option with rEFInd 0.8.3 or earlier, + it will be in EFI/refind or EFI/BOOT on the + ESP.
      • + +
      • If you used the --ownhfs option to refind-install, + rEFInd will be in the System/Library/CoreServices + directory on the volume you specified.
      • + +
      • If you installed rEFInd manually, it will be wherever you put + it.
      • + +
      • In all cases, there could be duplicate (inactive) rEFInd files in + unexpected places. This is particularly true if you tried + installing rEFInd multiple times, each with different options to + refind-install. Thus, if you delete rEFInd and it still comes + up, you may have deleted the wrong files. (Note that dragging files + to the Trash may have no effect, though—at least, not until + you empty the Trash.)
      • + +
    4. If necessary, mount the ESP or rEFInd-specific HFS+ volume, as described in Installing rEFInd Manually Using Mac OS - X.
    5. + X. (The mountesp script that comes with rEFInd will handle + this task.)
    6. Verify that rEFInd is installed in the directory noted in step #1. If a refind.conf file is present, rEFInd is almost certainly installed in that directory. If not, it's not rEFInd there and you should not proceed. Be extra cautious about deleting the System/Library/CoreServices directory, since that's - the default location of the OS X boot loader!
    7. + the default location of the OS X boot loader! Never delete this + directory from your OS X root (/) partition, only from the + partition you specified to refind-install using the + --ownhfs option.
    8. Once you've identified the rEFInd directory, delete it, or at least the rEFInd boot file. This file may be called refind_x64.efi, bootx64.efi, boot.efi, or conceivably something else. You may need to use sudo rm at the command line to accomplish this task, as in sudo rm -r - /Volumes/esp/EFI/refind. Note that dragging files to the Trash on - the Desktop may not be adequate unless you also empty the Trash.
    9. + /Volumes/ESP/EFI/refind.
    @@ -1168,8 +1079,6 @@ Timeout: 10 seconds BootOrder: 0007 Boot0007* CD/DVD Drive - -

    This example shows use of efibootmgr's --verbose (-v) option to display boot programs 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 program 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