From Gentoo Wiki
Jump to:navigation Jump to:search
This page is a translated version of the page GRUB2 and the translation is 5% complete.
Outdated translations are marked like this.
Other languages:
English • ‎español • ‎français • ‎polski • ‎português do Brasil • ‎русский • ‎中文(中国大陆)‎ • ‎日本語 • ‎한국어

GRUB 2 (GRand Unified Bootloader version 2), sometimes stylized as GRUB2 and commonly referred to as GRUB, 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.


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.


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.

FILE /etc/portage/make.confExample of setting the GRUB_PLATFORMS variable for EMU, EFI, and PC platforms
GRUB_PLATFORMS="emu efi-32 efi-64 pc"

The following platforms are supported depending on the target CPU:

Platform i386 ia64 mips mipsel powerpc sparc64 x86_64
ARC No No No Yes No No No
Coreboot Yes No No No No No 32-bit
EFI Yes Yes No No No No Yes
EMU Yes Yes Yes Yes Yes Yes Yes
IEEE 1275 (Open Firmware) Yes No No No Yes Yes 32-bit
Loongson No No No Yes No No No
Multiboot Yes No No No No No 32-bit
QEMU Yes No No No No No 32-bit
QEMU-MIPS No No Yes No No No No
PC Yes No No No No No 32-bit
Whenever the values in the GRUB_PLATFORMS variable are adjusted GRUB will need to be re-emerged in order to build the changed binary. Be sure to use the --newuse --deep options as shown in the emerge section below.

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.

Flagi USE

USE flags for sys-boot/grub GNU GRUB boot loader

device-mapper Enable support for device-mapper from sys-fs/lvm2
doc Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
efiemu Build and install the efiemu runtimes
fonts Build and install fonts for the gfxterm module
libzfs Enable support for sys-fs/zfs
mount Build and install the grub-mount utility
nls Add Native Language Support (using gettextGNU locale utilities)
sdl Add support for Simple Direct Layer (media library)
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
themes Build and install GRUB themes (starfield)
truetype Build and install grub-mkfont conversion utility


To install GRUB use the normal emerge syntax:

root #emerge --ask --newuse --deep sys-boot/grub:2

Additional software

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.

root #emerge --ask --newuse sys-boot/os-prober

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.


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

