Fedora Docs

The GRUB2 Bootloader


GRUB2 is the latest version of GNU GRUB, the GRand Unified Bootloader. A bootloader is the first software program that runs when a computer starts. It is responsible for loading and transferring control to the operating system kernel. In Fedora, the kernel is Linux. The kernel then initializes the rest of the operating system.

GRUB2 is the follower of the previous version GRUB (version 0.9x). The original version is available under the name GRUB Legacy.

Since Fedora 16, GRUB2 has been the default bootloader on x86 BIOS systems. For upgrades of BIOS systems, the default is also to install GRUB2, but you can opt to skip bootloader configuration entirely.

Installing GRUB2 on a BIOS system

Usually, GRUB2 will be installed by the installer, Anaconda, during the installation process. You will probably never have to deal with manual installation of GRUB2. However, in certain situations , you will want to install GRUB2 manually, if you want to update from an older or different bootloader, for instance. To install GRUB2:

  1. Install GRUB2 software using the dnf package manager

    $ sudo dnf install grub2

Installing GRUB2 on the hard disk on BIOS systems

Installing the GRUB2 software on your system does not change your bootloader configuration. In order to use GRUB2 for loading the operating system, you have to install it on the hard disk. There are two possible options to install it:

  1. in the master boot record (MBR) of the hard disk

  2. on an extra partition on the hard disk

GRUB2 is able to load many operating systems, including Windows, so it is recommended to install it as the default bootloader in the MBR of the primary hard disk, usually the sda device.

Before you start
  • Make sure you have installed the GRUB2 software onto your system. See Installing GRUB2 on your system for more information.

  • To automatically collect information about your disks and operating systems installed on them, the os-prober package needs to be installed on your system.

  1. List devices available on the system.

    $ lsblk
  2. Identify the primary hard disk. Usually, it is the sda device.

  3. Install GRUB2 in the MBR of the primary hard disk.

    $ sudo grub2-install /dev/sda
  4. Create a configuration file for GRUB2.

    $ sudo grub2-mkconfig -o /boot/grub2/grub.cfg
More information
  • The grub2-mkconfig command will create a new configuration based on the currently running system. It collects information from the /boot partition (or directory), from the /etc/default/grub file, and the customizable scripts in /etc/grub.d/.

  • The configuration format has evolved over time, and a new configuration file might be slightly incompatible with the old bootloader. It is therefore a good idea to first run grub2-install whenever you would need to run grub2-mkconfig.

  • It is generally safe to directly edit /boot/grub2/grub.cfg in Fedora. Grubby in Fedora patches the configuration when a kernel update is performed and will try to not make any other changes than what is necessary. Manual changes might however be overwritten with grub2-mkconfig next time the system is upgraded with Anaconda. Customizations can be placed in /etc/grub.d/40_custom or /boot/grub2/custom.cfg files and will survive running the grub2-mkconfig command.

Installing GRUB2 on a UEFI system

To install or fix GRUB2 on a UEFI system on Fedora 18 or newer, you need to do three things:

  • create an EFI System Partition (ESP)

  • install the bootloader files

  • configure the GRUB2 configuration

Create an ESP

UEFI firmware, in general, likes to boot from an EFI System Partition on a disk with a GPT label.

Before you start
  1. Learn how to create partitions using gdisk.

  1. List available block devices to find a place to create your ESP.

    $ lsblk
  2. Create at least a 128 MiB disk partition using a GPT label on the primary hard disk.

    $ sudo gdisk /dev/sda
  3. Format the partition with the FAT32 file system.

    $ sudo mkfs.vfat /dev/sda1
  4. Mount the partition to /boot/efi mount point.

    $ sudo mount /dev/sda1 /boot/efi

Install the bootloader files

In order to use GRUB2 with on the UEFI systems, you need to install appropriate packages:

Before you start
  1. Mount the /boot/efi mount point. See Create an ESP to create it.

  1. Install the necessary packages.

    dnf install grub2-efi grub2-efi-modules shim
  2. If they are already installed, reinstall them.

    dnf reinstall grub2-efi grub2-efi-modules shim
More information
  • This installs the signed shim and the GRUB2 binary.

Create a GRUB2 configuration

Under EFI, GRUB2 looks for its configuration in /boot/efi/EFI/fedora/grub.cfg. For newly installed kernels to work, grubby expects /etc/grub2-efi.cfg to be a symlink to the real grub.cfg (for example /boot/efi/EFI/fedora/grub.cfg).

If you already have a GRUB2 EFI config file, you do not need to do anything else. Otherwise, you can try to create the configuration file using the grub2-mkconfig command.

$ sudo grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg

Solve problems with UEFI bootloader.

Adding the boot menu entries

