X-Git-Url: https://code.delx.au/refind/blobdiff_plain/b06865fd80f51e75b573269f6f987a845da4648f..7c8edbc48e5df2c1f20968dd4949703621252297:/docs/refind/configfile.html diff --git a/docs/refind/configfile.html b/docs/refind/configfile.html index caae10f..47a9883 100644 --- a/docs/refind/configfile.html +++ b/docs/refind/configfile.html @@ -17,7 +17,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com
Originally written: 3/14/2012; last Web page update: -9/19/2015, referencing rEFInd 0.9.2
+12/12/2015, referencing rEFInd 0.10.1This 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!
@@ -43,8 +43,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com - - + @@ -58,8 +57,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com - - + @@ -74,8 +72,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com - - + @@ -89,8 +86,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com - - + @@ -104,8 +100,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com - - + @@ -118,8 +113,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com - - + @@ -132,7 +126,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.comMany 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 EFI System Partition (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).
+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 EFI System Partition (ESP) (or your OS X boot partition, in the case of Macs) in conventional locations 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).
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 adjust many of rEFInd's options by editing its configuration file, which is called refind.conf. You must first find this file, though. It is located in the rEFInd directory. On a UEFI-based PC, this directory will be located on the EFI System Partition (ESP), which can be in any number of places:
+ +As a further twist, on Macs rEFInd can exist on its own partition or on the main OS X partition, depending on the version of rEFInd you've installed and the options you passed to the installation script. rEFInd has installed to the ESP by default since version 0.8.4. rEFInd typically lives on the ESP in the EFI/refind directory, or sometimes in EFI/BOOT or elsewhere. Thus, the rEFInd configuration file might be /boot/efi/EFI/refind/refind.conf, /boot/EFI/BOOT/refind.conf, /Volumes/ESP/EFI/refind/refind.conf, S:\EFI\refind\refind.conf, or something else, depending on your OS and mount point.
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.
@@ -278,8 +286,8 @@ timeout 20Prior 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:
@@ -486,48 +497,48 @@ default_selection eliloAs an example, consider the following entries:
-menuentry "Ubuntu Linux" { +menuentry "Ubuntu" { loader /EFI/ubuntu/grubx64.efi disabled } -menuentry Gentoo { - 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 +menuentry Arch { + icon /EFI/refind/icons/os_arch.png + volume ARCHBOOT + loader /vmlinuz-linux + initrd /initramfs-linux.img options "root=/dev/sda3 ro" } menuentry "Windows via shell script" { - icon \EFI\refind\icons\os_win.icns + icon \EFI\refind\icons\os_win.png loader \EFI\tools\shell.efi options "fs0:\EFI\tools\launch_windows.nsh" }-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.
+This example sets up three entries: one for Ubuntu, one for Arch Linux, and one to launch a shell script. Note that the final entry uses different directory separators from the first two, simply to demonstrate the fact that it's possible. (The form of directory separators in options lines is important, though, because the program being launched may expect a particular directory separator character.) 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.png). This entire entry 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 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 Arch 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 ARCHBOOT. It passes the filename for an initial RAM disk using the initrd line and free-form options using the options line.
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:
mm 0003003E 8 -pci fs0:\EFI\Microsoft\Boot\bootmgfw.efi-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.
+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 prior to booting Windows on a computer of a person with whom I corresponded, but such needs are rare. (Using the spoof_osx_version option in rEFInd 0.9.3 and later may also help with some such problems, at least on Macs.) 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.
-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.
+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 Arch and Windows, since the Ubuntu entry is disabled), unless rEFInd found other boot options on an external or optical disk.
Creating Submenu Entries
-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.
+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, when you set the OS type via the ostype option, or when booting a Linux kernel directly. The Mac OS X boot loader, in particular, accepts various options that you can use to boot in various ways.
-Sometimes, you might want to create your own custom submenu entries, and rEFInd 0.2.1 and later enable you to do this. To create a custom submenu, you use the submenuentry keyword inside a menuentry stanza. Normally, you'll set the submenu definitions after you've set the main menu options, since the submenu options take the main menu options as defult, and so the main options must be set first. Like a menuentry stanza, a submenuentry definition begins with the keyword, the name of the item, and an open curly brace ({). It continues until a close curly brace (}). A submenu definition can use the keywords described in Table 3. Except as otherwise noted, using an option of a given name completely overrides the setting in the main stanza.
+Sometimes, you might want to create your own custom submenu entries, and rEFInd enables you to do this. To create a custom submenu, you use the submenuentry keyword inside a menuentry stanza. Normally, you'll set the submenu definitions after you've set the main menu options, since the submenu options take the main menu options as defult, and so the main options must be set first. Like a menuentry stanza, a submenuentry definition begins with the keyword, the name of the item, and an open curly brace ({). It continues until a close curly brace (}). A submenu definition can use the keywords described in Table 3. Except as otherwise noted, using an option of a given name completely overrides the setting in the main stanza.