X-Git-Url: https://code.delx.au/refind/blobdiff_plain/8e261d06ab599ac8eb4d0108a88c30a0a1b8f814..7c898f4a26b66344e4cc8ed5c2e272d5ea0a71dc:/docs/refind/configfile.html diff --git a/docs/refind/configfile.html b/docs/refind/configfile.html index 20e1246..2c6e161 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/14/2012, referencing rEFInd 0.2.6

+

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

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.
    • +
  • 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.
    • @@ -145,7 +146,12 @@ 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. + 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, 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,23 +161,38 @@ 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. + 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. Note that the shell and gptsync options both require the presence of programs not included with rEFInd; see the "Installing Additional Components" section of the Installing rEFInd page for pointers to these programs. 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. + + resolution + Two integer values + Sets the video resolution used by rEFInd; takes a width and a height as options. For instance, resolution 1024 768 sets the resolution to 1024x768. 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 either resolution value 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.) 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 subdirectory of the rEFInd installation directory, which is always scanned, if present. + scanfor internal, external, optical, hdbios, biosexternal, cd, and manual @@ -182,10 +203,20 @@ timeout 20 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). + + 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, on any partition. This 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. + + + 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. For this reason, it's disabled by default. + 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. (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.) @@ -197,15 +228,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: