X-Git-Url: https://code.delx.au/refind/blobdiff_plain/2eb4a9ca3c35a44bb35b7a0998ff036797a8580e..dfa921b680497937566695dfefd20a8751947c51:/docs/refind/configfile.html diff --git a/docs/refind/configfile.html b/docs/refind/configfile.html index 0e736dc..2a13366 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/22/2012, referencing rEFInd 0.3.0

+

Originally written: 3/14/2012; last Web page update: +5/6/2012, referencing rEFInd 0.3.3

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!

@@ -109,7 +110,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com

  • 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.
    • +
  • 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. (If you use the scan_all_linux_kernels option, you can give an icon for a Linux kernel without a .efi extension a name based on the kernel name but with a .icns extension—for instance, bzImage-3.3.2.icns will serve as the icon for the bzImage-3.3.2 kernel.) 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.
  • 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.
    • @@ -147,6 +148,11 @@ timeout 20 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. + + 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. + banner filename @@ -195,7 +201,7 @@ timeout 20 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. + 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. For this reason, it's disabled by default. default_selection @@ -308,15 +314,28 @@ menuentry Gentoo { initrd \kernels\initrd-3.3.0-rc7.img options "root=/dev/sda3 ro" } + +menuentry "Windows via shell script" { + icon \EFI\refind\icons\os_win.icns + loader \EFI\tools\shell.efi + options "fs0:\EFI\tools\launch_windows.nsh" +} -

    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.

    +

    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.

    Tip: Under Linux, you can learn a filesystem's label by using blkid, as in blkid /dev/sda1. The filesystem's label, if set, is identified by the keyword LABEL in the output.

    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.

    -

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

    + +

    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.

    Creating Submenu Entries