When you power on your system, your firmware will look for EFI variables that tell it how to boot. If you are already booted in EFI mode and EFI runtime services are working correctly, you can configure your boot menu with efibootmgr. If not, you will have to bootstrap the process.

Fortunately, shim can help you bootstrap. The EFI program /boot/efi/EFI/BOOT/fallback.efi will look for files called BOOT.CSV in your ESP and will add boot entries corresponding to them. The shim command provides a BOOT.CSV file that will add an entry for grub2-efi for you.

Using the EFI Shell to invoke fallback.efi should work for you. You can do this with commands like:

> fs0:
> fallback.efi

If you have no boot entries at all, then just booting off your disk in UEFI mode should automatically invoke /boot/efi/EFI/BOOT/BOOTX64.EFI, which will, in turn, invoke fallback.efi.

If you already have incorrect boot entries, you’ll either need to delete them or to modify BOOT.CSV to create new entries with different names.

Adding Other operating systems to the GRUB2 menu

The grub2-mkconfig command will add entries for all operating systems it can find. For the command to work, you have to have installed the os-prober tool that is provided by the os-prober package.

Unfortunately, problem sometimes can appear. See the GRUB manual to solve issues with booting secondary operating systems.

Setting default entry

Due to grub2-mkconfig (and os-prober) we cannot predict the order of the entries in /boot/grub2/grub.cfg, so we set the default by name/title instead.

Before you start
  1. Open /etc/default/grub and make sure these lines exist in the file.

  2. Apply the changes to grub.cfg by running.

    $sudo grub2-mkconfig -o /boot/grub2/grub.cfg
  1. List all possible menu entries.

    $sudo grep -P "submenu|^menuentry" /boot/grub2/grub.cfg | cut -d "'" -f2
  2. Set the desired default menu entry

    $sudo grub2-set-default "<submenu title><menu entry title>"
  3. Verify the default menu entry

    $sudo grub2-editenv list
More information

If you understand the risks involved, you can manually modify the /boot/grub2/grub.cfg file. In that case, set the number of the default operating system using the set default variable.

For example:

set default="5"

Additional Scenarios

Restoring the bootloader using the Live disk.

Sometimes, especially after a secondary operating systems has been installed, the master boot record gets damaged which then prevents the original Linux system from booting. If this happens, it is necessary to reinstall GRUB2 to recreate the original settings. The process not only discovers all installed operating systems, but usually adds them to the GRUB2 configuration files, so they will all become bootable by GRUB2.

Before you start
  1. Get the Fedora Live ISO from getfedora.org.

  2. Prepare a bootable device using the downloaded ISO, either a CD or a USB.

  1. Boot the Fedora live system from the bootable device you have created.

  2. Open the terminal.

  3. Examine the partition layout and identify the boot and the root partition.

    $ sudo fdisk -l

    If you are using the default Fedora layout, there will be one /dev/sda1 partition that holds the /boot directory and one /dev/mapper/fedora-root that holds the root file system.

  4. Create the mount point for the root partition.

    $ sudo mkdir -p /mnt/root
  5. Mount the root partition on the mount point.

    $ sudo mount /dev/mapper/fedora-root /mnt/root
  6. Mount the boot partition in the boot directory of the filesystem that you have mounted in the previous step.

    $ sudo mount /dev/sda1 /mnt/root/boot/
  7. Mount system processes and devices into the root filesystem in /mnt/root.

    $ sudo mount -o bind /dev /mnt/root/dev
    $ sudo mount -o bind /proc /mnt/root/proc
    $ sudo mount -o bind /sys /mnt/root/sys
    $ sudo mount -o bind /run /mnt/root/run
  8. Change your filesystem into the one mounted under /mnt/root.

    $ sudo chroot /mnt/root
  9. Reinstall GRUB2 into the MBR of the primary hard disk.

    $ sudo grub2-install --no-floppy --recheck /dev/sda
  10. Recreate the GRUB2 configuration files.

    $ sudo grub2-mkconfig -o /boot/grub2/grub.cfg
  11. Exit this temporary root filesystem.

    $ exit
  12. Your bootloader should be now restored. Reboot your computer to boot into your normal system.

    $ sudo systemctl reboot

Using the GRUB2 boot prompt

