From Fedora Project Wiki

Revision as of 16:07, 31 May 2021 by Quiet (talk | contribs)


GRUB 2 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, (Linux, in the case of Fedora). The kernel, in turn, initializes the rest of the operating system.

GRUB 2 has replaced what was formerly known as GRUB (i.e. version 0.9x), which has, in turn, become GRUB Legacy.

Starting with Fedora 16, GRUB 2 is the default bootloader on x86 BIOS systems. For upgrades of BIOS systems the default is also to install GRUB 2, but you can opt to skip bootloader configuration entirely.

Adding and removing kernel command-line parameters using grubby

Grubby is a utility that updates the bootloader-specific configuration files. The utility is a recommended way for making routine changes to the kernel boot parameters and setting a default kernel.

Following are some of the selected illustrations of grubby usage:

  • To add one kernel parameter to a single boot entry:
# grubby --args=<NEW_PARAMETER> --update-kernel=/boot/vmlinuz-5.11.14-300.fc34.x86_64
  • To add multiple kernel paramters to a single boot entry:
# grubby --args="<NEW_PARAMETER1> <NEW_PARAMETER2 <NEW_PARAMETER_n>" --update-kernel=/boot/vmlinuz-5.11.14-300.fc34.x86_64
  • To add one kernel parameter to all currently existing and future boot entries:
# grubby --args=<NEW_PARAMETER> --update-kernel=ALL
  • To remove one kernel parameter from all currently existing and future boot entries:
# grubby --remove-args=<PARAMETER_TO_REMOVE> --update-kernel=ALL
  • To set the default kernel:
# grubby --set-default=/boot/vmlinuz-5.11.12-300.fc34.x86_64

Updating and repairing the GRUB 2 main configuration file

The /boot/grub2/grub.cfg is the main GRUB 2 configuration file. It is a static file that you rarely modify. Except in cases of disk replacement or installation of another Linux distribution.

Discovering what firmware the system is running

To discover what firmware your machine is using, run the following command:

  • On UEFI systems:
# ls -ld /sys/firmware/efi
  • On BIOS systems:
# ls -lrt /etc/grub2.cfg

A directory listing of either of these commands indicate that you are running the corresponding firmware.

The grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg command adds entries for other detected operating systems. That will be done based on the output of the os-prober tool.

The above command for updating the GRUB 2 configuration file is only applicable for UEFI systems with Fedora 33 and earlier. Everybody else should use grub2-mkconfig -o /boot/grub2/grub.cfg.

Repairing GRUB 2

If your machine running Fedora 34 is not working because of the broken GRUB 2 bootloader, you can boot into the rescue mode to repair an already installed operating system.

For more details see Booting Your Computer in Rescue Mode.

After completing steps specified in the previous link, run the following command to mount the root partition:

# chroot /mnt/sysimage

Reinstalling GRUB 2

The GRUB 2 packages contain commands for installing the bootloader and for creating the grub.cfg configuration file.

The grub2-install command embeds two stages of the bootloader - one at LBA 0, and one in either the master boot record (MBR) gap, or the GUID Partition Table (GPT) BIOS Boot partition. The bootloader files are placed in the /boot/ directory.

To reinstall the GRUB 2 bootloader on systems running Fedora 34:

  • On UEFI systems run:
# dnf reinstall shim-* grub2-efi-*
  • On BIOS systems:
    • Find the device node the /boot/ directory is located on:
# mount | grep "/boot "
/dev/sda4 on /boot type ext4 (rw,relatime,seclabel)

The device node is /dev/sda4.

    • Reinstall the bootloader while specifying the device node without the number:
# grub2-install /dev/sda
Installing for i386-pc platform.
Installation finished. No error reported.
Do not use the grub2-install command on UEFI systems. On those systems, bootloaders are in the shim and grub-efi packages. By reinstalling those packages, the bootloaders are reinstalled to their proper location in /boot/efi/ (the EFI system partition).

Fixing a damaged GRUB 2 configuration file using a plaintext stub file

On Fedora 34 and later, you can repair a malfunctioning grub.cfg configuration file by creating a stub file with the following content.

  1. Discover the Universally Unique Identifier (UUID) for the /boot/ mount point:
# lsblk --fs
NAME   FSTYPE  FSVER            LABEL                 UUID                                 FSAVAIL FSUSE% MOUNTPOINT
sr0    iso9660 Joliet Extension Fedora-WS-Live-34-1-2 2021-04-23-11-17-40-00                     0   100% /run/media/jdoe/Fedora-WS-Live-34-1-2
zram0                                                                                                     [SWAP]
├─vda1 ext4    1.0                                    dc29837b-22dc-4469-be85-fc9acf3009fd  699.8M    21% /boot
└─vda2 btrfs                    fedora_localhost-live c58f3698-5587-40f2-b920-64d46c43161d   23.7G    14% /home

The UUID of /boot/ is dc29837b-22dc-4469-be85-fc9acf3009fd.

  1. Create a custom grub.cfg file with the following content:
search --no-floppy --fs-uuid --set=dev dc29837b-22dc-4469-be85-fc9acf3009fd
set prefix=($dev)/grub2

export $prefix
configfile $prefix/grub.cfg

At the end of first line (--set=dev), there is the UUID value of the /boot/ mount point.

The above example assumes default partitioning, where a separate ext4 file system is mounted at /boot/. In case of other configurations, you need to insert /boot/ into line 2. For example:

set prefix=($dev)/boot/grub2
  1. Move or copy the custom grub.cfg file you created in the previous step to /boot/efi/EFI/fedora/grub.cfg

Enabling serial console in GRUB 2

To enable serial console for usage on virtual environments you need to run the following command:

# grubby --args="systemd.journald.forward_to_console=1 console=ttyS0,38400 console=tty1" --update-kernel=/boot/vmlinuz-5.11.16-300.fc34.x86_64
# grubby --set-default=/boot/vmlinuz-5.11.16-300.fc34.x86_64

The first command specifies the baud rate, console forwarding for systemd, what console to use (tty1) and on what kernel such changes should be applied. The second command ensures the specified kernel is going to be loaded by default on next reboot.

For instructions on how to enable serial consol in GRUB 2 for baremetal machines, see Using GRUB via a serial line.

In UEFI boot environment, use efi0 instead of --unit=0. If it does not work, check that your serial port is visible in your UEFI environment, e.g. by running devtree or dh -p SerialIO in EFI Shell. See Grub2 UEFI boot and serial console output for more information.