REFIND-INSTALL(8)

REFIND-INSTALL(8) — rEFInd Manual 🎀

any later version

---

✨ NAME ✨

refind-install — installs rEFInd to the ESP and creates 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 💅

Okay so real talk, bestie: for rEFInd to actually do its thing, the rEFInd boot manager has to be installed to your computer's EFI System Partition (ESP) or some other EFI-accessible location. And most of the time you also need an NVRAM entry that says where rEFInd lives. You could do all this by hand, but refind-install is the automated bestie that handles it for you under both Linux and OS X. Fair warning though: the exact behavior and options are different depending on which OS you're on. 👑

Here are some deets that can affect how the script runs:

• If you run the script as an ordinary user, it tries to get root privileges using the sudo command. That works on Mac OS X and some Linux setups (like under Ubuntu, or if you've added yourself to the sudo users list), but on some Linux installations it will fail. On those systems, you should run refind-install as root. 👑
• On OS X, you can run the script with a mouse: open a Terminal session, then drag-and-drop the refind-install file into the Terminal window. You'll still need to press Return or Enter to actually run it. 🖱️
• 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'd rather use a separate HFS+ volume, you need the --ownhfs device-file option to refind-install. 🍓
• 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. This option is recommended when you're upgrading from a working rEFInd installation in that location. ✨
• If you're replacing rEFIt with rEFInd on a Mac, refind-install might warn you about 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. That's obviously not it if you're installing 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 manually copy it elsewhere instead. If you later 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. Not necessary on Macs, though — because dual boots with Windows on Macs are so popular, 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 that 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 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 it finds one, the script installs the EFI filesystem driver for the Linux ext4 filesystem. This lets rEFInd read your Linux kernel if it's on an ext2, ext3, or ext4 filesystem. Heads up: 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 lets you 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 /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, 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, bestie, please actually read the script's output to make sure everything looks OK. refind-install displays error messages when it hits errors — like if the ESP is mounted read-only or if you run out of disk space. You may need to fix those 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 like which partition to use for installation. 💖

✨ OPTIONS ✨

okay bestie, here's the whole menu of flags. pick your faves, no judgement 💅

• --notesp — this one is OS X only, no exceptions. it tells refind-install to put rEFInd on the OS X root partition instead of the ESP. fun fact: that was literally the default back in rEFInd 0.8.3 and earlier, so if you're upgrading an install from back then you might wanna use it — unless you used --esp (which is now the default behavior, even though the --esp option doesn't exist anymore 🙈) or --ownhfs. you might also want it on brand-new installs if you're 100% sure you're not using whole-disk encryption or logical volumes. periodt.
• --usedefault device-file — install rEFInd to a disk using the default/fallback filename EFI/BOOT/bootx64.efi — and also EFI/BOOT/bootia32.efi and EFI/BOOT/bootaa64.efi, if the IA-32 and ARM64 builds are available 🦋. the device-file should be an unmounted ESP, or at minimum a FAT partition, like so:

--usedefault /dev/sdc1

your computer's NVRAM entries will not be modified this way. the whole point is that you can make a bootable USB flash drive 📀 or install rEFInd on a computer that keeps "forgetting" its NVRAM settings (we've all met that computer). this option is mutually exclusive with --notesp and --root — pick one, bestie, you can't have both.

