grubby/boot/grub/persistent/docs/04_installation

4 Installation
**************

In order to install GRUB as your boot loader, you need to first install
the GRUB system and utilities under your UNIX-like operating system
(*note Obtaining and Building GRUB::).  You can do this either from the
source tarball, or as a package for your OS.

   After you have done that, you need to install the boot loader on a
drive (floppy or hard disk) by using the utility 'grub-install' (*note
Invoking grub-install::) on a UNIX-like OS.

   GRUB comes with boot images, which are normally put in the directory
'/usr/lib/grub/<cpu>-<platform>' (for BIOS-based machines
'/usr/lib/grub/i386-pc').  Hereafter, the directory where GRUB images
are initially placed (normally '/usr/lib/grub/<cpu>-<platform>') will be
called the "image directory", and the directory where the boot loader
needs to find them (usually '/boot') will be called the "boot
directory".

4.1 Installing GRUB using grub-install
======================================

For information on where GRUB should be installed on PC BIOS platforms,
*note BIOS installation::.

   In order to install GRUB under a UNIX-like OS (such as GNU), invoke
the program 'grub-install' (*note Invoking grub-install::) as the
superuser ("root").

   The usage is basically very simple.  You only need to specify one
argument to the program, namely, where to install the boot loader.  The
argument has to be either a device file (like '/dev/hda').  For example,
under Linux the following will install GRUB into the MBR of the first
IDE disk:

     # grub-install /dev/sda

   Likewise, under GNU/Hurd, this has the same effect:

     # grub-install /dev/hd0

   But all the above examples assume that GRUB should put images under
the '/boot' directory.  If you want GRUB to put images under a directory
other than '/boot', you need to specify the option '--boot-directory'.
The typical usage is that you create a GRUB boot floppy with a
filesystem.  Here is an example:

     # mke2fs /dev/fd0
     # mount -t ext2 /dev/fd0 /mnt
     # mkdir /mnt/boot
     # grub-install --boot-directory=/mnt/boot /dev/fd0
     # umount /mnt

   Some BIOSes have a bug of exposing the first partition of a USB drive
as a floppy instead of exposing the USB drive as a hard disk (they call
it "USB-FDD" boot).  In such cases, you need to install like this:

     # losetup /dev/loop0 /dev/sdb1
     # mount /dev/loop0 /mnt/usb
     # grub-install --boot-directory=/mnt/usb/bugbios --force --allow-floppy /dev/loop0

   This install doesn't conflict with standard install as long as they
are in separate directories.

   Note that 'grub-install' is actually just a shell script and the real
task is done by other tools such as 'grub-mkimage'.  Therefore, you may
run those commands directly to install GRUB, without using
'grub-install'.  Don't do that, however, unless you are very familiar
with the internals of GRUB. Installing a boot loader on a running OS may
be extremely dangerous.

   On EFI systems for fixed disk install you have to mount EFI System
Partition.  If you mount it at '/boot/efi' then you don't need any
special arguments:

     # grub-install

   Otherwise you need to specify where your EFI System partition is
mounted:

     # grub-install --efi-directory=/mnt/efi

   For removable installs you have to use '--removable' and specify both
'--boot-directory' and '--efi-directory':

     # grub-install --efi-directory=/mnt/usb --boot-directory=/mnt/usb/boot --removable

4.2 Making a GRUB bootable CD-ROM
=================================

GRUB supports the "no emulation mode" in the El Torito specification(1)
(*note Making a GRUB bootable CD-ROM-Footnote-1::).  This means that you
can use the whole CD-ROM from GRUB and you don't have to make a floppy
or hard disk image file, which can cause compatibility problems.

   For booting from a CD-ROM, GRUB uses a special image called
'cdboot.img', which is concatenated with 'core.img'.  The 'core.img'
used for this should be built with at least the 'iso9660' and 'biosdisk'
modules.  Your bootable CD-ROM will usually also need to include a
configuration file 'grub.cfg' and some other GRUB modules.

   To make a simple generic GRUB rescue CD, you can use the
'grub-mkrescue' program (*note Invoking grub-mkrescue::):

     $ grub-mkrescue -o grub.iso

   You will often need to include other files in your image.  To do
this, first make a top directory for the bootable image, say, 'iso':

     $ mkdir iso

   Make a directory for GRUB:

     $ mkdir -p iso/boot/grub

   If desired, make the config file 'grub.cfg' under 'iso/boot/grub'
(*note Configuration::), and copy any files and directories for the disc
to the directory 'iso/'.

   Finally, make the image:

     $ grub-mkrescue -o grub.iso iso

   This produces a file named 'grub.iso', which then can be burned into
