GRUB/en

GRUB 2 (GRand Unified Bootloader version 2), sometimes stylized as GRUB2 and commonly referred to as GRUB, Article description:: is a multiboot secondary bootloader capable of loading kernels from a variety of filesystems on most system architectures. GRUB supports PC BIOS, PC EFI, IEEE 1275 (Open Firmware), SPARC, and MIPS Lemote Yeeloong.

GRUB2 replaces for the original GRUB Legacy boot loader with an entirely separate code base featuring a new shell-like syntax for advanced scripting capabilities.

For a quick setup approach, see GRUB2 Quick Start.

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

Installation
Due to the way GRUB Legacy (grub-0.97) and GRUB2 were slotted in Gentoo, both versions of GRUB may be installed on the same system at the same time; however, only one version at a time may be installed in the Master Boot Record (MBR) of a hard drive.

It is recommended all systems should upgrade to GRUB2, since it supports all the same features sets as Legacy. Legacy was removed from the Gentoo ebuild repository.

Prerequisites
To control which platforms GRUB 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 GRUB use the normal syntax:

Additional software
Optionally, install the utility (provided through the  package) to have GRUB probe and generate boot entries for other operating systems when running the  command. In most instances, this will enable GRUB to automatically detect other operating systems including Windows 7, 8.1, 10, other distributions of Linux, etc.

The GRUB (and optionally ) installations do not automatically enable the boot loader's operation. These only install the boot loader software on the operating system. 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 GRUB:


 * 1) Installation of GRUB software as the secondary boot loader of the system.
 * 2) Configuration of the GRUB boot loader.

The installation of GRUB 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.

GRUB 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 GRUB will function:

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

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:

GRUB 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 configuration file using.

Manipulating configuration scripts
Some features or 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 GRUB and update the configuration file:

Installing the boot loader
Installing GRUB as the system's boot loader depends on how the system is meant to boot (through which type of firmware, e.g. on PCs either the legacy BIOS or its successor UEFI) and how the disk on which the boot loader should be installed is partitioned (e.g. on a PC, wheather it is using the MBR or the GPT partition layout).

This article covers the following situations:


 * BIOS with MBR
 * BIOS with GPT
 * UEFI with GPT
 * Open Firmware (IEEE 1275) on PowerPC

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 GRUB installer which directory to look for the 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 GRUB installer which directory to look in for the boot files. This defaults to the current but is useful when trying to move a root partition.

Dual-boot with Windows
When the system is meant to dual-boot with Microsoft Windows installed in BIOS mode, full and native GPT partitioning isn't possible. Windows only allows to be booted from an MBR partition when in BIOS mode, which includes the BIOS emulation mode of (U)EFI called 'CSM'. For Linux however it is still possible to use a GPT partitioning scheme even from BIOS (or EFI-CSM) mode, but for the dual-boot with Windows this requires hybrid partitioning: up to four partitions can be defined in both the GPT and the MBR partition tables simultainiously.

An already installed Windows will refuse to boot when the boot mode or the partitioning scheme is changed. Also, older Windows systems don't support GPT (or EFI) at all, demanding that a BIOS or the EFI-CSM along with an MBR must be used. If Windows supports EFI it can be re-installed in the native UEFI mode and the GPT partitioning scheme, as well as Linux; see section UEFI with GPT.

Hybrid partitioning between GPT and MBR creates both a valid GPT partition table and a valid MBR partition table at the same time, but limits the total number of hybrid partitions to four because of the four primary partition limit of the MBR. Since the ESP (the EFI System Partition holding the EFI bootloaders) takes up one partition this leaves only three shared partitions between MBR and GPT. When one partition is used for Windows and one for Linux, there is only one additional hybrid partition possible, like a separate Linux /boot partition or a shared data partition between the two operating systems.

If there are two physical disks available to the system, a great solution is to have one disk use the GPT and the other the MBR partitioning scheme. Normally, the Windows installation uses only one partition as 'system partition' and 'boot partition', called 'drive C:'. When in BIOS mode the initial partition for booting, the 'system partition', must be an MBR partition. This applies to every Windows version since Windows XP and includes Windows 10. Since Windows Vista (actually Windows XP x64 Edition) the Microsoft operating system supports accessing GPT partitions. The solution is to relocate the 'system partition' part of an installation to the MBR partitioned disk, and convert the 'boot partition' (the one containing \WINDOWS) to a GPT partitioned disk. Windows can thereafter access all the GPT partitions on the one disk, and will continue to use the MBR partitions (or hybrid partitions) on the disk containing the 'system partition'. The Windows installation (containing \WINDOWS) would be a GPT partition, even when booted in BIOS mode.

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 GRUB in, copy the core image to , and call efibootmgr to add a boot entry.

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 GRUB installer which directory to look for the boot files. This defaults to but is useful when trying to move a root partition.

Partitioning for UEFI with GPT
For UEFI GPT boot, the system must have a dedicated EFI System 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 GRUB 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 GRUB'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.

Open Firmware (IEEE 1275) on PowerPC
See here.

Extended features
GRUB 2 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
GRUB 2 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.

Password protection of GRUB menu
If you want to secure GRUB so it is not possible for anyone to change boot parameters or use the command line, you can add a user/password combination to GRUB's configuration files. The program grub-mkpasswd-pbkdf2 generates password hashes for GRUBː

Then, add the following toː

Using framebuffer display
To have GRUB 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 configuration file located at. For example:

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.

os-prober not running
When running the command,  is not running as expected, even though it is installed:

This can be corrected by setting the GRUB_DISABLE_OS_PROBER variable to  in  file.

Upon the next run, should find additional bootable partitions:

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:

You can also use the removable parameter with grub-install command to generate this file automatically:

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, GRUB must be reconfigured to recognize it. This can be done using, as shown below, or can be done manually.

Note that GRUB only needs to be reconfigured, not reinstalled to the boot drive's Master Boot Record (MBR). On the other hand, when GRUB 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 GRUB
 * Legacy BIOS issues with GPT article
 * GPT and Hybrid MBR article
 * GPT fdisk utility page
 * Arch Linux GRUB 2 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