• --ownhfs device-file — OS X only, do not try this elsewhere. it installs rEFInd to an HFS+ volume that isn't a standard Mac boot volume. the result? rEFInd shows up in the Mac's own boot manager, and — more importantly — suspend-to-RAM operations may actually work correctly 😭. heads up: this needs an HFS+ volume that is not currently an OS X boot volume. that can be a data volume or a dedicated rEFInd partition. the ESP might also work if you convert it to HFS+, but HFS+ is a non-standard filesystem for an ESP, so it's not recommended.
• --root mount-point — this one's for installing rEFInd from a "live CD" or other emergency system, main character rescue energy 🫶. to use it, 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. then refind-install drops rEFInd in the right spot: on Linux that's /mount-point/boot/EFI/refind or /mount-point/boot/efi/EFI/refind, depending on where you mounted your ESP. under OS X this option is only useful alongside --notesp, in which case rEFInd installs to /mount-point/EFI/refind. the script also adds an NVRAM entry for rEFInd at that location ✨. you cannot use this with --usedefault. also ngl, you don't need this at all for a dual-boot Linux/OS X installation — just install normally in OS X.
• --nodrivers — normally refind-install tries to install the driver it needs to read /boot on Linux. that attempt only works if you're using ext2fs, ext3fs, ext4fs, ReiserFS, or Btrfs on the relevant partition. if you'd rather skip the whole driver installation, pass --nodrivers. it's implicit when you use --usedefault.
• --alldrivers — say the word and refind-install copies all the driver files for your architecture. you'll probably wanna delete the unused ones afterward. but — warning — some computers hang or just refuse to work with any drivers if you use this, so use it with caution ⚠️. it's giving "with great power."
• --shim shim-filename or --preloader preloader-filename — pass this and the script copies the specified shim program file to the target directory, copies the MokManager.efi file from the shim program file's directory to the target directory, copies the 64-bit version of rEFInd as grubx64.efi, and registers 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, pretty much the same thing goes down, except refind-install copies HashTool.efi instead of MokManager.efi and copies rEFInd as loader.efi rather than as grubx64.efi. the intent here is to make rEFInd installation on a Secure Boot computer less of a nightmare; set up this way, rEFInd boots in Secure Boot mode with exactly one caveat: the very first time you boot, MokManager/HashTool launches, and you must use it to locate and install a public key or register rEFInd as a trusted application 👑. the rEFInd public key file lives in the rEFInd directory's keys subdirectory, under the name refind.cer.
• --localkeys — this tells refind-install to generate a brand-new Machine Owner Key (MOK), stash it in /etc/refind.d/keys as refind_local.*, and re-sign all the 64-bit rEFInd binaries with that key before installing them 🔐. honestly this is the preferable way to install rEFInd in Secure Boot mode, because it means your binaries get signed locally instead of with the author's own key (which signs a whole bunch of other users' binaries too). downside? this method requires that both the openssl and sbsign binaries be installed. openssl is readily available in most distributions' repositories, but sbsign is not, so this option is not the default.
• --encryptkeys — okay so normally, if you use --localkeys, refind-install stores the local key files on your hard disk in an unencrypted form. meaning: if your computer gets compromised, an intruder could use your own key to sign a modified boot loader, and poof 💀 — there go the benefits of Secure Boot. use this option and the private key is stored encrypted, secured via an encryption password. you have to enter that password before the key can sign any binary, which lowers the risk of someone hijacking your boot process. obviously this is highly desirable ✨ but the downside is real: you must remember the password and type it in whenever you update rEFInd or any other program signed with your private key. it also makes a fully automated update of rEFInd impossible.
• --keepname — only useful together with --shim. it tells refind-install to keep rEFInd's regular filename (typically refind_x64.efi) when used with shim, instead of renaming the binary to grubx64.efi. this cuts down on filename-related confusion 🎀; however, this feature requires that shim be launched with a command-line parameter pointing 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 🙈.) and if your NVRAM variables get corrupted or 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. also: 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 one makes the script assume a Y input to every yes/no prompt that can pop up under certain conditions, like if you specify --shim but refind-install finds no evidence of a Secure Boot installation. it's meant mainly for scripts, like the ones that might be part of an installation via an RPM or Debian package 🤖.

---

🌸 AUTHORS 🌸

primary author: Roderick W. Smith (rodsmith@rodsbooks.com) 👑

---

🦋 SEE ALSO 🦋

mkrlconf(8), mvrefind(8), refind-sb-healthcheck(8).

https://www.rodsbooks.com/refind/

---

💖 AVAILABILITY 💖

the refind-install command is part of the rEFInd package and is available from Roderick W. Smith.

---

and that's the whole thing bestie, you made it to the end 🎉 this page is from rEFInd 0.14.2, written by Roderick W. Smith, and it's the REFIND-INSTALL(8) man page — go forth and boot responsibly, iykyk 💅✨