a CD (or a DVD), or written to a USB mass storage device.

   The root device will be set up appropriately on entering your
'grub.cfg' configuration file, so you can refer to file names on the CD
without needing to use an explicit device name.  This makes it easier to
produce rescue images that will work on both optical drives and USB mass
storage devices.

   (1) El Torito is a specification for bootable CD using BIOS
functions.

4.3 The map between BIOS drives and OS devices
==============================================

If the device map file exists, the GRUB utilities ('grub-probe', etc.)
read it to map BIOS drives to OS devices.  This file consists of lines
like this:

     (DEVICE) FILE

   DEVICE is a drive specified in the GRUB syntax (*note Device
syntax::), and FILE is an OS file, which is normally a device file.

   Historically, the device map file was used because GRUB device names
had to be used in the configuration file, and they were derived from
BIOS drive numbers.  The map between BIOS drives and OS devices cannot
always be guessed correctly: for example, GRUB will get the order wrong
if you exchange the boot sequence between IDE and SCSI in your BIOS.

   Unfortunately, even OS device names are not always stable.  Modern
versions of the Linux kernel may probe drives in a different order from
boot to boot, and the prefix ('/dev/hd*' versus '/dev/sd*') may change
depending on the driver subsystem in use.  As a result, the device map
file required frequent editing on some systems.

   GRUB avoids this problem nowadays by using UUIDs or file system
labels when generating 'grub.cfg', and we advise that you do the same
for any custom menu entries you write.  If the device map file does not
exist, then the GRUB utilities will assume a temporary device map on the
fly.  This is often good enough, particularly in the common case of
single-disk systems.

   However, the device map file is not entirely obsolete yet, and it is
used for overriding when current environment is different from the one
on boot.  Most common case is if you use a partition or logical volume
as a disk for virtual machine.  You can put any comments in the file if
needed, as the GRUB utilities assume that a line is just a comment if
the first character is '#'.

4.4 BIOS installation
=====================

MBR
===

The partition table format traditionally used on PC BIOS platforms is
called the Master Boot Record (MBR) format; this is the format that
allows up to four primary partitions and additional logical partitions.
With this partition table format, there are two ways to install GRUB: it
can be embedded in the area between the MBR and the first partition
(called by various names, such as the "boot track", "MBR gap", or
"embedding area", and which is usually at least 31 KiB), or the core
image can be installed in a file system and a list of the blocks that
make it up can be stored in the first sector of that partition.

   Each of these has different problems.  There is no way to reserve
space in the embedding area with complete safety, and some proprietary
software is known to use it to make it difficult for users to work
around licensing restrictions; and systems are sometimes partitioned
without leaving enough space before the first partition.  On the other
hand, installing to a filesystem means that GRUB is vulnerable to its
blocks being moved around by filesystem features such as tail packing,
or even by aggressive fsck implementations, so this approach is quite
fragile; and this approach can only be used if the '/boot' filesystem is
on the same disk that the BIOS boots from, so that GRUB does not have to
rely on guessing BIOS drive numbers.

   The GRUB development team generally recommends embedding GRUB before
the first partition, unless you have special requirements.  You must
ensure that the first partition starts at least 31 KiB (63 sectors) from
the start of the disk; on modern disks, it is often a performance
advantage to align partitions on larger boundaries anyway, so the first
partition might start 1 MiB from the start of the disk.

GPT
===

Some newer systems use the GUID Partition Table (GPT) format.  This was
specified as part of the Extensible Firmware Interface (EFI), but it can
also be used on BIOS platforms if system software supports it; for
example, GRUB and GNU/Linux can be used in this configuration.  With
this format, it is possible to reserve a whole partition for GRUB,
called the BIOS Boot Partition.  GRUB can then be embedded into that
partition without the risk of being overwritten by other software and
without being contained in a filesystem which might move its blocks
around.

   When creating a BIOS Boot Partition on a GPT system, you should make
sure that it is at least 31 KiB in size.  (GPT-formatted disks are not
usually particularly small, so we recommend that you make it larger than
the bare minimum, such as 1 MiB, to allow plenty of room for growth.)
You must also make sure that it has the proper partition type.  Using
GNU Parted, you can set this using a command such as the following:

     # parted /dev/DISK set PARTITION-NUMBER bios_grub on

   If you are using gdisk, set the partition type to '0xEF02'.  With
partitioning programs that require setting the GUID directly, it should
be '21686148-6449-6e6f-744e656564454649'.

   *Caution:* Be very careful which partition you select!  When GRUB
finds a BIOS Boot Partition during installation, it will automatically
overwrite part of it.  Make sure that the partition does not contain any
other data.