source: chapter10/grub.xml@ d6f618b

<?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>Using GRUB to Set Up the Boot Process</title>

  <note>
    <para>
      This section assume your system has UEFI support and you wish to boot
      LFS with UEFI and GRUB built following the instructions in Chapter 8.
    </para>
    <para>
      If you've installed GRUB for UEFI with optional dependencies following
      BLFS, you should skip this page, and configure GRUB with UEFI support
      using the instructions provided in
      <ulink url="&blfs-book;postlfs/grub-setup.html">the BLFS page</ulink>,
      but replace <parameter>--target=x86_64-efi</parameter> with
      <parameter>--target=loongarch64-efi</parameter> for the 64-bit
      LoongArch system.
    </para>
    <para>
      If your system does not support UEFI or you don't want to use it,
      you'll need to figure out how to configure the booting process of
      the system on your own.
    </para>
  </note>

  <sect2>
    <title>Introduction</title>

    <warning><para>Configuring GRUB incorrectly can render your system
    inoperable without an alternate boot device such as a CD-ROM or bootable
    USB drive. This section is not required to boot your LFS system.  You may
    just want to modify your current boot loader, e.g. Grub-Legacy, GRUB2, or
    LILO.</para></warning>

    <para>Ensure that an emergency boot disk is ready to <quote>rescue</quote>
    the computer if the computer becomes unusable (un-bootable).  If you do not
    already have a boot device, you can create one.  To create a emergency
    boot device for UEFI, consult section <quote>Create an Emergency Boot
    Disk</quote> in
        <ulink url="&blfs-book;postlfs/grub-setup.html">the BLFS page</ulink>.</para>

  </sect2>

  <sect2>
    <title>Turn off Secure Boot</title>

    <para>LFS does not have the essential packages to support Secure Boot.
    To set up the boot process following the instructions in this section,
    Secure Boot must be turned off from the configuration interface of the
    firmware. Read the documentation provided by the manufacturer of your
    system to find out how.</para>
  </sect2>

  <sect2>
    <title>GRUB Naming Conventions</title>

    <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. The hard drive numbers start from zero, but the partition numbers
    start from one for normal partitions (from five for extended partitions).
    Note that this is different from earlier versions where
    both numbers started from zero. For example, partition <filename
    class="partition">sda1</filename> is <emphasis>(hd0,1)</emphasis> to
    GRUB and <filename class="partition">sdb3</filename> is
    <emphasis>(hd1,3)</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>

  </sect2>

  <sect2>
    <title>Setting Up the Configuration</title>

    <para>GRUB works by creating an EFI executable in the EFI System
    Partition (ESP).  You can find the ESP with:</para>

<screen role="nodump"><userinput>fdisk -l | grep 'EFI System'</userinput></screen>

    <para>If no ESP exists on your hard drive (for example, you are building
    LFS on a fresh new system with a Live CD as the host distro), read
    <ulink url="&blfs-book;postlfs/grub-setup.html">the BLFS page</ulink>
    for the instruction to create an ESP on your hard drive.</para>

    <para>If the ESP is not mounted at
    <filename class="directory">/boot/efi</filename> (in the chroot),
    mount it now:</para>

