en/handbook/hb-install-x86%2Bamd64-bootloader.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-install-x86+amd64-bootloader.xml,v 1.40 2014/08/17 16:18:31 swift Exp $ -->

<sections>

<version>25</version>
<date>2014-08-17</date>

<section>
<title>Making your Choice</title>
<subsection>
<title>Introduction</title>
<body>

<p>
Now that your kernel is configured and compiled and the necessary system
configuration files are filled in correctly, it is time to install a
program that will fire up your kernel when you start the system. Such a
program is called a <e>bootloader</e>.
</p>

</body>
<body test="contains('AMD64 x86', func:keyval('arch'))">

<p>
For <keyval id="arch"/>, Gentoo Linux provides <uri
link="#grub2">GRUB2</uri>, <uri link="#lilo">LILO</uri> and
<uri link="#grub">GRUB Legacy</uri>.
</p>

</body>
<body test="contains('IA64', func:keyval('arch'))">

<p>
Now, you should install the <uri link="#elilo">elilo bootloader</uri>.
</p>

</body>
</subsection>
</section>
<section id="grub2" test="contains('AMD64 x86', func:keyval('arch'))">
<title>Default: Using GRUB2</title>
<subsection>
<title>Installing GRUB2</title>
<body>

<p>
GRUB2 is provided through the <c>sys-boot/grub</c> package. 
</p>

<pre caption="Installing GRUB2">
# <i>emerge sys-boot/grub</i>
</pre>

<p>
The GRUB2 software is now installed on the system, but not activated yet.
</p>

</body>
</subsection>
<subsection>
<title>Configuring GRUB2</title>
<body>

<p>
First, let us install the necessary GRUB2 files in <path>/boot/grub</path>.
Assuming the first disk (the one where the system boots from) is
<path>/dev/sda</path>, the following command will do this for us:
</p>

<pre caption="Installing the GRUB2 files in /boot/grub">
# <i>grub2-install /dev/sda</i>
</pre>

<p>
Next, we can generate the GRUB2 configuration based on the user configuration
specified in the <path>/etc/default/grub</path> file and
<path>/etc/grub.d</path> scripts. In most cases, no configuration is needed
by users as GRUB2 will automatically detect which kernel to boot (the highest
one available in <path>/boot</path>) and what the root file system is.
</p>

<p>
To generate the final GRUB2 configuration, run the <c>grub2-mkconfig</c>
command:
</p>

<pre caption="Generating GRUB2 configuration">
# <i>grub2-mkconfig -o /boot/grub/grub.cfg</i>
Generating grub.cfg ...
Found linux image: /boot/<keyval id="kernel-name" />
Found initrd image: /boot/<keyval id="genkernel-initrd" />
done
</pre>

<p>
The output of the command <e>must</e> mention that at least one Linux image is
found, as those are needed to boot the system. If you use initramfs or used
<c>genkernel</c> to build the kernel, the correct initrd image should be
detected as well. If this is not the case, go to <path>/boot</path> and check
the contents using the <c>ls</c> command. If the files are indeed missing, go
back to the kernel configuration and installation instructions.
</p>

</body>
</subsection>
</section>
<section id="lilo" test="contains('AMD64 x86', func:keyval('arch'))">
<title>Alternative: Using LILO</title>
<subsection>
<title>Installing LILO</title>
<body>

<p>
LILO, the LInuxLOader, is the tried and true workhorse of Linux
bootloaders. However, it lacks some features that GRUB has (which is
also the reason why GRUB is currently gaining popularity). The reason
why LILO is still used is that, on some systems, GRUB doesn't work and
LILO does. Of course, it is also used because some people know LILO and
want to stick with it. Either way, Gentoo supports both, and apparently
you have chosen to use LILO.
</p>

<p>
Installing LILO is a breeze; just use <c>emerge</c>.
</p>

<pre caption="Installing LILO">
# <i>emerge lilo</i>
</pre>

</body>
</subsection>
<subsection>
<title>Configuring LILO</title>
<body>

