X-Git-Url: https://code.delx.au/refind/blobdiff_plain/d63a7f66945791bf980b4545f0f0edf0e1608eeb..9a669ad3b5fb341500d76d487c38a7102eb01b3d:/docs/refind/configfile.html diff --git a/docs/refind/configfile.html b/docs/refind/configfile.html index 00fdc66..2fa7a34 100644 --- a/docs/refind/configfile.html +++ b/docs/refind/configfile.html @@ -14,10 +14,11 @@
by Roderick W. Smith, rodsmith@rodsbooks.com
-Originally written: 3/14/2012; last Web page update: 3/23/2012, referencing rEFInd 0.2.2
+Originally written: 3/14/2012; last Web page update: +5/15/2014, referencing rEFInd 0.8.1
-I'm a technical writer and consultant specializing in Linux technologies. This Web page is provided free of charge and with no annoying outside ads; however, I did take time to prepare it, and Web hosting does cost money. If you find this Web page useful, please consider making a small donation to help keep this site up and running. Thanks!
+This Web page is provided free of charge and with no annoying outside ads; however, I did take time to prepare it, and Web hosting does cost money. If you find this Web page useful, please consider making a small donation to help keep this site up and running. Thanks!
Donate $2.50 | Donate $5.00 | Donate $10.00 | +Donate $20.00 | Donate another value |
Many casual users will be able to use rEFInd without making further changes; in its default configuration, the boot manager automatically detects all the EFI boot loader programs you have on your ESP (or your OS X boot partition, in the case of Macs) and displays icons for them. Sometimes, though, you may want to tweak rEFInd's configuration. Sometimes you can obtain your desired results by adjusting the filenames of your boot loaders. Other times, you can edit rEFInd's configuration file, refind.conf, which resides in the same directory as its binary file (refind.efi or whatever you've renamed it).
+Broadly speaking, rEFInd's configuration file is broken down into two sections: global options and OS stanzas. The global options section sets options that apply globally—to set the timeout period, enable graphics or text mode, and so on. OS stanzas are optional, but if present, they enable you to add new boot options or replace the auto-detected options with customized ones. Both sections include configuration lines and comment lines, the latter being denoted by a leading hash mark (#). rEFInd ignores comment lines, so you can add explanatory text. The default configuration file includes numerous comments explaining each of the options.
+Many casual users will be able to use rEFInd without making changes to its settings; in its default configuration, the boot manager automatically detects all the EFI boot loader programs you have on your ESP (or your OS X boot partition, in the case of Macs) and displays icons for them. On Macs, rEFInd also presents legacy BIOS boot options by default. Sometimes, though, you may want to tweak rEFInd's configuration. Sometimes you can obtain your desired results by adjusting the filenames of your boot loaders. Other times, you can edit rEFInd's configuration file, refind.conf, which resides in the same directory as its binary file (refind_x64.efi or whatever you've renamed it).
-ESPs use the FAT filesystem, which is case-insensitive. Unfortunately, at least one EFI implementation (Gigabyte's Hybrid EFI) contains a bug that causes string comparisons that should be case-insensitive to actually be done in a case-sensitive way. This can cause files that are present to appear to be missing. rEFInd includes code to work around this bug in some situations, but not in all of them. If boot loaders appear to be missing, try changing the case on their filenames or on the EFI directory in the ESP. (It's coded as uppercase in rEFInd; but EFI loader filename extensions are coded as lowercase .efi. I made these choices because they seem to be the most common uses on real-world installations.)
+Before delving into the configuration file, you should be aware of what you can do by renaming files. By default, rEFInd scans all the filesystems it can read for boot loaders. It scans most of the subdirectories of the EFI directory on every filesystem it can access for files with names that end in .efi. (rEFIt gives special treatment to the TOOLS subdirectory, where it looks for system tools rather than boot loaders.)
+Broadly speaking, rEFInd's configuration file is broken down into two sections: global options and OS stanzas. The global options section sets options that apply globally—to set the timeout period, enable graphics or text mode, and so on. OS stanzas are optional, but if present, they enable you to add new boot options or replace the auto-detected options with customized ones. Both sections include configuration lines and comment lines, the latter being denoted by a leading hash mark (#). rEFInd ignores comment lines, so you can add explanatory text. The default configuration file includes numerous comments explaining each of the options.
+ + +ESPs use the FAT filesystem, which is case-insensitive. Unfortunately, at least one EFI implementation (Gigabyte's Hybrid EFI) contains a bug that causes string comparisons that should be case-insensitive to actually be done in a case-sensitive way. This can cause files that are present to appear to be missing. rEFInd includes code to work around this bug in some situations, but not in all of them. If boot loaders appear to be missing, try changing the case on their filenames or on the EFI directory in the ESP. (It's coded as uppercase in rEFInd; but EFI loader filename extensions are coded as lowercase .efi. I made these choices because they seem to be the most common uses on real-world installations.)
+ +Before delving into the configuration file, you should be aware of what you can do by renaming files. By default, rEFInd scans all the filesystems it can read for boot loaders. It scans most of the subdirectories of the EFI directory on every filesystem it can access for files with names that end in .efi. (rEFInd gives special treatment to the tools subdirectory, where it looks for system tools rather than boot loaders.)
If you're like me, you may sometimes want to hide a boot loader from rEFInd's menu for a brief period—say, because you're testing a variety of configurations but you don't want them all to clutter the menu at once. You might also want to hide a boot loader if you want to override its default settings using a custom entry in refind.conf and you don't want an automatic search to duplicate that entry. You can easily hide a boot loader by removing or changing its .efi filename extension—for instance, changing grub.efi to grub.
Another way to hide a boot loader is to move it into rEFInd's own directory. In order to keep rEFInd from showing up in its own menu, it ignores boot loaders in its own directory. This obviously includes the rEFInd binary file itself, but also anything else you might store there.
+You can also use the dont_scan_volumes, dont_scan_dirs, and dont_scan_files tokens in refind.conf to hide entire volumes, directories, and individual files, respectively. Note that dont_scan_volumes works with both EFI and legacy scans, whereas the other two options make sense for hiding only EFI-mode boot loaders.
+ + +In addition to hiding boot loaders, you can adjust their icons. You can do this in any of seven ways for auto-detected boot loaders:
+ +As a special case, rEFInd assigns icons to the Windows and OS X boot loaders based on their conventional locations, so they get suitable icons even if they don't follow these rules.
+ +In addition to the main OS tag icon, you can set the badge icon for a volume by creating a file called .VolumeBadge.icns or .VolumeBadge.png in the root directory of a partition. If present, it replaces the disk-type icons that are overlaid on the main OS icon. If you use this feature, the badge is applied to all the boot loaders read from the disk, not just those stored in the root directory or the Apple boot loader location. You could use this feature to set a custom badge for different specific disks or to help differentiate multiple OS X installations on one computer. If you don't want any badges, you can replace the three badge icons in the rEFInd icons subdirectory (vol_external.icns, vol_internal.icns, and vol_optical.icns) with a completely transparent badge. The transparent.icns file in the rEFInd icons directory may be used for this purpose.
+ +The default icon sizes are 128x128 pixels for OS icons, 48x48 pixels for the second-row tools, and 32x32 pixels for badges. You can change the sizes of the big OS icons and the small tool icons with the big_icon_size and small_icon_size tokens in refind.conf, as noted in Table 1. The size of the disk-type badges is 1/4 the size of OS icons.
+ +You can adjust many of rEFInd's options by editing its refind.conf file. You can use any text editor you like for the job, but be sure it saves the file in plain ASCII text, not in a word processing format. (In theory, a UTF-16 encoding should also work, but I've not tried that myself.) Note that the EFI shell includes its own editor. If you need to make a change before you launch an OS, you can launch a shell, change to the rEFInd directory, and type edit refind.conf to edit the file. This EFI editor is quite primitive, but it gets the job done. After editing, you'll need to reboot for rEFInd to read the changed configuration file.
+You can adjust many of rEFInd's options by editing its configuration file. This file is called refind.conf by default; but you can use another filename by passing -c filename as an option, as in refind_x64.efi -c myrefind.conf to use myrefind.conf in rEFInd's main directory. You can specify a configuration file in another directory, but to do so, you must use backslashes as directory separators, as in -c \EFI\other\refind.conf. This feature is intended for users who want to have rEFInd appear in its own menu, with the version launched in this way behaving differently from the original—for instance, to have a secondary rEFInd that provides boot options hidden by the main one. In this scenario, the default refind.conf would have a manual boot stanza defining the new rEFInd instance, including its -c option.
+ +You can use any text editor you like to edit refind.conf, but be sure it saves the file in plain ASCII text, not in a word processing format. (In theory, a UTF-16 encoding should also work, but this has been poorly tested.) Note that the EFI shell includes its own editor. If you need to make a change before you launch an OS, you can launch a shell, change to the rEFInd directory, and type edit refind.conf to edit the file. This EFI editor is quite primitive, but it gets the job done. After editing, you'll need to reboot or re-launch rEFInd for rEFInd to read the changed configuration file.
Global configuration file options consist of a name token followed by one or more parameters, as in:
@@ -131,62 +228,167 @@ timeout 20As an example, consider the following refind.conf file:
+Prior to version 0.2.4, rEFInd supported a token called disable, whose function partially overlapped with hideui. Version 0.2.4 merges many of the features of these two tokens into hideui and creates the new showtools option, which provides the remaining functionality in a more flexible way.
+ +As an example of rEFInd configuration, consider the following refind.conf file:
# Sample refind.conf file timeout 5 banner custom.bmp +scan_driver_dirs drivers,EFI/tools/drivers scanfor manual,external,optical -default_selection L +default_selection elilo-
This example sets a timeout of 5 seconds; loads a custom graphic file called custom.bmp from the directory in which refind.efi resides; uses manual boot loader configuration but also scans for external EFI boot loaders and EFI boot loaders on optical discs; and sets the default boot loader to Linux. Of course, since this file specifies use of manual boot loader configuration, it's not complete; you'll need to add at least one OS stanza to be able to boot from anything but an external disk or optical drive....
+This example sets a timeout of 5 seconds; loads a custom graphic file called custom.bmp from the directory in which the rEFInd binary resides; scans the drivers and EFI/tools/drivers directories for EFI drivers; uses manual boot loader configuration but also scans for external EFI boot loaders and EFI boot loaders on optical discs; and sets the default boot loader to the first loader found that includes the string elilo. Of course, since this file specifies use of manual boot loader configuration, it's not complete; you'll need to add at least one OS stanza to be able to boot from anything but an external disk or optical drive, as described shortly.
+OS stanzas in rEFInd are similar to those in GRUB Legacy, GRUB 2, or ELILO. You can use them to add configuration options to those that are auto-detected. You cannot modify the auto-detected options, though; if you just want to tweak one OS's configuration, you has several options, none of which is ideal:
+OS stanzas in rEFInd are similar to those in GRUB Legacy, GRUB 2, or ELILO. You can use them to add EFI boot loaders to those that are auto-detected. rEFInd does not yet support manual boot stanzas for BIOS-mode boot loaders. You also cannot modify the auto-detected options; if you just want to tweak one OS's configuration, you have several options, none of which is ideal:
This example sets up two entries: one for Ubuntu Linux and one for Gentoo Linux. Note that the two entries use different directory separators, simply to demonstrate the fact that it's possible. The Ubuntu entry sets no icon, since rEFInd will note that the boot loader is stored in the ubuntu directory, and it will automatically find the appropriate Ubuntu icon (os_ubuntu.icns). This option is, however, disabled, so no matching icon will appear when you reboot unless you first comment out or delete the disabled line.
+This example sets up three entries: one for Ubuntu Linux, one for Gentoo Linux, and one to launch a shell script. Note that the first two entries use different directory separators, simply to demonstrate the fact that it's possible. The Ubuntu entry sets no icon, since rEFInd will note that the boot loader is stored in the ubuntu directory, and it will automatically find the appropriate Ubuntu icon (os_ubuntu.icns). This option is, however, disabled, so no matching icon will appear when you reboot unless you first comment out or delete the disabled line.
+ +Tip: Under Linux, you can learn a filesystem's label by using blkid, as in blkid /dev/sda1. The filesystem's label, if set, is identified by the keyword LABEL in the output. Some versions also return the partition's label and partition GUID (referred to as PARTUUID by blkid). You can obtain the partition's name and unique GUID using sgdisk, as in sgdisk -i 1 /dev/sda to find the data on /dev/sda1.
+ +The Gentoo entry begins with an icon specification to be sure that the icon is loaded from the same volume as rEFInd. (If the icon were stored on the same filesystem as the kernel, you'd place the icon line after the volume line.) This entry uses the volume token to tell rEFInd to load the kernel and initial RAM disk file from the filesystem or partition called G_KERNELS. It passes the filename for an initial RAM disk using the initrd line and free-form options using the options line. Note that the kernel filename does not include a .efi extension, which keeps rEFInd from picking up the kernel file in its auto-scans.
+ +The Windows via shell script entry may seem puzzling, but its purpose is to launch an OS (Windows in this case) after performing additional pre-boot initialization, which is handled by an EFI shell script. This works because you can pass the name of a shell script to an EFI shell—the script is named on the stanza's options line, using EFI file notation. The shell script, in turn, does whatever it needs to do and then launches the OS's boot loader:
-The Gentoo entry passes the filename for an initial RAM disk using the initrd line and free-form options using the option line. It also sets an icon name, since the path to the kernel doesn't include the distribution's name. Note that the kernel filename does not include a .efi extension, which keeps rEFInd from picking up the kernel file in its auto-scans.
+mm 0003003E 8 -pci +fs0:\EFI\Microsoft\Boot\bootmgfw.efi-
You can combine these OS stanzas with the global refind.conf options presented earlier. The result would contain just one entry on the rEFInd boot menu, unless rEFInd found other boot options on an external or optical disk.
+This example writes data to the computer's PCI bus via the EFI shell's mm command and then launches Windows. Chances are you won't need to engage in such operations, and I do not recommend you try this exact example unless you know what you're doing! This command was required to activate the video hardware on a computer of a person with whom I corresponded prior to booting Windows, but such needs are rare. Another example of a similar approach can be found in this forum thread. A few pointers on finding addresses for your hardware can be found in this post.
-Presently, an important limitation of rEFInd is that the manual boot loader definitions can only read files on the partition from which rEFInd launched. rEFInd can, however, auto-detect boot loaders on other disks or partitions via the internal, external, and similar options.
+You can combine these OS stanzas with the global refind.conf options presented earlier. The result would contain just two entries on the rEFInd boot menu (for Gentoo and Windows, since the Ubuntu entry is disabled), unless rEFInd found other boot options on an external or optical disk.
+As described on the Using rEFInd page, rEFInd can present a menu of options for certain loader tags when you press the Insert, F2, or + key. rEFInd does this automatically when it detects Mac OS X or ELILO boot loaders, or when you set the OS type via the ostype option. The Mac OS X boot loader, in particular, accepts various options that you can use to boot in various ways.
@@ -297,7 +520,7 @@ menuentry Gentoo {The following menu entry illustrates the use of submenu entries. This is an expansion on the second entry presented earlier:
+The following menu entry illustrates the use of submenu entries. This is a variant of the second entry presented earlier:
menuentry Gentoo { @@ -373,7 +596,7 @@ menuentry Gentoo {
-copyright © 2012 by Roderick W. Smith
+copyright © 2012–2014 by Roderick W. Smith
This document is licensed under the terms of the GNU Free Documentation License (FDL), version 1.3.
@@ -381,7 +604,7 @@ menuentry Gentoo { -Learn about methods of booting Linux with rEFInd
+Learn about how to use EFI drivers with rEFInd
Return to my main Web page.