<screen role="nodump"><userinput>mkdir -pv /boot/efi
mount /boot/efi</userinput></screen>

    <note>
      <para>The path to the device node is intentionally omitted in the
      command.  We expect the entry for mounting the ESP to
      <filename class="directory">/boot/efi</filename> is already in
      <filename>/etc/fstab</filename>.  Add the entry before running the
      command if you forgot to create an entry for the ESP in
      <xref linkend="ch-bootable-fstab"/>.</para>
    </note>

    <para>The location of the boot partition is a choice of the user that
    affects the configuration.  One recommendation is to have a separate small
    (suggested size is 200 MB) partition just for boot information.  That way
    each build, whether LFS or some commercial distro, can access the same boot
    files and access can be made from any booted system.  If you choose to do
    this, you will need to mount the separate partition, move all files in the
    current <filename class="directory">/boot</filename> directory (e.g. the
    Linux kernel you just built in the previous section) to the new partition.
    You will then need to unmount the partition and remount it as <filename
    class="directory">/boot</filename>.  If you do this, be sure to update
    <filename>/etc/fstab</filename>.</para>

    <para>Leaving <filename class="directory">/boot</filename> on
    the current LFS partition will also work, but configuration
    for multiple systems is more difficult.</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">sda2</filename>.</para>

    <para>Install the GRUB files into <filename
    class="directory">/boot/grub</filename> and the GRUB EFI executable into
    <filename>/boot/efi/EFI/BOOT/BOOTLOONGARCH64.EFI</filename>:</para>

    <warning>
      <para>The following command will overwrite
      <filename>BOOTLOONGARCH64.EFI</filename>. Do not run the command if
      this is not desired, for example, if it contains a third party boot
      manager.  You can backup it with <command>cp</command> as it's a
      regular file.</para>
    </warning>

<screen role="nodump"><userinput>grub-install --removable</userinput></screen>

    <note>
      <para>
        <parameter>--removable</parameter> may seem strange here.  The UEFI
        firmware searches EFI executables for boot loaders in a hardcoded
        path, <filename>EFI/BOOT/BOOTLOONGARCH64.EFI</filename> in the ESP, and other
        boot loader paths listed in the EFI variables.  We've not installed
        the utilities for manipulating EFI variables so we need to install
        the EFI executable into the hardcoded path.  The hardcoded path is
        usually used by removable devices (for example, USB thumb devices)
        so the <command>grub-install</command> option for this purpose is
        named <parameter>--removable</parameter>.
      </para>
      <para>
        UEFI implementation usually prefers the boot loaders with paths
        recorded in an EFI variable, to the boot loader with the hardcoded
        search path.  You may need to invoke the boot device selection menu
        or setting interface of your EFI firmware on next boot to explicitly
        select the bootloader.
      </para>
      <para>
        Some UEFI implementation may completely skip the hardcoded path if
        there are other boot loaders in the same hard drive with paths
        recorded in an EFI variable.  Then you need to create an EFI
        variable for the newly installed boot loader.  Install
        <ulink url="&blfs-book;postlfs/efibootmgr.html">efibootmgr</ulink>,
        then run the following commands:

<screen role="nodump"><userinput>mount -v -t efivarfs efivarfs /sys/firmware/efi/efivars
efibootmgr -B -L LFS || true
efibootmgr -c -L LFS -l '\EFI\BOOT\BOOTLOONGARCH64.EFI' -d /dev/sda
umount /sys/firmware/efi/efivars</userinput></screen>

        Replace <filename>/dev/sda</filename> with the device node of the
        hard drive where you are installing GRUB into.
      </para>
    </note>

<!-- This does not seem to be true any more
    <note><para><application>grub-install</application> is a script and calls another
    program, grub-probe, that may fail with a message "cannot stat `/dev/root'".
    If so, create a temporary symbolic link from your root partition to /dev/root:</para>

<screen role="nodump"><userinput>ln -sv /dev/sda2 /dev/root</userinput></screen>

    <para>The symbolic link will only be present until the system is rebooted.
    The link is only needed for the installation procedure.
    </para></note>
-->
  </sect2>

  <sect2 id="grub-cfg">
    <title>Creating the GRUB Configuration File</title>

    <para>Generate <filename>/boot/grub/grub.cfg</filename>:</para>

    <screen><userinput>cat &gt; /boot/grub/grub.cfg &lt;&lt; "EOF"
<literal># Begin /boot/grub/grub.cfg
set default=0
set timeout=5

insmod part_gpt
insmod ext2
set root=(hd0,2)

insmod all_video

