GRUB

GRUB2 is a bootloader with support for many modern day computer systems. It is meant to replace the older GRUB bootloader (now referred to by upstream as "GRUB Legacy"). GRUB2 has an entirely separate codebase from GRUB Legacy, and boasts features such as a new shell-like syntax which permit advanced scripting capabilities. GRUB Legacy users are encouraged to migrate to GRUB2.

Upgrading to GRUB 2 might be necessary as it allows:
 * booting from UEFI platforms;
 * booting from GPT partitioned drives without even needing an awkward hybrid MBR, even though one can use one for compatibility/portability reasons;
 * booting from directly logical volume management such as LVM2 support;
 * booting from raid DM-RAID support for RAID [0?] 1, 4, 5, 6, 9 and 10 [or 1x?];
 * and booting from encrypted devices, probably LUKS, because of the inexistent documentation despite the cypher/hash modules being there: so no guidance on a howto for the moment.

For a shotgun approach, see instead GRUB2 Quick Start.

Installation
The package is slotted; both grub-0.97 and grub-2.00 may be installed at the same time.

If you want to install grub-0.97 or keep it installed after an upgrade, call emerge with the "0" slot on the end of the package atom. This will add sys-boot/grub:0 to your world file. For example:

Only one version may be installed in your MBR at one time.

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

The following platforms are supported depending on the target CPU.

Install the package using the normal emerge syntax.

Configuration
GRUB2 does not require you to manually maintain your boot options configuration, instead it can optionally generate the file using the command grub2-mkconfig. This utility will parse the scripts in and the settings file.
 * GRUB_FONT
 * Path to the PF2 font you want GRUB2 to use. To create a PF2 font, use the grub2-mkfont utility, example:
 * and set GRUB_FONT=/boot/grub/fonts/DroidSansMonoSlashed20.pcf
 * and set GRUB_FONT=/boot/grub/fonts/DroidSansMonoSlashed20.pcf


 * GRUB_DEFAULT
 * Default menu entry selected on boot. May be a numeric index, a menu title, or "saved". Defaults to first detected entry.


 * GRUB_TIMEOUT
 * Delay before booting default menu entry. Set to 0 to wait indefinitely. Default is 5 seconds.


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


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


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


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


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


 * GRUB_DEVICE
 * The initial root device, i.e. the kernel's  parameter. Set this if you want to override grub2-mkconfig's root device auto-detection; for example,   will force   to be used in your kernel command line.

The directory holds the scripts grub2-mkconfig uses to generate grub.cfg. By default the contents of this directory should be similar to the following:

By default GRUB2 will use all scripts when first installed. If you want to disable any of them you only need to remove the executable bit. In the following example we disable everything but 00_header and 10_linux:

When configured you run grub2-mkconfig with the -o argument pointing to the output file, which should usually be :

This will (re)generate GRUB2 configuration. Note that if grub2-mkconfig doesn't report anything as found then nothing was, and GRUB2 will offer no boot selections.

BIOS/MBR or BIOS/GPT
Installing in this mode is straight forward as it's just like the legacy GRUB with new GRUB2 additions. If needed, start with mounting the parition:

Run the grub2-install 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. grub2-install accepts a --target option to specify which CPU/Platform to install. If unspecified, grub2-install will make a guess; on amd64/x86 it will use "i386-pc" by default:

<!--

Partitioning and preparing boot disk
Before installing GRUB2 to the boot media a little care should be taken when preparing and partitioning the boot device, be it an internal disk or a removable device. This depends on the boot type involved: BIOS or UEFI. BIOS booting can be easily achieved either by booting from disk partitioned with the aging MBR, or booting with GPT with a protective MBR or a hybrid MBR if dual booting is involved with GPT unaware OS like MSDOS/Windows. It is another story for UEFI as GPT is part of UEFI specification and it is mandatory to use GPT partitioned disk in this case.

When dual booting with Windows, be aware that Windows cannot boot from anything but BIOS/MBR or or a GPT partitioned disk on an EFI platform. In the latter case, dual booting Windows is not difficult. In the former case, it can be difficult to dual boot on a GPT partitioned disk with a hybrid MBR. More on this subject will come later.

Before going further, one could back up the boot device MBR with something like:

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

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

Here is an example of a GPT partitioned disk with BIOS boot [0xEF02] partition and an EFI [0xEF00] partition. the following is the output of the `p' command in gdisk main menu.

parted gives a somewhat different output with a slightly different semantics for the same device, here is the output.

Creating partions in gdisk is pretty straight forward for somebody who used fdisk. Just type `n' in the main menu, then provide a beginning and end sector if need be and then type the partition type EF00 for an EFI system partition for example. That's all. -->

UEFI/GPT
Before setting up UEFI boot, one has to partition the boot device with a GPT compatible disk tools like GPT fdisk or gdisk, parted or gparted (a gtk gui) or other tools that I did not bother to try at this point. It's advised to have something greater than 200MB and maybe smaller than 500MB for multi boot systems. GPT fdisk is a powerful tool that can be used to setup a few advanced settings like hybrid MBR or the number of alignment sectors. The default 2048 sectors (1MiB) is a sane default which will permit to make use of sector 34-2048 to embed GRUB2 core.img for example if one forgot to leave some space for BIOS boot partition.

Let's move to installing GRUB2 and setting up an EFI boot entry. I do not have an EFI board so EFI specifc boot steps are not tested!

First, create a filesystem and a mount point for the EFI partition with something like:

And then install GRUB2 (x86 users should replace x86_64 by i386)

or install everything manually if something goes wrong.

With this configuration must be saved in, instead of , thus

It might be necessary to build a customized core.img with a few builtin modules to be safe or to satisfy specific requirements.

Before any attempt to add a menu entry to EFI boot menu, inserting EFI module and merge the utility is necessary.

And then add an boot menu entry.

Hybrid GPT/MBR
Multi booting OSs that aren't aware of GPT partitioned disk, e.g. Windows 7 or Windows XP for those who still use that thing--that's because MSDOS/Windows cannot boot from anything else than BIOS/MBR aside from MSDOS/Windows 7 and possibly 8 from EFI platforms,--require this tricky workaround. The thing to keep in mind is that playing with a hybrid MBR can be tricky so, nothing in this sub-section should be taken as solid rock working but rather simply guidances to experiment to get something working.

First off, GRUB2 should boot and should recognize a partition table be it GPT or MBR simply by loading the associated module (part_gpt or part_msdos). So it should be expected to be able to boot on BIOS/MBR or BIOS/GPT depending on GRUB2 loaded module? Nothing is further from the truth, because, the previous sections outlined the differences between installing GRUB2 on BIOS/MBR and BIOS/GPT. I don't know how grub2-install behave when trying to install in BIOS/MBR mode with an EF02 (or bios_boot in parted terms) partition because I did not simply try it.

Actually there's simple thing that would determine grub2-install to install in BIOS/MBR or BIOS/GPT: it's the presence of a EE00 (GPT protective) and being the first partition in the MBR with that. With a hybrid MBR, GRUB2 will install just fine if and only if the first partition in the MBR table is an EE00 partition. An EF02 partition should be present anywhere in the disk and not necessarily in the MBR list to leave a few room to embed core.img in the disk tough.

Creating a hybrid MBR is easy with gdisk: just hit `r' (recovery and transformation) in the main, then hit `h' (CHS recompute) in that menu, and then enter a series of partition (less or equal to 3) in the order you want it to be listed in the MBR, and then enter the hexadecimal partition type without the `0x' prefix or accept the default with hitting repeatedly with `Y', and enable only a single boot flag as the following example.

And then check out if the operation was successful or not 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
There's a truly improved chainload mode compared to GRUB LEGACY: the new iso (or loop) chainload mechanism. Actually, one could still chainload iso images with GRUB LEGACY, and I did, but there were no way to pass kernel cmdline arguments. In either case, the iso image in question should have been built with that in mind like SysRescueCd or on a lesser extend Gentoo liveCD, otherwise booting will just fail badly in the physical media check/test. Gentoo liveCD is handy because it has a minimal shell which let mount the squashed image to the right place and then hit ESC to continue the boot process. That's a handy way to install an OS with everything in RAM, especially for such light liveCD, without listening to a whining drive on each command.

ISO images
To chainload an iso with custom or defaults kernel cmdline arguments, something like the following can be easily added: menuentry "SYSRESCUECD" { loopback loop /sysrecuecd-x86-2.3.1.iso linux (loop)/isolinux/rescue64 nomodeset vga=791 docache setkmap=fr isoloop=/sysrecuecd-x86-2.3.1.iso initrd (loop)/isolinux/initram.igz }

For a permanent and automatic entry to grub.cfg, a custom file could be added to `/etc/grub.d'.

