source: chapter08/grub.xml@ fbe0187

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../general.ent">
  %general-entities;
]>

<sect1 id="ch-bootable-grub" role="wrap">
  <?dbhtml filename="grub.html"?>

  <sect1info condition="script">
    <productname>grub</productname>
    <productnumber>&grub-version;</productnumber>
    <address>&grub-url;</address>
  </sect1info>

  <title>GRUB-&grub-version;</title>

  <indexterm zone="ch-bootable-grub">
    <primary sortas="a-Grub">GRUB</primary>
  </indexterm>

  <sect2 role="package">
    <title/>

    <para>The GRUB package contains the GRand Unified Bootloader.</para>

    <segmentedlist>
      <segtitle>&buildtime;</segtitle>
      <segtitle>&diskspace;</segtitle>

      <seglistitem>
        <seg>&grub-ch6-sbu;</seg>
        <seg>&grub-ch6-du;</seg>
      </seglistitem>
    </segmentedlist>

  </sect2>

  <sect2 role="installation">
    <title>Installation of GRUB</title>

    <para>Your shiny new LFS system is almost complete. One of the last
    things to do is to ensure that the system can be properly booted.</para>

    <caution>
      <para>This package will only build for x86 and x86_64 architectures
      containing 32-bit libs. If you chose to build on x86_64 without 32-bit
      libraries (no multilib), then you must use LILO instead. Information on
      <quote>boot loading</quote> for other architectures should be available in
      the usual resource-specific locations for those architectures.</para>
    </caution>

    <para>This package is known to have issues when its default
    optimization flags (including the <parameter>-march</parameter> and
    <parameter>-mcpu</parameter> options) are changed. If any environment
    variables that override default optimizations have been defined, such
    as <envar>CFLAGS</envar> and <envar>CXXFLAGS</envar>,
    unset them when building GRUB.</para>

    <para>Start by applying the following patch to allow for better drive
    detection, fix some GCC 4.x issues, and provide better SATA support
    for some disk controllers:</para>

<screen><userinput remap="pre">patch -Np1 -i ../&grub-geometry-patch;</userinput></screen>

    <para>By default, GRUB doesn't support ext2 filesystems with 256-byte inodes.
    Fix this by applying the following patch:</para>

<screen><userinput remap="pre">patch -Np1 -i ../&grub-inode-patch;</userinput></screen>

    <para>Prepare GRUB for compilation:</para>

<screen><userinput remap="configure">./configure --prefix=/usr</userinput></screen>

    <para>Compile the package, but use custom optimization flags to
    prevent an error flagged in the test routines:</para>

<screen><userinput remap="make">make CFLAGS="-march=i486 -mtune=native -Os"</userinput></screen>

    <para>To test the results, issue:</para>

<screen><userinput remap="test">make check</userinput></screen>

    <para>Install the package:</para>

<screen><userinput remap="install">make install
mkdir -v /boot/grub
cp -v /usr/lib/grub/i386-pc/stage{1,2} /boot/grub</userinput></screen>

    <para>Replace <filename class="directory">i386-pc</filename> with whatever
    directory is appropriate for the hardware in use.</para>

    <para>The <filename class="directory">i386-pc</filename> directory
    contains a number of <filename>*stage1_5</filename> files, different
    ones for different file systems. Review the files available and copy
    the appropriate ones to the <filename
    class="directory">/boot/grub</filename> directory. Most users will
    copy the <filename>e2fs_stage1_5</filename> and/or
    <filename>reiserfs_stage1_5</filename> files.</para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring GRUB</title>


    <para>Boot loading can be a complex area, so a few cautionary
    words are in order. Be familiar with the current boot loader and any other
    operating systems present on the hard drive(s) that need to be
    bootable. Make sure that an emergency boot disk is ready to
    <quote>rescue</quote> the computer if the computer becomes
    unusable (un-bootable).</para>

    <para>The procedure involves writing some special GRUB files to specific
    locations on the hard drive. We highly recommend creating a GRUB boot floppy
    diskette as a backup. Insert a blank floppy diskette and run the following
    commands:</para>

<screen><userinput>dd if=/boot/grub/stage1 of=/dev/fd0 bs=512 count=1
dd if=/boot/grub/stage2 of=/dev/fd0 bs=512 seek=1</userinput></screen>

    <para>Remove the diskette and store it somewhere safe. Now, run the
    <command>grub</command> shell:</para>

<screen><userinput>grub</userinput></screen>

    <para>GRUB uses its own naming structure for drives and partitions in
    the form of <emphasis>(hdn,m)</emphasis>, where <emphasis>n</emphasis>
    is the hard drive number and <emphasis>m</emphasis> is the partition
    number, both starting from zero. For example, partition <filename
    class="partition">hda1</filename> is <emphasis>(hd0,0)</emphasis> to
    GRUB and <filename class="partition">hdb3</filename> is
    <emphasis>(hd1,2)</emphasis>. In contrast to Linux, GRUB does not
    consider CD-ROM drives to be hard drives. For example, if using a CD
    on <filename class="partition">hdb</filename> and a second hard drive
    on <filename class="partition">hdc</filename>, that second hard drive
    would still be <emphasis>(hd1)</emphasis>.</para>

    <para>Using the above information, determine the appropriate
    designator for the root partition (or boot partition, if a separate
    one is used). For the following example, it is assumed that the root
    (or separate boot) partition is <filename
    class="partition">hda4</filename>.</para>

    <para>Tell GRUB where to search for its
    <filename>stage{1,2}</filename> files. The Tab key can be used
    everywhere to make GRUB show the alternatives:</para>