If improperly configured, GRUB2 may fail to load and subsequently drop to a boot prompt. To address this issue, proceed as follows:

  1. Load the XFS and LVM modules

    insmod xfs
    insmod lvm
  2. List the drives which GRUB2 sees:

    grub2> ls
  3. Study the output for the partition table of the /dev/sda device. It may look similar to the following example on a dos partition table with three partitons. will look something like this:

    (hd0) (hd0,msdos3) (hd0,msdos2) (hd0,msdos1)

    or similar to this output on a gpt partition table of the /dev/sda device with four partitions.

    (hd0) (hd0,gpt4) (hd0,gpt3)  (hd0,gpt2) (hd0,gpt1)
  4. Probe each partition of the drive and locate your vmlinuz and initramfs files.

    ls (hd0,1)/

    The outcome of the previous command will list the files on /dev/sda1. If this partition contains the /boot directory, it will show the full name of vmlinuz and initramfs.

  5. Set the root partition.

    grub> set root=(hd0,3)
  6. Set the desired kernel.

    grub> linux (hd0,1)/vmlinuz-3.0.0-1.fc16.i686 root=/dev/sda3 rhgb quiet selinux=0
    # NOTE : add other kernel args if you have need of them
    # NOTE : change the numbers to match your system
  7. Set the desired initrd.

    grub> initrd (hd0,1)/initramfs-3.0.0-1.fc16.i686.img
    # NOTE : change the numbers to match your system
  8. Boot with the selected settings.

    grub> boot
  9. When the system starts, open a terminal.

  10. Enter the grub2-mkconfig command to re-create the grub.cfg file to enable GRUB2 to boot your system.

    grub2-mkconfig -o /boot/grub2/grub.cfg
  11. Enter the grub2-install command to install GRUB2 to your hard disk to use of your config file.

    grub2-install --boot-directory=/boot /dev/sda
    # Note: your drive may have another device name. Check for it with mount command output.

Booting the system using a configuration file on a different partition.

It’s also possible to boot into a configfile that’s located on another partition. If the user is faced with such a scenario, as is often the case with multi-boot systems containing Ubuntu and Fedora, the following steps in the GRUB2 rescue shell might become useful to know:

  1. Load necessary modules to read the partitions.

    insmod part_msdos
    insmod xfs
    insmod lvm
  2. Set the root partition.

    set root='hd0,msdos1'
  3. Set the path to the configuration file.

    configfile /grub2/grub.cfg
More information

The hd0,msdos1 line shows the pertinent boot partition, which holds the grub.cfg file.

Dealing with the "Absent Floppy Disk" Error

It has been reported by some users that GRUB2 may fail to install on a partition’s boot sector if the computer’s floppy controller is activated in BIOS without an actual floppy disk drive being present. Such situations resulted in an Absent Floppy Disk error.

To workaround this issue, go into the rescue mode and install GRUB2 with the --no-floppy option:

grub2-install <target device> --no-floppy

Setting a password for interactive edit mode

If you wish to password-protect the GRUB2 interactive edit mode without forcing users to enter a password to boot the computer, use this procedure.

  1. Create the /etc/grub.d/01_users file.

    cat << EOF
    set superusers="root"
    export superusers
    password root secret
  2. Apply your changes.

    grub2-mkconfig -o /boot/grub2/grub.cfg
More information

You can encrypt the password by using pbkdf2. Use grub2-mkpasswd-pbkdf2 to encrypt the password, then replace the password line with:

password_pbkdf2 root grub.pbkdf2.sha512.10000.1B4BD9B60DE889A4C50AA9458C4044CBE129C9607B6231783F7E4E7191D8254C0732F4255178E2677BBE27D03186E44815EEFBAD82737D81C87F5D24313DDDE7.E9AEB53A46A16F30735E2558100D8340049A719474AEEE7E3F44C9C5201E2CA82221DCF2A12C39112A701292BF4AA071EB13E5EC8C8C84CC4B1A83304EA10F74

More details can be found at Ubuntu Help: GRUB2 Passwords.


Starting from Fedora 21, the --md5pass kickstart option must be set using output from the grub2-mkpasswd-pbkdf2 command.

Using old graphics modes in bootloader

Terminal device is chosen with GRUB_TERMINAL; additional quote from http://www.gnu.org/software/grub/manual/grub.html#Simple-configuration

Valid terminal output names depend on the platform, but may include console (PC BIOS and EFI consoles), serial (serial terminal), gfxterm (graphics-mode output), ofconsole (Open Firmware console), or vga_text (VGA text output, mainly useful with Coreboot).

The default is to use the platform’s native terminal output.

The default in Fedora is gfxterm and to get the legacy graphics modes you need to set GRUB_TERMINAL to the right variable from the description above in /etc/default/grub.

Enabling Serial Console in GRUB2

To enable Serial console in grub:

  1. Add the following entry to /etc/default/grub. Adjust baudrate, parity, bits, and flow controls to fit your environment and cables.

    GRUB_CMDLINE_LINUX='console=tty0 console=ttyS0,115200n8'
    GRUB_SERIAL_COMMAND="serial --speed=115200 --unit=0 --word=8 --parity=no --stop=1"
  2. Re-generate the GRUB2 config file.

    grub2-mkconfig -o /boot/grub2/grub.cfg

Further Reading

See a typo, something missing or out of date, or anything else which can be improved? Edit this document at https://pagure.io/fedora-docs/quick-docs.