Make the script executable:

And lastly regenerate your grub.cfg with grub2-mkconfig.

Another Bootloader
Chainloading other bootloader is fairly easy if there's support in GRUB2 for that specific bootloader. Otherwise, one could use a man in the middle or another bootloader in other words to do the task if necessary. 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 become problematic in a single multiboot disk, otherwise something as simple as the following is enough to boot another disk with whatever bootloader.

menuentry "WHATEVER" { insmod part_msdos insmod chain chainloader (hd1,1)+1 }

TrueCrypt
Well, let's make a long story short: GRUB2 cannot neither chainload a disk with TrueCrypt in the MBR neither the rescue CD image. This is perfectly possible, feasible and works just fine with GRUB LEGACY. It even works with GRUB4DOS! This could be used as workaround. See for more info and the above GRUB4DOS menu entry as a starting point. The infamous `invalid signature' await the more adventurous ones.

Simply put, one should stick to GRUB LEGACY or to another bootloader or else... use GRUB4DOS as workaround for this. GRUB4DOS has a very similar GRUB LEGACY interface and menu.lst entry which can be used to chainload TrueCrypt bootloader or rescue CD to boot from an encrypted partition. An executable with grldr in the `/' root of the booting device is required, plus a menu.lst. See below for a menu entry example. Chainloading TrueCrypt bootloader in another disk is straightforward 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 ESC[ape] to chainload the following partition if any or the following disk.

MSDOS/Windows
If MSDOS/Windows is in another disk with its bootloader in the MBR, then one can boot with a simple menu entry as the previous example in Chainloading other bootloader section.

Things could become more complicated if MSDOS/Windows is in another partition of the disk and the partition is encrypted with TrueCrypt for example, or simply if a hybrid MBR is involved.

The simplest way to dual boot MSDOS/Windows is using BIOS/MBR combination. Simply backup the whole MBR to be safe or simply the bootloader before installing MSDOS/Windows as that thing will overwrite the bootloader for sure. And then simple menu entry could added to grub.cfg.

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

Or the following for MSDOS/Windows XP

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

An entry with GPT/hybrid MBR doesn't not to the list to the previous usual BIOS/MBR examples. Booting multiple MSDOS/Windows could be achieved with remapping and/hiding partion with partool.

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

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

An UEFI dual boot could be achieved with the following, if, for example, the default bootloader was overwritten with GRUB2 or simply that bootmgr doesn't do the trick for different reasons.

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 /etc/default/grub with root privileges and add

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

It looks like you are using UUID instead and that's fine. /etc/default/grub only affects the current operating system so don't worry about every linux OS using grub to start using that swap. After finishing your edits, run

(substitute grub.cfg with whatever file grub reads at boot, e.g. it may be named /boot/grub/grub.efi) to update your grub startup information with what you changed in /etc/default/grub.

Chroot
If you have a separate /boot partition and plan to install GRUB2, be sure to mount only the target root partition before chrooting, but not the `/boot' partition as well. Mount /boot once inside the chroot environment. This is required because grub2-mkconfig will not detect /boot as a separate partition and will assume /boot and root are on the same partition if /boot was mounted before chrooting.

Booting from LVM, RAID and/or Encrypted Volumes
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

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

Booting from LVM Logical Volumes
GRUB2 supports booting from an LVM partition. However, one must set the device-mapper USE flag in order to activate this feature:

