From Fedora Project Wiki

(update what is grub2, v2)
(bunch of streamlining edits)
Line 4: Line 4:
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 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 GRUB version 0.9x, which has become GRUB Legacy.
GRUB 2 has replaced GRUB version 0.9x, which has become GRUB Legacy. Upstream refers to GRUB 2 as just GRUB.


GRUB 2 is the bootloader used on x86_64 systems, and on aarch64 if UEFI firmware is also used.
GRUB 2 is the bootloader used on x86_64 systems, and on aarch64 if UEFI firmware is also used.
Line 29: Line 29:
<pre># grubby --set-default=/boot/vmlinuz-5.11.12-300.fc34.x86_64</pre>
<pre># grubby --set-default=/boot/vmlinuz-5.11.12-300.fc34.x86_64</pre>


= Updating and repairing the GRUB 2 main configuration file =
= Updating the GRUB configuration file =


The <code>/boot/grub2/grub.cfg</code> file is the main GRUB 2 configuration file. It is a static file that you rarely need to modify. Except in cases of disk replacement or installation of another Linux distribution.
The GRUB configuration file is located at <code>/boot/grub2/grub.cfg</code> and is intended to be a static file that doesn't need updating. In case of disk replacement, or installation of another Linux distribution, it should be updated. Use the following commands:


<code>grub2-mkconfig -o /etc/grub2.cfg</code>


== Discovering computer firmware ==
<code>grub2-mkconfig -o /etc/grub2-efi.cfg</code>


To discover what firmware your machine uses, run the following command:
These commands use information provided by the <code>os-prober</code> utility to add entries for other Linux distributions and Windows.
 
{{admon/note|Please refrain from using `grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg` going forward. This is a valid location on Fedora 33 and older. But on Fedora 34 and newer, it's a small stub file that merely forwards to `/boot/grub2/grub.cfg`. See the reinstallation section below if you've accidentally overwritten this file.|}}
 
= I have a `grub>` prompt! Now what?  =


<pre># [ -d /sys/firmware/efi ] && echo UEFI || echo BIOS</pre>
If you are stuck at a `grub>` prompt, you can use any Fedora edition or spin Network Installer or DVD Installer, and use rescue mode to repair the already installed operating system.