<p>
To configure LILO, you must create <path>/etc/lilo.conf</path>. Fire up
your favorite editor (in this handbook we use <c>nano</c> for
consistency) and create the file.
</p>

<pre caption="Creating /etc/lilo.conf">
# <i>nano -w /etc/lilo.conf</i>
</pre>

<p>
Some sections ago we have asked you to remember the kernel-image name
you have created. In the next example <path>lilo.conf</path> we use the
example partitioning scheme. 
</p>

<p>
Make sure you use <e>your</e> kernel image filename and, if appropriate,
<e>your</e> initrd image filename.
</p>

<note>
If your root filesystem is JFS, you <e>must</e> add a <c>append="ro"</c>
line after each boot item since JFS needs to replay its log before it allows
read-write mounting.
</note>

<pre caption="Example /etc/lilo.conf">
boot=/dev/sda             <comment># Install LILO in the MBR</comment>
prompt                    <comment># Give the user the chance to select another section</comment>
timeout=50                <comment># Wait 5 (five) seconds before booting the default section</comment>
default=gentoo            <comment># When the timeout has passed, boot the "gentoo" section</comment>

image=/boot/<keyval id="kernel-name"/>
  label=gentoo            <comment># Name we give to this section</comment>
  read-only               <comment># Start with a read-only root. Do not alter!</comment>
  root=/dev/sda4          <comment># Location of the root filesystem</comment>

image=/boot/<keyval id="kernel-name"/>
  label=gentoo.rescue     <comment># Name we give to this section</comment>
  read-only               <comment># Start with a read-only root. Do not alter!</comment>
  root=/dev/sda4          <comment># Location of the root filesystem</comment>
  append="init=/bin/bb"   <comment># Launch the Gentoo static rescue shell</comment>

<comment># The next two lines are only if you dualboot with a Windows system.</comment>
<comment># In this example, Windows is hosted on /dev/sda6.</comment>
other=/dev/sda6
  label=windows
</pre>

<note>
If you use a different partitioning scheme and/or kernel image, adjust
accordingly.
</note>

<p>
If, while building the Linux kernel, you opted to include an initramfs to boot
from, then you will need to change the configuration by referring to this
initramfs file and telling the initramfs where your real root device is at:
</p>

<pre caption="LILO snippet for initramfs-enabled kernel builds">
image=/boot/<keyval id="kernel-name"/>
  label=gentoo
  read-only
  <i>append="real_root=/dev/sda4"</i>
  <i>initrd=/boot/<keyval id="genkernel-initrd" /></i>
</pre>

<p>
If you need to pass any additional options to the kernel, add an
<c>append</c> statement to the section. As an example, we add the
<c>video</c> statement to enable framebuffer:
</p>

<pre caption="Using append to add kernel options">
image=/boot/<keyval id="kernel-name"/>
  label=gentoo
  read-only
  root=/dev/sda4
  <i>append="video=uvesafb:mtrr,ywrap,1024x768-32@85"</i>
</pre>

<p>
If you're using a 2.6.7 or higher kernel and you jumpered your harddrive
because the BIOS can't handle large harddrives you'll need to append
<c>sda=stroke</c>. Replace sda with the device that requires this option.
</p>

<p>
<c>genkernel</c> users should know that their kernels use the same boot options
as is used for the Installation CD. For instance, if you have SCSI devices, you
should add <c>doscsi</c> as kernel option.
</p>

<p>
Now save the file and exit. To finish up, you have to run <c>/sbin/lilo</c> so
LILO can apply the <path>/etc/lilo.conf</path> to your system (i.e. install
itself on the disk). Keep in mind that you'll also have to run
<c>/sbin/lilo</c> every time you install a new kernel or make any changes to
the menu.
</p>

<pre caption="Finishing the LILO installation">
# <i>/sbin/lilo</i>
</pre>

<p>
If you have more questions regarding LILO, please consult its <uri
link="http://en.wikipedia.org/wiki/LILO_(boot_loader)">wikipedia page</uri>.
</p>

<p>
You can now continue with <uri link="#reboot">Rebooting the System</uri>.
</p>

</body>
</subsection>
</section>
<section id="grub" test="contains('AMD64 x86',func:keyval('arch'))">
<title>Alternative: Using GRUB Legacy</title>
<subsection>
<title>What is Legacy?</title>
<body>

<p>
GRUB has been reworked and a new release dubbed GRUB2 is made available. The new
GRUB2 codebase is quite different from the current GRUB, which is why this GRUB
version is now dubbed as "GRUB Legacy".
</p>

</body>
</subsection>
<subsection>
<title>Understanding GRUB's terminology</title>
<body>

<p>
The most critical part of understanding GRUB is getting comfortable with how
GRUB refers to hard drives and partitions. Your Linux partition
<path>/dev/sda2</path> will most likely be called <path>(hd0,1)</path> under
GRUB. Notice the parentheses around the <path>hd0,1</path> - they are
required.
</p>

<p>
Hard drives count from zero rather than "a" and partitions start at zero
rather than one. Be aware too that with the hd devices, only hard drives are
counted, not atapi-ide devices such as cdrom players and burners.  Also, the
same construct is used with SCSI drives. (Normally they get higher numbers
than IDE drives except when the BIOS is configured to boot from SCSI devices.)
When you ask the BIOS to boot from a different hard disk (for instance your
primary slave), <e>that</e> harddisk is seen as <path>hd0</path>.
</p>

<p>
Assuming you have a hard drive on <path>/dev/sda</path> and two more on
<path>/dev/sdb</path> and <path>/dev/sdc</path>, <path>/dev/sdb7</path> gets
translated to <path>(hd1,6)</path>. It might sound tricky and tricky it is
indeed, but as we will see, GRUB offers a tab completion mechanism that comes
handy for those of you having a lot of hard drives and partitions and who are a
little lost in the GRUB numbering scheme.
</p>

<p>
Having gotten the feel for that, it is time to install GRUB.
</p>

</body>
</subsection>
<subsection>
<title>Installing GRUB</title>
<body>

<p>
To install GRUB Legacy, let's first emerge it:
</p>

<impo test="func:keyval('arch')='AMD64'">
If you are using a non-multilib <uri
link="?part=1&amp;chap=6#doc_chap2">profile</uri> and still intend to use the
GRUB Legacy (instead of GRUB2), you should <b>not</b> emerge
<c>grub:0</c>, but instead you should emerge <c>grub-static</c> (only possible
if you have enabled IA-32 emulation).
</impo>

<pre caption="Installing GRUB">
# <i>emerge sys-boot/grub:0</i>
</pre>

<p>
Although GRUB is now installed, we still need to write up a
configuration file for it and place GRUB in our MBR so that GRUB automatically
boots your newly created kernel. Create <path>/boot/grub/grub.conf</path> with
<c>nano</c> (or, if applicable, another editor):
</p>

<pre caption="Creating /boot/grub/grub.conf">
# <i>nano -w /boot/grub/grub.conf</i>
</pre>

<p>
Now we are going to write up a <path>grub.conf</path>. Make
sure you use <e>your</e> kernel image filename and, if appropriate, <e>your</e>
initrd image filename.
</p>

<note>
Grub assigns device designations from the BIOS. If you change your BIOS
settings, your device letters and numbers may change, too. For example, if you
change your device boot order, you may need to change your grub configuration.
</note>

<note>
If your root filesystem is JFS, you <e>must</e> add " ro" to the <c>kernel</c>
line since JFS needs to replay its log before it allows read-write mounting.
</note>

<note>
If dualboot with Windows is used, the partitioning example used in this
book will not be sufficient (our example uses all four primary partitions
for Linux, whereas at least one would need to be extended if Windows is
installed on a logical partition). Please proceed with caution and consider
the listing to be an example that needs to be modified to suit your own needs.
</note>

<pre caption="Example grub.conf">
<comment># Which listing to boot as default. 0 is the first, 1 the second etc.</comment>
default 0
<comment># How many seconds to wait before the default listing is booted.</comment>
timeout 30
<comment># Nice, fat splash-image to spice things up :)
# Comment out if you don't have a graphics card installed</comment>
splashimage=(hd0,1)/boot/grub/splash.xpm.gz

title Gentoo Linux <keyval id="kernel-version"/>
<comment># Partition where the kernel image (or operating system) is located</comment>
root (hd0,1)
kernel /boot/<keyval id="kernel-name"/> root=/dev/sda4

title Gentoo Linux <keyval id="kernel-version"/> (rescue)
<comment># Partition where the kernel image (or operating system) is located</comment>
root (hd0,1)
kernel /boot/<keyval id="kernel-name"/> root=/dev/sda4 init=/bin/bb

<comment># The next four lines are only if you dualboot with a Windows system.</comment>
<comment># In this case, Windows is hosted on /dev/sda6.</comment>
title Windows XP
rootnoverify (hd0,5)
makeactive
chainloader +1
</pre>

<p>
If, while building the Linux kernel, you opted to include an initramfs to boot
from, then you will need to change the configuration by referring to this
initramfs file and telling the initramfs where your real root device is at:
</p>

<pre caption="GRUB snippet for initramfs-enabled kernel builds">
title Gentoo Linux <keyval id="kernel-version"/>
root (hd0,1)
kernel /boot/<keyval id="kernel-version"/> <i>real_</i>root=/dev/sda4
<i>initrd /boot/<keyval id="genkernel-initrd"/></i>
</pre>

<p>
If you used a different partitioning scheme and/or kernel image, adjust
accordingly. However, make sure that anything that follows a GRUB-device (such
as <path>(hd0,1)</path>) is relative to the mountpoint, not the root. In other
words, <path>(hd0,1)/grub/splash.xpm.gz</path> is in reality
<path>/boot/grub/splash.xpm.gz</path> since <path>(hd0,1)</path> is
<path>/boot</path>.
</p>

<p>
Besides, if you chose to use a different partitioning scheme and did not put
<path>/boot</path> in a separate partition, the <path>/boot</path> prefix used
in the above code samples is really <e>required</e>. If you followed our
suggested partitioning plan, the <path>/boot</path> prefix it not required, but
a <path>boot</path> symlink makes it work. In short, the above examples should
work whether you defined a separate <path>/boot</path> partition or not.
</p>

<p>
If you need to pass any additional options to the kernel, simply add them to the
end of the kernel command. We're already passing one option
(<c>root=/dev/sda4</c> or <c>real_root=/dev/sda4</c>), but you can pass others
as well, such as the <c>video</c> statement for framebuffer as we discussed
previously.
</p>

<p>
If your bootloader configuration file contains the real_root parameter, use the
real_rootflags parameter to set root filesystem mount options.
</p>

<p>
If you're using a 2.6.7 or higher kernel and you jumpered your harddrive
because the BIOS can't handle large harddrives you'll need to append
<c>sda=stroke</c>. Replace sda with the device that requires this option.
</p>

<p>
<c>genkernel</c> users should know that their kernels use the same boot options
as is used for the Installation CD. For instance, if you have SCSI devices, you
should add <c>doscsi</c> as kernel option.
</p>

<p>
Now save the <path>grub.conf</path> file and exit. You still need to install
GRUB in the MBR (Master Boot Record) so that GRUB is automatically executed when
you boot your system.
</p>

<p>
The GRUB developers recommend the use of <c>grub-install</c>. However, if for
some reason <c>grub-install</c> fails to work correctly you still have the
option to manually install GRUB.
</p>

<p>
Continue with <uri link="#grub-install-auto">Default: Setting up GRUB using
grub-install</uri> or <uri link="#grub-install-manual">Alternative: Setting up
GRUB using manual instructions</uri>.
</p>

</body>
</subsection>
<subsection id="grub-install-auto">
<title>Default: Setting up GRUB using grub-install</title>
<body>