Reemerge if needed. Next tell GRUB2 to preload its "lvm" module,

And (re)generate grub.cfg with grub2-mkconfig.

Booting from RAID Array
The documentation on this subject, along with booting from encrypted physical volumes, is close to null. As I do not boot from a RAID array, anyone who managed to boot from a complex RAID array is welcomed to complete this section.

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

I can guess tat this should work with a simple software RAID setup. However, I have 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 Physical Volume
... insmod gzio insmod part_gpt insmod cryptodisk insmod luks insmod gcry_twofish insmod gcry_sha256 cryptomount -u insmod lvm insmod ext2 set root='lvm/-' ...

Booting from newtwork (PXE)

 * Booting from newtwork (PXE)

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

Then, you can configure. For example:

To find out what modes your graphics card supports, use the following commands on the GRUB 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 partion 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 `/boot/grub/grub.cfg' 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 require an EE00 partition type first in the MBR partition list entry, but that may pose a problem to boot other OSs in the same disk especially MSDOS/Windows, to recognize a GPT partitioned disk with or without hybrid MBR. A workaround would be simply removing any protective EE00 partition, with fdisk for example but not gdisk! (it won't work with gdisk as the fake partition is just there to protect GPT main table), and boot in BIOS/MBR mode. Just remember to not use other disk tools but gdisk (it should work with [g]parted) to resize after that, else, use gdisk to add protective EE00 partitions to protect at least GPT main and backup partition before using any non GPT aware tools if necessary.

There's another issue, MSDOS/Windows may not find any suitable partition to boot from if there's a EE00 partition protecting GPT main partition table (sector 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 gdisk to recompute the CHS value for hybrid MBR (in the recovery and transformation menu, or in the expert main menu).

Attempting to install GRUB to a disk or a partition
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. this could mean that:
 * If you're getting this error:
 * 1st: A `/boot' partition is not mounted, simply run as root `mount /boot'.
 * 2nd: If you're trying to install GRUB2 in traditional BIOS/GPT setup, this could mean more likely that there isn't any EF02 or bios_boot to embed core.img. A little partition of a few hundreds kilo bytes may be enough, although it's : good to align it's partition to something like 2048 sectors to avoid performance penalty, so a 1MiB partition should do.


 * If you're trying to install GRUB2 in a partition e.g. `/dev/sda5' in BIOS/MBR setup (who did try it to BIOS/GPT?), simply add `--force' cmdline switch to get going. You should be fine with either enough gap before the first sector of the first partition or else use chattr command (as described in BIOS/MBR installation) to get going or else... destroy your partition boundary and possibly your LUKS or LVM2 header if any.


 * If grub2-install does not print any errors message or if the message is about scanning disk files and you have several platforms enabled in `/etc/portage/make.conf' and nothing is installed in the disk. Then, you should edit `/sbin/grub2-install' `platform=qemu' to `platform=pc', for example, or the appropriate platform in that case. This happened to me, and I had to look arround to found out, at last, that the platform shall be rightly set when installing grub:2.

No post-MBR gap
This error means, that grub could not find the usual gap between the MBR and first partition of a disk. It is possible that the disk does not have this gap. Some tools format disks (e.g. LiveUSB disk installer) so that the first partition starts at sector 1 instead of 2048. Repartitioning the disk can fix this. Some visualization-based blockdevices can also cause problems. See http://bbs.archlinux.org/viewtopic.php?pid=581760#p581760

Embedding area is unusually small
If you receive this error, it means that there is not enough room at the beginning of your disk before the first partition:

In general this is going to be a bit of trouble to fix. You will need to resize one or more patitions to leave some free space at the beginning of your drive. The gParted liveCD is recommended.

If you are lucky however, your swap partition is the first one on the disk, e.g. /dev/sda1. In that case, you can simply wipe out your swap space and repartition it on the fly.

Begin by disabling the swap partition and launching fdisk:

This should bring you to the fdisk prompt, where the following commands can be used to shrink the first partition on /dev/sda:

A number smaller than 4096 may work, but 4096 worked for the author.
 * '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

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

You should now be able to install grub onto /dev/sda.

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