GRUB

GRUB2 is a boot loader with support for modern day computer systems. It is meant to replace the older GRUB boot loader (now referred to as "GRUB Legacy"). GRUB2 has an entirely separate code base from GRUB Legacy and boasts features such as a new shell-like syntax which permits advanced scripting capabilities. Current GRUB Legacy users are encouraged to migrate their systems to GRUB2.

Upgrading to GRUB 2 might be done out of necessary, as it allows:


 * Booting from UEFI platforms.
 * Booting from GPT partitioned drives without needing a hybrid MBR (hybrid MBR can enabled as needed for compatibility or portability).
 * Booting from a btrfs formatted partition.
 * Booting directly from a btrfs raid set without needing an initramfs for early mount setup.
 * Booting directly from logical volume management (such as LVM2).
 * Booting with support for DM-RAID (RAID 0, 1, 4, 5, 6, 9 and 10).
 * Booting from encrypted devices (LUKS).

For a shotgun approach, see GRUB2 Quick Start.

Installation
The package is slotted. Both grub-0.97 (GRUB Legacy) and grub-2.00 may be installed at the same time, however only one version of GRUB may be installed in a MBR at a time. In this article, we focus on GRUB2.

By default, GRUB2 will guess a default platform target at build time. This may be overridden by setting the  variable in.

The following platforms are supported depending on the target CPU:

To install GRUB2 use the normal emerge syntax:

Optionally, install the os-prober utility (provided through the package) to have GRUB2 probe for other operating systems when running the grub2-mkconfig command. In most instances, this will enable GRUB2 to automatically detect other operating systems (Windows 7, Windows 8.1, etc.).

The GRUB2 (and optionally ) installations do not automatically enable the boot loader. These only install the software on the operating system, but to install the boot loader to the system itself (so that it is used when booting the system), additional steps need to be taken, which are covered in the Configuration section.

Configuration
There are two important aspects to the configuration of GRUB2:
 * 1) installation of GRUB2 software as the boot loader of the system
 * 2) configuration of the GRUB2 boot loader itself

The installation of GRUB2 software is specific to the type of system, and is covered in Installing the boot loader. First we cover the configuration of the boot loader itself.

Main configuration file
GRUB2 does not require the administrator to manually maintain a boot option configuration (as is the case with boot loaders such as GRUB Legacy and LILO). Instead it can generate its configuration file using the grub2-mkconfig command. This utility will use the scripts in and the settings in.