The output returns only UEFI or BIOS, depending on the firmware your machine runs.
For more details see [https://docs.fedoraproject.org/en-US/fedora/rawhide/install-guide/advanced/Boot_Options/#sect-boot-options-rescue Booting Your Computer in Rescue Mode].


The <code>grub2-mkconfig -o /etc/grub2.cfg</code> and <code>grub2-mkconfig -o /etc/grub2-efi.cfg</code> commands add entries for other detected operating systems. That will be done based on the output of the <code>os-prober</code> utility.
After completing steps specified in the previous link, run the following command to mount the root partition:


{{admon/note|To update the GRUB 2 configuration file on Fedora 33 and earlier use <code>grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg</code> on UEFI-based systems, and <code>grub2-mkconfig -o /etc/grub2-efi.cfg</code> on BIOS-based systems. |}}
<pre># chroot /mnt/sysimage</pre>


== Repairing GRUB 2 ==
Next, update the GRUB configuration file as described in the previous section. And then continue with the section below for firmware specific instructions on reinstalling GRUB.


If your machine running Fedora 34 is not working because of the broken GRUB 2 bootloader, the first possible step to take is that you boot into the rescue mode to repair the already installed operating system.
= Reinstalling GRUB =


For more details see [https://docs.fedoraproject.org/en-US/fedora/rawhide/install-guide/advanced/Boot_Options/#sect-boot-options-rescue Booting Your Computer in Rescue Mode].
GRUB comes in two flavors, BIOS GRUB and UEFI GRUB. Reinstallation instructions depend on the firmware type. Systems with UEFI firmware have their GRUB RPM packages updated, which in turn updates the bootloader installed on the EFI System volume.


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


<pre># chroot /mnt/sysimage</pre>
To discover what firmware your machine uses, run the following command:


<pre># [ -d /sys/firmware/efi ] && echo UEFI || echo BIOS</pre>


== Reinstalling GRUB 2 ==
The output returns only UEFI or BIOS, depending on the firmware your machine runs.


The GRUB 2 packages contain commands for installing the bootloader, and for creating the <code>grub.cfg</code> configuration file.
== Instructions for UEFI-based systems ==


The <code>grub2-install</code> 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 <code>/boot/</code> directory.
* Learn what firmware your machine is running. See [https://fedoraproject.org/wiki/GRUB_2#Discovering_the_firmware_type Discovering the firmware type] section.


=== Instructions for UEFI-based systems ===
* Systems with UEFI firmware have the shim and GRUB RPM packages updated, which in turn updates the bootloader files found on the EFI System volume. Reasons for reinstallation include troubleshooting early boot problems, and following inadvertent use of `grub2-install` which results in an unsupported configuration on UEFI systems.


* Learn what firmware your machine is running. See [https://fedoraproject.org/wiki/GRUB_2#Discovering_what_firmware_the_system_is_running Discovering what firmware the system is running] section.
* Remove the following files:
<pre>
# rm /boot/efi/EFI/fedora/grub.cfg
# rm /boot/grub2/grub.cfg
</pre>


* Reinstall the following packages:
* Reinstall the following packages:
<pre># dnf reinstall shim-* grub2-efi-*</pre>
<pre># dnf reinstall shim-* grub2-efi-* grub2-common</pre>
 
{{admon/note|The removal of the two `grub.cfg` files will trigger a script in `grub2-common` to recreate these files.|}}


=== Instructions for BIOS-based systems ===


* Learn what firmware your machine is running. See [https://fedoraproject.org/wiki/GRUB_2#Discovering_what_firmware_the_system_is_running Discovering what firmware the system is running] section.
== Instructions for BIOS-based systems ==
 
* Learn what firmware your machine is running. See [https://fedoraproject.org/wiki/GRUB_2#Discovering_the_firmware_type Discovering the firmware type] section.
 
* Systems with BIOS firmware have the GRUB RPM packages updated, but the installed (or embedded) bootloader is never updated automatically. It's a good idea to update it between Fedora release versions.


* Find the device node the <code>/boot/</code> directory is located on:
* Find the device node the <code>/boot/</code> directory is located on:
Line 89: Line 104:
</pre>
</pre>


{{admon/warning| Do not use the <code>grub2-install</code> command on UEFI systems. On those systems, bootloaders are in the <code>shim</code> and <code>grub-efi</code> packages. By reinstalling those packages, the bootloaders are reinstalled to their proper location in <code>/boot/efi/</code> on the EFI system partition. }}
{{admon/warning| Do not use the <code>grub2-install</code> command on UEFI systems. On those systems, bootloaders are in the <code>shim</code> and <code>grub-efi</code> RPM packages. By reinstalling those packages, the bootloaders are reinstalled to their proper location in <code>/boot/efi/</code> on the EFI System volume. }}
 
== Fixing a damaged GRUB 2 configuration file using a plaintext stub file on UEFI-based systems==
 
On Fedora 34 and later, you can repair a malfunctioning <code>grub.cfg</code> configuration file by creating a stub.
 
# Discover the  Universally Unique Identifier (UUID) for the <code>/boot/</code> mount point:
 
<pre>
# 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]
vda                                                                                                     
├─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
</pre>
 
The UUID of <code>/boot/</code> is <code>dc29837b-22dc-4469-be85-fc9acf3009fd</code>.
 
# Create a custom grub.cfg file with the following content:
<pre>
search --no-floppy --fs-uuid --set=dev dc29837b-22dc-4469-be85-fc9acf3009fd
set prefix=($dev)/grub2
 
export $prefix
configfile $prefix/grub.cfg
</pre>
 
At the end of first line (<code>--set=dev</code>), there is the UUID value of the <code>/boot/</code> mount point.
 
The above example assumes default partitioning, where a separate ext4 file system is mounted on the <code>/boot/</code> directory. In case of other configurations, you need to insert <code>/boot/</code> into line 2. For example:
 
<pre>
...
set prefix=($dev)/boot/grub2
...
</pre>
 
# 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 ==
= Enabling serial console in GRUB 2 =


On Fedora 34 and later, you can enable serial console for usage on virtual environments. The following procedure explains how to achieve this goal.
On Fedora 34 and later, you can enable serial console for usage on virtual environments. The following procedure explains how to achieve this goal.

Revision as of 21:10, 1 July 2021

What is GRUB 2

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 GRUB version 0.9x, which has become GRUB Legacy. Upstream refers to GRUB 2 as just GRUB.

GRUB 2 is the bootloader used on x86_64 systems, and on aarch64 if UEFI firmware is also used.

Changing kernel command-line parameters with grubby

The grubby utility 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 parameters 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 the GRUB configuration file

The GRUB configuration file is located at /boot/grub2/grub.cfg and is intended to be a static file that doesn't need updating. In case of disk replacement, or installation of another Linux distribution, it should be updated. Use the following commands:

grub2-mkconfig -o /etc/grub2.cfg

grub2-mkconfig -o /etc/grub2-efi.cfg

These commands use information provided by the os-prober utility to add entries for other Linux distributions and Windows.

Please refrain from using grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg going forward. This is a valid location on Fedora 33 and older. But on Fedora 34 and newer, it's a small stub file that merely forwards to /boot/grub2/grub.cfg. See the reinstallation section below if you've accidentally overwritten this file.

I have a grub> prompt! Now what?

If you are stuck at a grub> prompt, you can use any Fedora edition or spin Network Installer or DVD Installer, and use rescue mode to repair the 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

Next, update the GRUB configuration file as described in the previous section. And then continue with the section below for firmware specific instructions on reinstalling GRUB.

Reinstalling GRUB

GRUB comes in two flavors, BIOS GRUB and UEFI GRUB. Reinstallation instructions depend on the firmware type. Systems with UEFI firmware have their GRUB RPM packages updated, which in turn updates the bootloader installed on the EFI System volume.

Discovering the firmware type

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

# [ -d /sys/firmware/efi ] && echo UEFI || echo BIOS

The output returns only UEFI or BIOS, depending on the firmware your machine runs.

Instructions for UEFI-based systems

  • Systems with UEFI firmware have the shim and GRUB RPM packages updated, which in turn updates the bootloader files found on the EFI System volume. Reasons for reinstallation include troubleshooting early boot problems, and following inadvertent use of grub2-install which results in an unsupported configuration on UEFI systems.
  • Remove the following files:
# rm /boot/efi/EFI/fedora/grub.cfg
# rm /boot/grub2/grub.cfg
  • Reinstall the following packages:
# dnf reinstall shim-* grub2-efi-* grub2-common
The removal of the two grub.cfg files will trigger a script in grub2-common to recreate these files.


Instructions for BIOS-based systems

  • Systems with BIOS firmware have the GRUB RPM packages updated, but the installed (or embedded) bootloader is never updated automatically. It's a good idea to update it between Fedora release versions.
  • 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 RPM packages. By reinstalling those packages, the bootloaders are reinstalled to their proper location in /boot/efi/ on the EFI System volume.

Enabling serial console in GRUB 2

On Fedora 34 and later, you can enable serial console for usage on virtual environments. The following procedure explains how to achieve this goal.

# grubby --args="systemd.journald.forward_to_console=1 console=ttyS0,38400 console=tty1" --update-kernel=/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.

# grubby --set-default=/boot/vmlinuz-5.11.16-300.fc34.x86_64

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.