quick-docs/en-US/grub2.adoc

= The GRUB2 Bootloader

[[introduction]]
== Introduction
*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-grub-2-on-a-bios-system]]
== 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*: 

. Install *GRUB2* software using the *dnf* package manager
+
----
$ sudo dnf install grub2
----

[[Installing-grub-2-on-the-hard-disk-bios]]
== 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:

. in the master boot record (MBR) of the hard disk
. 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 xref:installing-grub-2-on-a-system[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.

.Procedure

. List devices available on the system.
+
----
$ lsblk
----  

. Identify the primary hard disk. Usually, it is the `sda` device.

. Install *GRUB2* in the MBR of the primary hard disk.
+
----
$ sudo grub2-install /dev/sda
----

. 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-grub-2-configuration-on-uefi-system]]
== 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]]
=== 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

. Learn how to create partitions using `gdisk`.

.Procedure

. List available block devices to find a place to create your ESP.
+
----
$ lsblk
----

. Create at least a 128 MiB disk partition using a GPT label on the primary hard disk.
+
----
$ sudo gdisk /dev/sda
----

. Format the partition with the _FAT32_ file system.
+
----
$ sudo mkfs.vfat /dev/sda1
----

. Mount the partition to `/boot/efi` mount point. 
+
----
$ sudo mount /dev/sda1 /boot/efi
----


[[install-the-bootloader-files]]
=== Install the bootloader files

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

.Before you start

. Mount the `/boot/efi` mount point. See xref:create-an-esp[Create an ESP] to create it.

.Procedure

. Install the necessary packages.
+
----
dnf install grub2-efi grub2-efi-modules shim
----

. 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-grub-2-configuration]]
=== 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]]
=== Solve problems with UEFI bootloader.


[[adding-the-boot-menu-entries]]
==== 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:
> cd EFI\BOOT
> 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-grub-2-menu]]
==== 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 link:http://www.gnu.org/software/grub/manual/grub.html#Multi_002dboot-manual-config[GRUB manual] to solve issues with booting secondary operating systems.

[[setting-default-entry]]
==== 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

. Open `/etc/default/grub` and make sure these lines exist in the file.
+
----
GRUB_DEFAULT=saved
GRUB_SAVEDEFAULT=false
----

. Apply the changes to `grub.cfg` by running.
+
----
$sudo grub2-mkconfig -o /boot/grub2/grub.cfg
----

.Procedure

. List all possible menu entries.
+
----
$sudo grep -P "submenu|^menuentry" /boot/grub2/grub.cfg | cut -d "'" -f2
----

. Set the desired default menu entry
+
----
$sudo grub2-set-default "<submenu title><menu entry title>"
----

. 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-scenario]]
== Additional Scenarios

[[restoring-bootloader-using-live-disk]]
=== 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

. Get the Fedora Live ISO from link:https://download.fedoraproject.org/pub/fedora/linux/releases/27/Workstation/x86_64/iso/Fedora-Workstation-Live-x86_64-27-1.6.iso[getfedora.org].
. Prepare a bootable device using the downloaded ISO, either a CD or a USB.

.Procedure

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

. Open the terminal.

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

. Create the mount point for the root partition.
+
----
$ sudo mkdir -p /mnt/root
---- 

. Mount the root partition on the mount point.
+
----
$ sudo mount /dev/mapper/fedora-root /mnt/root
----

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

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

. Change your filesystem into the one mounted under `/mnt/root`.
+
----
$ sudo chroot /mnt/root
----

. Reinstall *GRUB2* into the MBR of the primary hard disk.
+
----
$ sudo grub2-install --no-floppy --recheck /dev/sda
----

. Recreate the *GRUB2* configuration files.
+
----
$ sudo grub2-mkconfig -o /boot/grub2/grub.cfg
----

. Exit this temporary root filesystem.
+
----
$ exit
----

. Your bootloader should be now restored. Reboot your computer to boot into your normal system.
+
----
$ sudo systemctl reboot
----

[[using-the-grub-2-boot-prompt]]
==== 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:

. Load the XFS and LVM modules
+
----
insmod xfs
insmod lvm
----

. List the drives which *GRUB2* sees:
+
----
grub2> ls
----

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

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

. Set the root partition.
+
----
grub> set root=(hd0,3)
----

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

. Set the desired `initrd`.
+
----
grub> initrd (hd0,1)/initramfs-3.0.0-1.fc16.i686.img
# NOTE : change the numbers to match your system
----

. Boot with the selected settings.
+
----
grub> boot
----

. When the system starts, open a terminal.

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

. 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-with-configfile-on-different-partition]]
=== 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:

.Procedure

. Load necessary modules to read the partitions.
+
----
insmod part_msdos
insmod xfs
insmod lvm
----

. Set the root partition.
+
----
set root='hd0,msdos1'
----

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

[[absent-floppy-disk]]
=== 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]]
=== 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.

.Procedure

. Create the `/etc/grub.d/01_users` file.
+
----
cat << EOF
set superusers="root"
export superusers
password root secret
EOF
----

. 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
https://help.ubuntu.com/community/Grub2/Passwords[Ubuntu Help: GRUB2
Passwords].

[NOTE]
====
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]]
=== 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-grub]]
=== Enabling Serial Console in GRUB2

To enable Serial console in grub: 

. 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_TERMINAL=serial
GRUB_SERIAL_COMMAND="serial --speed=115200 --unit=0 --word=8 --parity=no --stop=1"
----

. Re-generate the GRUB2 config file.
+
`grub2-mkconfig -o /boot/grub2/grub.cfg`

[[further-reading]]
== Further Reading

* http://www.gnu.org/software/grub/manual/grub.html
* Features/Grub2
* Anaconda/Features/Grub2Migration
'''

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.