X-Git-Url: https://code.delx.au/refind/blobdiff_plain/4677259a82b13dd1ab9fb6696d0ffe8976aeae34..2a6ed1155086a30aaa01ced44b559183e7521083:/docs/refind/configfile.html
diff --git a/docs/refind/configfile.html b/docs/refind/configfile.html
index c246c43..a93cd73 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/9/2014, referencing rEFInd 0.7.8
+5/15/2014, referencing rEFInd 0.8.1
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!
@@ -168,11 +168,13 @@ 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.
+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.
+
Setting OS Icons
-In addition to hiding boot loaders, you can adjust their icons. You can do this in any of six ways for auto-detected 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:
@@ -184,9 +186,11 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com
- You can give the filesystem from which the boot loader is loaded a name that matches the OS name component of the icon filename. For instance, if you call your boot filesystem CentOS, it matches the os_centos.icns icon. This match is performed on a word-by-word basis within the name, with "words" being delimited by spaces, dashes (-), and underscores (_). Thus, a volume called Debian-boot will match os_debian.icns or os_boot.icns.
-- Certain boot loaders have hard-coded icons associated with them. For instance, filenames beginning with vmlinuz or bzImage acquire Linux "Tux" icons and the bootmgfw.efi loader acquires a Windows icon. For the most part, these are the associations you want to overcome with the preceding rules, but sometimes renaming a boot loader to a more conventional name is the better approach.
+- You can give the GPT partition from which the boot loader is loaded a name that matches the OS name component of the icon filename. This works much like the previous method, except that you'd use a tool like gdisk or parted to set the partition's name, rather than tune2fs or GParted to set the filesystem's name.
+
+- rEFInd attempts to guess the Linux distribution based on data in the /etc/os-release file. This file will only be accessible if a separate /boot partition is not used, though. Manually adjusting the os-release file to change an OS icon in rEFInd is not recommended.
-- rEFInd attempts to guess the Linux distribution based on clues in the kernel's filename and data in the /etc/os-release file. This file will only be accessible if a separate /boot partition is not used, though. Fedora and Red Hat kernels can be identified by the presence of .fc or .el strings in their filenames, and so acquire suitable icons automatically. Manually adjusting the os-release file to change an OS icon in rEFInd is not recommended. Renaming a locally-compiled kernel so that it acquires a Fedora or Red Hat icon is reasonable, but I don't recommend renaming precompiled kernels unless you also manually copy them to the ESP.
+- Certain boot loaders have hard-coded icons associated with them. For instance, filenames beginning with vmlinuz or bzImage acquire Linux "Tux" icon and the bootmgfw.efi loader acquires a Windows icon. Fedora and Red Hat kernels can be identified by the presence of .fc or .el strings in their filenames, and so acquire suitable icons automatically. For the most part, these are the associations you want to overcome with the preceding rules, but sometimes renaming a boot loader to a more conventional name is the better approach. Renaming a locally-compiled kernel so that it acquires a Fedora or Red Hat icon is reasonable, but I don't recommend renaming precompiled kernels unless you also manually copy them to the ESP.
@@ -270,8 +274,8 @@ timeout 20
| showtools |
- 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. |
+ shell, memtest, gdisk, 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, gdisk launches the partitioning tool of the same name, 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, gdisk, 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 |
@@ -320,8 +324,8 @@ timeout 20
| 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", LRS_ESP, to keep the Mac OS X and Lenovo Windows recovery volumes from appearing. (These should get their 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. |
+ filesystem or partition 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", LRS_ESP, to keep the Mac OS X and Lenovo Windows recovery volumes from appearing. (These should get their 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. You can use dont_scan_volumes to hide disks or partitions from legacy-mode scans, too. In this case, you can enter any part of the description that appears beneath the icons to hide entries that include the string you specify. |
| dont_scan_dirs or don't_scan_dirs |
@@ -341,7 +345,7 @@ timeout 20
| 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.) |
+ 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. This simplifies use of rEFInd on most Linux distributions, which usually provide kernels with EFI stub loader support but 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.) 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 |
@@ -379,7 +383,7 @@ default_selection elilo
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 have 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:
@@ -406,8 +410,8 @@ default_selection elilo
| 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. |
+ filesystem label, partition label, GUID value, or filesystem number |
+ 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, a partition's label, a partition's GUID, or a volume number. A filesystem or partition label is typically displayed under the volume's icon in file managers and rEFInd displays it 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 partition GUID number. You can also 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 |
@@ -476,9 +480,9 @@ menuentry "Windows via shell script" {
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.
-
+
-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.
+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: