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.6 2006/11/02 07:27:24 nightmorph Exp $ -->

<sections>

<version>4.3</version>
<date>2007-03-12</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>

<p test="func:keyval('arch')='x86'">
For x86, Gentoo Linux provides <uri
link="#grub">GRUB</uri> and <uri link="#lilo">LILO</uri>.
</p>

<p>
But before we install the bootloader, we inform you how to configure
framebuffer (assuming you want it of course). With framebuffer you can run the
Linux command line with (limited) graphical features (such as using the nice
bootsplash image Gentoo provides).
</p>

</body>
</subsection>
<subsection>
<title>Optional: Framebuffer</title>
<body>

<p>
<e>If</e> you have configured your kernel with framebuffer support (or you used
<c>genkernel</c> default kernel configuration), you can activate it by adding a
<c>vga</c> and/or a <c>video</c> statement to your bootloader configuration
file.
</p>

<p test="func:keyval('arch')='x86'">
First of all, you need to know what type of framebuffer device you're using. If
you use a Gentoo patched kernel tree (such as <c>gentoo-sources</c>) you will
have had the possibility of selecting <c>vesafb-tng</c> as the <e>VESA driver
type</e> (which is default for these kernel sources). If this is the case, you
are using <c>vesafb-tng</c> and <e>do not need</e> to set a <c>vga</c>
statement. Otherwise you are using the <c>vesafb</c> driver and <e>need</e> to
set the <c>vga</c> statement.
</p>

<p test="func:keyval('arch')='AMD64'">
64-bit systems must use the the <c>vesafb</c> driver, and need the <c>vga</c>
statement.
</p>

<p>
The <c>vga</c> statement controls the resolution and color depth of your
framebuffer screen for <c>vesafb</c>. As stated in
<path>/usr/src/linux/Documentation/fb/vesafb.txt</path> (which gets installed
when you install a kernel source package), you need to pass the VESA number
corresponding to the requested resolution and color depth to it.
</p>

<p>
The following table lists the available resolutions and color depths and
matches those against the value that you need to pass on to the <c>vga</c>
statement.
</p>

<table>
<tr>
  <ti></ti>
  <th>640x480</th>
  <th>800x600</th>
  <th>1024x768</th>
  <th>1280x1024</th>
</tr>
<tr>
  <th>256</th>
  <ti>0x301</ti>
  <ti>0x303</ti>
  <ti>0x305</ti>
  <ti>0x307</ti>
</tr>
<tr>
  <th>32k</th>
  <ti>0x310</ti>
  <ti>0x313</ti>
  <ti>0x316</ti>
  <ti>0x319</ti>
</tr>
<tr>
  <th>64k</th>
  <ti>0x311</ti>
  <ti>0x314</ti>
  <ti>0x317</ti>
  <ti>0x31A</ti>
</tr>
<tr>
  <th>16M</th>
  <ti>0x312</ti>
  <ti>0x315</ti>
  <ti>0x318</ti>
  <ti>0x31B</ti>
</tr>
</table>

<p>
The <c>video</c> statement controls framebuffer display options. It needs to be
given the framebuffer driver (<c>vesafb</c> for 2.6 kernels, or <c>vesa</c> for
2.4 kernels) followed by the control statements you wish to enable. All
variables are listed in
<path>/usr/src/linux/Documentation/fb/vesafb.txt</path>. The most-used options
are:
</p>

<table>
<tr>
  <th>Control</th>
  <th>Description</th>
</tr>
<tr>
  <ti>ywrap</ti>
  <ti>
    Assume that the graphical card can wrap around its memory (i.e. continue at
    the beginning when it has approached the end)
  </ti>
</tr>
<tr>
  <ti>mtrr:n</ti>
  <ti>
    Setup MTRR registers. <c>n</c> can be:<br/>
    0 - disabled<br/>
    1 - uncachable<br/>
    2 - write-back<br/>
    3 - write-combining<br/>
    4 - write-through
  </ti>
</tr>
<tr test="func:keyval('arch')='x86'">
  <ti><c>mode</c></ti>
  <ti>
    (<c>vesafb-tng</c> only)<br/>
    Set up the resolution, color depth and refresh rate. For instance,
    <c>1024x768-32@85</c> for a resolution of 1024x768, 32 bit color depth and a
    refresh rate of 85 Hz.
  </ti>
</tr>
</table>

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

<p>
The result of those two statements could be something like <c>vga=0x318
video=vesafb:mtrr:3,ywrap</c>. Write this setting down; you will need it
shortly.
</p>

<p>
While LILO does work on AMD64, Gentoo only supports using GRUB. Now continue by
its <uri link="#grub">installation</uri>.
</p>

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

<p>
The result of those two statements could be something like <c>vga=0x318
video=vesafb:mtrr:3,ywrap</c> or
<c>video=vesafb:mtrr:3,ywrap,1024x768-32@85</c>. Write this setting down; you
will need it shortly.
</p>

<p>
Now continue by installing <uri link="#grub">GRUB</uri> <e>or</e> <uri
link="#lilo">LILO</uri>.
</p>

