X-Git-Url: https://code.delx.au/refind/blobdiff_plain/5664ed3ea160466286aa2c5711f8094b0ec7003b..c9ff72d4b0e75b0683497678aff962911a9364fe:/docs/refind/configfile.html
diff --git a/docs/refind/configfile.html b/docs/refind/configfile.html
index 9c3b9b1..354349e 100644
--- a/docs/refind/configfile.html
+++ b/docs/refind/configfile.html
@@ -14,7 +14,7 @@
by Roderick W. Smith, rodsmith@rodsbooks.com
- Originally written: 3/14/2012; last Web page update: 3/26/2012, referencing rEFInd 0.2.3
+ Originally written: 3/14/2012; last Web page update: 4/19/2012, referencing rEFInd 0.2.7
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!
@@ -93,13 +93,9 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com
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.
-Hiding EFI Boot Loaders
+Hiding and Displaying EFI Boot Loaders
-
+
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.)
@@ -107,6 +103,22 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com
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.
+In addition to hiding boot loaders, you can adjust their icons. You can do this in any of three ways for auto-detected boot loaders:
+
+
+
+- You can place a boot loader in a directory with a name that matches one of rEFInd's standard icons, which take names of the form os_name.icns. To use this icon, you would place the boot loader in the directory called name.
+
+- You can name an icon file after your boot loader, but with an extension of .icns. For instance, if you're using loader.efi, you would name the icon file loader.icns. These icon files should be 128x128 images in Apple's ICNS format. You can create such files easily in OS X or convert PNG files to ICNS format with libicns. Note that the scan_all_linux_kernels option can cause loader-specific icon files for Linux kernels (but not other loaders) to be improperly assigned loader tags, so if you want to use this option, you should not also assign your kernels custom icons in this way.
+
+- If you're booting OS X from its standard boot loader, or if you place a boot loader file in the root directory of a partition, you can create a file called .VolumeIcon.icns that holds an icon file. OS X uses this file for its volume icons, so rEFInd picks up these icons automatically, provided they include 128x128 bitmaps.
+
+
+
+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 though 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 in the root directory of a partition. This icon file must include a 32x32 bitmap. 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.
+
Adjusting the Global Configuration
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.
@@ -131,9 +143,9 @@ timeout 20
Sets the timeout period in seconds. If 0, the timeout is disabled—rEFInd waits indefinitely for user input. |
- | disable |
- shell, tools, singleuser, hwtest, or all |
- Removes the specified menu options for improved security. shell removes the EFI shell, tools removes all the EFI tools, singleuser removes the single-user option from the Mac OS sub-menu, hwtest removes the Mac OS hardware test option, and all removes all of these options. You can specify multiple parameters with this option. The default is to set none of these options. |
+ hideui |
+ banner, label, singleuser, hwtest, arrows, or all |
+ Removes the specified user interface features. banner removes the banner graphic, label removes the text description of each tag, singleuser removes the single-user option from the Mac OS sub-menu, hwtest removes the Mac OS hardware test option, arrows removes the arrows to the right or left of the OS tags when rEFInd finds too many OSes to display simultaneously, and all removes all of these options. You can specify multiple parameters with this option. The default is to set none of these values. |
| banner |
@@ -151,20 +163,35 @@ timeout 20
Like selection_big, this sets an alternate highlight graphic, but for the smaller utility tags on the second row. |
- | hideui |
- banner, shell, tools, funcs, label, or all |
- Hides the specified user interface elements: The rEFInd logo, the EFI shell icon, all the tools, built-in functions (restart and about), text labels, and all of the above, respectively. Some of these parameters are redundant with disable parameters. The default is to set none of these options. |
+ showtools |
+ shell, gptsync, about, exit, shutdown, and reboot |
+ Specifies which tool tags to display on the second row. shell launches an EFI shell, gptsync launches a tool that creates a hybrid MBR, about displays information about the program, exit terminates rEFInd, shutdown shuts down the computer (or reboots it, on UEFI PCs), and reboot reboots the computer. The tags appear in the order in which you specify them. The default is shell, about, shutdown, reboot. |
| textonly |
None |
rEFInd defaults to a graphical mode; however, if you prefer to do without the flashy graphics, you can run it in text mode by including this option. |
+
+ | scan_driver_dirs |
+ directory path(s) |
+ Scans the specified directory or directories for EFI driver files. If rEFInd discovers .efi files in those directories, they're loaded and activated as drivers. This option sets directories to scan in addition to the drivers subdirectory of the rEFInd installation directory, which is always scanned, if present. |
+
| scanfor |
internal, external, optical, hdbios, biosexternal, cd, and manual |
Tells rEFInd what methods to use to locate boot loaders. The internal, external, and optical parameters tell rEFInd to scan for EFI boot loaders on internal, external, and optical (CD, DVD, and Blu-ray) devices, respectively. The hdbios, biosexternal, and cd parameters are similar, but scan for BIOS boot loaders. (Note that the BIOS options are likely to be useless on UEFI PCs.) The manual parameter tells rEFInd to scan the configuration file for manual settings. You can specify multiple parameters to have the program scan for multiple boot loader types. When you do so, the order determines the order in which the boot loaders appear in the menu. The default is internal, external, optical. |
+
+ | also_scan_dirs |
+ directory path(s) |
+ Adds the specified directory or directories to the directory list that rEFInd scans for EFI boot loaders when scanfor includes the internal, external, or optical options. Directories are specified relative to the filesystem's root directory. If this option is used, it's applied to all the filesystems that rEFInd scans. If a specified directory doesn't exist, rEFInd ignores it (no error results). |
+
+
+ | scan_all_linux_kernels |
+ None |
+ When set, causes rEFInd to add Linux kernels (files with names that begin with vmlinuz or bzImage) to the list of EFI boot loaders, even if they lack .efi filename extensions. The hope is that this will simplify use of rEFInd on distributions that provide kernels with EFI stub loader support but that don't give those kernels names that end in .efi. Of course, the kernels must still be stored on a filesystem that rEFInd can read, and in a directory that it scans. (Drivers and the also_scan_dirs options can help with those issues.) Note that this option can cause unwanted files to be improperly detected and given loader tags, such as older kernels without EFI stub loader support and .icns files used to give kernels unique icons. For this reason, it's disabled by default. |
+
| default_selection |
A substring of a boot loader's title |
@@ -172,17 +199,20 @@ timeout 20
-As 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 refind.efi 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.
Creating OS Stanzas
@@ -211,15 +241,20 @@ default_selection L
name for the entry |
Sets the name that's displayed along with the icon for this entry. If the name should contain a space, it must be enclosed in quotes. Following the name, an open curly brace ({) ends the menuentry line. |
+
+ | volume |
+ filesystem label |
+ Sets the volume that's used for subsequent file accesses (by icon and loader, and by implication by initrd if loader follows volume). You pass this token a filesystem's label or a volume number. A filesystem label is typically displayed under the volume's icon in file managers and that rEFInd displays on its menu at the end of the boot prompt string. If this label isn't unique, the first volume with the specified label is used. The matching is nominally case-insensitive, but on some EFIs it's case-sensitive. If a filesystem has no label, you can use a volume number followed by a colon, such as 0: to refer to the first filesystem or 1: to refer to the second. The assignment of numbers is arbitrary and may not be consistent across boots, though. It might change if you insert an optical disc or plug in a USB flash drive, for instance. If this option is not set, the volume defaults to the one from which rEFInd launched. |
+
| loader |
filename |
- Sets the filename for the boot loader. You may use either Unix-style slashes (/) or Windows/EFI-style backslashes (\) to separate directory elements. In either case, the references are to files on the ESP from which rEFInd launched; you can't (yet) launch loaders from other locations. This option should normally be the first in the body of an OS stanza; if it's not, some other options may be ignored. |
+ Sets the filename for the boot loader. You may use either Unix-style slashes (/) or Windows/EFI-style backslashes (\) to separate directory elements. In either case, the references are to files on the ESP from which rEFInd launched or to the one identified by a preceding volume token. This option should normally be the first in the body of an OS stanza; if it's not, some other options may be ignored. An exception is if you want to boot a loader from a volume other than the one on which rEFInd resides, in which case volume should precede loader. |
| initrd |
filename |
- Sets the filename for a Linux kernel's initial RAM disk (initrd). This option is useful only when booting a Linux kernel that includes an EFI stub loader, which enables you to boot a kernel without the benefit of a separate boot loader. When booted in this way, though, you must normally pass an initrd filename to the boot loader. You must specify the complete EFI path to the initrd file with this option, as in initrd EFI/linux/initrd-3.3.0-rc7.img. You'll also have to use the options line to pass the Linux root filesystem, and perhaps other options (as in options "root=/dev/sda4 ro"). |
+ Sets the filename for a Linux kernel's initial RAM disk (initrd). This option is useful only when booting a Linux kernel that includes an EFI stub loader, which enables you to boot a kernel without the benefit of a separate boot loader. When booted in this way, though, you must normally pass an initrd filename to the boot loader. You must specify the complete EFI path to the initrd file with this option, as in initrd EFI/linux/initrd-3.3.0-rc7.img. You'll also have to use the options line to pass the Linux root filesystem, and perhaps other options (as in options "root=/dev/sda4 ro"). The initial RAM disk file must reside on the same volume as the kernel. |
| icon |
@@ -234,7 +269,7 @@ default_selection L
| graphics |
on or off |
- Enables or disables a graphical boot mode. This option is important only for Mac OS X. |
+ Enables or disables a graphical boot mode. This option has an effect only on Macintoshes; UEFI PCs seem to be unaffected by it. |
| options |
@@ -262,20 +297,21 @@ menuentry "Ubuntu Linux" {
}
menuentry Gentoo {
- loader \EFI\linux\bzImage-3.3.0-rc7
- initrd \EFI\linux\initrd-3.3.0-rc7.img
- options "root=/dev/sda3 ro"
icon \EFI\refind\icons\os_gentoo.icns
+ volume G_KERNELS
+ loader \kernels\bzImage-3.3.0-rc7
+ initrd \kernels\initrd-3.3.0-rc7.img
+ options "root=/dev/sda3 ro"
}
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.
-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.
+
-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.
+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 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.
-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 one entry on the rEFInd boot menu, unless rEFInd found other boot options on an external or optical disk.
Creating Submenu Entries
@@ -297,7 +333,7 @@ menuentry Gentoo {
| loader |
filename |
- Sets the filename for the boot loader, as described in Table 2. |
+ Sets the filename for the boot loader, as described in Table 2. Note that the loader is read from whatever filesystem is specified by the main stanza's volume option, provided that option precedes the submenu definition. |
| initrd |
@@ -326,7 +362,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 {
@@ -381,7 +417,7 @@ menuentry Gentoo {
Go to the main rEFInd page
-Learn about methods of booting Linux with rEFInd
+Learn about how to use EFI drivers with rEFInd
Return to my main Web page.