code.delx.au - refind/blob - docs/refind/configfile.html

   1 <?xml version="1.0" encoding="utf-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   3   "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   4
   5 <html xmlns="http://www.w3.org/1999/xhtml">
   6 <head>
   7   <title>The rEFInd Boot Manager: Configuring the Boot Manager</title>
   8   <link href="../Styles/styles.css" rel="stylesheet" type="text/css" />
   9 </head>
  10
  11 <body>
  12   <h1>The rEFInd Boot Manager:<br />Configuring the Boot Manager</h1>
  13
  14   <p class="subhead">by Roderick W. Smith, <a
  15 href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
  16
  17   <p>Originally written: 3/14/2012; last Web page update: 4/9/2012, referencing rEFInd 0.2.5</p>
  18
  19
  20 <p>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!</p>
  21
  22 <table border="1">
  23 <tr>
  24 <td>Donate $1.00</td>
  25 <td>Donate $2.50</td>
  26 <td>Donate $5.00</td>
  27 <td>Donate $10.00</td>
  28 <td>Donate another value</td>
  29 </tr>
  30 <tr>
  31 <td><form name="_xclick" action="https://www.paypal.com/cgi-bin/webscr" method="post">
  32 <input type="hidden" name="cmd" value="_xclick">
  33 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
  34 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
  35 <input type="hidden" name="currency_code" value="USD">
  36 <input type="hidden" name="amount" value="1.00">
  37 <input type="image" src="http://www.paypal.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="Make payments with PayPal - it's fast, free and secure!">
  38 </form>
  39
  40 </td>
  41 <td><form name="_xclick" action="https://www.paypal.com/cgi-bin/webscr" method="post">
  42 <input type="hidden" name="cmd" value="_xclick">
  43 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
  44 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
  45 <input type="hidden" name="currency_code" value="USD">
  46 <input type="hidden" name="amount" value="2.50">
  47 <input type="image" src="http://www.paypal.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="Make payments with PayPal - it's fast, free and secure!">
  48 </form>
  49
  50 </td>
  51 <td><form name="_xclick" action="https://www.paypal.com/cgi-bin/webscr" method="post">
  52 <input type="hidden" name="cmd" value="_xclick">
  53 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
  54 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
  55 <input type="hidden" name="currency_code" value="USD">
  56 <input type="hidden" name="amount" value="5.00">
  57 <input type="image" src="http://www.paypal.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="Make payments with PayPal - it's fast, free and secure!">
  58 </form>
  59
  60 </td>
  61 <td><form name="_xclick" action="https://www.paypal.com/cgi-bin/webscr" method="post">
  62 <input type="hidden" name="cmd" value="_xclick">
  63 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
  64 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
  65 <input type="hidden" name="currency_code" value="USD">
  66 <input type="hidden" name="amount" value="10.00">
  67 <input type="image" src="http://www.paypal.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="Make payments with PayPal - it's fast, free and secure!">
  68 </form>
  69
  70 </td>
  71 <td>
  72 <form action="https://www.paypal.com/cgi-bin/webscr" method="post">
  73 <input type="hidden" name="cmd" value="_donations">
  74 <input type="hidden" name="business" value="rodsmith@rodsbooks.com">
  75 <input type="hidden" name="lc" value="US">
  76 <input type="hidden" name="no_note" value="0">
  77 <input type="hidden" name="currency_code" value="USD">
  78 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
  79 <input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
  80 <input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
  81 <img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
  82 </form>
  83 </td></tr>
  84 </table>
  85
  86 <hr />
  87
  88 <p>This page is part of the documentation for the rEFInd boot manager. If a Web search has brought you here, you may want to start at the <a href="index.html">main page.</a></p>
  89
  90 <hr />
  91
  92 <p>Many casual users will be able to use rEFInd without making further changes; in its default configuration, the boot manager automatically detects all the EFI boot loader programs you have on your ESP (or your OS X boot partition, in the case of Macs) and displays icons for them. 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, <tt>refind.conf</tt>, which resides in the same directory as its binary file (<tt>refind.efi</tt> or whatever you've renamed it).</p>
  93
  94 <p>Broadly speaking, rEFInd's configuration file is broken down into two sections: <i>global options</i> and <i>OS stanzas.</i> The global options section sets options that apply globally&mdash;to set the timeout period, enable graphics or text mode, and so on. OS stanzas are optional, but if present, they enable you to add new boot options or replace the auto-detected options with customized ones. Both sections include configuration lines and comment lines, the latter being denoted by a leading hash mark (<tt>#</tt>). rEFInd ignores comment lines, so you can add explanatory text. The default configuration file includes numerous comments explaining each of the options.</p>
  95
  96 <h2>Hiding and Displaying EFI Boot Loaders</h2>
  97
  98 <p class="sidebar">ESPs use the FAT filesystem, which is case-insensitive. Unfortunately, at least one EFI implementation (Gigabyte's <a href="http://www.rodsbooks.com/gb-hybrid-efi/">Hybrid EFI</a>) contains a bug that causes string comparisons that should be case-insensitive to actually be done in a case-sensitive way. This can cause files that are present to appear to be missing. rEFInd includes code to work around this bug in some situations, but not in all of them. If boot loaders appear to be missing, try changing the case on their filenames or on the <tt>EFI</tt> directory in the ESP. (It's coded as uppercase in rEFInd; but EFI loader filename extensions are coded as lowercase <tt>.efi</tt>. I made these choices because they seem to be the most common uses on real-world installations.)</p>
  99
 100 <p>Before delving into the configuration file, you should be aware of what you can do by renaming files. By default, rEFInd scans all the filesystems it can read for boot loaders. It scans most of the subdirectories of the <tt>EFI</tt> directory on every filesystem it can access for files with names that end in <tt>.efi</tt>. (rEFIt gives special treatment to the <tt>TOOLS</tt> subdirectory, where it looks for system tools rather than boot loaders.)</p>
 101
 102 <p>If you're like me, you may sometimes want to hide a boot loader from rEFInd's menu for a brief period&mdash;say, because you're testing a variety of configurations but you don't want them all to clutter the menu at once. You might also want to hide a boot loader if you want to override its default settings using a custom entry in <tt>refind.conf</tt> and you don't want an automatic search to duplicate that entry. You can easily hide a boot loader by removing or changing its <tt>.efi</tt> filename extension&mdash;for instance, changing <tt>grub.efi</tt> to <tt>grub</tt>.</p>
 103
 104 <p>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.</p>
 105
 106 <p>In addition to hiding boot loaders, you can adjust their icons. You can do this in any of three ways for auto-detected boot loaders:</p>
 107
 108 <ul>
 109
 110 <li>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 <tt>os_<tt class="variable">name</tt>.icns</tt>. To use this icon, you would place the boot loader in the directory called <tt class="variable">name</tt>.</li>
 111
 112 <li>You can name an icon file after your boot loader, but with an extension of <tt>.icns</tt>. For instance, if you're using <tt class="variable">loader</tt><tt>.efi</tt>, you would name the icon file <tt class="variable">loader</tt><tt>.icns</tt>. These icon files should be 128x128 images in <a href="http://en.wikipedia.org/wiki/Apple_Icon_Image_format">Apple's ICNS format.</a> You can create such files easily in OS X or convert PNG files to ICNS format with <a href="http://icns.sourceforge.net/">libicns.</a></li>
 113
 114 <li>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 <tt>.VolumeIcon.icns</tt> 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.</li>
 115
 116 </ul>
 117
 118 <p>As a special case, rEFInd assigns icons to the Windows and OS X boot loaders based on their conventional locations, so they get suitable icons even though they don't follow these rules.</p>
 119
 120 <p>In addition to the main OS tag icon, you can set the <i>badge</i> icon for a volume by creating a file called <tt>.VolumeBadge.icns</tt> in the root directory of a partition. This icon file must include a 32x32 bitmap. If present, it replaces the disk-type icons that are overlaid on the main OS icon. If you use this feature, the badge is applied to all the boot loaders read from the disk, not just those stored in the root directory or the Apple boot loader location. You could use this feature to set a custom badge for different specific disks or to help differentiate multiple OS X installations on one computer.</p>
 121
 122 <h2>Adjusting the Global Configuration</h2>
 123
 124 <p>You can adjust many of rEFInd's options by editing its <tt>refind.conf</tt> 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 <b><tt>edit refind.conf</tt></b> 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.</p>
 125
 126 <p>Global configuration file options consist of a name token followed by one or more parameters, as in:</p>
 127
 128 <pre class="listing">
 129 timeout 20
 130 </pre>
 131
 132 <p>This example's name token is <tt>timeout</tt> and its parameter is <tt>20</tt>. The net effect of this line is to set the timeout period to 20 seconds&mdash;rEFInd will wait 20 seconds before launching the default boot loader. Some options can take multiple parameters. These may be separated by commas, spaces, or tabs. The global options are summarized in the Table 1.</p>
 133
 134 <table border="1" cellpadding="1" cellspacing="2" summary="Table 1: Global options in <tt>refind.conf</tt>"><a name="table1"><caption><b>Table 1: Global options in <tt>refind.conf</tt></b></caption></a>
 135 <tr>
 136    <th>Token</th>
 137    <th>Possible parameters</th>
 138    <th>Explanation</th>
 139 </tr>
 140 <tr>
 141    <td><tt>timeout</tt></td>
 142    <td>numeric value</td>
 143    <td>Sets the timeout period in seconds. If <tt>0</tt>, the timeout is disabled&mdash;rEFInd waits indefinitely for user input.</td>
 144 </tr>
 145 <tr>
 146    <td><tt>hideui</tt></td>
 147    <td><tt>banner</tt>, <tt>label</tt>, <tt>singleuser</tt>, <tt>hwtest</tt>, <tt>arrows</tt>, or <tt>all</tt></td>
 148    <td>Removes the specified user interface features. <tt>banner</tt> removes the banner graphic, <tt>label</tt> removes the text description of each tag, <tt>singleuser</tt> removes the single-user option from the Mac OS sub-menu, <tt>hwtest</tt> removes the Mac OS hardware test option, <tt>arrows</tt> removes the arrows to the right or left of the OS tags when rEFInd finds too many OSes to display simultaneously, and <tt>all</tt> removes all of these options. You can specify multiple parameters with this option. The default is to set none of these values.</td>
 149 </tr>
 150 <tr>
 151    <td><tt>banner</tt></td>
 152    <td>filename</td>
 153    <td>Specifies a custom banner file to replaced the rEFInd banner image. The file should be a BMP image with a color depth of 24, 8, 4, or 1 bits. The file path is relative to the directory where <tt>refind.efi</tt> is stored.</td>
 154 </tr>
 155 <tr>
 156    <td><tt>selection_big</tt></td>
 157    <td>filename</td>
 158    <td>Specifies a graphics file that can be used to highlight the OS selection icons. This should be a 144x144 image in BMP format.</td>
 159 </tr>
 160 <tr>
 161    <td><tt>selection_small</tt></td>
 162    <td>filename</td>
 163    <td>Like <tt>selection_big</tt>, this sets an alternate highlight graphic, but for the smaller utility tags on the second row.</td>
 164 </tr>
 165 <tr>
 166    <td><tt>showtools</tt></td>
 167    <td><tt>shell</tt>, <tt>gptsync</tt>, <tt>about</tt>, <tt>exit</tt>, <tt>shutdown</tt>, and <tt>reboot</tt></td>
 168    <td>Specifies which tool tags to display on the second row. <tt>shell</tt> launches an EFI shell, <tt>gptsync</tt> launches a tool that creates a hybrid MBR, <tt>about</tt> displays information about the program, <tt>exit</tt> terminates rEFInd, <tt>shutdown</tt> shuts down the computer (or reboots it, on UEFI PCs), and <tt>reboot</tt> reboots the computer. The tags appear in the order in which you specify them. The default is <tt>shell, about, shutdown, reboot</tt>.</td>
 169 </tr>
 170 <tr>
 171    <td><tt>textonly</tt></td>
 172    <td>None</td>
 173    <td>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.</td>
 174 </tr>
 175 <tr>
 176    <td><tt>scanfor</tt></td>
 177    <td><tt>internal</tt>, <tt>external</tt>, <tt>optical</tt>, <tt>hdbios</tt>, <tt>biosexternal</tt>, <tt>cd</tt>, and <tt>manual</tt></td>
 178    <td>Tells rEFInd what methods to use to locate boot loaders. The <tt>internal</tt>, <tt>external</tt>, and <tt>optical</tt> parameters tell rEFInd to scan for EFI boot loaders on internal, external, and optical (CD, DVD, and Blu-ray) devices, respectively. The <tt>hdbios</tt>, <tt>biosexternal</tt>, and <tt>cd</tt> parameters are similar, but scan for BIOS boot loaders. (Note that the BIOS options are likely to be useless on UEFI PCs.) The <tt>manual</tt> parameter tells rEFInd to scan the configuration file for manual settings. You can specify multiple parameters to have the program scan for multiple boot loader types. When you do so, the order determines the order in which the boot loaders appear in the menu. The default is <tt>internal, external, optical</tt>.</td>
 179 </tr>
 180 <tr>
 181    <td><tt>default_selection</tt></td>
 182    <td>A substring of a boot loader's title</td>
 183    <td>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 <tt>Boot <i>Title</i> from <i>Disk</i></tt>. You can enter any substring of <tt><i>Title</i></tt> as the <tt>default_selection</tt>, 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.)</td>
 184 </tr>
 185 </table>
 186
 187 <p>Prior to version 0.2.4, rEFInd supported a token called <tt>disable</tt>, whose function partially overlapped with <tt>hideui</tt>. Version 0.2.4 merges many of the features of these two tokens into <tt>hideui</tt> and creates the new <tt>showtools</tt> option, which provides the remaining functionality in a more flexible way.</p>
 188
 189 <p>As an example of rEFInd configuration, consider the following <tt>refind.conf</tt> file:</p>
 190
 191 <pre class="listing">
 192 # Sample refind.conf file
 193 timeout 5
 194 banner custom.bmp
 195 scanfor manual,external,optical
 196 default_selection elilo
 197 </pre>
 198
 199 <p>This example sets a timeout of 5 seconds; loads a custom graphic file called <tt>custom.bmp</tt> from the directory in which <tt>refind.efi</tt> 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 <tt>elilo</tt>. 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....</p>
 200
 201 <h2>Creating OS Stanzas</h2>
 202
 203 <p>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:</p>
 204
 205 <ul>
 206
 207 <li>You can move or rename the boot loader file for the boot loader you want to tweak.</li>
 208
 209 <li>You can disable all auto-detection options and add manual configurations for all your boot loaders, even those that work fine when auto-detected.</li>
 210
 211 <li>You can put up with having duplicate tags in your OS list.</li>
 212
 213 </ul>
 214
 215 <p>Each OS stanza begins with the keyword <tt>menuentry</tt>, a name for the entry, and an open curly brace (<tt>{</tt>). Subsequent lines constitute the bulk of the stanza, which concludes with a line containing nothing but a close curly brace (<tt>}</tt>). Table 2 summarizes the keywords that you can include in a stanza.</p>
 216
 217 <table border="1" cellpadding="1" cellspacing="2" summary="Table 2: OS stanza definitions in <tt>refind.conf</tt>"><a name="table2"><caption><b>Table 2: OS stanza definitions in <tt>refind.conf</tt></b></caption></a>
 218 <tr>
 219    <th>Token</th>
 220    <th>Possible parameters</th>
 221    <th>Explanation</th>
 222 </tr>
 223 <tr>
 224    <td><tt>menuentry</tt></td>
 225    <td>name for the entry</td>
 226    <td>Sets the name that's displayed along with the icon for this entry. If the name should contain a space, it <i>must</i> be enclosed in quotes. Following the name, an open curly brace (<tt>{</tt>) ends the <tt>menuentry</tt> line.</td>
 227 </tr>
 228 <tr>
 229    <td><tt>loader</tt></td>
 230    <td>filename</td>
 231    <td>Sets the filename for the boot loader. You may use either Unix-style slashes (<tt>/</tt>) or Windows/EFI-style backslashes (<tt>\</tt>) to separate directory elements. In either case, the references are to files on the ESP from which rEFInd launched; you can't (yet) launch loaders from other locations. This option should normally be the first in the body of an OS stanza; if it's not, some other options may be ignored.</td>
 232 </tr>
 233 <tr>
 234    <td><tt>initrd</tt></td>
 235    <td>filename</td>
 236    <td>Sets the filename for a Linux kernel's initial RAM disk (initrd). This option is useful only when booting a Linux kernel that includes an <a href="http://www.rodsbooks.com/efi-bootloaders/efistub.html">EFI stub loader</a>, which enables you to boot a kernel without the benefit of a separate boot loader. When booted in this way, though, you must normally pass an initrd filename to the boot loader. You must specify the complete EFI path to the initrd file with this option, as in <tt>initrd EFI/linux/initrd-3.3.0-rc7.img</tt>. You'll also have to use the <tt>options</tt> line to pass the Linux root filesystem, and perhaps other options (as in <tt>options "root=/dev/sda4 ro"</tt>).</td>
 237 </tr>
 238 <tr>
 239    <td><tt>icon</tt></td>
 240    <td>filename</td>
 241    <td>Sets the filename for an icon for the menu. If you omit this item, a default icon will be used, based on rEFInd's auto-detection algorithms.</td>
 242 </tr>
 243 <tr>
 244    <td><tt>ostype</tt></td>
 245    <td><tt>MacOS</tt>, <tt>Linux</tt>, <tt>ELILO</tt>, <tt>Windows</tt>, <tt>XOM</tt></td>
 246    <td>Determines the options that are available on a sub-menu obtained by pressing the Insert key with an OS selected in the main menu. If you omit this option, rEFInd selects options using an auto-detection algorithm. Note that this option is case-sensitive.</td>
 247 </tr>
 248 <tr>
 249    <td><tt>graphics</tt></td>
 250    <td><tt>on</tt> or <tt>off</tt></td>
 251    <td>Enables or disables a graphical boot mode. This option has an effect only on Macintoshes; UEFI PCs seem to be unaffected by it.</td>
 252 </tr>
 253 <tr>
 254    <td><tt>options</tt></td>
 255    <td>options passed to the boot loader</td>
 256    <td>Pass arbitrary options to your boot loader with this line. Note that if the option string should contain spaces (as it often should) or characters that should not be modified by rEFInd's option parser (such as slashes or commas), it <i>must</i> be enclosed in quotes.</td>
 257 </tr>
 258 <tr>
 259    <td><tt>disabled</tt></td>
 260    <td>None</td>
 261    <td>Disable an entry. This is often easier than commenting out an entire entry if you want to temporarily disable it.</td>
 262 </tr>
 263 <tr>
 264    <td><tt>submenuentry</tt></td>
 265    <td>submenu entry name and tokens</td>
 266    <td>This keyword identifies a submenu entry, as described in more detail shortly.</td>
 267 </tr>
 268 </table>
 269
 270 <p>As an example, consider the following entries:</p>
 271
 272 <pre class="listing">
 273 menuentry "Ubuntu Linux" {
 274     loader /EFI/ubuntu/grubx64.efi
 275     disabled
 276 }
 277
 278 menuentry Gentoo {
 279     loader \EFI\linux\bzImage-3.3.0-rc7
 280     initrd \EFI\linux\initrd-3.3.0-rc7.img
 281     options "root=/dev/sda3 ro"
 282     icon \EFI\refind\icons\os_gentoo.icns
 283 }
 284 </pre>
 285
 286 <p>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 <tt>ubuntu</tt> directory, and it will automatically find the appropriate Ubuntu icon (<tt>os_ubuntu.icns</tt>). This option is, however, disabled, so no matching icon will appear when you reboot unless you first comment out or delete the <tt>disabled</tt> line.</p>
 287
 288 <p>The Gentoo entry passes the filename for an initial RAM disk using the <tt>initrd</tt> line and free-form options using the <tt>option</tt> line. It also sets an icon name, since the path to the kernel doesn't include the distribution's name. Note that the kernel filename does <i>not</i> include a <tt>.efi</tt> extension, which keeps rEFInd from picking up the kernel file in its auto-scans.</p>
 289
 290 <p>You can combine these OS stanzas with the global <tt>refind.conf</tt> 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.</p>
 291
 292 <p>Presently, an important limitation of rEFInd is that the manual boot loader definitions can only read files on the partition from which rEFInd launched. rEFInd can, however, auto-detect boot loaders on other disks or partitions via the <tt>internal</tt>, <tt>external</tt>, and similar options.</p>
 293
 294 <h2>Creating Submenu Entries</h2>
 295
 296 <p>As described on the <a href="using.html">Using rEFInd</a> 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 <tt>ostype</tt> option. The Mac OS X boot loader, in particular, accepts various options that you can use to boot in various ways.</p>
 297
 298 <p>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 <tt>submenuentry</tt> keyword <i>inside</i> a <tt>menuentry</tt> stanza. Normally, you'll set the submenu definitions <i>after</i> 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 <tt>menuentry</tt> stanza, a <tt>submenuentry</tt> definition begins with the keyword, the name of the item, and an open curly brace (<tt>{</tt>). It continues until a close curly brace (<tt>}</tt>). A submenu definition can use the keywords described in <a href="#table3">Table 3.</a> Except as otherwise noted, using an option of a given name completely overrides the setting in the main stanza.</p>
 299
 300 <table border="1" cellpadding="1" cellspacing="2" summary="Table 3: Submenu keywords in <tt>refind.conf</tt>"><a name="table3"><caption><b>Table 3: Submenu keywords in <tt>refind.conf</tt></b></caption></a>
 301 <tr>
 302    <th>Token</th>
 303    <th>Possible parameters</th>
 304    <th>Explanation</th>
 305 </tr>
 306 <tr>
 307    <td><tt>submenuentry</tt></td>
 308    <td>name for the entry</td>
 309    <td>Sets the name that's displayed for this entry on the submenu page. If the name should contain a space, it <i>must</i> be enclosed in quotes. Following the name, an open curly brace (<tt>{</tt>) ends the <tt>submenuentry</tt> line.</td>
 310 </tr>
 311 <tr>
 312    <td><tt>loader</tt></td>
 313    <td>filename</td>
 314    <td>Sets the filename for the boot loader, as described in <a href="#table2">Table 2.</a></td>
 315 </tr>
 316 <tr>
 317    <td><tt>initrd</tt></td>
 318    <td>filename</td>
 319    <td>Sets the filename for a Linux kernel's initial RAM disk (initrd), as described in <a href="#table2">Table 2.</a> If you want to eliminate the initrd specification, you should use this keyword alone, with no options. You might do this because your main entry is for a Linux kernel with EFI stub support and this submenu entry launches ELILO, which sets the initrd in its own configuration file.</td>
 320 </tr>
 321 <tr>
 322    <td><tt>graphics</tt></td>
 323    <td><tt>on</tt> or <tt>off</tt></td>
 324    <td>Enables or disables a graphical boot mode, as described in <a href="#table2">Table 2.</a></td>
 325 </tr>
 326 <tr>
 327    <td><tt>options</tt></td>
 328    <td>options passed to the boot loader</td>
 329    <td>Pass arbitrary options to your boot loader with this line, as described in <a href="#table2">Table 2.</a> As with <tt>initrd</tt>, you can eliminate all options by passing this keyword alone on a line.</td>
 330 </tr>
 331 <tr>
 332    <td><tt>add_options</tt></td>
 333    <td>options passed to the boot loader</td>
 334    <td>This token works just like <tt>options</tt>, except that instead of <i>replacing</i> the default options, it causes the specified options to be <i>added to</i> those specified in the main stanza listing's <tt>options</tt> line.</td>
 335 </tr>
 336 <tr>
 337    <td><tt>disabled</tt></td>
 338    <td>None</td>
 339    <td>Disable a submenu entry. This is often easier than commenting out an entire entry if you want to temporarily disable it.</td>
 340 </tr>
 341 </table>
 342
 343 <p>The following menu entry illustrates the use of submenu entries. This is an expansion on the second entry presented earlier:</p>
 344
 345 <pre class="listing">
 346 menuentry Gentoo {
 347     loader \EFI\linux\bzImage-3.3.0-rc7
 348     initrd \EFI\linux\initrd-3.3.0-rc7.img
 349     options "root=/dev/sda3 ro"
 350     icon \EFI\refind\icons\os_gentoo.icns
 351     submenuentry "single-user mode" {
 352         add_options "single"
 353     }
 354     submenuentry "3.3.0 final release kernel" {
 355         loader \EFI\linux\bzImage-3.3.0
 356         initrd \EFI\linux\initrd-3.3.0.img
 357     }
 358     submenuentry "boot via ELILO" {
 359         loader \EFI\elilo\elilo.efi
 360         initrd
 361         options
 362     }
 363 }
 364 </pre>
 365
 366 <p>The main menu item for this entry won't look different with the submenus defined than without them; but if you press the Insert key, you'll see the submenu items:</p>
 367
 368     <br /><center><img src="manual-submenu.png" align="center" width="372"
 369     height="272" alt="Manually defining submenus enables you to customize
 370     your boot options." border=2></center><br />
 371
 372 <p>The main menu item appears at the top of the list&mdash;<tt>Run bzImage-3.3.0-rc7</tt> in this example. The three submenus defined in this example's configuration file appear next, enabling you to launch in single-user mode, run the 3.3.0 release kernel, or boot via ELILO, respectively. Submenus also include an item called <tt>Return to Main Menu</tt> that does just as it says. (Alternatively, you can return to the main menu by pressing the Esc key.)</p>
 373
 374 <p>This example illustrates some of the things you can do with submenu entries:</p>
 375
 376 <ul>
 377
 378 <li>You can add kernel options when booting via the EFI stub loader&mdash;to launch single-user mode, to add graphical boot options, or what have you.</li>
 379
 380 <li>You can change kernel options when booting via the EFI stub loader&mdash;to <i>remove</i> graphical boot options, to boot to a different root device, and so on.</li>
 381
 382 <li>You can change your kernel and/or initial RAM disk when booting via the EFI stub loader.</li>
 383
 384 <li>You can give users a choice of boot loaders. In this example, the main option boots via the kernel stub loader, but the submenu gives users the chance to boot via ELILO instead. In fact, you could even boot two entirely different OSes from manually-defined submenu entries, although that could be confusing.</li>
 385
 386 </ul>
 387
 388 <hr />
 389
 390 <p>copyright &copy; 2012 by Roderick W. Smith</p>
 391
 392 <p>This document is licensed under the terms of the <a href="FDL-1.3.txt">GNU Free Documentation License (FDL), version 1.3.</a></p>
 393
 394 <p>If you have problems with or comments about this Web page, please e-mail me at <a href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com.</a> Thanks.</p>
 395
 396 <p><a href="index.html">Go to the main rEFInd page</a></p>
 397
 398 <p><a href="linux.html">Learn about methods of booting Linux with rEFInd</a></p>
 399
 400   <p><a href="http://www.rodsbooks.com/">Return</a> to my main Web page.</p>
 401 </body>
 402 </html>