File Format Edits recommended? Description
/usr/sbin/grub-mkconfig POSIX shell script No Installed as part of the sys-boot/grub:2 package. Run this script to generate /boot/grub/grub.cfg after configuring the files described below.
/boot/grub/grub.cfg GRUB2 shell script No The file generated by grub-mkconfig. This file is evaluated by GRUB2's built-in script interpreter and doesn't necessarily support all POSIX commands or syntax. See the scripting reference in the GRUB manual for supported features. Be aware that modifications to this file won't persist to the next time grub-mkconfig is run.
/etc/grub.d/* POSIX shell scripts Maybe Each script under /etc/grub.d/* that has its execute bit set is evaluated in sequence, and the stdout is concatenated to form the final /boot/grub/grub.cfg (or whatever file is given to the grub-mkconfig -o option). These scripts use the current system shell and therefore can use any supported syntax. Ideally they should be POSIX-compatible scripts, and the output script must be compatible with the GRUB2 interpreter. It may be necessary to disable or add scripts. For instance, to add menu items that couldn't be automatically generated.
/boot/grub/custom.cfg GRUB2 shell script Maybe The /etc/grub.d/41_custom script will reference this file to be read in at boot time if it exists. This file provides a place to add additional entries or commands and does not require regeneration of the main grub.cfg file.
/etc/default/grub POSIX shell script Yes In most cases this is the only file that should be modified directly. It is mainly used to assign variables used by the scripts in /etc/grub.d to generate a working configuration file. See GRUB2 configuration variables or the official reference for supported variables.

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.

The grub-mkconfig utility does not work properly when using software RAID. Manual configuration of the scripts in /etc/grub.d/ is necessary, as otherwise after installation the system will be left in a non-bootable state.

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

root #grub-mkconfig -o /boot/grub/grub.cfg
Generating grub.cfg ...
Found linux image: /boot/vmlinuz-3.3.0-gentoo

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

If grub-mkconfig does not report any found entries then no entries were found. In this case GRUB will offer no boot selections when upon system restart which may be a tricky, time consuming situation to resolve. Make sure the output is satisfactory before restarting the system.

Setting configuration parameters

The following variables in /etc/default/grub are the most common ones to set to control how GRUB will function:

Variable Explanation Default value
GRUB_DEFAULT Defines the default menu entry selected on boot. May be a numeric index, a menu title, or "saved". Defaults to first detected entry.
GRUB_TIMEOUT Delay (in seconds) before booting default menu entry. Set to 0 to boot immediately or -1 to wait indefinitely. The default is 5 seconds.
GRUB_CMDLINE_LINUX Parameters to be passed on the kernel command line for all Linux menu entries. For instance, to support hibernation, users will need to add GRUB_CMDLINE_LINUX="resume=/dev/sdXY" with /dev/sdXY being the swap partition.
GRUB_CMDLINE_LINUX_DEFAULT Parameters to be passed on the kernel command line for non-recovery Linux menu entries.
GRUB_DEVICE The initial root device (i.e. the kernel's root= parameter). Set this to override the grub-mkconfig command's root device auto-detection. For example, GRUB_DEVICE=/dev/ram0 will force root=/dev/ram0 to be used in the kernel command line.

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

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:

user $ls /etc/grub.d/
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:

root #chmod -x /etc/grub.d/{20_linux_xen,30_os-prober,40_custom,41_custom}

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

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

FILE /etc/grub.d/40_customDodawanie wpisu dla możliwości uruchamiania dwóch systemów (dualboot)
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.

Users familiar with how GRUB Legacy numbered partitions should note partitions starting from 1, not 0, with GRUB2.

Next install GRUB and update the configuration file:

root #grub-install /dev/sda
root #grub-mkconfig -o /boot/grub/grub.cfg

Installing the boot loader

The --efi-directory used in this article deviates from that one used in the AMD64 Handbook.

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:

Select the installation instructions appropriate for the system.


When the system is meant to dual-boot with another (pre-installed) operating system, such as Microsoft Windows, make sure that the Linux bootloader can coexist or dual-boot both operating systems. On PCs it is recommended to use the same boot method as the pre-installed system, e.g. when Windows is using the legacy MBR partitioning, it is also booted in 'legacy BIOS' mode (UEFI calls it CSM, short for Compatibility Support Module, in essence a BIOS emulation). If the mode is changed, e.g. from EFI-CSM (BIOS mode) to native (U)EFI mode, the pre-installed system will most certainly no longer be bootable.

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

root #mount /boot

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:

root #grub-install /dev/sda
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.

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.


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

root #mount /boot

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

root #grub-install /dev/sda
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.

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.

Traditionally x86-PCs used a BIOS as firmware. After the switch to (U)EFI on PCs (around 2005) there used to be a BIOS emulation called 'Compatibility Support Module' (CSM), PCs were therefor still compatible with existing operating systems. On mainstream PCs the EFI-CSM has been phased out since 2020. Even before 2020 some (U)EFI implementations, such as servers, lacked the CSM completely. 'Legacy BIOS mode' is therefor no longer available on modern UEFI systems. UEFI in its native boot mode demands the GUID Partition Table (GPT), a pre-installed operating system will therefore already be using a GPT partitioning scheme.

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.

Normally, a GPT partition table will always also create an MBR partition table which holds only one partition spanning over the whole disk. This will ensure that older software doesn't mistake the disk as 'empty'. The MBR with its protective partition is therefor called a 'protecive MBR' and is part of the GPT specification. By defining hybrid partitions, this protective feature of the GPT is sacrificed! Legacy software will no longer see used space when analyzing the hybrid MBR. Software that is unaware of the GPT and only sees the MBR may mistake undefined disk space as unused and empty space. Data written between the defined MBR partitions may cause data loss to the underlying GPT partitions!

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 EF02 (which is different from the EFI System Partition (ESP) which has type EF00) 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 grub-install command will overwrite any existing filesystem with one of its own.

The BIOS boot partition is not the same partition that is commonly mounted at /boot. The /boot and BIOS boot are different partitions and should be handled separately. The BIOS boot partition should not be regularly mounted on the system (i.e., it should not be defined in /etc/fstab). The /boot partition can be regularly mounted with no issues and therefore can be present in the /etc/fstab file.

To set a partition as a BIOS partition use the command-line tool parted (sys-block/parted) by typing (change 1 to the number of the partition to mark as a BIOS boot partition!):

(parted)set 1 bios_grub on

With sys-apps/gptfdisk's cgdisk utility, this is accomplished by setting the partition type to 0xEF02 and giving it a label of gptbios.

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 p key using the gdisk utility on a GPT-partitioned disk with both a BIOS boot [0xEF02] partition and an EFI [0xEF00] partition:

root #gdisk /dev/sdc
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): 
The 0x hexadecimal prefix does not need to be entered for GPT when using fdisk.

Using the same setup, the parted utility gives output with slightly different syntax:

root #parted /dev/sdc
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

Creating partitions in gdisk is straightforward for users familiar with the fdisk partitioning utility. After starting gdisk, type n (for new) in the main menu, provide beginning and end sectors (if needed), and set the partition type to EF00 for an EFI system partition.

Users who have followed the Gentoo installation instructions will already have the proper partitioning layout set up.


If the UEFI-CSM is used, refer to BIOS with MBR or BIOS with GPT instead. CSM stands for 'Compatibility Support Module' and is a BIOS emulation, making the UEFI behave like a BIOS. In the firmware setup it is often called 'Legacy Mode' oder 'Compatibility Mode'. UEFI-CSM has always been optional and was phased out on mainstream systems (such as PCs) in 2020.

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

root #mount /boot

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.

root #grub-install --efi-directory=/boot/efi
Installation finished. No error reported.
The above command assumes a FAT formatted EFI System Partition (ESP) is mounted at /boot/efi. If the ESP is mounted directly at /boot, use --efi-directory=/boot instead.

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.

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 /boot partition on /dev/sda1 by having a /boot/efi partition on /dev/sda1. 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 /boot folder will be located in the root / partition (at /boot) and the EFI partition will mount in the boot folder (at /boot/efi). For further clarification, see the example /etc/fstab file below.

FILE /etc/fstabExample of an UEFI capable /etc/fstab file with a swap partition:
/dev/sda1       /boot/efi       vfat    noauto,noatime  1 2
/dev/sda2       none            swap    sw              0 0
/dev/sda3       /               ext4    noatime         0 1

Generating a 100MB partition for /boot/efi should provide plenty of space for holding multiple

  • .efi 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 gdisk (sys-apps/gptfdisk) and parted (sys-block/parted) tools fit nicely for this purpose. When using the gdisk utility, be sure to use type EF00.

Proceed to create a FAT filesystem on the EFI system partition using mkfs.fat and add it to /etc/fstab by following the example below:

root #mkfs.fat -F 32 -n efi-boot /dev/sda1
root #mkdir /boot/efi
FILE /etc/fstabDodawanie wpisu /boot/efi do montowania
/dev/sda1		/boot/efi	vfat		noauto,noatime	1 2
root #mount /boot/efi
It is helpful to set the GRUB_PLATFORMS variable in /etc/portage/make.conf. This will assist GRUB in determining what options to use when detecting the proper EFI target. For 32-bit UEFI systems use efi-32. For 64-bit use efi-64.
In order for GRUB to install properly, the EFI directory must be mounted and the efivars kernel module must be loaded before the grub-install command will complete successfully.

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 /boot/efi then copy the file grubx64.efi located at /boot/efi/EFI/gentoo/grubx64.efi to /boot/efi/EFI/BOOT/BOOTX64.EFI. 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:

  • Uruchamianie z platform UEFI.
  • Uruchamianie z dysków podzielonych na partycje GPT bez konieczności posiadania hybrydowego MBR (hybrydowy MBR może być włączony, jeśli jest potrzebny do kompatybilności lub portowania).
  • Uruchamianie partycji /boot z systemem plików btrfs.
  • Uruchamianie z zbioru ZFS.
  • Uruchamianie bezpośrednio z raid (btrfs) bez konieczności posiadania intramfs dla wczesnej konfiguracji montowania.
  • Uruchamianie bezpiśrednio z zarządu woluminu logicznego (jak LVM2).
  • Uruchamianie z wsparciem dla DM-RAID (RAID 0, 1, 4, 5, 6, 9 oraz 10).
  • Uruchamianie z zaszyfrowanych urządzeń (LUKS).

Some specific features are explained in more detail next.


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

FILE /etc/grub.d/40_customChainloading another bootloader
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

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ː

user $grub-mkpasswd-pbkdf2
Reenter password:

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

Then, add the following toː

FILE /etc/grub.d/35_auth:
# Grub user
echo 'set superusers="username"'
# Grub password
echo 'password_pbkdf2 <username> <password>'

Using framebuffer display

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.

root #emerge --ask --newuse sys-boot/grub:2

Proceed to configure the default configuration file located at /etc/default/grub. For example:

FILE /etc/default/grubFramebuffer related settings
# Set resolution and color depth
# Keep resolution when loading the kernel
# Set a background image
# Use a custom font, converted using grub-mkfont utility
# Set the menu colors 


For more troubleshooting, please refer to the Troubleshooting sub-article.

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 /boot/grub/grub.cfg was correctly generated with grub-mkconfig, or generate one with a custom menu entry.

os-prober not running

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

root #grub-mkconfig -o /boot/grub/grub.cfg
Generating grub configuration file ...
Found linux image: /boot/vmlinuz-5.11.14-gentoo-x86_64
Found initrd image: /boot/amd-uc.img /boot/initramfs-5.11.14-gentoo-x86_64.img
Warning: os-prober will not be executed to detect other bootable partitions.
Systems on them will not be added to the GRUB boot configuration.
Check GRUB_DISABLE_OS_PROBER documentation entry.
Adding boot menu entry for UEFI Firmware Settings ...

This can be corrected by setting the GRUB_DISABLE_OS_PROBER variable to false in /etc/default/grub file.

FILE /etc/default/grub

Upon the next run, grub-mkconfig should find additional bootable partitions:

root #grub-mkconfig -o /boot/grub/grub.cfg
Generating grub configuration file ...
Found linux image: /boot/vmlinuz-5.11.14-gentoo-x86_64
Found initrd image: /boot/amd-uc.img /boot/initramfs-5.11.14-gentoo-x86_64.img
Warning: os-prober will be executed to detect other bootable partitions.
It's output will be used to detect bootable binaries on them and create new boot entries.
Found Windows Boot Manager on /dev/nvme0n1p2@/efi/Microsoft/Boot/bootmgfw.efi
Adding boot menu entry for UEFI Firmware Settings ...

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

root #mkdir -p /boot/efi/efi/boot
root #cp /boot/efi/efi/gentoo/grubx64.efi /boot/efi/efi/boot/bootx64.efi

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

root #grub-install --efi-directory=/boot/efi --removable
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

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

root #mkdir -p /mnt/gentoo/run/udev
root #mount -o bind /run/udev /mnt/gentoo/run/udev
root #mount --make-rslave /mnt/gentoo/run/udev

Instalacja nowego jądra

Whenever a new kernel is installed, GRUB must be reconfigured to recognize it. This can be done using grub-mkconfig, as shown below, or can be done manually.

Upewnij się, że partycja /boot jest zamontowana.
root #grub-mkconfig -o /boot/grub/grub.cfg
Generating grub.cfg ...
Found linux image: /boot/kernel-3.3.8-gentoo
Found initrd image: /boot/initramfs-genkernel-x86_64-3.3.8-gentoo
Found linux image: /boot/kernel-3.2.12-gentoo
Found initrd image: /boot/initramfs-genkernel-x86_64-3.2.12-gentoo

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.

See also

  • In Chainloading the use of GRUB2 to boot other boot loaders is described. This is important to read when dual-booting systems, or when GRUB2 needs to be configured to boot ISO files.
  • In Advanced storage the necessary steps are documented on how to install and use GRUB on more advanced storage situations, such as software RAID, logical volumes or encrypted file systems.
  • In Configuration variables an exhaustive list of GRUB configuration variables, as used by /etc/default/grub, is documented.
  • In Troubleshooting a list of common GRUB errors (with their solutions) is presented.
  • In Hybrid partition table the use of a mixed MBR/GPT setup is documented, as well as how to use such hybrid partition layout with GRUB.

External resources

For more information, please see: