GRUB2

Prerequisites[edit | edit source]

To control which platforms GRUB will install for, set the GRUB_PLATFORMS variable in make.conf. The amd64 architecture includes a profile default which works for most systems.

GRUB_PLATFORMS="emu efi-32 efi-64 pc"

The following platforms are supported depending on the target CPU:

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

USE flags[edit | edit source]

Emerge[edit | edit source]

To install GRUB use the normal emerge syntax:

Additional software[edit | edit source]

Optionally, install the os-prober utility (provided through the sys-boot/os-prober package) to have GRUB probe and generate boot entries for other operating systems when running the grub-mkconfig 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 sys-boot/os-prober) 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.

Main configuration file[edit | edit source]

The grub-mkconfig script is used to generate a grub configuration. It uses the scripts under /etc/grub.d/* together with the /etc/default/grub configuration file to generate the final /boot/grub/grub.cfg - 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 (/boot/grub/grub.cfg) using the grub-mkconfig command. This utility will use the scripts in /etc/grub.d/ and the settings in /etc/default/grub.

After modifying one or more settings, run the grub-mkconfig utility with the -o option pointing to the output file located at /boot/grub/grub.cfg (this is GRUB2's default output location):

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

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

Setting configuration parameters[edit | edit source]

The following variables in /etc/default/grub 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 info page of grub-mkconfig.

After modifying the parameters, regenerate the GRUB2 configuration file with grub-mkconfig.

Enabling or disabling configuration scripts[edit | edit source]

The directory /etc/grub.d/ contains the scripts that grub-mkconfig uses to generate a grub.cfg file. By default the contents of this directory should be similar to the following:

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

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 chmod command. In the following example every script but 00_header and 10_linux are disabled:

After modifying the scripts (or removing the executable bit), regenerate the configuration file using grub-mkconfig.

Manipulating configuration scripts[edit | edit source]

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 /etc/grub.d/40_custom script to:

menuentry "FreeBSD" --class freebsd --class bsd --class os {
 insmod ufs2
 insmod bsd
 set root=(hd0,1)
 kfreebsd /boot/kernel/kernel
 kfreebsd_loadenv /boot/device.hints
 set kFreeBSD.vfs.root.mountfrom=ufs:/dev/ada0s1a
 set kFreeBSD.vfs.root.mountfrom.options=rw
 set kFreeBSD.hw.psm.synaptics_support=1
}

/dev/sda1 or (hd0,1) is the partition in which FreeBSD resides. If the normal UFS install was used for the FreeBSD partition then /dev/sda1 is a container (something like a logical partition). It consists of the swap and root partition. Verify the 40_custom script is executable by running ls -la /etc/grub.d/40_custom. If the executable bit is not set then set it using the chmod u+x 40_custom command.

Next install GRUB and update the configuration file:

BIOS with MBR[edit | edit source]

Make sure that the /boot location is available - if this uses a separate partition, make sure that it is mounted:

Run the grub-install command 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. If all goes well, after running grub-install an output such as the one below is to be expected:

Installation finished. No error reported.

grub-install accepts a --target option to set the CPU architecture and system platform. If unspecified, grub-install will attempt to guess the proper values; on an amd64/x86 system it will use i386-pc by default. grub-install also accepts a --boot-directory option to tell the GRUB installer which directory to look for the boot files. This defaults to the current /boot but is useful when trying to move a root partition.

BIOS with GPT[edit | edit source]

If a /boot partition is needed, start by mounting the /boot partition:

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

Installation finished. No error reported.

grub-install accepts a --target option to set the CPU architecture and system platform. If unspecified, grub-install will attempt to guess the correct values; on an amd64/x86 system it will use i386-pc by default. grub-install also accepts a --boot-directory option to tell the GRUB installer which directory to look in for the boot files. This defaults to the current /boot but is useful when trying to move a root partition.

GPT fdisk (gdisk) version 0.8.1
 
Partition table scan:
  MBR: protective
  BSD: not present
  APM: not present
  GPT: present
 
Found valid GPT with protective MBR; using GPT.
 
Command (? for help): p
Disk /dev/sdc: 976773168 sectors, 465.8 GiB
Logical sector size: 512 bytes
Disk identifier (GUID): AA369F4D-37A4-4C0D-A357-DC24B99A6337
Partition table holds up to 128 entries
First usable sector is 34, last usable sector is 976773134
Partitions will be aligned on 2048-sector boundaries
Total free space is 2014 sectors (1007.0 KiB)
 
Number  Start (sector)    End (sector)  Size       Code  Name
   1            2048       828377087   395.0 GiB   8E00  Linux LVM
   2       828377088       891291647   30.0 GiB    0700  Microsoft basic data
   3       891291648       975177727   40.0 GiB    0700  Microsoft basic data
   4       975177728       976754687   770.0 MiB   8300  Linux filesystem
   5       976754688       976756735   1024.0 KiB  EF02  BIOS boot partition
   6       976756736       976773134   8.0 MiB     EF00  EFI System
 
Command (? for help): 

GNU Parted 3.0
Using /dev/sdc
(parted) print
...
Sector size (logical/physical): 512B/512B
Partition Table: gpt
  
Number  Start   End    Size    File system  Name                  Flags
 1      1049kB  424GB  424GB                Linux LVM             lvm
 2      424GB   456GB  32.2GB               Microsoft basic data
 3      456GB   499GB  42.9GB               Microsoft basic data
 4      499GB   500GB  807MB   ext2         Linux filesystem
 5      500GB   500GB  1049kB               BIOS boot partition   bios_grub
 6      500GB   500GB  8396kB               EFI System            boot
  
(parted)

UEFI with GPT[edit | edit source]

Make sure that the /boot location is available - if this uses a separate partition, make sure that it is mounted:

Run the grub-install command to copy the relevant files to /boot/grub. This should install GRUB in /boot/grub, copy the core image to /boot/efi/EFI/gentoo/grubx64.efi, and call efibootmgr to add a boot entry.

Installation finished. No error reported.

grub-install also accepts a --target option to set the CPU architecture and system platform. If unspecified, grub-install will attempt to guess the proper values; on an AMD64 UEFI-booted system it will use x86_64-efi by default. grub-install also accepts a --boot-directory option to tell the GRUB installer which directory to look for the boot files. This defaults to /boot but is useful when trying to move a root partition.

/dev/sda1		/boot/efi	vfat		noauto,noatime	1 2
/dev/sda2		none		swap		sw		0 0
/dev/sda3		/		ext4		noatime		0 1

/dev/sda1		/boot/efi	vfat		noauto,noatime	1 2

Open Firmware (IEEE 1275) on PowerPC[edit | edit source]

See here.

Chainloading[edit | edit source]

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

menuentry "Custom Super-bootloader example" {
     insmod part_msdos
     insmod chain
     chainloader (hd1,1)+1
}

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

Password protection of GRUB menu[edit | edit source]

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ː

Password:
Reenter password:

PBKDF2 hash of your password is grub.pbkdf2.sha512.10000.9CA4611006FE96BC77A...

Then, add the following toː

# Grub user
echo 'set superusers="username"'
# Grub password
echo 'password_pbkdf2 <username> <password>'

Using framebuffer display[edit | edit source]

To have GRUB use a framebuffer graphical display, re-emerge GRUB with the truetype 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 /etc/default/grub. For example:

# Set resolution and color depth
GRUB_GFXMODE=1366x768x32
 
# Keep resolution when loading the kernel
GRUB_GFXPAYLOAD_LINUX=keep
  
# Set a background image
GRUB_BACKGROUND="/boot/grub/bg.png"
 
# Use a custom font, converted using grub-mkfont utility
GRUB_FONT="/boot/grub/fonts/roboto.pf2"
 
# Set the menu colors 
GRUB_COLOR_NORMAL="light-blue/black"
GRUB_COLOR_HIGHLIGHT="light-cyan/blue"

Motherboard firmware not finding the .EFI file[edit | edit source]

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 /efi/boot/ location. First, make sure the ESP is mounted. Presuming the ESP is mounted at /boot/efi (as suggested in the Handbook), execute:

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

Installation finished. No error reported.

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[edit | edit source]

The sys-boot/os-prober 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 /mnt/gentoo like in the Handbook):