menuentry "GNU/Linux, Linux &linux-version;-lfs-&version;" {
        linux   /boot/vmlinuz-&linux-version;-lfs-&version; root=/dev/sda2 ro
}</literal>
EOF</userinput></screen>

    <para>
      The <command>insmod</command> commands load the
      <application>GRUB</application> modules named
      <filename>part_gpt</filename> and <filename>ext2</filename>.
      Despite the naming, <filename>ext2</filename> actually supports
      <systemitem class='filesystem'>ext2</systemitem>,
      <systemitem class='filesystem'>ext3</systemitem>, and
      <systemitem class='filesystem'>ext4</systemitem> filesystems.
      The <command>grub-install</command> command has embedded some modules
      into the main <application>GRUB</application> image (installed into
      the MBR or the GRUB BIOS partition) to access the other modules
      (in <filename class='directory'>/boot/grub/i386-pc</filename>) without
      a chicken-or-egg issue, so with a typical configuration these two
      modules are already embedded and those two <command>insmod</command>
      commands will do nothing.  But they do no harm anyway, and they may
      be needed with some rare configurations.
    </para>

    <note><para>From <application>GRUB</application>'s perspective, the
    kernel files are relative to the partition used.  If you
    used a separate /boot partition, remove /boot from the above
    <emphasis>linux</emphasis> line.  You will also need to change the
    <emphasis>set root</emphasis> line to point to the boot partition.
    </para></note>

    <note>
      <para>The GRUB designator for a partition may change if you added or
      removed some disks (including removable disks like USB thumb devices).
      The change may cause boot failure because
      <filename>grub.cfg</filename> refers to some <quote>old</quote>
      designators.  If you wish to avoid such a problem, you may use
      the UUID of a partition and the UUID of a filesystem instead of a GRUB designator to
      specify a device.
      Run <command>lsblk -o UUID,PARTUUID,PATH,MOUNTPOINT</command> to show
      the UUIDs of your filesystems (in the <literal>UUID</literal> column) and
      partitions (in the <literal>PARTUUID</literal> column).  Then replace
      <literal>set root=(hdx,y)</literal> with
      <literal>search --set=root --fs-uuid <replaceable>&lt;UUID of the filesystem
      where the kernel is installed&gt;</replaceable></literal>, and replace
      <literal>root=/dev/sda2</literal> with
      <literal>root=PARTUUID=<replaceable>&lt;UUID of the partition where LFS 
      is built&gt;</replaceable></literal>.</para>
      <para>Note that the UUID of a partition is completely different from the
      UUID of the filesystem in this partition.  Some online resources may
      instruct you to use
      <literal>root=UUID=<replaceable>&lt;filesystem UUID&gt;</replaceable></literal>
      instead of
      <literal>root=PARTUUID=<replaceable>&lt;partition UUID&gt;</replaceable></literal>,
      but doing so will require an initramfs, which is beyond the scope of
      LFS.</para>
      <para>The name of the device node for a partition in
      <filename class='directory'>/dev</filename> may also change (this is less
      likely than a GRUB designator change).  You can also replace
      paths to device nodes like <literal>/dev/sda1</literal> with
      <literal>PARTUUID=<replaceable>&lt;partition UUID&gt;</replaceable></literal>,
      in <filename>/etc/fstab</filename>, to avoid a potential boot failure
      in case the device node name has changed.</para>
    </note>

    <para>GRUB is an extremely powerful program and it provides a tremendous
    number of options for booting from a wide variety of devices, operating
    systems, and partition types.  There are also many options for customization
    such as graphical splash screens, playing sounds, mouse input, etc.  The
    details of these options are beyond the scope of this introduction.</para>

    <caution><para>There is a command, <application>grub-mkconfig</application>, that
    can write a configuration file automatically.  It uses a set of scripts in
    /etc/grub.d/ and will destroy any customizations that you make.  These scripts
    are designed primarily for non-source distributions and are not recommended for
    LFS.  If you install a commercial Linux distribution, there is a good chance
    that this program will be run.  Be sure to back up your grub.cfg file.</para></caution>

   </sect2>

</sect1>