X-Git-Url: https://code.delx.au/refind/blobdiff_plain/a9871b0532ef974ab83c95a62ff70dcb979c99b4..0189958c722bdd4e7f323d59f81e25579bb0aad2:/docs/refind/configfile.html diff --git a/docs/refind/configfile.html b/docs/refind/configfile.html index 587adba..248af25 100644 --- a/docs/refind/configfile.html +++ b/docs/refind/configfile.html @@ -15,7 +15,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com

Originally written: 3/14/2012; last Web page update: -3/18/2013, referencing rEFInd 0.6.8

+12/15/2013, referencing rEFInd 0.7.6

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!

@@ -26,49 +26,87 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com

Donate $2.50 Donate $5.00 Donate $10.00 +Donate $20.00 Donate another value -
- + + + + - + + - + + + +Donate with PayPal
- -
- + + + + - + + - + + + +Donate with PayPal
- -
- + + + + + - + + - + + + +Donate with PayPal
- -
- + + + + - + + - + + + +Donate with PayPal
+ + +
+ + + + + + + + + +Donate with PayPal +
+
@@ -82,7 +120,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com

Donate with PayPal
- +
@@ -152,7 +190,9 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com

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.

+

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:

@@ -173,6 +213,11 @@ timeout 20 numeric value Sets the timeout period in seconds. If 0, the timeout is disabled—rEFInd waits indefinitely for user input. + + screensaver + numeric value + Sets the number of seconds of inactivity before the screen blanks to prevent burn-in. The display returns after most keypresses (unfortunately, not including modifiers such as Shift, Control, Alt, or Option). The default is 0, which disables this feature. Setting this token to -1 causes a blank display until the timeout value passes or you press a key. + hideui banner, label, singleuser, safemode, hwtest, arrows, hints, editor, or all @@ -200,8 +245,8 @@ timeout 20 showtools - 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. + shell, memtest, gptsync, apple_recovery, mok_tool, about, exit, shutdown, reboot, and firmware + Specifies which tool tags to display on the second row. shell launches an EFI shell, memtest (or memtest86 launches the Memtest86 program, gptsync launches a tool that creates a hybrid MBR, apple_recovery boots the OS X Recovery HD, windows_recovery boots a Windows recovery tool, 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 some UEFI PCs), reboot reboots the computer, and firmware reboots the computer into the computer's own setup utility. The tags appear in the order in which you specify them. The default is shell, memtest, apple_recovery, mok_tool, about, shutdown, reboot, firmware. Note that the shell, memtest, apple_recovery, and mok_tool options all require the presence of programs not included with rEFInd. The gptsync option requires use of a like-named program which, although it ships with rEFInd 0.6.9 and later, is not installed by default except under OS X. See the "Installing Additional Components" section of the Installing rEFInd page for pointers to the shell, Memtest86, 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). The firmware option works only on computers that support this option; on other computers, the option is quietly ignored. See the Secure Boot page for information on Secure Boot and MOK management. font @@ -226,7 +271,7 @@ timeout 20 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. + 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. To add to the default list, specify + as the first option, as in use_graphics_for + windows. scan_driver_dirs @@ -246,32 +291,42 @@ timeout 20 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. You may precede a directory path with a volume name and colon, as in somevol:/extra/path, to restrict the extra scan to a single volume. A volume number, preceded by fs, can be used for volumes that lack names, as in fs1:/extra/path. If you don't specify a volume name or number, this option is 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. + 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. You may precede a directory path with a volume name and colon, as in somevol:/extra/path, to restrict the extra scan to a single volume. A volume number, preceded by fs, can be used for volumes that lack names, as in fs1:/extra/path. If you don't specify a volume name or number, this option is 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. To add to, rather than replace, the default value, specify + as the first item in the list, as in also_scan_dirs +,loaders. 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. The default value is Recovery HD, to keep the Mac recovery volume from appearing. (It should get its own tools icon instead—see the showtools token.) + 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. The default value is Recovery HD, to keep the Mac recovery volume from appearing. (It should get its own tools icon instead—see the showtools token.) Note that on a Macintosh with whole-disk encryption, you may need to uncomment this token and leave "Recovery HD" off the list to boot the system. 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; otherwise all volumes are affected. 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; 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. + 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; otherwise all volumes are affected. 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; 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. To add directories to the default list rather than replace the list, specify + as the first option, as in dont_scan_dirs + EFI/dontscan. 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, HashTool.efi, TextMode.efi, ebounce.efi, GraphicsConsole.efi. + 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, shim-fedora.efi, shimx64.efi, PreLoader.efi, TextMode.efi, ebounce.efi, GraphicsConsole.efi, MokManager.efi, HashTool.efi, HashTool-signed.efi. To add files to the default list rather than replace the list, specify + as the first option, as in dont_scan_files + badloader.efi. + + + windows_recovery_files + filename(s) + Adds the specified filename or filenames to list that will be recognized as Windows recovery tools and presented as such on the second row, if windows_recovery is among the options to showtools. The filename must include a complete path and may optionally include a filesystem label, as in LRS_EFI:\EFI\Microsoft\Boot\LrsBootmgr.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.) + + max_tags + numeric (integer) value + Limits the number of tags that rEFInd will display at one time. If rEFInd discovers more loaders than this value, they're shown in a scrolling list. The default value is 0, which imposes no limit. + default_selection - 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. + a substring of a boot loader's title, or a numeric position; optionally followed by two times in HH:MM format + 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. If you specify a comma-delimited list of names in quotation marks, rEFInd will search on these in turn until it finds a match. For instance, default_selection "alpha,beta" will launch alpha if it's available, and beta if alpha is not available but beta is. You may optionally follow the match string by two times, in 24-hour format, in which case the entry applies only between those two times. For instance, default_selection Safety 1:30 2:30 boots the entry called Safety by default between the hours of 1:30 and 2:30. These times are specified in whatever format the motherboard clock uses (local time or UTC). If the first value is larger than the second, as in 23:00 1:00, it is interpreted as crossing midnight—11:00 PM to 1:00 AM in this example. The last default_selection setting takes precedence over preceding ones if the time value matches. Thus, you can set a main default_selection without a time specification and then set one or more others to override the main setting at specific times. include