After modifying one or more settings, run the grub2-mkconfig utility with the -o option pointing to the output file located at (this is GRUB2's default output location):

Each time the grub2-mkconfig utility is called a new configuration will be generated.

Setting configuration parameters
GRUB2 uses as its configuration file. However, it is advised to automatically generate this file based on the configuration entries in. The file uses key/value pairs which are used by the scripts in to generate a working configuration file.

The following variables can be set to control how GRUB2 will function:

After modifying the parameters, regenerate the GRUB2 configuration file with grub2-mkconfig.

Enabling or disabling configuration scripts
The directory contains the scripts that grub2-mkconfig uses to generate a  file. By default the contents of this directory should be similar to the following:

GRUB2 will use all installed scripts that are marked as executable (which by default, they all are). To disable any of the scripts simply remove the executable bit from the script's file permissions using the chmod command. In the following example every script but and  are disabled:

After modifying the scripts (or removing the executable bit), regenerate the GRUB2 configuration file using grub2-mkconfig.

Installing the boot loader
Installing GRUB2 as the system's boot loader depends on how the system is meant to boot (through BIOS or UEFI) and how the disk on which the boot loader should be installed is partitioned (using MBR or GPT partition layout).

This article covers the following situations:


 * BIOS with MBR
 * BIOS with GPT
 * UEFI with GPT
 * BIOS with hybrid MBR-GPT partitioning

Select the installation instructions appropriate for the system.

BIOS with MBR
Make sure that the location is available - if this uses a separate partition, make sure that it is mounted:

Run the grub2-install command to copy the relevant files to. On the PC platform, this also installs a boot image to the Master Boot Record (MBR) or a partition's boot sector. If all goes well, after running the grub2-install command an output such as the one below is to be expected:

grub2-install accepts a --target option to set the CPU architecture and system platform. If unspecified, grub2-install will attempt to guess the proper values; on an AMD64/x86 system it will use i386-pc</tt> by default. grub2-install</tt> also accepts a --boot-directory</tt> option to tell the GRUB2 installer which directory to look for GRUB2's boot files. This defaults to the current but is useful when trying to move a root partition.

Partitioning for BIOS with MBR
Be sure to leave enough free space before the first partition. Starting the first partition at sector 2048 leaves at least 1 MiB of disk space for the master boot record. It is recommended (but not mandatory) to create an additional partition for GRUB called the BIOS boot partition. This partition just needs to be defined, but not formatted.

If the Gentoo installation instructions were followed, this BIOS boot partition will already be avaialble.

BIOS with GPT
If a partition is needed, start by mounting the  partition:

If all goes well, after running the grub2-install command an output such as the one below is to be expected:

grub2-install</tt> accepts a --target</tt> option to set the CPU architecture and system platform. If unspecified, grub2-install</tt> will attempt to guess the correct at the correct values; on an AMD64/x86 system it will use i386-pc</tt> by default. grub2-install</tt> also accepts a --boot-directory</tt> option to tell the GRUB2 installer which directly to look for GRUB2's boot files. This defaults to the current but is useful when trying to move a root partition.

Partitioning for BIOS with GPT
When a GPT partition table is present on the system, a small BIOS boot partition (with type, which is different from the EFI System Partition (ESP) which has type  ) will need to be available. 1 MiB will be enough to work but 2-4 MiB is a more safe option. This BIOS boot partition will hold the stage 2 of the bootloader. BIOS boot partitions do not need formatted with a filesystem; the grub2-install</tt> command will overwrite any pre-existing filesystem with one of it's own.

To set a partition as a BIOS partition use the command line tool parted by typing (change   to the number of the partition to mark as a BIOS Boot partition!):

With 's cgdisk</tt> utility, this is accomplished by setting the partition type to  and give it a label of.

Next to a BIOS partition, an EFI System Partition must be available (which is FAT-formatted).

The following is the output of pressing the key using the gdisk utility on a GPT partitioned disk with both a BIOS boot [0xEF02] partition and an EFI [0xEF00] partition:

Using the same setup, the parted utility gives an output with slightly different syntax:

Creating partitions in gdisk</tt> is straight forward for users already familiar with the fdisk</tt> partitioning utility. After starting gdisk, type (for new) in the main menu, provide beginning and end sectors (if needed), then set the partition type   for an EFI system partition.

Users who have followed the Gentoo installation instructions will already have the proper partitioning layout set up.

UEFI with GPT
Make sure that the location is available - if this uses a separate partition, make sure that it is mounted:

Run the grub2-install command to copy the relevant files to. This should install Grub2 in, copy the core image to , and call efibootmgr to add a boot entry.

grub2-install</tt> accepts a --target</tt> option to set the CPU architecture and system platform. If unspecified, grub2-install</tt> will attempt to guess the proper values; on an AMD64/x86 system it will use <tt>i386-pc</tt> by default. <tt>grub2-install</tt> also accepts a <tt>--boot-directory</tt> option to tell the GRUB2 installer which directory to look for GRUB2's boot files. This defaults to the current but is useful when trying to move a root partition.

Partitioning for UEFI with GPT
For UEFI GPT boot using GRUB2, the system must have a dedicated EFI partition containing a FAT filesystem.

The EFI partition can replace having a partition on  by having a  partition on. This is to say a successful EFI boot scenario using GRUB2 can operate with two partitions total (three total if a swap partition is needed): a root partition and an EFI partition. Using this configuration, the folder will be located in the root  partition (at ) and the EFI partition will mount in the boot folder (at ). For further clarification, see the example file below.

Generating a 100MB partition for should provide plenty of space for holding multiple  files (multiple entries will most likely not be needed; most systems will only use one).

Create the partition using the partitioning tool of choice. The <tt>gdisk</tt> and <tt>parted</tt>  tools fit nicely for this purpose. When using the <tt>gdisk</tt> utility, be sure to use type.

Proceed to create a FAT filesystem on the EFI system partition using mkdosfs and add it to by following the example below:

Alternative: using the default UEFI firmware location
If the system's UEFI firmware fails to find GRUB2's EFI bootloader file, using the default boot loader location should provide a working solution. This circumvents the boot menu managed by efibootmgr and thus offers reduced functionality, but is less error prone. Do do this, verify the EFI partition is mounted at then copy the file  located at  to. This example assumes a 64-bit EFI system, adjust accordingly for 32-bit EFI systems.

BIOS with hybrid MBR-GPT partitioning
Dual booting with operating systems that are blind to a GPT-partitioned disk requires a tricky workaround.

Some operating systems lack the ability to boot from anything but BIOS - MBR (which includes all versions of Microsoft Windows prior to Windows Vista). It should be noted that support for 32-bit (as opposed to 64-bit) UEFI is less than perfect for certain machines.

GRUB2 supports booting from GPT and MBR partition tables via the <tt>part_gpt</tt> and <tt>part_msdos</tt> modules. However, a successful setup and GRUB2's ability to boot correctly depends both on loaded partition modules and on correctly installing GRUB2. A determining factor in how GRUB2 is installed (BIOS-MBR vs BIOS-GPT) is the presence of a EE00 (GPT protective) partition as the first partition in the MBR.

With a hybrid MBR, GRUB2 will install if the first partition in the MBR table is an  partition. An  partition should be present anywhere in the disk and not necessarily in the MBR list. Leave enough open sectors before the first partition!

Creating a hybrid MBR is easy using gdisk : at the main menu press the key (for recovery and transformation), then press  key (CHS recompute), then enter the series of partitions (less or equal to 3) in the order they should be be listed in the MBR. Finally enter the hexadecimal partition type without the  prefix or accept the defaults by repeatedly pressing the  key.

Enable only a single boot flag as found the following example:

Finally install GRUB2. See the troubleshooting section below for possible issues not listed in the notes above.

Enabling resume swap for suspend
Open up with root privileges and add:

Where XY is the swap partition location, which can be found by running the  command:

If it appears UUID labels are being used in instead of a device path then enter the UUID instead. In order to update the menu list with the startup information that was changed in GRUB2's configuration file run:

Installing GRUB2 from within a chroot
When a separate partition exists, be sure to mount the target root partition before chrooting, but do not the  partition until after chrooting to the new environment. This is required because <tt>grub2-mkconfig</tt> will not detect as a separate partition and will assume  and root are on the same partition.

Booting from LVM, RAID and/or encrypted volumes
This section is based on converting a non-UEFI, MBR partition based system to boot from a GPT RAID enabled disk. It is currently incomplete, and partially edited from the previous version.

Booting from LVM logical volumes
GRUB2 supports booting from an LVM partition however the  USE flag must be set in order to activate this feature.

If GRUB2 is currently installed, re-emerge it using the --newuse option:

Next tell GRUB2 to pre-load the  module:

Finally (re)generate a GRUB2 file using the grub2-mkconfig command.

Booting from RAID array
In this section, we assume a system has three hard drives. is the original MBR Windows Vista disk, untouched apart from installing GRUB2 onto it. and are configured identically.

and are raided together to make the  partition.

and are raided together to make the  partition.

(or ) is needed otherwise GRUB2 will not be able to read the partition table.

is required for RAID v1.1 or higher. If using RAID v0.9 or v1.0 the RAID module might not be needed ( for v0.9) because the RAID information is stored at the end of the partition. Any references to  are obsolete.

is required for ext partitions. For a other file systems substitute the appropriate module.

tells GRUB2 what root device Linux will be using.

At this point, GRUB2 is ready to hand over control to Linux. Any errors up to this point (missing modules, missing boot partition, etc.) are problems with GRUB2 not the Linux kernel. Onward from this point, it is safe to narrow errors down to Linux.

Linux is unable to assemble RAID assemblies in the kernel. It must call out to user-space tools; if the root partition is a RAID set, an initramfs must be used.

Make sure the kernel is configured correctly. Especially make sure that  variable is set (this is why genkernel must not be used - genkernel will reset the value of   and reap havoc upon the RAID set).

Compile the kernel manually by running the following commands as root:

At this point it is probably a good idea to emerge udev - and make sure all warnings are fixed!

Use the genkernel utility to generate an initramfs:

The  and   lines in  should now load the Linux kernel. Add the  parameter to the Linux kernel command line in GRUB2. Without it the RAID set will not assemble and the Linux kernel will not find the root device.

The first boot option correctly assembles the root RAID set at boot time, and boots successfully. Any attempt to access the root device from user space will fail as if the RAID set does not exist. This breaks GRUB2, and making the mistake of trying to run <tt>grub2-install</tt> on top of these errors will break GRUB boot altogether. Make sure Rescue CD and a copy of the Gentoo handbook are easily available before attempting to use a RAID set on the root disk.

The second option drops into a GRUB2 shell. Running ls /dev/md* will show that initrd has found the RAID set devices, and giving it the device, eg, will boot into a fully working system with userspace access to the boot device.

Put these into a script at the first available opportunity.

Further documentation on this subject, along with booting from encrypted physical volumes, is close to null.

Any further documentation from a user that has successfully booted a system from a RAID array welcome to complete add a RAID boot section to this article.

Booting from a RAID array is very similar to booting from a LVM Logical Volume aside from RAID specific terminology and syntax of RAID partitioned volume.

This should work with a simple software RAID setup. However, the author has no idea or what command, if any exit at the moment of writing, to use to assemble an array such as mdadm --assemble --scan /dev/md0 that an initramfs could take care of.

Booting from LUKS
Tell GRUB2 to look for cryptodisks:

(Re)generate the with the   utility.

Booting from the network (PXE)
For more information on network booting with GRUB2, read the official "Network (PXE)" section from the GNU software manual.

Using framebuffer display
To have GRUB2 use a framebuffer graphical display, re-emerge GRUB with the  USE flag enabled. This will install a default True Type font as well as a font conversion utility.

Proceed to configure the default GRUB2 configuration file located at For example:

In order to find out what display modes the system's graphics card supports, use the following commands on the GRUB2 shell:

Troubleshooting
First off, check if the system has a EFI02 (GPT disk) or bios_grub ([G]parted) for BIOS - GPT installation or enough gap before the first partition of the disk or the boot partition for BIOS - MBR installation before firing up <tt>grub2-install</tt> command. This will spare considerable debugging time.

Secondly, check if was correctly generated with grub2-mkconfig or generate one with a custom menu entry. Refer to previous section for more information. Do not fail to do this simple check before rebooting!

GPT hybrid MBR workaround
GRUB2 requires an  partition type at the first listing in the MBR partition list entry, however it may pose a problem when booting other operating systems on the same disk (especially Windows). A workaround is available in order to recognize a GPT partitioned disk with (or without) hybrid MBR. Removing any protective  partition with the <tt>fdisk</tt> command.

Use other disk tools such as <tt>parted</tt> or <tt>gparted</tt>  to resize after that. Otherwise use <tt>gdisk</tt> to add protective  partitions to protect at least GPT main and backup the partition before using any non-GPT aware tools if necessary.

Another issue should be addressed when attempting to use a GPT Hybrid MBR configuration: Windows MSDOS based bootloaders) may not find suitable partitions to boot from if there is a  partition protecting the GPT main partition table (sectors 1-2047). If this happens remove the protective   partition before getting a valid MBR partition list in [MS]DOS tools (to format a partition for example, the tools recognized a GPT partitioned disk at least). And then use <tt>gdisk</tt> to recompute the CHS value for hybrid MBR (in the recovery and transformation menu, or in the expert section of <tt>gdisk</tt>'s main menu).

Repopulating EFI boot manager entries
In case the Boot Manager entries need to be restored, they can be re-added without invoking grub-install. Load the  kernel module and install :

Next add a boot menu entry:

grub2-install: error: cannot find EFI directory.
Error message:

Resolution:

Properly setting the  variable in  (the first time!) as listed above would have resolved this error. Set the  variable then re-emerge GRUB2 using the following command:

In the case this error persists try forcing the install to the EFI directory by issuing the grub2-install command with correct parameters for the --target and --efi-directory options:

Attempting to install GRUB2 to a disk or partition
Error message:

Possible explanations followed by resolutions:


 * A partition is not mounted, run (as root): mount /boot


 * Attempting to install GRUB2 with a traditional BIOS - GPT setup. This could mean there is not any  or   partition to embed the  file. Creating a little partition of a few hundreds kilobytes may be enough, although it is good practice to align this partition to 2048 sectors to avoid a performance penalty with the disk. A 1 MiB partition should work well.


 * Attempting to install GRUB2 in a partition e.g. using a BIOS - MBR setup (who did try it to BIOS - GPT?), simply add <tt>--force</tt> option switch to force install. It should behave with enough gap before the first sector of first partition or by using the chattr command (as described in the BIOS - MBR instructions above). It is also possible to destroy the partition boundary and the LUKS or LVM2 header (if one exists).


 * If grub2-install does not print any errors message or if the error message is about scanning disk files and several platforms are enabled in while nothing is installed on the disk, then edit the  script with a text editor of choice. Change the   variable to appropriate platform for the current use case. The platform must be rightly set when emerging, else it will be incorrectly configured in the  script. For example, to set the platform for "PC", change   to.

No post-MBR gap (free space)
Error message:

Explanation:

This error means, that GRUB2 could not find the usual gap between the MBR and first partition of a disk. It is possible that the gap does not exist. Some tools (e.g. LiveUSB disk installer) format disks so that the first partition starts at sector 1 instead of 2048.

Resolution:

Repartitioning the disk should resolve the issue.

Some visualization-based block devices can also cause problems. See this post from the Arch Linux forum for more information.

Embedding area is unusually small
Error message:

Explanation:

There is not enough room at the beginning of the disk before the first partition.

Resolution:

In general this is a bit of trouble to fix. One or more partitions need to be resized in order to leave some free space at the beginning of the drive. The GParted LiveCD or Gentoo-based [SystemRescueCD] are excellent tools to make this job less difficult.

If the swap partition is the first partition on the disk (e.g. ) it is possible to simply remove the existing swap space partition and re-partition the space. This resolution would avoid the need for booting into a live medium in order to resize a root partition.

Begin by disabling the swap partition and launching fdisk:

This should bring up the fdisk prompt, where the following commands can be entered to shrink the partition found on :


 * - extra functionality
 * - move beginning of data in a partition
 * - Choose the first partition
 * - New beginning of data (1-8000369, default 63)
 * - write table to disk and exit

A number smaller than 4096 may work, but 4096 is a wise choice.

Next, reformat the swap partition, and re-enable it:

It should now be possible to install GRUB2 onto.

DualBoot Gentoo and FreeBSD [MBR]
Change the script to:

or  is the partition in which FreeBSD resides. If the normal UFS install was used for the FreeBSD partition then is a container (something like a logical partition). It consists of the swap and root partition. Verify the script is executable by running ls -la /etc/grub.d/40_custom. If the executable bit is not set then set it using the chmod u+x 40_custom command.

Next install GRUB2 using the grub2-install command and update GRUB2's configuration file:

Unless modified by the end user, script files in located in are executable and will be read by GRUB2 to create boot configuration files.

External resources

 * GNU GRUB 2 manual page
 * Legacy BIOS issues with GPT article
 * GPT and Hybrid MBR article
 * GPT fdisk utility page
 * Arch Linux GRUB2 wiki article
 * Fedora GRUB2 wiki article : Encountering the dreaded GRUB2 boot prompt
 * ubuntu UEFI booting help
 * http://unix.stackexchange.com/questions/109272/dualboot-freebsd-gentoo-with-grub2-mbr