+<p>The Linux <a href="http://www.rodsbooks.com/efi-bootloaders/efistub.html">EFI stub loader</a> is a way to turn a Linux kernel into an EFI application. In a sense, the kernel becomes its own boot loader. This approach to booting Linux is very elegant in some ways, but as described on the page to which I just linked, it has its disadvantages, too. One challenge to booting in this way is that modern Linux installations typically require that the kernel be passed a number of options at boot time. These tell the kernel where the Linux root (<tt>/</tt>) filesystem is, where the initial RAM disk is, and so on. Without these options, Linux won't boot. These options are impossible for a generic boot loader to guess without a little help. It's possible to build a kernel with a default set of options, but this is rather limiting. Thus, rEFInd provides configuration options to help.</p>
+
+<p>With all versions of rEFInd, you can create manual boot loader stanzas
+in the <tt>refind.conf</tt> file to identify a Linux kernel and to pass it
+all the options it needs. This approach is effective and flexible, but it
+requires editing a single configuration file for all the OSes you want to
+define in this way. If a computer boots two different Linux distributions,
+and if both were to support rEFInd, problems might arise as each one tries
+to modify its own rEFInd configuration; or the one that controls rEFInd
+might set inappropriate options for another distribution. This is a problem
+that's been a minor annoyance for years under BIOS, since the same
+potential for poor configuration applies to LILO, GRUB Legacy, and GRUB 2
+on BIOS. The most reliable solution under BIOS is to chainload one boot
+loader to another. The same solution is possible under EFI, but rEFInd
+offers another possibility.</p>
+
+<p>rEFInd supports semi-automatic Linux EFI stub loader detection. This
+feature works as part of the standard boot loader scan operation, but it
+extends it as follows:</p>
+
+<ol>
+
+<li>rEFInd looks for boot loaders whose names include the strings
+ <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 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
+ without the key won't boot on a computer with Secure Boot active, and
+ either will boot if Secure Boot is inactive. Thus, rEFInd excludes the
+ redundant (unsigned) file in order to help keep the list of boot
+ options manageable.</li>
+
+<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
+ <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.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 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
+ <tt>/etc/fstab</tt> on the partition that holds the kernel. If this
+ standard Linux file is present, rEFInd uses it to identify the root
+ (<tt>/</tt>) filesystem and creates two sets of Linux kernel boot
+ options: One set launches the kernel normally, but with minimal
+ options, and the other set launches the kernel into single-user mode.
+ This step can get a computer to boot without any rEFInd-specific
+ configuration files, aside from <tt>refind.conf</tt> in rEFInd's own
+ directory, but only if <tt>/boot</tt> is not a separate partition. The
+ intent is to facilitate the use of rEFInd as an emergency boot manager
+ or to help users who must install rEFInd from OS X or Windows. Note
+ that rEFInd uses <tt>/etc/fstab</tt> only if <tt>refind_linux.conf</tt>
+ is <i>not</i> found.</li>
+
+<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>