<screen><userinput>root (hd0,3)</userinput></screen>

    <warning>
      <para>The following command will overwrite the current boot loader. Do not
      run the command if this is not desired, for example, if using a third party
      boot manager to manage the Master Boot Record (MBR). In this scenario, it
      would make more sense to install GRUB into the <quote>boot sector</quote>
      of the LFS partition. In this case, this next command would become
      <userinput>setup (hd0,3)</userinput>.</para>
    </warning>

    <para>Tell GRUB to install itself into the MBR of
    <filename class="partition">hda</filename>:</para>

<screen><userinput>setup (hd0)</userinput></screen>

    <para>If all went well, GRUB will have reported finding its files in
    <filename class="directory">/boot/grub</filename>. That's all there is
    to it. Quit the <command>grub</command> shell:</para>

<screen><userinput>quit</userinput></screen>

    <para>Create a <quote>menu list</quote> file defining GRUB's boot menu:</para>

<screen><userinput>cat &gt; /boot/grub/menu.lst &lt;&lt; "EOF"
<literal># Begin /boot/grub/menu.lst

# By default boot the first menu entry.
default 0

# Allow 30 seconds before booting the default.
timeout 30

# Use prettier colors.
color green/black light-green/black

# The first entry is for LFS.
title LFS &version;
root (hd0,3)
kernel /boot/lfskernel-&linux-version; root=/dev/hda4</literal>
EOF</userinput></screen>

    <para>Add an entry for the host distribution if desired. It might look
    like this:</para>

<screen><userinput>cat &gt;&gt; /boot/grub/menu.lst &lt;&lt; "EOF"
<literal>title Red Hat
root (hd0,2)
kernel /boot/kernel-2.6.5 root=/dev/hda3
initrd /boot/initrd-2.6.5</literal>
EOF</userinput></screen>

    <para>If dual-booting Windows, the following entry will allow
    booting it:</para>

<screen><userinput>cat &gt;&gt; /boot/grub/menu.lst &lt;&lt; "EOF"
<literal>title Windows
rootnoverify (hd0,0)
chainloader +1</literal>
EOF</userinput></screen>

    <para>If <command>info grub</command> does not provide all necessary material,
    additional information regarding GRUB is located on its website at:
    <ulink url="http://www.gnu.org/software/grub/"/>.</para>

    <para>The FHS stipulates that GRUB's <filename>menu.lst</filename> file should
    be symlinked to <filename class="symlink">/etc/grub/menu.lst</filename>. To
    satisfy this requirement, issue the following command:</para>

<screen><userinput>mkdir -v /etc/grub
ln -sv /boot/grub/menu.lst /etc/grub</userinput></screen>

  </sect2>

  <sect2 id="contents-gRUB" role="content">
    <title>Contents of GRUB</title>

    <segmentedlist>
      <segtitle>Installed programs</segtitle>

      <seglistitem>
        <seg>grub, grub-install, grub-md5-crypt, grub-set-default,
        grub-terminfo, and mbchk</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="grub">
        <term><command>grub</command></term>
        <listitem>
          <para>The Grand Unified Bootloader's command shell</para>
          <indexterm zone="ch-bootable-grub grub">
            <primary sortas="b-grub">grub</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="grub-install">
        <term><command>grub-install</command></term>
        <listitem>
          <para>Installs GRUB on the given device</para>
          <indexterm zone="ch-bootable-grub grub-install">
            <primary sortas="b-grub-install">grub-install</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="grub-md5-crypt">
        <term><command>grub-md5-crypt</command></term>
        <listitem>
          <para>Encrypts a password in MD5 format</para>
          <indexterm zone="ch-bootable-grub grub-md5-crypt">
            <primary sortas="b-grub-md5-crypt">grub-md5-crypt</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="grub-set-default">
        <term><command>grub-set-default</command></term>
        <listitem>
          <para>Sets the default boot entry for GRUB</para>
          <indexterm zone="ch-bootable-grub grub-set-default">
            <primary sortas="b-grub-set-default">grub-set-default</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="grub-terminfo">
        <term><command>grub-terminfo</command></term>
        <listitem>
          <para>Generates a terminfo command from a terminfo name; it can be
          employed if an unknown terminal is being used</para>
          <indexterm zone="ch-bootable-grub grub-terminfo">
            <primary sortas="b-grub-terminfo">grub-terminfo</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="mbchk">
        <term><command>mbchk</command></term>
        <listitem>
          <para>Checks the format of a multi-boot kernel</para>
          <indexterm zone="ch-bootable-grub mbchk">
            <primary sortas="b-mbchk">mbchk</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>