1 .\" Copyright 2015 Roderick W. Smith (rodsmith@rodsbooks.com)
2 .\" May be distributed under the GNU General Public License version 3 or
4 .TH "REFIND-INSTALL" "8" "0.10.0" "Roderick W. Smith" "rEFInd Manual"
6 refind-install \- Install rEFInd to the ESP and create an NVRAM entry
9 [--notesp | --usedefault \fIdevice-file\fR | --root \fImount-point\fR |
10 --ownhfs \fIdevice-file\fR ] [--keepname ] [--nodrivers | --alldrivers]
11 [--shim \fIshim-filename\fR] [--localkeys] [--yes]
16 To be useful, the rEFInd boot manager must be installed to the computer's
17 EFI System Partition (ESP) or other EFI-accessible location. In most cases,
18 an NVRAM entry describing rEFInd's location must also be created. These
19 steps can be performed manually; however, the \fBrefind-install\fR command
20 provides an automated way to perform these tasks under both Linux and OS X.
21 The exact behavior and options vary depending on the OS, however.
27 This option, which is valid only under OS X, tells \fBrefind-install\fR to
28 install rEFInd to the OS X root partition rather than to the ESP. This
29 behavior was the default in rEFInd 0.8.3 and earlier, so you may want to
30 use it when upgrading installations of that version, unless you used
31 \-\-esp (which is now the default behavior, although the \-\-esp option no
32 longer exists) or \-\-ownhfs. You may also want to use \-\-notesp on new
33 installations if you're sure you're not using whole\-disk encryption or
37 .B \-\-usedefault \fIdevice-file\fR
38 You can install rEFInd to a disk using the default/fallback filename of
39 \fBEFI/BOOT/bootx64.efi\fR (and \fBEFI/BOOT/bootia32.efi\fR, if the 32\-bit
40 build is available) using this option. The device\-file should be an
41 unmounted ESP, or at least a FAT partition, as in \fB\-\-usedefault
42 /dev/sdc1\fR. Your computer's NVRAM entries will not be modified when
43 installing in this way. The intent is that you can create a bootable USB
44 flash drive or install rEFInd on a computer that tends to "forget" its
45 NVRAM settings with this option. This option is mutually exclusive with
46 \-\-notesp and \-\-root.
49 .B \-\-ownhfs \fIdevice-file\fR
50 This option should be used only under OS X. It's used to install rEFInd to
51 an HFS+ volume other than a standard Mac boot volume. The result should be
52 that rEFInd will show up in the Mac's own boot manager. More importantly,
53 suspend\-to\-RAM operations may work correctly. Note that this option
54 requires an HFS+ volume that is not currently an OS X boot volume. This can
55 be a data volume or a dedicated rEFInd partition. The ESP might also work,
56 if it's converted to use HFS+; however, HFS+ is a non\-standard filesystem
57 for an ESP, and so is not recommended.
60 .B \-\-root \fImount-point\fR
61 This option is intended to help install rEFInd from a "live CD" or other
62 emergency system. To use it, you should mount your regular installation at
63 \fI/mount\-point\fR, including your /boot directory (if it's separate) at
64 \fI/mount\-point\fR/boot and (on Linux) your ESP at that location or at
65 \fI/mount\-point\fR/boot/efi. The \fBrefind\-install\fR script then
66 installs rEFInd to the appropriate location -- on Linux,
67 \fI/mount\-point\fR/boot/EFI/refind or
68 \fI/mount\-point\fR/boot/efi/EFI/refind, depending on where you've mounted
69 your ESP. Under OS X, this option is useful only in conjunction with
70 \-\-notesp, in which case rEFInd will install to
71 \fI/mount\-point\fR/EFI/refind. The script also adds an entry to your NVRAM
72 for rEFInd at this location. You cannot use this option with
73 \-\-usedefault. Note that this option is not needed when doing a dual-boot
74 Linux/OS X installation; just install normally in OS X.
78 Ordinarily \fBrefind\-install\fR attempts to install the driver required to
79 read /boot on Linux. This attempt works only if you're using ext2fs,
80 ext3fs, ext4fs, ReiserFS, or Btrfs on the relevant partition. If you want
81 to forego this driver installation, pass the \-\-nodrivers option. This
82 option is implicit when you use \-\-usedefault.
86 When you specify this option, \fBrefind\-install\fR copies all the driver
87 files for your architecture. You may want to remove unused driver files
88 after you use this option. Note that some computers hang or fail to work
89 with any drivers if you use this option, so use it with caution.
92 .B \-\-shim \fIshim\-filename\fR or \fB\-\-preloader \fIpreloader\-filename\fR\fB
93 If you pass this option to \fBrefind\-install\fR, the script will copy the
94 specified shim program file to the target directory, copy the
95 MokManager.efi file from the shim program file's directory to the target
96 directory, copy the 64-bit version of rEFInd as grubx64.efi, and register
97 shim with the firmware. (If you also specify \-\-usedefault, the NVRAM
98 registration is skipped. If you also use \-\-keepname, the renaming to
99 grubx64.efi is skipped.) When the target file is identified as PreLoader,
100 much the same thing happens, but \fBrefind\-install\fR copies HashTool.efi
101 instead of MokManager.efi and copies rEFInd as loader.efi rather than as
102 grubx64.efi. The intent is to simplify rEFInd installation on a computer
103 that uses Secure Boot; when so set up, rEFInd will boot in Secure Boot
104 mode, with one caveat: The first time you boot, MokManager/HashTool will
105 launch, and you must use it to locate and install a public key or register
106 rEFInd as a trusted application. The rEFInd public key file will be located
107 in the rEFInd directory's keys subdirectory under the name refind.cer.
111 This option tells \fBrefind\-install\fR to generate a new Machine Owner Key
112 (MOK), store it in /etc/refind.d/keys as refind_local.*, and re-sign all
113 the 64-bit rEFInd binaries with this key before installing them. This is
114 the preferable way to install rEFInd in Secure Boot mode, since it means
115 your binaries will be signed locally rather than with my own key, which is
116 used to sign many other users' binaries; however, this method requires that
117 both the \fBopenssl\fR and \fBsbsign\fR binaries be installed. The former
118 is readily available in most distributions' repositories, but the latter is
119 not, so this option is not the default.
123 This option is useful only in conjunction with \-\-shim. It tells
124 \fBrefind\-install\fR to keep rEFInd's regular filename (typically
125 refind_x64.efi) when used with shim, rather than rename the binary to
126 grubx64.efi. This change cuts down on the chance of confusion because of
127 filename issues; however, this feature requires that shim be launched with
128 a command-line parameter that points to the rEFInd binary under its real
129 name. versions of shim prior to 0.7 do not properly support this feature.
130 (Version 0.4 supports it but with a buggy interpretation of the follow-on
131 loader specification.) If your NVRAM variables become corrupted or are
132 forgotten, this feature may make rEFInd harder to launch. This option is
133 incompatible with \-\-usedefault and is unavailable when run under OS X or
134 without the \-\-shim option. If the script discovers an existing rEFInd
135 installation under EFI/BOOT or EFI/Microsoft/Boot and no other rEFInd
136 installation when this option is used, it will abort.
140 This option causes the script to assume a \fBY\fR input to every yes/no
141 prompt that can be generated under certain conditions, such as if you
142 specify \-\-shim but \fBrefind\-install\fR detects no evidence of a Secure
143 Boot installation. This option is intended mainly for use by scripts such
144 as those that might be used as part of an installation via an RPM or Debian
148 Primary author: Roderick W. Smith (rodsmith@rodsbooks.com)
154 \fIhttp://www.rodsbooks.com/refind/\fR
157 The \fBrefind\-install\fR command is part of the \fIrEFInd\fR package and is
158 available from Roderick W. Smith.