<p>
To install GRUB you will need to issue the <c>grub-install</c> command.
However, <c>grub-install</c> won't work off-the-shelf since we are inside a
chrooted environment. We need to create <path>/etc/mtab</path> which lists all
mounted filesystems. Fortunately, there is an easy way to accomplish this -
just copy over <path>/proc/mounts</path> to <path>/etc/mtab</path>, excluding
the <c>rootfs</c> line if you haven't created a separate boot partition. The
following command will work in both cases:
</p>

<pre caption="Creating /etc/mtab">
# <i>grep -v rootfs /proc/mounts &gt; /etc/mtab</i>
</pre>

<p>
When using Linux virtio disks, we need to tell grub where to find the disks as
the <c>grub-install</c> command will otherwise fail. This is done by adding the
device definition to the <path>device.map</path> file:
</p>

<pre caption="Adding the virtio disk to the device map table">
# <i>echo "(hd0)        /dev/vda" >> /boot/grub/device.map</i>
</pre>

<p>
Now we can install GRUB using <c>grub-install</c>:
</p>

<pre caption="Running grub-install">
# <i>grub-install --no-floppy /dev/sda</i>
</pre>

<p>
If you have more questions regarding GRUB, please consult the <uri
link="http://www.gnu.org/software/grub/grub-faq.html">GRUB FAQ</uri>, the <uri
link="http://grub.enbug.org/GrubLegacy">GRUB Wiki</uri>, or read <c>info
grub</c> in your terminal.
</p>

<p>
Continue with <uri link="#reboot">Rebooting the System</uri>.
</p>

</body>
</subsection>
<subsection id="grub-install-manual">
<title>Alternative: Setting up GRUB using manual instructions</title>
<body>

<p>
To start configuring GRUB, you type in <c>grub</c>. You'll be presented
with the <path>grub&gt;</path> grub command-line prompt. Now, you need to type
in the right commands to install the GRUB boot record onto your hard drive.
</p>

<pre caption="Starting the GRUB shell">
# <i>grub --no-floppy</i>
</pre>

<note>
If your system does not have any floppy drives, add the <c>--no-floppy</c>
option to the above command to prevent grub from probing the (non-existing)
floppy drives.
</note>

<p>
In the example configuration we want to install GRUB so that it reads its
information from the boot partition <path><keyval id="/boot"/></path>, and
installs the GRUB boot record on the hard drive's MBR (master boot record) so
that the first thing we see when we turn on the computer is the GRUB prompt. Of
course, if you haven't followed the example configuration during the
installation, change the commands accordingly.
</p>

<p>
The tab completion mechanism of GRUB can be used from within GRUB.
For instance, if you type in "<c>root (</c>" followed by a TAB, you will
be presented with a list of devices (such as <path>hd0</path>). If you
type in "<c>root (hd0,</c>" followed by a TAB, you will receive a list
of available partitions to choose from (such as <path>hd0,1</path>).
</p>

<p>
By using the tab completion, setting up GRUB should be not that hard.
Now go on, configure GRUB, shall we? :-)
</p>

<pre caption="Installing GRUB in the MBR">
grub&gt; <i>root (hd0,1)</i>    <comment>(Specify where your /boot partition resides)</comment>
grub&gt; <i>setup (hd0)</i>     <comment>(Install GRUB in the MBR)</comment>
grub&gt; <i>quit</i>            <comment>(Exit the GRUB shell)</comment>
</pre>

<note>
If you want to install GRUB in a certain partition instead of the MBR,
you have to alter the <c>setup</c> command so it points to the right
partition. For instance, if you want GRUB installed in
<path>/dev/sda4</path>, then the command becomes <c>setup (hd0,3)</c>.
Few users however want to do this.
</note>

<p>
If you have more questions regarding GRUB, please consult the <uri
link="http://www.gnu.org/software/grub/grub-faq.html">GRUB FAQ</uri>, the <uri
link="http://grub.enbug.org/GrubLegacy">GRUB Wiki</uri>, or read <c>info
grub</c> in your terminal.
</p>

<p>
Continue with <uri link="#reboot">Rebooting the System</uri>.
</p>

</body>
</subsection>
</section>

<section id="elilo" test="func:keyval('arch')='IA64'">
<title>Default: Installing elilo</title>
<body>

