]> code.delx.au - refind/blobdiff - docs/refind/linux.html
Updated NEWS and docs for 0.10.6
[refind] / docs / refind / linux.html
index 42a4b6e5f5ad204221cd407aa178d014d802ab3e..3f240024101b2bcbdc7fc1a567920d1ac732f848 100644 (file)
@@ -8,6 +8,8 @@
   <link href="../Styles/styles.css" rel="stylesheet" type="text/css" />
 </head>
 
+<meta name="viewport" content="width=device-width, initial-scale=1">
+
 <body>
 <h1>The rEFInd Boot Manager:<br />Methods of Booting Linux</h1>
 
@@ -15,7 +17,7 @@
 href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
 
 <p>Originally written: 3/19/2012; last Web page update:
-7/28/2014, referencing rEFInd 0.8.3</p>
+3/4/2017, referencing rEFInd 0.10.5</p>
 
 
 <p>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>
@@ -41,8 +43,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
 <input type="hidden" name="amount" value="1.00">
 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
 <input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
-<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!">
-<img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
+<input type="image" src="donate.png" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
 </form>
 </td>
 
@@ -56,8 +57,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
 <input type="hidden" name="amount" value="2.50">
 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
 <input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
-<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!">
-<img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
+<input type="image" src="donate.png" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
 </form>
 </td>
 
@@ -72,8 +72,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
 <input type="hidden" name="amount" value="5.00">
 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
 <input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
-<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!">
-<img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
+<input type="image" src="donate.png" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
 </form>
 </td>
 
@@ -87,8 +86,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
 <input type="hidden" name="amount" value="10.00">
 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
 <input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
-<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!">
-<img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
+<input type="image" src="donate.png" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
 </form>
 </td>
 
@@ -102,8 +100,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
 <input type="hidden" name="amount" value="20.00">
 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
 <input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
-<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!">
-<img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
+<input type="image" src="donate.png" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
 </form>
 </td>
 
@@ -116,8 +113,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
 <input type="hidden" name="currency_code" value="USD">
 <input type="hidden" name="item_name" value="rEFInd Boot Manager">
 <input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
-<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!">
-<img alt="Donate with PayPal" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
+<input type="image" src="donate.png" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
 </form>
 </td></tr>
 </table>
@@ -182,9 +178,9 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
 <h3>For Those With Foresight or Luck: The Easiest Method</h3>
 </a>
 
-<p>This method requires that your <tt>/boot</tt> directory, whether it's on a separate partition or is a regular directory in your root (<tt>/</tt>) filesystem, be readable by the EFI. At the moment, all EFI implementations can read FAT and Macs can read HFS+. By using <a href="drivers.html">drivers,</a> you can make any EFI read HFS+, ISO-9660, ReiserFS, ext2fs, ext3fs, ext4fs, or Btrfs. Thus, if you use any of these filesystems on a regular partition (not an LVM or RAID configuration) that holds your kernels in <tt>/boot</tt>, you qualify for this easy method. The default partition layouts used by Ubuntu, Fedora, and many other distributions qualify, because they use one of these filesystems (usually ext4fs) in a normal partition or on a separate <tt>/boot</tt> partition. You must also have a 3.3.0 or later Linux kernel with EFI stub support, of course.</p>
+<p>This method requires that your <tt>/boot</tt> directory, whether it's on a separate partition or is a regular directory in your root (<tt>/</tt>) filesystem, be readable by the EFI. At the moment, all EFI implementations can read FAT and Macs can read HFS+. By using <a href="drivers.html">drivers,</a> you can make any EFI read HFS+, ISO-9660, ReiserFS, ext2fs, ext3fs, ext4fs, Btrfs, or other filesystems. Thus, if you use any of these filesystems on a regular partition (not an LVM or RAID configuration) that holds your kernels in <tt>/boot</tt>, you qualify for this easy method. The default partition layouts used by Ubuntu, Fedora, and many other distributions qualify, because they use one of these filesystems (usually ext4fs) in a normal partition or on a separate <tt>/boot</tt> partition. You must also have a 3.3.0 or later Linux kernel with EFI stub support, of course.</p>
 
