GRUB2 Quick Start

Other languages:

This article provides information on how to get up and running with GRUB in the simplest configurations. For a migration from GRUB Legacy to GRUB2, see GRUB2 Migration.

Installing GRUB software

To install GRUB, first set the GRUB_PLATFORMS variable with one or more appropriate values in the system's make.conf. If unset, GRUB will guess which platform to use on the system. It guesses pc (which is the MBR style of installation) for x86/amd64 architectures.

Standard PC (BIOS) support:

FILE /etc/portage/make.confPC BIOS GRUB_PLATFORMS example

GRUB_PLATFORMS="pc"

UEFI on amd64:

FILE /etc/portage/make.conf64-bit UEFI GRUB_PLATFORMS example

GRUB_PLATFORMS="efi-64"

Both standard PC (BIOS) and UEFI support:

FILE /etc/portage/make.confMultiple GRUB_PLATFORMS example

GRUB_PLATFORMS="efi-64 pc"

After the variable is set, emerge the software:

root #emerge --ask sys-boot/grub

Activating the GRUB boot loader

Mount /boot if applicable:

root #mount /boot

When using an EFI platform, make sure that the EFI System Partition is available (mounted) at /boot/efi. This can either be through a specific mount point (at /boot/efi) or by having an entire /boot partition formatted with the FAT filesystem. This will effectually render /boot into a large EFI System Partition.

Presuming only /boot/efi is FAT:

root #mount /boot/efi

Run the grub-install utility to copy the relevant files to /boot/grub. On the PC platform, this also installs a boot image to the Master Boot Record (MBR) or a partition's boot sector.

To install GRUB to the MBR:

root #grub-install /dev/sda

Installation finished. No error reported.

To install GRUB on an EFI capable system:

root #grub-install --target=x86_64-efi

Installation finished. No error reported.

The grub-install command accepts a --target option to specify which CPU/Platform to install. If unspecified, grub-install will make a guess: on x86/amd64 it will use the i386-pc value by default.

Automatic configuration

GRUB is configured by using the grub-mkconfig program to generate a configuration file.

grub-mkconfig generates the configuration file based on template sections located in /etc/grub.d. The default templates should cover most common boot setups.

user $ls /etc/grub.d

00_header  10_linux  20_linux_xen  30_os-prober  40_custom  41_custom  README

The behavior of these templates can be controlled by setting variables in /etc/default/grub. See the GRUB manual for more information.

Kernel naming scheme

In order for grub-mkconfig to detect the available Linux kernel(s), their names must start with vmlinuz- or kernel-.

For example:

CODE Example kernel names that GRUB can detect

/boot/vmlinuz-3.4.3
 /boot/kernel-2.6.39-gentoo
 /boot/kernel-genkernel-x86_64-3.17.1-gentoo-r1

When using an initramfs, its name should start with initramfs- or initrd- and end with .img. The version must match one of a kernel image. File names generated by genkernel will also work.

For example:

CODE Example initramfs names that GRUB can detect

/boot/initrd.img-3.4.3
 /boot/initrd-3.4.3.img
 /boot/initrd-3.4.3.gz
 /boot/initrd-3.4.3
 /boot/initramfs-3.4.3.img
 /boot/initramfs-genkernel-3.4.3-gentoo
 /boot/initramfs-genkernel-x86_64-2.6.39-gentoo

To generate the grub.cfg file, execute the grub-mkconfig command like so:

root #grub-mkconfig -o /boot/grub/grub.cfg

Generating grub.cfg ...
Found linux image: /boot/vmlinuz-3.2.9
done

Silent kernel decompression

To silence kernel decompression at boot time, edit /etc/default/grub and add quiet to the GRUB_CMDLINE_LINUX_DEFAULT variable.

FILE /etc/default/grubSilent decompression example

GRUB_CMDLINE_LINUX_DEFAULT="quiet"

systemd

To boot systemd while using GRUB configure the GRUB_CMDLINE_LINUX variable look like this:

Important
This is no longer necessary with sys-apps/systemd when the sysv-utils USE is enabled. This defaults to on with at least version 239 in Gentoo

FILE /etc/default/grubSystemd example

GRUB_CMDLINE_LINUX="init=/usr/lib/systemd/systemd"

Loading another operating system

grub-mkconfig can also generate configurations to load other operating systems. This requires the sys-boot/os-prober package.

To boot Windows, the sys-fs/ntfs3g also needs to be installed. It allows for the grub-mkconfig utility to probe NTFS filesystems.

Manual configuration

Use of grub-mkconfig is not required. The grub.cfg file can be edited manually as well.

Migrating from the GRUB Legacy config format to the GRUB 2 config format is usually quite simple, requiring a few minor syntax changes.

FILE grub.confGRUB Legacy

timeout 5
 
'''<span style="color:maroon">title</span>''' Gentoo Linux 3.2.12
root '''<span style="color:maroon">(</span>'''hd0,'''<span style="color:maroon">0)</span>'''
'''<span style="color:maroon">kernel</span>''' /boot/kernel-3.2.12-gentoo root=/dev/sda3
<br>

⇨

FILE grub.confGRUB

timeout'''<span style="color:green">=</span>'''5
 
'''<span style="color:green">menuentry '</span>'''Gentoo Linux 3.2.12'''<span style="color:green">' &#123;</span>'''
    root'''<span style="color:green">=</span>'''hd0,'''<span style="color:green">1</span>'''
    '''<span style="color:green">linux</span>''' /boot/kernel-3.2.12-gentoo root=/dev/sda3
'''<span style="color:green">&#125;</span>'''

Note
GRUB Legacy numbers partitions starting with 0; GRUB numbers partitions starting with 1. Both bootloaders number drives starting with 0.