<p>
On the IA64 platform, the boot loader is called <c>elilo</c>. You may need to
emerge it on your machine first.
</p>

<pre caption="Installing elilo">
# <i>emerge elilo</i>
</pre>

<p>
You can find the configuration file at <path>/etc/elilo.conf</path> and a
sample file in the typical docs dir
<path>/usr/share/doc/elilo-&lt;ver&gt;/</path>. Here is another sample
configuration:
</p>

<pre caption="/etc/elilo.conf example">
boot=/dev/sda1
delay=30
timeout=50
default=Gentoo
append="console=ttyS0,9600"
prompt

image=/vmlinuz
        label=Gentoo
        root=/dev/sda2
        read-only

image=/vmlinuz.old
        label=Gentoo.old
        root=/dev/sda2
        read-only
</pre>

<p>
The <c>boot</c> line tells elilo the location of the boot partition (in this
case, <path>/dev/sda1</path>). The <c>delay</c> line sets the number of
10<sup>th</sup> of seconds before automatically booting the default when in
non-interactive mode. The <c>timeout</c> line is just like the delay line but
for interactive mode. The <c>default</c> line sets the default kernel entry
(which is defined below). The <c>append</c> line adds extra options to the
kernel command line. The <c>prompt</c> sets the default elilo behavior to
interactive.
</p>

<p>
The sections that start with <c>image</c> define different bootable images.
Each image has a nice <c>label</c>, a <c>root</c> filesystem, and will only
mount the root filesystem <c>read-only</c>.
</p>

<p>
If, while building the Linux kernel, you opted to include an initramfs to boot
from, then you will need to change the configuration by referring to this
initramfs file and telling the initramfs where your real root device is at:
</p>

<pre caption="ELILO snippet for initramfs-enabled kernel-builds">
image=/vmlinuz
        label=Gentoo
        <i>initrd=/<keyval id="genkernel-initrd"/></i>
        <i>append = "initrd=<keyval id="genkernel-initrd"/> real_root=/dev/sda2 console=ttyS0,9600"</i>
        read-only
</pre>

<p>
When configuration is done, just run <c>elilo --efiboot</c>. The
<c>--efiboot</c> option adds a menu entry for Gentoo Linux to the EFI Boot
Manager.
</p>

<pre caption="Applying the elilo configuration">
# <i>elilo --efiboot</i>
</pre>

<p>
Now continue with <uri link="#reboot">Rebooting the System</uri>.
</p>

</body>
</section>
<section id="reboot">
<title>Rebooting the System</title>
<subsection>
<body>

<p>
Exit the chrooted environment and unmount all mounted partitions. Then type in
that one magical command you have been waiting for: <c>reboot</c>.
</p>

<pre caption="Unmounting all partitions and rebooting" test="func:keyval('arch')='IA64'">
# <i>exit</i>
cdimage ~# <i>cd</i>
cdimage ~# <i>umount -l /mnt/gentoo/dev{/pts,/shm,}</i>
cdimage ~# <i>umount /mnt/gentoo{/boot,/sys,/proc,}</i>
cdimage ~# <i>reboot</i>
</pre>

<pre caption="Unmounting all partitions and rebooting" test="not(func:keyval('arch')='IA64')">
# <i>exit</i>
cdimage ~# <i>cd</i>
cdimage ~# <i>umount -l /mnt/gentoo/dev{/shm,/pts,}</i>
cdimage ~# <i>umount /mnt/gentoo{/boot,/sys,/proc,}</i>
cdimage ~# <i>reboot</i>
</pre>

<p>
Of course, don't forget to remove the bootable CD, otherwise the CD will be
booted again instead of your new Gentoo system.
</p>

<p test="func:keyval('arch')='IA64'">
When you reboot you should see a new Gentoo Linux menu option in the EFI Boot
Manager which will boot Gentoo.
</p>

<p>
Once rebooted in your Gentoo installation, finish up with <uri
link="?part=1&amp;chap=11">Finalizing your Gentoo Installation</uri>.
</p>

</body>
</subsection>
</section>
</sections>