1REFIND-INSTALL(8)                rEFInd Manual               REFIND-INSTALL(8)
2
3
4
5any later version
6

NAME

8       refind-install - Install rEFInd to the ESP and create an NVRAM entry
9

SYNOPSIS

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
16
17

DESCRIPTION

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
27       Some details that can affect how the script runs include the following:
28
29
30       *      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
37
38       *      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
43
44       *      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
51
52       *      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
57
58       *      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
71
72       *      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
78
79       *      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
89
90       *      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
104
105       *      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
116
117       *      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
125
126       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
134

OPTIONS

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
147
148       --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
161
162       --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
173
174       --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
191
192       --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
200
201       --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
208
209       --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
228
229       --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
241
242       --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
257
258       --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
276
277       --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
284

AUTHORS

286       Primary author: Roderick W. Smith (rodsmith@rodsbooks.com)
287
288

SEE ALSO

290       mkrlconf(8), mvrefind(8).
291
292       https://www.rodsbooks.com/refind/
293
294

AVAILABILITY

296       The refind-install command is part of the rEFInd package and is  avail‐
297       able from Roderick W. Smith.
298
299
300
301Roderick W. Smith                   0.13.3                   REFIND-INSTALL(8)
Impressum