GRUB

GRUB2 is a bootloader with support for modern day computer systems. It is meant to replace the older GRUB bootloader (now referred to as "GRUB Legacy"). GRUB2 has an entirely separate codebase 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.

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 GRUB Legacy (grub-0.97) or to keep it installed after an upgrade, call  with the "0" slot on the end of the package atom. Doing so will add sys-boot/grub:0 to Portage's world file:

To prevent mounting of the partition during installation, export the   variable.

To install GRUB2 use the normal  syntax:

Optionally, install   to have GRUB2 probe for other operating systems when running the   utility. In most instances, this will enable GRUB2 to automatically detect other operating systems (Windows 7, Windows 8.1, etc.).

Configuration
GRUB2 does not require manually maintaining a boot option configuration. Instead it can optionally generate a configuration file using the   command. This utility will parse the scripts in and the settings file in

GRUB2's Configuration File
In Gentoo, the main configuration file for controlling GRUB2 can be found in the /etc folder at The following variables can be set to control how GRUB2 will function:


 * - Sets a path to a PF2 font for GRUB2 to use.
 * PF2 fonts can be created using the  utility.
 * For example, to create a GRUB2 PF2 font from a TTF (True Text Font) called "DroidSansMonoSlash.ttf" run:
 * To use the newly created font, set the  variable to the font's location.
 * To use the newly created font, set the  variable to the font's location.


 * - Defines the default menu entry selected on boot. May be a numeric index, a menu title, or "saved". Defaults to first detected entry.


 * - Delay (in seconds) before booting default menu entry. Set to 0 to wait indefinitely. The default is 5 seconds.


 * - If set to true, recovery menu entries will not be generated. On Linux, recovery entries pass "single" on the kernel command line.


 * - Parameters to be passed on the kernel command line for all Linux menu entries.


 * - Parameters to be passed on the kernel command line for non-recovery Linux menu entries.

- If false, ${GRUB_DEVICE_UUID} is passed in the root parameter on the kernel command line when an initramfs is available.
 * - If true, ${GRUB_DEVICE} is passed in the root parameter on the kernel command line.


 * - Controls the video mode in which the Linux kernel starts. May be set to "text", "keep", or a display resolution.


 * - The initial root device (i.e. the kernel's  parameter). Set this if you want to override   command's root device auto-detection. For example,   will force   to be used in the kernel command line.

GRUB2-Mkconfig Scripts
The directory holds the scripts   uses to generate a  file. By default the contents of this directory should be similar to the following:

By default GRUB2 will use all scripts when installed. 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 00_header and 10_linux are disabled:

After configuration has been establashed, run the  utility with the   argument 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.

BIOS MBR and BIOS GPT
Installing GRUB2 in BIOS MBR or BIOS GPT mode is reminiscent of installing Legacy GRUB, the main difference is that GRUB2 uses new GRUB2 additions. If a GPT partition table is present on the system, a small BIOS boot partition will need to be created. 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  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   by typing (change 1 to the number of the partition you want to mark as a BIOS Boot partition!):

More specifically, the following type of layout will work for BIOS GPT, and it is easier to use the curses-based  utility. Create the first partition at sector 2048, leaving the first 1 MiB of disk space free for MBRs, etc.). Provide it with an additional 4096 to 8192 sectors (2-4 MiB) for size. Set the type code to  and give it a label of "gptbios" (effectively what the bios_grub command does in parted). Continue adding partitions as needed (,, etc.).

If a partition is needed, start by mounting the  parition:

Run the  utility 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. accepts a  option to set the CPU architecture and system platform. If unspecified,  will attempt to guess the correct at the correct values; on an AMD64/x86 system it will use "i386-pc" by default. also accepts a  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.

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

Partitioning and Preparing Boot Disk
Before installing GRUB2 to a boot medium (internal disk, a removable device, etc.) some special care should be given while preparing and partitioning the boot device. The type of special care depends on the boot type involved: BIOS or UEFI. BIOS booting can be easily achieved using one of three methods:

1. Booting from disk partitioned with an existing MBR boot scheme. 2. Booting using GPT with a protective MBR. 3. Booting a hybrid MBR (useful if dual booting is involved with a GPT unaware Operating System such as Windows).

A different kind of special care should be provided when using UEFI. GPT is part of the UEFI specification. UEFI specification states is mandatory to use GPT partitioned disk.

When dual booting with Windows, be aware that Windows cannot boot from either a BIOS MBR or a GPT partitioned disk using an EFI platform. In the latter case, dual booting Windows is not difficult. In the former case, it can be difficult to dual boot with Windows on a GPT partitioned disk that uses a hybrid MBR.

Before going further, consider backing up the boot device MBR. Presuming the MBR resides on the device, the following command could be used to backup the MBR:

Or to simply its boot loader with something (here one can go as far as 446 bytes):

Booting in full [U]EFI mode requires an [0x]EF00 (EFI System Partition) partition, while booting from BIOS - GPT mode requires an [0x]EF02 (bios_boot) partition. GRUB (either GRUB2 or a patched GRUB Legacy) requires an additional [0x]EE00 protective partition in the protective MBR (if present) to recognize a GPT partitioned disk. This protective partition should be listed in the MBR first (in the case of a hybrid MBR configuration). Booting in BIOS - MBR mode does not require any additional partition; however, a gap (free space, a couple of sectors) should be left vacant in order to embed the before the first partition (if installing on a traditional `/dev/sd ' manner) or before the specified partition (if installing on a `/dev/sd  ' manner).

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

The  utility gives an output with slightly different syntax for the same setup:

Creating partions in  is straight forward for users already familar with the   partitioning utility. After starting, type   (for new) in the main menu, provide beginning and end sectors (if needed), then set the partition type EF00 for an EFI system partition.

UEFI Partition
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   and    tools utilities nicely for this purpose. When using the  utility, be sure to use type ef00.

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

Install Grub2 for UEFI
This should install Grub2 in, copy the core image to , and call  to add a boot entry.

Alternative: Using the Default UEFI Firmware Location
If the system's UEFI firmware fails to find Grub2's EFI bootloader file, using the default bootloader location should provide a working solution. This circumvents the boot menu managed by  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.

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

Some operating systems lack ability to boot from anything but BIOS - MBR (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  and   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 to leave enough open sectors embed the   file to the disk.

Creating a hybrid MBR is easy using : just press the  key (for recovery and transformation) in the main menu, then press  key (CHS recompute), and 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:

Verify successful operation by listing the devices.

And finally install GRUB as usual. Everything should be fine at this point. See troubleshooting section for possible issues not listed on the previous Notes and comments.

Chainloading
GRUB2 was built with a truly improved chainload mode when compared to GRUB Legacy. The new ISO (or loop) chainload mechanism makes chainloading a breeze. It is actually possible to chainload ISO images (LiveCD/DVDs) with GRUB Legacy, however there exists no way to pass kernel cmd line arguments before boot. In any case, the ISO images in question should be built keeping kernel cmd line arguments in mind. The SystemRescueCd or, on a lesser extent, Gentoo Minimal LiveCD. Without kernel cmd line options, booting ISO images with GRUB2 will fail in the physical media check/test stage of the ISOs boot process. Gentoo liveCD is handy because it has a minimal shell which lets the user mount the squashed image to the correct location and then press the key to continue the boot process. This makes it possible to have a handy way to install an operating system with everything in RAM, especially for "light weight" LiveCDs. No more need to listen to a whining CD/DVD drive on each new command!

ISO images
To chainload an ISO with custom or default kernel cmdline arguments, an entry similar to (or exactly like) the following can be added to GRUB2's file: menuentry "SYSRESCUECD" { set iso=/systemrescuecd-x86-3.8.1.iso loopback loop ${iso} linux (loop)/isolinux/rescue64 nomodeset vga=791 docache setkmap=fr isoloop=${iso} initrd (loop)/isolinux/initram.igz }

For a permanent and automatic entry to GRUB2's file, a custom script could be added to the  script location:

Do not forget to make the script executable:

Finally regenerate GRUB2's file using   command.

Another Bootloader
Chainloading another bootloader to GRUB2 is fairly easy if support in GRUB2 for the specific bootloader in question. Otherwise, one could use a man in the middle (in other works "another bootloader") to do the task. In the latter case, one could use GRUB4DOS as it has functionalities similar to GRUB Legacy. This is required when loading another bootloader like TrueCrypt becomes problematic in a single multiboot disk. Otherwise something as simple as the following example is enough to boot another disk that uses a "Custom Super Bootloader":

menuentry "Custom Super Bootloader Example" { insmod part_msdos insmod chain chainloader (hd1,1)+1 }

TrueCrypt
To make a long story short GRUB2 cannot chainload a disk with TrueCrypt in the MBR or Rescue CD image located in encrypted partitions. For other boot loaders this is perfectly possible, feasible; it even works with GRUB Legacy. It also works with GRUB4DOS (which could be used as workaround; see for more information) If attempting to boot from an single disk that contains a TrueCrypt partition use the above GRUB4DOS menu entry as a starting point. The infamous `invalid signature' await the more adventurous ones who attempt to do so using GRUB2.

Since GRUB2 has problems with attempting to boot an encrypted TrueCrypt partition, use either GRUB Legacy or GRUB4DOS as workaround. GRUB4DOS has an interface very similar to GRUB Legacy and menu.lst entry which can be used to chainload the TrueCrypt bootloader or to boot a Rescue CD (from an encrypted partition on the same disk). An executable with  in the  root of the booting device is required, plus a menu.lst. See below for a menu entry example. Chainloading TrueCrypt bootloader on a separate disk is relatively simple and can be done in GRUB2 like any other bootloader.

title Windows7-TrueCrypt-BIOS/MBR find --set-root /truecrypt_rescue_image.iso map --mem /truecrypt_rescue_image.iso (hd32) map (hd0) (hd1) map (hd1) (hd0) map --hook root (hd32) chainloader (hd32)

Another workaround cited on the bug is to boot from TrueCrypt as the main boot loader and then hit the to chainload the following partition (if one exists) or the following disk.

Windows (MSDOS based boot loaders)
If Windows (or any other MSDOS based bootloaders) are on another disk partitioned with a MSDOS partition layout with its bootloader within the MBR, then it should be possible to boot using a simple menu entry as the previous example in the GRUB2 section. This section describes how to probe and manually specify a Windows partition for booting. This use case is encountered when multiple Windows operating systems are installed on a single hard disk.

Microsoft Windows 8 (and above versions) are no longer installed using MSDOS partitions by default, however they do maintain backwards compatibility with BIOS MBR systems. In order to specify Windows 8 (and above) to use MSDOS partitioning the install DVD needs to be booted in BIOS mode (a non-UEFI boot mode) in order for Windows to install into MSDOS partitions. Manually create a MSDOS partition layout, then manually boot the Windows DVD using a BIOS option in the boot menu list. Sometimes it is necessary in the BIOS firmware configuration tool to disable UEFI mode completely in order to force BIOS MBR mode.

Opinions differ on whether MBR (MSDOS) or GPT EFI is partition schemes are better. MBR is older, it's limited to using no greater than 3TB drives and can only have four primary partitions (more if logical partitions are used). GTP EFI has newer, up to date standards, and is compatible with drives greater than 3TB. GPT EFI can have as many primary partitions as desired, however not all motherboard hardware has support for EFI firmware options. It might be best to stick with the simple MSDOS option until extra disk space is absolutely needed.

MSDOS Partitions
The simplest way to dual boot Windows (or MS-DOS) is to add an MBR menu entry to GRUB2's file for each Windows operating system installed.

Windows 7 example the file:

menuentry "Windows 7 BIOS MBR" { insmod part_msdos insmod ntldr insmod ntfs ntldr (hd0,msdos1)/bootmgr }

A Windows XP example the file:

menuentry "Windows XP BIOS MBR" { insmod part_msdos insmod ntldr insmod ntfs ntldr (hd0,msdos1)/ntldr }

An entry for a GPT hybrid MBR works bit different than the previous BIOS - MBR examples. Booting multiple versions of Windows can be achieved with remapping and/or hiding partitions with GRUB2's  option:

menuentry "Windows 7 BIOS MBR" { insmod part_msdos insmod chain parttool hd1,msdos1 hidden+ boot- parttool hd1,msdos2 hidden- boot+ chainloader (hd1,msdos2)+1 }

Remapping the devices to set the primary boot disk to additional disks can be achieved by setting the file to something like the following example:

menuentry "Windows 7 BIOS MBR" { insmod part_msdos insmod chain drivemap hd0 hd1 chainloader (hd1,msdos2)+1 }

Probing
GRUB2 is capable of automatically finding Windows partitions and assigning the root partitions. The Windows partition must first be mounted before the probe will be successful. See notes at the end of this section concerning missing C:\bootmgr and C:\Boot files and folders, and make sure they exist before trying to boot Windows.

Probing feature requires package which is not initially pulled in when installing GRUB2.

--hint-bios=hd1,msdos1 --hint-efi=hd1,msdos1 --hint-baremetal=ahci1,msdos1
 * 1) grub2-probe --target=hints_string /mnt/windows7/bootmgr

2ABF87DC395CFC02
 * 1) grub2-probe --target=fs_uuid /mnt/windows7/bootmgr

From the output provided by the above two commands, the 'search' line within GRUB2's file (below) can be constructed. Remapping the drive and partition as the first hard drive and first partition will make Windows XP or Windows 8 more free of silent errors while loading. Also note from the previously covered  command usage, specifying the $root prefix is no longer needed. Using it will generate boot errors.

menuentry 'Microsoft Windows 7 or Windows 8 (on sdb1)' --class windows { insmod part_msdos insmod ntfs insmod search_fs_uuid insmod ntldr search --fs-uuid --set=root --hint-bios=hd1,msdos1 --hint-efi=hd1,msdos1 --hint-baremetal=ahci1,msdos1 2ABF87DC395CFC02 drivemap (hd1,msdos1) (hd0,msdos1) #Or, "drivemap (hd1,msdos2) (hd0,msdos1)" for those with Windows installed on sdb2)       ntldr /bootmgr }

Seeing a boot error message concerning a missing bootmgr file after attempting to boot one of the previously mentioned entries is the indication the C:\Boot folder is missing. This happens when using Windows 8 since the C:\Boot folder does not seem to be generated by default.

GPT Partitions
In the case the Windows bootloader was overwritten with GRUB2 (or simply  doesn't do the trick, a UEFI dual boot could be achieved using the following menu entry:

menuentry "Windows 7 UEFI/GPT" { insmod part_gpt insmod search_fs_uuid insmod chain search --fs-uuid --no-floppy --set=root 28cf-35de chainloader ($root)/EFI/MICROSOFT/BOOT/bootmgfw.efi }

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 menulist with the startup information that was changed in GRUB2's configuration file run:

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  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.

Code block 1:

Disk /dev/sda: 160.0 GB, 160000000000 bytes, 312500000 sectors Units = sectors of 1 * 512 = 512 bytes Sector size (logical/physical): 512 bytes / 512 bytes I/O size (minimum/optimal): 512 bytes / 512 bytes Disk identifier: 0x000cfe45

Device Boot     Start         End      Blocks   Id  System /dev/sda1  *          63    48821534    24410736   8e  Linux LVM

Code block 2:

Disk /dev/sda: 320.1 GB, 320072933376 bytes, 625142448 sectors Units = sectors of 1 * 512 = 512 bytes Sector size (logical/physical): 512 bytes / 512 bytes I/O size (minimum/optimal): 512 bytes / 512 bytes Disk identifier: 0x0009d633

Device Boot     Start         End      Blocks   Id  System /dev/sda1  *        2048      499711      248832   8e  Linux LVM

Code block 3:

GPT fdisk (gdisk) version 0.8.8

Partition table scan: MBR: protective BSD: not present APM: not present GPT: present

Found valid GPT with protective MBR; using GPT. Disk /dev/sdb: 5860533168 sectors, 2.7 TiB Logical sector size: 512 bytes Disk identifier (GUID): 47915407-BA7E-4869-8D3E-3CB44F5FDA12 Partition table holds up to 128 entries First usable sector is 34, last usable sector is 5860533134 Partitions will be aligned on 2048-sector boundaries Total free space is 1050590 sectors (513.0 MiB)

Number Start (sector)    End (sector)  Size       Code  Name 1           2048         1050623   512.0 MiB   EF02  BIOS boot partition 2        1312768        68421631   32.0 GiB    8200  Linux swap 3       68683776       270010367   96.0 GiB    8300  root 4      270272512       471599103   96.0 GiB    8300  var 5      471861248      5860533134   2.5 TiB     8300  home

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  emerge option:

Next tell GRUB2 to pre-load the "lvm" module:

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

Booting from RAID Array
After considerable grief, the following working configuration was obtained.

The system has three hard drives. /dev/sda is the original MBR Windows Vista disk, untouched apart from installing GRUB2 onto it. /dev/sdb and /dev/sdc are configured identically.

GPT fdisk (gdisk) version 0.8.10

Partition table scan: MBR: protective BSD: not present APM: not present GPT: present

Found valid GPT with protective MBR; using GPT. Disk /dev/sdc: 1953525168 sectors, 931.5 GiB Logical sector size: 512 bytes Disk identifier (GUID): CB232664-F98D-45C0-8111-2AC526D5EA61 Partition table holds up to 128 entries First usable sector is 34, last usable sector is 1953525134 Partitions will be aligned on 2048-sector boundaries Total free space is 509918 sectors (249.0 MiB)

Number Start (sector)    End (sector)  Size       Code  Name 1           2048        67110911   32.0 GiB    8200  Linux swap 2       67110912        67127295   8.0 MiB     EF02  BIOS boot partition 3       67373056       402917375   160.0 GiB   8300  Linux filesystem 4      403179520      1953525134   739.3 GiB   8300  Linux filesystem

sdb3/sdc3 are raided together to make the / partition.

sdb4/sdc4 are raided together to make the /home partition.

menuentry 'Gentoo GNU/Linux, with Linux x86_64-3.14.14-gentoo' --class gentoo --class gnu-linux --class gnu --class os $menuentry_id_option 'gnulinux-x86_64-3.14.14-gentoo-advanced-8bb0e52c-d524-4af8-ac08-f3c9238c6040' { load_video set gfxpayload=keep insmod gzio insmod part_msdos insmod part_gpt insmod diskfilter insmod mdraid1x insmod ext2 set root='mduuid/660afb13150e817a0cdd36476d5b2c51' if [ x$feature_platform_search_hint = xy ]; then search --no-floppy --fs-uuid --set=root --hint='mduuid/660afb13150e817a0cdd36476d5b2c51' 8bb0e52c-d524-4af8-ac08-f3c9238c6040 else search --no-floppy --fs-uuid --set=root 8bb0e52c-d524-4af8-ac08-f3c9238c6040 fi echo	'Loading Linux x86_64-3.14.14-gentoo ...' linux	/boot/kernel-3.14.14-gentoo domdadm root=UUID=8bb0e52c-d524-4af8-ac08-f3c9238c6040 ro 	echo	'Loading initial ramdisk ...' initrd	/boot/initramfs-genkernel-x86_64-3.14.14-gentoo }

menuentry 'Gentoo GNU/Linux mirror 2' --class gentoo --class gnu-linux --class gnu --class os $menuentry_id_option 'gnulinux-simple-8bb0e52c-d524-4af8-ac08-f3c9238c6040' { load_video insmod gzio insmod part_msdos insmod part_gpt insmod mdraid1x insmod ext2 set root=(mduuid/660afb13:150e817a:0cdd3647:6d5b2c51) if [ x$feature_platform_search_hint = xy ]; then search --no-floppy --fs-uuid --set=root --hint-bios=hd1,msdos2 --hint-efi=hd1,msdos2 --hint-baremetal=ahci1,msdos2 --hint='hd1,msdos2' 8bb0e52c-d524-4af8-ac08-f3c9238c6040 else search --no-floppy --fs-uuid --set=root 660afb13:150e817a:0cdd3647:6d5b2c51 fi	echo   'Loading Linux 3.14.14-gentoo ...' linux  /boot/kernel-3.14.14-gentoo domdadm root=/dev/disk/by-id/md-uuid-660afb13:150e817a:0cdd3647:6d5b2c51 ro	echo    'Loading initial ramdisk ...' initrd /boot/initramfs-genkernel-x86_64-3.14.14-gentoo }

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

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

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

set root='mduuid/660afb13150e817a0cdd36476d5b2c51' 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   must not be used - genkernel will reset CONFIG_FHANDLE it and play havoc with the RAID).

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! This is how I picked up on FHANDLE, before that the raid was randomly losing devices (separate from, but confused with, it losing the root device led to a real puzzle).

Use  generate an initramfs:

The linux and initrd lines in should now load the Linux kernel. Add the "domdadm" command to the Linux kernel cmdline in GRUB2. Without it the RAID set will not assemble and the Linux kernel will not find the root device.

Note that the second boot option contains a deliberate error. Linux will be unable to find root device by itself and will drop into the GRUB2 shell. This is needed.

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  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  will show that initrd has found the RAID set devices, and giving it the device, eg /dev/md127, 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.

...   insmod raid insmod mdraid09 set root=(md0p1) set root=(md0) ...
 * 1)    and load the related `mdraid' module `mdraid09' for RAID arrays with version 0.9 metadata, and `mdraid1x' for arrays with version 1.x metadata.
 * 1)    or the following for an unpartitioned RAID array

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 I havePhysical Volume
Tell GRUB2 to look for cryptodisks:

(Re)generate the with the   utility.

Booting from 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, checkout if you have an 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 `grub2-install' command. This will spare you some time.

Secondly, checkout if was correctly generated with `grub2-mkconfig' or generate one yourself with at least a `menuentry'. Refers to previous section for more information. And avoid writing `Boots up to prompt' section in the wiki because of failing to do that simple check before rebooting!

GPT Hybrid MBR Workaround
GRUB2 requires an EE00 partition type first in the MBR partition list entry, but that may pose a problems when booting other operating systems on the same disk (especially Windows). In order to recognize a GPT partitioned disk with or without hybrid MBR a workaround can be used. Removing any protective EE00 partition with the  but not NOT USE  ! The  partition protecting the GPT main partition table (sectors 1-2047). This is happened to me and I had to remove the protective EE00 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  to recompute the CHS value for hybrid MBR (in the recovery and transformation menu, or in the expert main menu).

Repopulating EFI Boot Manager Entries
In case the Boot Manager entries need to be restored, they can be re-added without invoking. 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 and then re-emerge GRUB2 using the following command: {Emerge|--newuse sys-boot/grub:2}}

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

Attempting to Install GRUB2 to a Disk or Partition
Error message:

Attempting to install GRUB to a partition disk or to a partition. This is a BAD idea. Embedding is not possible. GRUB can only be installed in this setup by using blocklists. However, blocklists are UNRELIABLE and their use is discouraged.

Possible explanations followed by resolutions:

1 A partition is not mounted, simply run (as root) 2 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. 3 Attemping to install GRUB2 in a partition e.g. using a BIOS - MBR setup (who did try it to BIOS - GPT?), simply add   option switch to force install. It should behave with enough gap before the first sector of first partition or by using the  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). 4. If  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 {{Path|/sbin/grub2-install} script with a text editor of choice. Change the platform= 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 {{Path|/sbin/grub2-install} script. For example, to set the platform for "PC", change `platform=qemu to `platform=pc'.

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:this

Repartitioning the disk should resolve the issue.

Some visualization-based blockdevices 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 :

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


 * 'x' - extra functionality
 * 'b' - move beginning of data in a partition
 * '1' - Choose the first partition
 * '4096' - New beginning of data (1-8000369, default 63)
 * 'w' - 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  grub.d script located at  to:

or (hd0,1) is the partition in which FreeBSD resides. If the normal  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 mkconfig 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