refind-install(8)
NAME
refind-install - Install rEFInd to the ESP and create an NVRAM entry
SYNOPSIS
refind-install [--notesp | --usedefault device-file | --root mount- point | --ownhfs device-file ] [--keepname] [--nodrivers | --alldrivers] [--shim shim-filename] [--localkeys] [--yes]
DESCRIPTION
To be useful, the rEFInd boot manager must be installed to the
computer's EFI System Partition (ESP) or other EFI-accessible location.
In most cases, an NVRAM entry describing rEFInd's location must also be
created. These steps can be performed manually; however, the refind-
install command provides an automated way to perform these tasks under
both Linux and OS X. The exact behavior and options vary depending on
the OS, however.
Some details that can affect how the script runs include the following:
* If you run the script as an ordinary user, it attempts to
acquire root privileges by using the sudo command. This works on
Mac OS X and some Linux installations (such as under Ubuntu or
if you've added yourself to the sudo users list), but on some
Linux installations this will fail. On such systems, you should
run refind-install as root.
* Under OS X, you can run the script with a mouse by opening a
Terminal session and then dragging-and-dropping the
refind-install file to the Terminal window. You'll need to press
the Return or Enter key to run the script.
* If you're using OS X 10.7's Whole Disk Encryption (WDE) feature,
or the loogical volumes feature in OS X 10.10, you must install
rEFInd to the ESP or to a separate HFS+ partition. The default
in rEFInd 0.8.4 and later is to install to the ESP. If you
prefer to use a separate HFS+ volume, the --ownhfs device-file
option to refind-install is required.
* If you're not using WDE or logical volumes, you can install
rEFInd to the OS X root (/) partition by using the --notesp
option to refind-install. Using this option is recommended when
upgrading from a working rEFInd installation in this location.
* If you're replacing rEFIt with rEFInd on a Mac, there's a chance
that refind-install will warn you about the presence of a
program called /Library/StartupItems/rEFItBlesser and ask if you
want to delete it. This program is designed to keep rEFIt set
as the boot manager by automatically re-blessing it if the
default boot manager changes. This is obviously undesirable if
you install rEFInd as your primary boot manager, so it's
generally best to remove this program. If you prefer to keep
your options open, you can answer N when refind-install asks if
you want to delete rEFItBlesser, and instead manually copy it
elsewhere. If you subsequently decide to go back to using rEFIt
as your primary boot manager, you can restore rEFItBlesser to
its place.
* If you intend to boot BIOS-based OSes on a UEFI-based PC, you
must edit the refind.conf file's scanfor line to enable the
relevant searches. This is not necessary on Macs, though;
because of the popularity of dual boots with Windows on Macs,
the BIOS/legacy scans are enabled by default on Macs.
* On Linux, refind-install checks the filesystem type of the /boot
directory and, if a matching filesystem driver is available,
installs it. Note that the "/boot directory" may be on a
separate partition or it may be part of your root (/)
filesystem, in which case the driver for your root filesystem is
installed. This feature is unlikely to work properly from an
emergency system, although it might if you have a separate /boot
partition and if you mount that partition at /boot in your
emergency system, and the ESP at /boot/efi.
* On OS X, refind-install checks your partition tables for signs
of a Linux installation. If such a sign is found, the script
installs the EFI filesystem driver for the Linux ext4
filesystem. This will enable rEFInd to read your Linux kernel if
it's on an ext2, ext3, or ext4 filesystem. Note that some
configurations will require a /boot/refind_linux.conf file,
which can be reliably generated only under Linux. (The mkrlconf
script that comes with rEFInd will do this job once you've
booted Linux.) In the meantime, you can launch GRUB from rEFInd
or press F2 or Insert twice after highlighting the Linux option
in rEFInd. This will enable you to enter a root=/dev/whatever
specification, where /dev/whatever is the device identifier of
your Linux root (/) filesystem.
* If you run refind-install on Linux and if
/boot/refind_linux.conf doesn't already exist, refind-install
creates this file and populates it with a few sample entries. If
/boot is on a FAT partition (or HFS+ on a Mac), or if it's on an
ext2fs, ext3fs, ext4fs, ReiserFS, Btrfs, or HFS+ partition and
you install an appropriate driver, the result is that rEFInd
will detect your kernel and will probably boot it correctly.
Some systems will require manual tweaking to refind_linux.conf,
though -- for instance, to add dolvm to the boot options on
Gentoo systems that use LVM.
* If you pass the --shim option to the script (along with a
filename for a Shim binary), the script sets up for a Secure
Boot configuration via Shim. By default, this causes the rEFInd
binary to be renamed as grubx64.efi. Recent versions of Shim
support passing the name of the follow-on program to Shim via a
parameter, though. If you want to use this feature, you can pass
the --keepname option to refind-install.
After you run refind-install, you should peruse the script's output to
ensure that everything looks OK. refind-install 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.
OPTIONS
--notesp
This option, which is valid only under OS X, tells refind-
install to install rEFInd to the OS X root partition rather than
to the ESP. This behavior was the default in rEFInd 0.8.3 and
earlier, so you may want to use it when upgrading installations
of that version, unless you used --esp (which is now the default
behavior, although the --esp option no longer exists) or
--ownhfs. You may also want to use --notesp on new installations
if you're sure you're not using whole-disk encryption or logical
volumes.
--usedefault device-file
You can install rEFInd to a disk using the default/fallback
filename of EFI/BOOT/bootx64.efi (as well as
EFI/BOOT/bootia32.efi and EFI/BOOT/bootaa64.efi, if the IA-32
and ARM64 builds are available) using this option. The
device-file should be an unmounted ESP, or at least a FAT
partition, as in --usedefault /dev/sdc1. Your computer's NVRAM
entries will not be modified when installing in this way. The
intent is that you can create a bootable USB flash drive or
install rEFInd on a computer that tends to "forget" its NVRAM
settings with this option. This option is mutually exclusive
with --notesp and --root.
--ownhfs device-file
This option should be used only under OS X. It's used to install
rEFInd to an HFS+ volume other than a standard Mac boot volume.
The result should be that rEFInd will show up in the Mac's own
boot manager. More importantly, suspend-to-RAM operations may
work correctly. Note that this option requires an HFS+ volume
that is not currently an OS X boot volume. This can be a data
volume or a dedicated rEFInd partition. The ESP might also work,
if it's converted to use HFS+; however, HFS+ is a non-standard
filesystem for an ESP, and so is not recommended.
--root mount-point
This option is intended to help install rEFInd from a "live CD"
or other emergency system. To use it, you should mount your
regular installation at /mount-point, including your /boot
directory (if it's separate) at /mount-point/boot and (on Linux)
your ESP at that location or at /mount-point/boot/efi. The
refind-install script then installs rEFInd to the appropriate
location -- on Linux, /mount-point/boot/EFI/refind or
/mount-point/boot/efi/EFI/refind, depending on where you've
mounted your ESP. Under OS X, this option is useful only in
conjunction with --notesp, in which case rEFInd will install to
/mount-point/EFI/refind. The script also adds an entry to your
NVRAM for rEFInd at this location. You cannot use this option
with --usedefault. Note that this option is not needed when
doing a dual-boot Linux/OS X installation; just install normally
in OS X.
--nodrivers
Ordinarily refind-install attempts to install the driver
required to read /boot on Linux. This attempt works only if
you're using ext2fs, ext3fs, ext4fs, ReiserFS, or Btrfs on the
relevant partition. If you want to forego this driver
installation, pass the --nodrivers option. This option is
implicit when you use --usedefault.
--alldrivers
When you specify this option, refind-install copies all the
driver files for your architecture. You may want to remove
unused driver files after you use this option. Note that some
computers hang or fail to work with any drivers if you use this
option, so use it with caution.
--shim shim-filename or --preloader preloader-filename
If you pass this option to refind-install, the script will copy
the specified shim program file to the target directory, copy
the MokManager.efi file from the shim program file's directory
to the target directory, copy the 64-bit version of rEFInd as
grubx64.efi, and register shim with the firmware. (If you also
specify --usedefault, the NVRAM registration is skipped. If you
also use --keepname, the renaming to grubx64.efi is skipped.)
When the target file is identified as PreLoader, much the same
thing happens, but refind-install copies HashTool.efi instead of
MokManager.efi and copies rEFInd as loader.efi rather than as
grubx64.efi. The intent is to simplify rEFInd installation on a
computer that uses Secure Boot; when so set up, rEFInd will boot
in Secure Boot mode, with one caveat: The first time you boot,
MokManager/HashTool will launch, and you must use it to locate
and install a public key or register rEFInd as a trusted
application. The rEFInd public key file will be located in the
rEFInd directory's keys subdirectory under the name refind.cer.
--localkeys
This option tells refind-install to generate a new Machine Owner
Key (MOK), store it in /etc/refind.d/keys as refind_local.*, and
re-sign all the 64-bit rEFInd binaries with this key before
installing them. This is the preferable way to install rEFInd in
Secure Boot mode, since it means your binaries will be signed
locally rather than with my own key, which is used to sign many
other users' binaries; however, this method requires that both
the openssl and sbsign binaries be installed. The former is
readily available in most distributions' repositories, but the
latter is not, so this option is not the default.
--keepname
This option is useful only in conjunction with --shim. It tells
refind-install to keep rEFInd's regular filename (typically
refind_x64.efi) when used with shim, rather than rename the
binary to grubx64.efi. This change cuts down on the chance of
confusion because of filename issues; however, this feature
requires that shim be launched with a command-line parameter
that points to the rEFInd binary under its real name. versions
of shim prior to 0.7 do not properly support this feature.
(Version 0.4 supports it but with a buggy interpretation of the
follow-on loader specification.) If your NVRAM variables become
corrupted or are forgotten, this feature may make rEFInd harder
to launch. This option is incompatible with --usedefault and is
unavailable when run under OS X or without the --shim option. If
the script discovers an existing rEFInd installation under
EFI/BOOT or EFI/Microsoft/Boot and no other rEFInd installation
when this option is used, it will abort.
--yes This option causes the script to assume a Y input to every
yes/no prompt that can be generated under certain conditions,
such as if you specify --shim but refind-install detects no
evidence of a Secure Boot installation. This option is intended
mainly for use by scripts such as those that might be used as
part of an installation via an RPM or Debian package.
AUTHORS
Primary author: Roderick W. Smith ([email protected])
SEE ALSO
mkrlconf (8), mvrefind (8) http://www.rodsbooks.com/refind/
AVAILABILITY
The refind-install command is part of the rEFInd package and is available from Roderick W. Smith.
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