</body>
</subsection>
</section>
<section id="grub">
<title>Default: Using GRUB</title>
<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/hda1</path> (for IDE drives) or <path>/dev/sda1</path> (for
SATA/SCSI drives) will most likely be called <path>(hd0,0)</path> under GRUB.
Notice the parentheses around the <path>hd0,0</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/hda</path>, a cdrom player on
<path>/dev/hdb</path>, a burner on <path>/dev/hdc</path>, a second hard drive
on <path>/dev/hdd</path> and no SCSI hard drive, <path>/dev/hdd7</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, 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>, you should <b>not</b> emerge
grub, but instead you should emerge <c>grub-static</c>.
</impo>

<pre caption="Installing GRUB">
# <i>emerge grub</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>. Below you'll find two
possible <path>grub.conf</path> for the partitioning example we use in this
guide. We've only extensively commented the first <path>grub.conf</path>. Make
sure you use <e>your</e> kernel image filename and, if appropriate, <e>your</e>
initrd image filename.
</p>

<ul>
  <li>
    The first <path>grub.conf</path> is for people who have not used
    <c>genkernel</c> to build their kernel
  </li>
  <li>
    The second <path>grub.conf</path> is for people who have used
    <c>genkernel</c> to build their kernel
  </li>
</ul>

<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>

<pre caption="grub.conf for non-genkernel users">
<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,0)/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,0)
kernel /boot/<keyval id="kernel-name"/> root=/dev/hda3

title=Gentoo Linux <keyval id="kernel-version"/> (rescue)
<comment># Partition where the kernel image (or operating system) is located</comment>
root (hd0,0)
kernel /boot/<keyval id="kernel-name"/> root=/dev/hda3 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/hda6.</comment>
title=Windows XP
rootnoverify (hd0,5)
makeactive
chainloader +1
</pre>

<pre caption="grub.conf for genkernel users">
default 0
timeout 30
splashimage=(hd0,0)/boot/grub/splash.xpm.gz

title=Gentoo Linux <keyval id="kernel-version"/>
root (hd0,0)
kernel /boot/<keyval id="genkernel-name"/> root=/dev/ram0 init=/linuxrc ramdisk=8192 real_root=/dev/hda3 udev
initrd /boot/<keyval id="genkernel-initrd"/>

<comment># Only in case you want to dual-boot</comment>
title=Windows XP
rootnoverify (hd0,5)
makeactive
chainloader +1
</pre>

<note>
The <c>udev</c> mentioned at the end of the kernel line is needed to work around
a bug in some genkernel versions <e>if</e> you use udev in the first place
(which is the default behaviour).
</note>

<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,0)</path>) is relative to the mountpoint, not the root. In other
words, <path>(hd0,0)/grub/splash.xpm.gz</path> is in reality
<path>/boot/grub/splash.xpm.gz</path> since <path>(hd0,0)</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/hda3</c> or <c>real_root=/dev/hda3</c>), but you can pass others
as well, such as the <c>video</c> and/or <c>vga</c> statements for framebuffer
as we discussed previously.
</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>hdx=stroke</c>.
</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>
Now we can install GRUB using <c>grub-install</c>:
</p>

<pre caption="Running grub-install">
# <i>grub-install --no-floppy /dev/hda</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> or the
<uri link="http://www.gnu.org/software/grub/manual/">GRUB Manual</uri>.
</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,0</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,0)</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/hda3</path>, then the command becomes <c>setup (hd0,2)</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> or the <uri
link="http://www.gnu.org/software/grub/manual/">GRUB Manual</uri>.
</p>

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

</body>
</subsection>
</section>
<section id="lilo" test="func:keyval('arch')='x86'">
<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. There are two separate parts:
</p>

<ul>
  <li>
    One for those who have not used <c>genkernel</c> to build their kernel
  </li>
  <li>
    One for those who have used <c>genkernel</c> to build their kernel
  </li>
</ul>

<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/hda             <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>

<comment># For non-genkernel users</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/hda3          <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/hda3          <comment># Location of the root filesystem</comment>
  append="init=/bin/bb"   <comment># Launch the Gentoo static rescue shell</comment>

<comment># For genkernel users</comment>
image=/boot/<keyval id="genkernel-name"/>
  label=gentoo
  read-only
  root=/dev/ram0
  append="init=/linuxrc ramdisk=8192 real_root=/dev/hda3 udev"
  initrd=/boot/<keyval id="genkernel-initrd"/>

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

<note>
The <c>udev</c> mentioned at the end of the append line is needed to work around
a bug in some genkernel versions <e>if</e> you use udev in the first place
(which is the default behaviour).
</note>

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

<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/hda3
  <i>append="video=vesafb: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>hdx=stroke</c>.
</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="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">
# <i>exit</i>
cdimage ~# <i>cd</i>
cdimage ~# <i>umount /mnt/gentoo/boot /mnt/gentoo/dev /mnt/gentoo/proc /mnt/gentoo</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>
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>