X-Git-Url: https://code.delx.au/refind/blobdiff_plain/1f5e6865fb9bf8ebb78b4818a6d54440c7c4004a..39f21d099c9fb310bae28b54dc68d266ed610ed7:/docs/refind/configfile.html diff --git a/docs/refind/configfile.html b/docs/refind/configfile.html index 95720e5..9fa9eaa 100644 --- a/docs/refind/configfile.html +++ b/docs/refind/configfile.html @@ -14,7 +14,8 @@

by Roderick W. Smith, rodsmith@rodsbooks.com

-

Originally written: 3/14/2012; last Web page update: 4/9/2012, referencing rEFInd 0.2.5

+

Originally written: 3/14/2012; last Web page update: +12/30/2012, referencing rEFInd 0.6.2

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!

@@ -89,7 +90,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com

-

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).

+

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.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.

@@ -97,27 +98,31 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com

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.)

+

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.

-

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:

+

In addition to hiding boot loaders, you can adjust their icons. You can do this in any of five 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 though they don't follow these rules.

+

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 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.

+

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. 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.

Adjusting the Global Configuration

@@ -144,8 +149,13 @@ timeout 20 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, label, singleuser, hwtest, arrows, hints, editor, or all + Removes the specified user interface features. banner removes the banner graphic, label removes the text description of each tag and the countdown timer, 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, hints removes the brief description of what basic keypressed do, editor disables the options editor, and all removes all of these options. You can specify multiple parameters with this option. The default is to set none of these values. + + + icons_dir + directory name + Specifies a directory in which custom icons may be found. This directory should contain files with the same names as the files in the standard icons directory. The directory name is specified relative to the directory in which the rEFInd binary resides. The standard icons directory is searched if an icon can't be found in the one specified by icons_dir, so you can use this location to redefine just some icons. banner @@ -155,32 +165,87 @@ timeout 20 selection_big filename - Specifies a graphics file that can be used to highlight the OS selection icons. This should be a 144x144 image in BMP format. + Specifies a graphics file that can be used to highlight the OS selection icons. This should be a 144x144 image in BMP format, stored in rEFInd's main directory. selection_small filename - Like selection_big, this sets an alternate highlight graphic, but for the smaller utility tags on the second row. + Like selection_big, this sets an alternate highlight graphic, but for the smaller utility tags on the second row. This should be a 64x64 image in BMP format, stored in rEFInd's main directory. 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. + shell, gptsync, apple_recovery, mok_tool, 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, apple_recovery boots the OS X Recovery HD, mok_tool launches a tool to manage Machine Owner Keys (MOKs) on systems with Secure Boot active, 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, apple_recovery, mok_tool, about, shutdown, reboot. Note that the shell, apple_recovery, mok_tool, and gptsync options all require the presence of programs not included with rEFInd. See the "Installing Additional Components" section of the Installing rEFInd page for pointers to the shell and gptsync programs. The apple_recovery option will appear only if you've got an Apple Recovery HD partition (which has a boot loader called com.apple.recovery.boot/boot.efi). See the Secure Boot page for information on Secure Boot and MOK management. 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. + none or 0 + 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. Passing any option but 0 causes text mode to be used; passing a 0 causes graphics mode to be used. (This could be useful if you want to override a text-mode setting in an included secondary configuration file.) + + + textmode + text mode number + Sets the text-mode video resolution to be used in conjunction with textonly or for the line editor and program-launch screens. This option takes a single-digit code. Mode 0 is guaranteed to be present and should be 80x25. Mode 1 is supposed to be either invalid or 80x50, but some systems use this number for something else. Higher values are system-specific. Mode 1024 is a rEFInd-specific code that means to not set any mode at all; rEFInd instead uses whatever mode was set when it launched. If you set this option to an invalid value, rEFInd pauses during startup to tell you of that fact. Note that setting textmode can sometimes force your graphics-mode resolution to a higher value than you specify in resolution. + + + resolution + one or two integer values + Sets the video resolution used by rEFInd; takes either a width and a height or a single UEFI video mode number as options. For instance, resolution 1024 768 sets the resolution to 1024x768. On UEFI systems, resolution 1 sets video mode 1, the resolution of which varies from system to system. If you set a resolution that doesn't work on a UEFI-based system, rEFInd displays a message along with a list of valid modes. On an system built around EFI 1.x (such as a Mac), setting an incorrect resolution fails silently; you'll get the system's default resolution. You'll also get the system's default resolution if you set both resolution values to 0 or if you pass anything but two numbers. (Note that passing a resolution with an x, as in 1024x768, will be interpreted as one option and so will cause the default resolution to be used.) If you get a higher resolution than you request, try commenting out or changing the textmode value, since it can force the system to use a higher graphics resolution than you specify with resolution. Also, be aware that it is possible to set a valid resolution for your video card that's invalid for your monitor. If you do this, your monitor will go blank until you've booted an OS that resets the video mode. + + + use_graphics_for + osx, linux, elilo, grub, and windows + Ordinarily, rEFInd clears the screen and displays basic boot information when launching any OS but Mac OS X. For OS X, the default behavior is to clear the screen to the default background color and display no information. You can specify the simpler Mac-style behavior by specifying the OSes or boot loaders you want to work this way with this option. (OSes that should use text-mode displays should be omitted from this list.) Note that this option doesn't affect what the boot loader does; it may display graphics, text, or nothing at all. Thus, the effect of this option is likely to last for just a fraction of a second. On at least one firmware (used on some Gigabyte boards), setting use_graphics_for linux is required to avoid a system hang when launching Linux via its EFI stub loader. + + + 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 and drivers_arch subdirectories of the rEFInd installation directory, which are 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. + 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 scan more thoroughly and actively on Macs than on UEFI-based PCs; for the latter, only options in the firmware's boot list are scanned, as described on the Using rEFInd page.) 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, manual on most systems, but internal, hdbios, external, biosexternal, optical, cd, manual on Macs. + + + scan_delay + numeric (integer) value + Imposes a delay before rEFInd scans for disk devices. Ordinarily this is not necessary, but on some systems, some disks (particularly external drives and optical discs) can take a few seconds to become available. If some of your disks don't appear when rEFInd starts but they do appear when you press the Esc key to re-scan, try uncommenting this option and setting it to a modest value, such as 2, 5, or even 10. The default is 0. + + + 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). The default value is boot, which is useful for locating Linux kernels when you have an EFI driver for your Linux root (/) filesystem. + + + dont_scan_volumes or don't_scan_volumes + filesystem label(s) + Adds the specified volume or volumes to a volume "blacklist"—these filesystems are not scanned for EFI boot loaders. This may be useful to keep unwanted EFI boot entries, such as for a Macintosh recovery partition, from appearing on the main list of boot loaders. + + + dont_scan_dirs or don't_scan_dirs + directory path(s) + Adds the specified directory or directories to a directory "blacklist"—these directories are not scanned for boot loaders. You may optionally precede a directory path with a volume name and a colon to limit the blacklist to that volume. For instance, EFI/BOOT prevents scanning the EFI/BOOT directory on all volumes, whereas ESP:EFI/BOOT blocks scans of EFI/BOOT on the volume called ESP but not on other volumes. You can use a filesystem number, as in fs0, in place of a volume name. This token may be useful to keep duplicate boot loaders out of the menu (say, if EFI/BOOT/bootx64.efi is a duplicate of another boot loader); or to keep drivers or utilities out of the boot menu, if you've stored them in a subdirectory of EFI. This option takes precedence over also_scan_dirs; if a directory appears in both lists, it will not be scanned. + + + dont_scan_files or don't_scan_files + filename(s) + Adds the specified filename or filenames to a filename "blacklist"—these files are not included as boot loader options even if they're found on the disk. This is useful to exclude support programs (such as shim.efi and MokManager.efi) and drivers from your OS list. The default value is shim.efi, MokManager.efi, TextMode.efi, ebounce.efi, GraphicsConsole.efi. + + + scan_all_linux_kernels + none or 0 + 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. Versions of rEFInd prior to 0.5.0 left this option commented out in the refind.conf-sample file, but as of version 0.5.0, this option is enabled in the default configuration file. The program default remains to not scan for such kernels, though, so you can delete or uncomment this option to keep them from appearing in your boot menu. Passing any option but 0 causes scans for all kernels to occur; passing a 0 causes these kernels to not be scanned. (This could be useful if you want to override a setting of scan_all_linux_kernels in an included secondary configuration file.) default_selection - A substring of a boot loader's title - Sets the default boot OS based on the loader's title, which appears in the main menu when you select the loader; the text reads Boot Title from Disk. You can enter any substring of Title as the default_selection, so long as it's two or more characters in length. Be sure you enter a unique substring, though; rEFInd stops searching when it finds the first match. One-character entries are matched against the first character of the title, except for digits, which refer to the numeric order of the boot loader entries. (Note: In version 0.2.0, only the first character of this entry was used, and was matched against the first character of the title.) + a substring of a boot loader's title; or a numeric position + Sets the default boot OS based on the loader's title, which appears in the main menu beneath the icons when you select the loader. You can enter any substring of the title as the default_selection, so long as it's two or more characters in length. It's best to use a unique substring, since rEFInd stops searching when it finds the first match. Because rEFInd sorts entries within a directory in descending order by file modification time, if you specify a directory (or volume name, for loaders in a partition's root directory) as the default_selection, the most recent loader in that directory will be the default. One-character entries are matched against the first character of the title, except for digits, which refer to the numeric order of the boot loader entries. + + + include + filename + Includes the specified file into the current configuration file. Essentially, the included file replaces the include line, so positioning of this token is important if the included file includes options that contradict those in the main file. The included file must reside in the same directory as the rEFInd binary and the main configuration file. This option is valid only in the main configuration file; included files may not include third-tier configuration files. @@ -192,15 +257,16 @@ timeout 20 # Sample refind.conf file timeout 5 banner custom.bmp +scan_driver_dirs drivers,EFI/tools/drivers scanfor manual,external,optical 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 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....

+

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

-

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 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 have several options, none of which is ideal: