1REFIND-INSTALL(8) rEFInd Manual REFIND-INSTALL(8)
2any later version
6
8 refind-install - Install rEFInd to the ESP and create an NVRAM entry
9
11 refind-install [--notesp | --usedefault device-file | --root mount-
12 point | --ownhfs device-file ] [--keepname] [--nodrivers |
13 --alldrivers] [--shim shim-filename] [--localkeys] [--encryptkeys]
14 [--yes]
15
19 To be useful, the rEFInd boot manager must be installed to the com‐
20 puter's EFI System Partition (ESP) or other EFI-accessible location. In
21 most cases, an NVRAM entry describing rEFInd's location must also be
22 created. These steps can be performed manually; however, the refind-in‐
23 stall command provides an automated way to perform these tasks under
24 both Linux and OS X. The exact behavior and options vary depending on
25 the OS, however.
26 Some details that can affect how the script runs include the following:
28 * If you run the script as an ordinary user, it attempts to ac‐
31 quire root privileges by using the sudo command. This works on
32 Mac OS X and some Linux installations (such as under Ubuntu or
33 if you've added yourself to the sudo users list), but on some
34 Linux installations this will fail. On such systems, you should
35 run refind-install as root.
36 * Under OS X, you can run the script with a mouse by opening a
39 Terminal session and then dragging-and-dropping the refind-in‐
40 stall file to the Terminal window. You'll need to press the Re‐
41 turn or Enter key to run the script.
42 * If you're using OS X 10.7's Whole Disk Encryption (WDE) feature,
45 or the loogical volumes feature in OS X 10.10, you must install
46 rEFInd to the ESP or to a separate HFS+ partition. The default
47 in rEFInd 0.8.4 and later is to install to the ESP. If you pre‐
48 fer to use a separate HFS+ volume, the --ownhfs device-file op‐
49 tion to refind-install is required.
50 * If you're not using WDE or logical volumes, you can install rE‐
53 FInd to the OS X root (/) partition by using the --notesp option
54 to refind-install. Using this option is recommended when upgrad‐
55 ing from a working rEFInd installation in this location.
56 * If you're replacing rEFIt with rEFInd on a Mac, there's a chance
59 that refind-install will warn you about the presence of a pro‐
60 gram called /Library/StartupItems/rEFItBlesser and ask if you
61 want to delete it. This program is designed to keep rEFIt set
62 as the boot manager by automatically re-blessing it if the de‐
63 fault boot manager changes. This is obviously undesirable if you
64 install rEFInd as your primary boot manager, so it's generally
65 best to remove this program. If you prefer to keep your options
66 open, you can answer N when refind-install asks if you want to
67 delete rEFItBlesser, and instead manually copy it elsewhere. If
68 you subsequently decide to go back to using rEFIt as your pri‐
69 mary boot manager, you can restore rEFItBlesser to its place.
70 * If you intend to boot BIOS-based OSes on a UEFI-based PC, you
73 must edit the refind.conf file's scanfor line to enable the rel‐
74 evant searches. This is not necessary on Macs, though; because
75 of the popularity of dual boots with Windows on Macs, the
76 BIOS/legacy scans are enabled by default on Macs.
77 * On Linux, refind-install checks the filesystem type of the /boot
80 directory and, if a matching filesystem driver is available, in‐
81 stalls it. Note that the "/boot directory" may be on a separate
82 partition or it may be part of your root (/) filesystem, in
83 which case the driver for your root filesystem is installed.
84 This feature is unlikely to work properly from an emergency sys‐
85 tem, although it might if you have a separate /boot partition
86 and if you mount that partition at /boot in your emergency sys‐
87 tem, and the ESP at /boot/efi.
88 * On OS X, refind-install checks your partition tables for signs
91 of a Linux installation. If such a sign is found, the script in‐
92 stalls the EFI filesystem driver for the Linux ext4 filesystem.
93 This will enable rEFInd to read your Linux kernel if it's on an
94 ext2, ext3, or ext4 filesystem. Note that some configurations
95 will require a /boot/refind_linux.conf file, which can be reli‐
96 ably generated only under Linux. (The mkrlconf script that comes
97 with rEFInd will do this job once you've booted Linux.) In the
98 meantime, you can launch GRUB from rEFInd or press F2 or Insert
99 twice after highlighting the Linux option in rEFInd. This will
100 enable you to enter a root=/dev/whatever specification, where
101 /dev/whatever is the device identifier of your Linux root (/)
102 filesystem.
103 * If you run refind-install on Linux and if /boot/re‐
106 find_linux.conf doesn't already exist, refind-install creates
107 this file and populates it with a few sample entries. If /boot
108 is on a FAT partition (or HFS+ on a Mac), or if it's on an
109 ext2fs, ext3fs, ext4fs, ReiserFS, Btrfs, or HFS+ partition and
110 you install an appropriate driver, the result is that rEFInd
111 will detect your kernel and will probably boot it correctly.
112 Some systems will require manual tweaking to refind_linux.conf,
113 though -- for instance, to add dolvm to the boot options on Gen‐
114 too systems that use LVM.
115 * If you pass the --shim option to the script (along with a file‐
118 name for a Shim binary), the script sets up for a Secure Boot
119 configuration via Shim. By default, this causes the rEFInd bi‐
120 nary to be renamed as grubx64.efi. Recent versions of Shim sup‐
121 port passing the name of the follow-on program to Shim via a pa‐
122 rameter, though. If you want to use this feature, you can pass
123 the --keepname option to refind-install.
124 After you run refind-install, you should peruse the script's output to
127 ensure that everything looks OK. refind-install displays error messages
128 when it encounters errors, such as if the ESP is mounted read-only or
129 if you run out of disk space. You may need to correct such problems
130 manually and re-run the script. In some cases you may need to fall back
131 on manual installation, which gives you better control over details
132 such as which partition to use for installation.
133
136 --notesp
137 This option, which is valid only under OS X, tells refind-in‐
138 stall to install rEFInd to the OS X root partition rather than
139 to the ESP. This behavior was the default in rEFInd 0.8.3 and
140 earlier, so you may want to use it when upgrading installations
141 of that version, unless you used --esp (which is now the default
142 behavior, although the --esp option no longer exists) or --own‐
143 hfs. You may also want to use --notesp on new installations if
144 you're sure you're not using whole-disk encryption or logical
145 volumes.
146 --usedefault device-file
149 You can install rEFInd to a disk using the default/fallback
150 filename of EFI/BOOT/bootx64.efi (as well as
151 EFI/BOOT/bootia32.efi and EFI/BOOT/bootaa64.efi, if the IA-32
152 and ARM64 builds are available) using this option. The de‐
153 vice-file should be an unmounted ESP, or at least a FAT parti‐
154 tion, as in --usedefault /dev/sdc1. Your computer's NVRAM en‐
155 tries will not be modified when installing in this way. The in‐
156 tent is that you can create a bootable USB flash drive or in‐
157 stall rEFInd on a computer that tends to "forget" its NVRAM set‐
158 tings with this option. This option is mutually exclusive with
159 --notesp and --root.
160 --ownhfs device-file
163 This option should be used only under OS X. It's used to install
164 rEFInd to an HFS+ volume other than a standard Mac boot volume.
165 The result should be that rEFInd will show up in the Mac's own
166 boot manager. More importantly, suspend-to-RAM operations may
167 work correctly. Note that this option requires an HFS+ volume
168 that is not currently an OS X boot volume. This can be a data
169 volume or a dedicated rEFInd partition. The ESP might also work,
170 if it's converted to use HFS+; however, HFS+ is a non-standard
171 filesystem for an ESP, and so is not recommended.
172 --root mount-point
175 This option is intended to help install rEFInd from a "live CD"
176 or other emergency system. To use it, you should mount your reg‐
177 ular installation at /mount-point, including your /boot direc‐
178 tory (if it's separate) at /mount-point/boot and (on Linux) your
179 ESP at that location or at /mount-point/boot/efi. The refind-in‐
180 stall script then installs rEFInd to the appropriate location --
181 on Linux, /mount-point/boot/EFI/refind or
182 /mount-point/boot/efi/EFI/refind, depending on where you've
183 mounted your ESP. Under OS X, this option is useful only in con‐
184 junction with --notesp, in which case rEFInd will install to
185 /mount-point/EFI/refind. The script also adds an entry to your
186 NVRAM for rEFInd at this location. You cannot use this option
187 with --usedefault. Note that this option is not needed when do‐
188 ing a dual-boot Linux/OS X installation; just install normally
189 in OS X.
190 --nodrivers
193 Ordinarily refind-install attempts to install the driver re‐
194 quired to read /boot on Linux. This attempt works only if you're
195 using ext2fs, ext3fs, ext4fs, ReiserFS, or Btrfs on the relevant
196 partition. If you want to forego this driver installation, pass
197 the --nodrivers option. This option is implicit when you use
198 --usedefault.
199 --alldrivers
202 When you specify this option, refind-install copies all the
203 driver files for your architecture. You may want to remove un‐
204 used driver files after you use this option. Note that some com‐
205 puters hang or fail to work with any drivers if you use this op‐
206 tion, so use it with caution.
207 --shim shim-filename or --preloader preloader-filename
210 If you pass this option to refind-install, the script will copy
211 the specified shim program file to the target directory, copy
212 the MokManager.efi file from the shim program file's directory
213 to the target directory, copy the 64-bit version of rEFInd as
214 grubx64.efi, and register shim with the firmware. (If you also
215 specify --usedefault, the NVRAM registration is skipped. If you
216 also use --keepname, the renaming to grubx64.efi is skipped.)
217 When the target file is identified as PreLoader, much the same
218 thing happens, but refind-install copies HashTool.efi instead of
219 MokManager.efi and copies rEFInd as loader.efi rather than as
220 grubx64.efi. The intent is to simplify rEFInd installation on a
221 computer that uses Secure Boot; when so set up, rEFInd will boot
222 in Secure Boot mode, with one caveat: The first time you boot,
223 MokManager/HashTool will launch, and you must use it to locate
224 and install a public key or register rEFInd as a trusted appli‐
225 cation. The rEFInd public key file will be located in the rEFInd
226 directory's keys subdirectory under the name refind.cer.
227 --localkeys
230 This option tells refind-install to generate a new Machine Owner
231 Key (MOK), store it in /etc/refind.d/keys as refind_local.*, and
232 re-sign all the 64-bit rEFInd binaries with this key before in‐
233 stalling them. This is the preferable way to install rEFInd in
234 Secure Boot mode, since it means your binaries will be signed
235 locally rather than with my own key, which is used to sign many
236 other users' binaries; however, this method requires that both
237 the openssl and sbsign binaries be installed. The former is
238 readily available in most distributions' repositories, but the
239 latter is not, so this option is not the default.
240 --encryptkeys
243 Ordinarily, if you use the --localkeys option, refind-install
244 stores the local key files on your hard disk in an unencrypted
245 form. Thus, should your computer be compromised, the intruder
246 could use your own key to sign a modified boot loader, eliminat‐
247 ing the benefits of Secure Boot. If you use this option, then
248 the private key is stored in an encrypted form, secured via an
249 encryption password. You must enter this password before the key
250 can be used to sign any binary, thus reducing the risk that an
251 intruder could hijack your boot process. This is obviously a
252 highly desirable option, but the downside is that you must re‐
253 member the password and enter it whenever you update rEFInd or
254 any other program signed with your private key. This also makes
255 a fully automated update of rEFInd impossible.
256 --keepname
259 This option is useful only in conjunction with --shim. It tells
260 refind-install to keep rEFInd's regular filename (typically re‐
261 find_x64.efi) when used with shim, rather than rename the binary
262 to grubx64.efi. This change cuts down on the chance of confusion
263 because of filename issues; however, this feature requires that
264 shim be launched with a command-line parameter that points to
265 the rEFInd binary under its real name. versions of shim prior to
266 0.7 do not properly support this feature. (Version 0.4 supports
267 it but with a buggy interpretation of the follow-on loader spec‐
268 ification.) If your NVRAM variables become corrupted or are for‐
269 gotten, this feature may make rEFInd harder to launch. This op‐
270 tion is incompatible with --usedefault and is unavailable when
271 run under OS X or without the --shim option. If the script dis‐
272 covers an existing rEFInd installation under EFI/BOOT or EFI/Mi‐
273 crosoft/Boot and no other rEFInd installation when this option
274 is used, it will abort.
275 --yes This option causes the script to assume a Y input to every
278 yes/no prompt that can be generated under certain conditions,
279 such as if you specify --shim but refind-install detects no evi‐
280 dence of a Secure Boot installation. This option is intended
281 mainly for use by scripts such as those that might be used as
282 part of an installation via an RPM or Debian package.
283
286 Primary author: Roderick W. Smith (rodsmith@rodsbooks.com)
287
290 mkrlconf(8), mvrefind(8).
291 https://www.rodsbooks.com/refind/
293
296 The refind-install command is part of the rEFInd package and is avail‐
297 able from Roderick W. Smith.
298Roderick W. Smith 0.13.3 REFIND-INSTALL(8)