-<p>If you installed rEFInd 0.6.0 or later with its <tt>install.sh</tt> script from your regular Linux installation, chances are everything's set up; you should be able to reboot and see your Linux kernels as boot options. If you installed manually, from OS X, or from an emergency system, though, you may need to do a couple of things manually:
+<p>If you installed rEFInd 0.6.0 or later with its <tt>refind-install</tt> (formerly <tt>install.sh</tt>) script from your regular Linux installation, chances are everything's set up; you should be able to reboot and see your Linux kernels as boot options. If you installed manually, from OS X, or from an emergency system, though, you may need to do a couple of things manually:
 
 <ul>
 
@@ -194,14 +190,17 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
     Partition (ESP). You may need to create this subdirectory, too.</li>
 
 <li>Create a <tt>refind_linux.conf</tt> file in your <tt>/boot</tt>
-    directory. The <tt>mkrlconf.sh</tt> script that comes with rEFInd
+    directory. The <tt>mkrlconf</tt> script that comes with rEFInd
     should do this job, or you can do it manually as described <a
     href="#efistub">later.</a> Starting with version 0.6.12, rEFInd can
     create minimal boot options from <tt>/etc/fstab</tt>, if <tt>/boot</tt>
     is <i>not</i> a separate partition, so a <tt>refind_linux.conf</tt>
-    file may not be strictly necessary. It remains desirable, though, and
-    is necessary if <tt>/boot</tt> is on a separate partition or if you
-    need unusual kernel options to boot your computer.</li>
+    file may not be strictly necessary. Version 0.9.0 also adds the ability
+    to identify the root (<tt>/</tt>) partition via the <a
+    href="http://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable
+    Partitions Spec,</a> if your disk uses the appropriate type codes. A
+    <tt>refind_linux.conf</tt> file remains desirable, though, and is
+    necessary in some situations.</li>
 
 </ul>
 
@@ -211,7 +210,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
 <h3>Preparing a Test Configuration</h3>
 </a>
 
-<p>If you're not sure you want to use the EFI stub loader in the long term, you can perform a fairly quick initial test of it. This procedure assumes that you have access to a 3.3.0 or later Linux kernel with EFI stub support compiled into it. (Fedora 17, Ubuntu 12.10, and probably other distributions ship with such kernels.) Creating this configuration poses no risk to your current boot options, provided you don't accidentally delete existing files. The procedure for a quick test is:</p>
+<p>If you're not sure you want to use the EFI stub loader in the long term, you can perform a fairly quick initial test of it. This procedure assumes that you have access to a 3.3.0 or later Linux kernel with EFI stub support compiled into it. (Fedora since version 17, Ubuntu since 12.10, and most other distributions ship with such kernels.) Creating this configuration poses no risk to your current boot options, provided you don't accidentally delete existing files. The procedure for a quick test is:</p>
 
 <ol>
 
@@ -219,8 +218,8 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
     disk file (<tt>init*</tt>) from <tt>/boot</tt> to a subdirectory of
     <tt>EFI</tt> on your ESP. Your distribution's directory there should
     work fine. For instance, typing <tt class="userinput">cp
-    /boot/vmlinuz-3.6.7-4.fc17.x86_64
-    /boot/initramfs-3.6.7-4.fc17.x86_64.img /boot/efi/EFI/redhat</tt> might
+    /boot/vmlinuz-4.2.5-300.fc23.x86_64
+    /boot/initramfs-4.2.5-300.fc23.x86_64.img /boot/efi/EFI/fedora</tt> might
     do the trick on a Fedora system, although you'll probably have to
     adjust the version numbers. Note that the filename forms vary from one
     distribution to another, so don't worry if yours look different from
