Ubuntu Manpage: refind-install - Install rEFInd to the ESP and create an NVRAM entry

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] [--encryptkeys] [--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.

--encryptkeys
Ordinarily, if you use the --localkeys option, refind-install stores the local key
files on your hard disk in an unencrypted form. Thus, should your computer be
compromised, the intruder could use your own key to sign a modified boot loader,
eliminating the benefits of Secure Boot. If you use this option, then the private
key is stored in an encrypted form, secured via an encryption password. You must
enter this password before the key can be used to sign any binary, thus reducing
the risk that an intruder could hijack your boot process. This is obviously a
highly desirable option, but the downside is that you must remember the password
and enter it whenever you update rEFInd or any other program signed with your
private key. This also makes a fully automated update of rEFInd impossible.

--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 (rodsmith@rodsbooks.com)

AVAILABILITY