GRUB

GRUB2 (the GRand Unified Bootloader version 2) is a replacement for the original GRUB boot loader, now referred to as "GRUB Legacy". GRUB2 has an entirely separate code base from GRUB Legacy, and features a new shell-like syntax for advanced scripting capabilities.

For a shotgun approach, see GRUB2 Quick Start.

If migrating from GRUB Legacy to GRUB2, see GRUB2 Migration.

Installation
The package is slotted. Both (GRUB Legacy) and  may be installed at the same time; however, only one version at a time may be installed in the Master Boot Record (MBR) of a hard drive.

Prerequisites
To control which platforms GRUB2 will install for, set the GRUB_PLATFORMS variable in. The architecture includes a profile default which works for most systems.

The following platforms are supported depending on the target CPU:

The profiles enable support for (U)EFI functionality by default. When using a BIOS-based system, set GRUB_PLATFORMS variable to  to avoid unneeded dependencies.

Emerge
To install GRUB2 use the normal syntax:

Additional software
Optionally, install the utility (provided through the  package) to have GRUB2 probe for other operating systems when running the  command. In most instances, this will enable GRUB2 to automatically detect other operating systems including Windows 7, 8.1, 10, other distributions of Linux, 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.

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
The script is used to generate a grub configuration. It uses the scripts under together with the  configuration file to generate the final  - the only configuration file used by GRUB2 itself.

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  command. This utility will use the scripts in and the settings in.

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

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

Setting configuration parameters
The following variables in are the most common ones to set to control how GRUB2 will function:

For a more complete list, please refer to the GRUB2 configuration variables sub-page.

After modifying the parameters, regenerate the GRUB2 configuration file with.

Enabling or disabling configuration scripts
The directory contains the scripts that  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 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.

Manipulating configuration scripts
Some features or GRUB2 functionalities are only possible to be exploited by modifying the configuration scripts. For instance, to support dual-booting with FreeBSD, the following manipulation needs to be done.

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. If the executable bit is not set then set it using the command.

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

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

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 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 an output such as the one below is to be expected:

accepts a  option to set the CPU architecture and system platform. If unspecified, will attempt to guess the proper values; on an / system it will use   by default. also accepts a  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. It is only needed if the system is later migrated to the GPT partition layout. When sticking with MBR, this is not needed.

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

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

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

accepts a  option to set the CPU architecture and system platform. If unspecified, will attempt to guess the correct values; on an / system it will use   by default. also accepts a  option to tell the GRUB2 installer which directory to look in 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 safer option. This BIOS boot partition will hold the stage 2 of the bootloader. BIOS boot partitions do not need to be formatted with a filesystem; the command will overwrite any existing filesystem with one of its own.

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

With 's utility, this is accomplished by setting the partition type to   and giving it a label of.

An EFI System Partition is not required, but it would be sensible to make sure that the BIOS boot partition is large enough to be converted to one, should the system motherboard later be upgraded to an UEFI board.

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

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

Creating partitions in is straightforward for users familiar with the  partitioning utility. After starting, type (for new) in the main menu, provide beginning and end sectors (if needed), and set the partition type to   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 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.

The above command assumes the vfat EFI System Partition (ESP) is mounted at. If the ESP is mounted directly at, use.

also accepts a  option to set the CPU architecture and system platform. If unspecified, will attempt to guess the proper values; on an AMD64 UEFI-booted system it will use   by default. also accepts a  option to tell the GRUB2 installer which directory to look for GRUB2's boot files. This defaults to 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 UEFI 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  and   tools fit nicely for this purpose. When using the utility, be sure to use type.

Proceed to create a FAT filesystem on the EFI system partition using 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. To do this, verify the EFI partition is mounted at then copy the file  located at  to. This example assumes a 64-bit UEFI system, adjust accordingly for 32-bit UEFI systems.

Extended features
GRUB2 has many features that make it a very powerful boot loader. It supports:


 * 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 from a ZFS pool.
 * 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).

Some specific features are explained in more detail next.

Chainloading
GRUB2 was built with a truly improved chainload mode when compared to GRUB Legacy. To chainload another boot loader, use the  option.

For more information on chainloading, please see the Chainloading sub-page.

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
Most of the issues can be resolved by ensuring that the partition layout is correct. Make sure enough space is available before the first partition of the disk, or optionally make sure that a BIOS boot partition is available. Also verify that was correctly generated with, or generate one with a custom menu entry.

For more GRUB2 troubleshooting, please refer to the Troubleshooting sub-article.

Motherboard firmware not finding the .EFI file
Some motherboard manufacturers seem to only support one location for the .EFI file in the EFI System Partition (ESP). If this seems to be the case, simply move GRUB's default file to the location. First, make sure the ESP is mounted. Presuming the ESP is mounted at (as suggested in the Handbook), execute:

This should aid the motherboard firmware in loading the GRUB executable. Reboot the system to see if the firmware now correctly loads GRUB.

os-prober and UEFI in chroot
The utility is used to discover alternate installs, such as Microsoft Windows. To function properly, it needs to have access to information from the live environment's udev to test for the EFI System Partition.

Run these commands in the host environment to provide the required files (example shows Gentoo mounted on like in the Handbook):

Installing a new kernel
Whenever a new kernel is installed, GRUB2 must be reconfigured to recognize it. This can be done using, as shown below, or can be done manually.

Note that GRUB2 only needs to be reconfigured, not reinstalled to the boot drive's Master Boot Record (MBR). On the other hand, when GRUB2 itself has been upgraded it does need to be reinstalled on the boot drive, but usually does not need to be reconfigured.

External resources
For more information, please see:


 * GNU GRUB 2 manual page
 * Network (PXE) section of GRUB2
 * 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
 * A blog post entry on locking specific GRUB2 boot entries with a password