@@ -229,7 +228,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
 
 <li>Copy the <tt>/boot/refind_linux.conf</tt> file to the same directory to
     which you copied your kernel. If this file doesn't exist, create it by
-    running (as <tt>root</tt>) the <tt>mkrlconf.sh</tt> script that came
+    running (as <tt>root</tt>) the <tt>mkrlconf</tt> script that came
     with rEFInd. This step may not be strictly necessary if <tt>/boot</tt>
     is an ordinary directory on your root (<tt>/</tt>) partition.</li>
 
@@ -293,7 +292,7 @@ href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
     <tt>/boot/refind_linux.conf</tt> and populate it with kernel options,
     as described <a href="#refind_linux">later.</a> If this file doesn't
     already exist, the easiest way to create it is to run the
-    <tt>mkrlconf.sh</tt> script that comes with rEFInd 0.5.1 and
+    <tt>mkrlconf</tt> script that comes with rEFInd 0.5.1 and
     later.</li>
 
 <li>Check your <tt>refind.conf</tt> file (presumably in
@@ -344,20 +343,19 @@ extends it as follows:</p>
 <ol>
 
 <li>rEFInd looks for boot loaders whose names include the strings
-    <tt>bzImage</tt> or <tt>vmlinuz</tt> and that end in <tt>.efi</tt>. For
-    instance, <tt>bzImage-3.3.0.efi</tt> or <tt>vmlinuz-3.3.0-fc17.efi</tt>
-    would match, and trigger subsequent steps in this procedure. Beginning
-    with version 0.3.0, if you uncomment the
-    <tt>scan_all_linux_kernels</tt> option in <tt>refind.conf</tt>, rEFInd
-    will also scan for kernels <i>without</i> a <tt>.efi</tt> filename
-    extension. This option is uncommented by default, but if you comment it
-    out, delete it, or change it to read <tt>scan_all_linux_kernels 0</tt>,
-    rEFInd won't scan for kernels that lack <tt>.efi</tt> filename
-    extensions.</li>
+    <tt>bzImage</tt> or <tt>vmlinuz</tt>. For instance,
+    <tt>bzImage-3.19.0.efi</tt> or <tt>vmlinuz-4.2.0</tt> would match, and
+    trigger subsequent steps in this procedure. The
+    <tt>scan_all_linux_kernels</tt> option in <tt>refind.conf</tt> controls
+    the scanning for kernels whose names do not end in <tt>.efi</tt>; if
+    this option is set to <tt>false</tt>, kernel filenames must end in
+    <tt>.efi</tt> to be picked up by rEFInd. This option is set to
+    <tt>true</tt> by default, but you can change it if you don't want to
+    scan all Linux kernels.</li>
 
 <li>If a file's name ends in <tt>.efi.signed</tt>, any other file with an
     otherwise-identical name that <i>lacks</i> this extension is excluded.
-    This peculiar rule exists because Ubuntu has begun delivering two
+    This peculiar rule exists because Ubuntu delivers two
     copies of every kernel, one with and one without this extension. The
     one with the extension is signed with a Secure Boot key; the one
     without it is not so signed. Thus, if both files are present, the one
@@ -368,29 +366,63 @@ extends it as follows:</p>
 
 <p class="sidebar">A kernel whose filename lacks a version string matches an initial RAM disk that also lacks a version string in its filename. Note that you can reliably use only <i>one</i> kernel and initial RAM disk per directory that lack version numbers in their filenames.</p>
 
-<li>rEFInd looks for an initial RAM disk in the same directory as the
-    kernel file. A matching initial RAM disk has a name that begins with
+<li>rEFInd looks for an initial RAM disk in the same directory as the kernel
+    file. A matching initial RAM disk has a name that begins with
     <tt>init</tt> and that includes the same version string as the kernel.
-    The version string is defined as the part of the filename from the
-    first digit to the last digit, inclusive. Note that the version string
-    can include non-digits. For instance, the version string for
-    <tt>bzImage-3.3.0.efi</tt> is <tt>3.3.0</tt>, which matches
-    <tt>initramfs-3.3.0.bz</tt>; and <tt>vmlinuz-3.3.0-fc17.efi</tt>'s
-    version string is <tt>3.3.0-fc17</tt>, which matches
-    <tt>initrd-3.3.0-fc17.img</tt>. Many other matches are possible. If an
-    initial RAM disk is identified, rEFInd passes a suitable
-    <tt>initrd=</tt> option to the kernel when it boots.</li>
+    The version string is defined as the part of the filename from the first
+    digit to the last digit, inclusive. Note that the version string can
+    include non-digits. For instance, the version string for
+    <tt>bzImage-3.19.0.efi</tt> is <tt>3.19.0</tt>, which matches
+    <tt>initramfs-3.19.0.bz</tt>; and
+    <tt>vmlinuz-4.2.5-300.fc23.x86_64</tt>'s version string is
+    <tt>4.2.5-300.fc23.x86_64</tt>, which matches
+    <tt>initrd-4.2.5-300.fc23.x86_64.img</tt>. In order to support Arch Linux
+    kernel naming the strings <tt>linux</tt> and <tt>linux-lts</tt> are
+    treated as digits. So <tt>vmlinuz-linux-lts</tt> has version
+    <tt>linux-lts</tt>, which matches <tt>initramfs-linux-lts.img</tt>.
+    Many other matches are possible. If an initial RAM disk is identified,
+    rEFInd passes a suitable <tt>initrd=</tt> option to the kernel when it
+    boots. There are two variants on this rule:
+
+    <ul>
+
+    <li>As an extension to the preceding point, if multiple initial RAM disk
+       files match one kernel, the one whose filename matches the most
+       characters after the version string is used. For instance, suppose
+       the kernel filename is <tt>vmlinuz-4.8.0-32-standard</tt>, and two
+       initial RAM disk files are <tt>initrd-4.8.0-32-standard</tt> and
+       <tt>initrd-4.8.0-32-debug</tt>. The first of those files has nine
+       matching characters after the version string (<tt>-standard</tt>),
+       vs. just one matching character (<tt>-</tt>) for the second. Thus,
+       the first file will be used.</li>
+
+    <li>If the <tt>refind_linux.conf</tt> file (described next) is present,
+       and if an <tt>initrd=</tt> specification is present for the option
+       you're using, rEFInd will <i>not</i> add a pointer to the initial
+       RAM disk file that it discovers. This feature enables you to
+       override rEFInd's initial RAM disk discovery. This is most useful in
+       Arch Linux, which can be configured with two different initial RAM
+       disk files, one to be used for normal booting and one for recovery
+       situations. You can specify each initial RAM disk file on its own
+       line, which gives you the ability to control which to use at boot
+       time.</li></ul>
 
 <li>rEFInd looks for a file called <tt>refind_linux.conf</tt> in the same
-    directory as the kernel file. It consists of a series of lines,
-    each of which consists of a label followed by a series of kernel
-    options. The first line sets default options, and subsequent lines set
-    options that are accessible from the main menu tag's submenu screen. If
-    you installed rEFInd 0.5.1 or later with the <tt>install.sh</tt>
-    script, that script created a sample <tt>refind_linux.conf</tt> file,
-    customized for your computer, in <tt>/boot</tt>. This file will work
-    without changes on many installations, but you may need to tweak it for
-    some.</li>
+    directory as the kernel file. It consists of a series of lines, each of
+    which consists of a label followed by a series of kernel options. The
+    first line sets default options, and subsequent lines set options that
+    are accessible from the main menu tag's submenu screen. If you installed
+    rEFInd with the <tt>refind-install</tt> script, that script created a
+    sample <tt>refind_linux.conf</tt> file, customized for your computer, in
+    <tt>/boot</tt>. This file will work without changes on many
+    installations, but you may need to tweak it for some. If the kernel
+    options string includes the substring <tt>%v</tt>, rEFInd substitutes
+    the kernel version number for that string. (If you need the actual
+    string <tt>%v</tt> in your kernel options, use <tt>%%v</tt> instead;
+    rEFInd will change this to <tt>%v</tt>.) This feature can be used to
+    match an initial RAM disk file that requires special treatment, such as
+    if you have multiple numbered kernels, each of which has two initial RAM
+    disk files.</li>
 
 <li>If rEFInd can't find a <tt>refind_linux.conf</tt> file in the directory
     that holds the kernel, the program looks for a file called
@@ -407,67 +439,71 @@ extends it as follows:</p>
     that rEFInd uses <tt>/etc/fstab</tt> only if <tt>refind_linux.conf</tt>
     is <i>not</i> found.</li>
 
-</ol>
+<li>If rEFInd can't find a <tt>refind_linux.conf</tt> file or an
+    <tt>/etc/fstab</tt> file, it tries to identify the Linux root
+    (<tt>/</tt>) filesystem by looking for a partition with a GUID type code
+    matching that specified for the root (<tt>/</tt>) filesystem in the <a
+    href="http://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Freedesktop.org
+    Discoverable Partitions Specification.</a> These type codes are as yet
+    seldom used, but if and when they become common, they should help a lot
+    for situations similar to those of the preceding case, but when a
+    separate <tt>/boot</tt> partition is used.</li>
 
-<p>The intent of this system is that distribution maintainers can place their kernels, initial RAM disks, and a <tt>refind_linux.conf</tt> file in their own subdirectories on the ESP, on EFI-accessible <tt>/boot</tt> partitions, or in <tt>/boot</tt> directories on EFI-accessible Linux root (<tt>/</tt>) partitions. rEFInd will detect these kernels and create one main menu entry for each kernel. Each entry will implement as many options as there are lines in the <tt>refind_linux.conf</tt> file. In this way, two or more distributions can each maintain their boot loader entries, without being too concerned about who maintains rEFInd as a whole.</p>
+</ol>
 
-<p>The <tt>scan_all_linux_kernels</tt> option is intended to help users and distribution maintainers when rEFInd is used in conjunction with a Linux filesystem driver for EFI or when the ESP is mounted as the Linux <tt>/boot</tt> partition. In these cases, if all the kernels in Linux's <tt>/boot</tt> directory include EFI stub loader support, rEFInd will automatically detect and use kernels installed in the usual way, such as via an automatic system update. You won't even need to move or rename your kernels. You will need to set up a <tt>refind_linux.conf</tt> file and you may need to install a driver or set the <tt>also_scan_dirs</tt> option in <tt>refind.conf</tt>; but these are one-time requirements. Set up in this way, ongoing maintenance to handle kernel updates drops to zero!</p>
+<p>The intent of this system is that distribution maintainers can place their kernels, initial RAM disks, and a <tt>refind_linux.conf</tt> file in their own subdirectories on the ESP, on EFI-accessible <tt>/boot</tt> partitions, or in <tt>/boot</tt> directories on EFI-accessible Linux root (<tt>/</tt>) partitions. rEFInd will detect these kernels and create one main menu entry for each directory that holds kernels; or if <tt>fold_linux_kernels</tt> is set to <tt>false</tt>, one menu entry for each kernel. Each entry will implement as many options as there are lines in the <tt>refind_linux.conf</tt> file (multiplied by the number of kernels, if <tt>fold_linux_kernels</tt> is <tt>true</tt>). In this way, two or more distributions can each maintain their boot loader entries, without being too concerned about who maintains rEFInd as a whole.</p>
 
-<p>As an example, consider the following file configuration:</p>
+<p>As an example, consider the following (partial) file listing:</p>
 
 <pre class="listing">
-$ <b>ls -l /boot/efi/EFI/ubuntu/</b>
+$ <b>ls -l /boot/vmlin*</b>
 total 17943
--rwxr-xr-x 1 root root  4781632 2012-03-18 12:01 bzImage-3.3.0.efi
--rwxr-xr-x 1 root root   131072 2011-10-14 04:10 grubx64.EFI
--rwxr-xr-x 1 root root 13459936 2012-03-18 12:02 initrd.img-3.3.0
--rwxr-xr-x 1 root root      266 2012-03-26 19:39 refind_linux.conf
+-rw-r--r-- 1 root root 5271984 Aug  7 10:18 /boot/vmlinuz-3.16.7-24-default
+-rw-r--r-- 1 root root 5271536 Oct 23 17:25 /boot/vmlinuz-3.16.7-29-default
 </pre>
 
-<p>When rEFInd scans this directory, it will find two EFI boot loaders in <tt>EFI/ubuntu</tt>: <tt>grubx64.EFI</tt> and <tt>bzImage-3.3.0.efi</tt>. rEFInd will create two main-menu tags for these two loaders, one of which will launch Ubuntu's standard GRUB and the other of which will launch the 3.3.0 kernel file directly. The <tt>refind_linux.conf</tt> file contains a list of labels and options:</p>
+<p>When rEFInd scans this directory, it will discover two kernels in <tt>/boot</tt>. Assuming <tt>fold_linux_kernels</tt> is its default of <tt>true</tt>, rEFInd will create one main-menu tag for these two kernels. A <tt>refind_linux.conf</tt> file in this directory should contain a list of labels and options:</p>
 
 <a name="refind_linux">
 <pre class="listing">
-"Boot with standard options" "root=/dev/sda3 ro quiet splash vt.handoff=7"
-"Boot to single-user mode"   "root=UUID=1cd95082-bce0-494c-a290-d2e642dd82b7 ro single"
-"Boot with minimal options"  "root=UUID=1cd95082-bce0-494c-a290-d2e642dd82b7 ro"
-# "Boot alternate install"     "root=/dev/sdb9 ro quiet splash vt.handoff=7"
+"Boot with standard options"  "ro root=UUID=084f544a-7559-4d4b-938a-b920f59edc7e splash=silent quiet showopts "
+"Boot to single-user mode"    "ro root=UUID=084f544a-7559-4d4b-938a-b920f59edc7e splash=silent quiet showopts single"
+"Boot with minimal options"   "ro root=UUID=084f544a-7559-4d4b-938a-b920f59edc7e"
+# This line is a comment
 </pre>
 </a>
 
 <p>Ordinarily, both fields in this file must be enclosed in quotes. If you have to pass an option that includes quotes, you can do so by doubling up on them, as in <tt>"root=/dev/sdb9 my_opt=""this is it"""</tt>, which passes <tt>root=/dev/sdb9 my_opt="this is it"</tt> to the shell. You can include as much white space as you like between options. You can also place comments in the file, or remove an option by commenting it out with a leading hash mark (<tt>#</tt>), as in the fourth line in this example.</p>
 
-<p>In the preceding example, the first line sets the options that rEFInd passes to the kernel by default (along with the name of the <tt>initrd.img-3.3.0</tt> file, since its version string matches that of the kernel). The next two lines set options that you can obtain by pressing Insert, F2, or + on the main menu, as shown here:</p>
+<p>In the preceding example, the first line sets the options that rEFInd passes to the kernel by default (along with the name of the discovered initrd file, since its version string matches that of the kernel). The next two lines set options that you can obtain by pressing Insert, F2, or + on the main menu, as shown here:</p>
 
     <br /><center><img src="automatic-submenu.png" align="center"
-    width="471" height="189" alt="rEFInd can load Linux boot options from
+    width="622" height="210" alt="rEFInd can load Linux boot options from
     a refind_linux.conf file in the Linux kernel's directory."
     border=2></center><br />
 
-<p>To assist in initial configuration, rEFInd's <tt>install.sh</tt> script creates a sample <tt>refind_linux.conf</tt> file in <tt>/boot</tt>. This sample file defines three entries, the first two of which use the default GRUB options defined in <tt>/etc/default/grub</tt> and the last of which uses minimal options. The first entry boots normally and the second boots into single-user mode. If you want to create a new file, you can use the <tt>mkrlconf.sh</tt> script that comes with rEFInd. If you pass it the <tt>--force</tt> option, it will overwrite the existing <tt>/boot/refind_linux.conf</tt> file; otherwise it will create the file only if one doesn't already exist.</p>
+<p>Note that in this example, the default kernel (the one with the most recent time stamp) appears first on the list, with the labels specified in <tt>refind_linux.conf</tt>. Subsequent kernels (just one in this example) appear below it, with the same labels preceded by the kernel filename. If you were to set <tt>fold_linux_kernels false</tt>, each kernel would get its own entry on the main menu, and each one's submenu would enable options for launching it alone.</p>
+
+<p>To assist in initial configuration, rEFInd's <tt>refind-install</tt> script creates a sample <tt>refind_linux.conf</tt> file in <tt>/boot</tt>. This sample file defines three entries, the first two of which use the default GRUB options defined in <tt>/etc/default/grub</tt> and the last of which uses minimal options. The first entry boots normally and the second boots into single-user mode. If you want to create a new file, you can use the <tt>mkrlconf</tt> script that comes with rEFInd. If you pass it the <tt>--force</tt> option, it will overwrite the existing <tt>/boot/refind_linux.conf</tt> file; otherwise it will create the file only if one doesn't already exist.</p>
 
 <p>From a user's perspective, the submenus defined in this way work just like submenus defined via the <tt>submenuentry</tt> options in <tt>refind.conf</tt>, or like the submenus that rEFInd creates automatically for Mac OS X or ELILO. There are, however, limitations in what you can accomplish with this method:</p>
 
 <ul>
 
-<li>Your kernels must be compiled with EFI stub loader support.</li>
+<li>Your kernels must be compiled with EFI stub loader support. (This is
+    almost always true of distribution-provided kernels these days.)</li>
 
 <li>You can't set a submenu option to boot via a different boot loader,
     such as ELILO or GRUB; all the submenu options apply to a single boot
     loader&mdash;that is, a single kernel. (rEFInd will still detect other
     boot loaders and provide separate main-menu tags for them,
-    though.)</li>
-
-<li>If an installation includes two or more kernel files, each one receives
-    its own main-menu entry; you can't combine them together in one menu
-    item. This is essentially a corollary of the preceding limitation. The
-    result can be an overburdened main menu if your system has many
-    kernels.</li>
+    though.) Folded kernel entries are an exception to this rule.</li>
 
 <li>All the kernels in a given directory use the same
     <tt>refind_linux.conf</tt> file. If you need to set different options
     for different kernels, you'll need to place those kernels in different
-    directories.</li>
+    directories. (A partial exception is the kernel version string, which
+    can be passed via the <tt>%v</tt> variable, as noted earlier.)</li>
 
 <li>You must place your kernels in a directory other than the one that
     holds the main rEFInd <tt>.efi</tt> file. This is because rEFInd does
@@ -475,19 +511,19 @@ total 17943
 
 </ul>
 
-<p>Ordinarily, a kernel booted in this way must reside on the ESP, or at least on another FAT partition. On a Macintosh, though, you can use HFS+ to house your kernel files. In fact, that may be necessary; my Mac Mini hangs when I try to boot a Linux kernel via an EFI stub loader from the computer's ESP, but it works fine when booting from an HFS+ partition. If you use <a href="drivers.html">EFI drivers,</a> though, you can place your kernel on any filesystem for which an EFI driver exists. This list is currently good (ext2fs/ext3fs, ext4fs, ReiserFS, Btrfs, ISO-9660, and HFS+), so chances are you'll be able to use this method to boot your kernel from your root (<tt>/</tt>) partition or from a <tt>/boot</tt> partition.</p>
+<p>Ordinarily, a kernel booted in this way must reside on the ESP, or at least on another FAT partition. On a Macintosh, though, you can use HFS+ to house your kernel files. In fact, that may be necessary; my Mac Mini hangs when I try to boot a Linux kernel via an EFI stub loader from the computer's ESP, but it works fine when booting from an HFS+ partition. If you use <a href="drivers.html">EFI drivers,</a> though, you can place your kernel on any filesystem for which an EFI driver exists. This list is currently good (ext2fs/ext3fs, ext4fs, ReiserFS, Btrfs, ISO-9660, HFS+, and NTFS in rEFInd, plus more from other sources), so chances are you'll be able to use this method to boot your kernel from your root (<tt>/</tt>) partition or from a <tt>/boot</tt> partition.</p>
 
 <p>rEFInd sorts boot loader entries <i>within each directory</i> by time stamp, so that the most recent entry comes first. Thus, if you specify a directory name (or a volume label, for loaders stored in a volume's root directory) as the <tt>default_selection</tt>, rEFInd will make the most recent loader in the directory the default. This can obviate the need to adjust this configuration parameter when you add a new kernel; chances are you want the most recently-added kernel to be the default, and rEFInd makes it so when you set the <tt>default_selection</tt> in this way. If you <i>don't</i> want the latest kernel to become the default, you can use <tt>touch</tt> to give the desired kernel (or other boot loader) in the directory a more recent time stamp, or you can set <tt>default_selection</tt> to a value that uniquely identifies your desired default loader. One caveat you should keep in mind is that the EFI and Windows interpret the hardware clock as local time, whereas Mac OS X uses <a href="http://en.wikipedia.org/wiki/Coordinated_Universal_Time">Coordinated Universal Time (UTC)</a>. Linux can work either way. Thus, time stamps for boot loaders can be skewed by several hours depending on the environment in which they were created or last modified.</p>
 
 <p class="sidebar"><b>Tip for distribution maintainers:</b> If you maintain an <tt>EFI/<tt class="variable">distname</tt></tt> directory for your kernels, you can place your version of rEFInd in a directory called <tt>EFI/<tt class="variable">distname</tt>/refind</tt>. This will avoid collisions with duplicate rEFInd installations from other distributions.</p>
 
-<p>On the whole, this method of configuration has a lot going for it. For distribution maintainers, if you place your Linux kernel files (with EFI stub support) on the ESP, with suitable filenames, matching initial RAM disk files, and a <tt>refind_linux.conf</tt> file, then any rEFInd 0.2.3 or later installation should detect your files, even if the user installs another distribution with another rEFInd that takes over from yours. (If the user, or this other rEFInd installation, disables auto-detection, this won't work.)</p>
+<p>On the whole, auto-detecting kernels and passing boot options using <tt>refind_linux.conf</tt> has a lot going for it. For distribution maintainers, if you place your Linux kernel files (with EFI stub support) on the ESP, with suitable filenames, matching initial RAM disk files, and a <tt>refind_linux.conf</tt> file, then rEFInd should detect your files, even if the user installs another distribution with another rEFInd that takes over from yours. (If the user, or this other rEFInd installation, disables auto-detection, this won't work.)</p>
 
 <p>For end users, this method is simpler than maintaining manual configurations in <tt>refind.conf</tt> (or equivalents for ELILO or GRUB). To install a new kernel, you need only copy it and its initial RAM disk, under suitable names, to a scanned directory on the ESP. There's no need to touch any configuration file, provided you've already set up <tt>refind_linux.conf</tt> in your kernel's directory. You will, however, have to adjust <tt>refind_linux.conf</tt> if you make certain changes, such as if your root directory identifier changes.</p>
 
 <hr/>
 
-<p>copyright &copy; 2012&ndash;2014 by Roderick W. Smith</p>
+<p>copyright &copy; 2012&ndash;2017 by Roderick W. Smith</p>
 
 <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>