= GRUB 2

'''

[NOTE]
======

This page was automatically converted from https://fedoraproject.org/wiki/GRUB_2

It is probably

* Badly formatted
* Missing graphics and tables that do not covert well from mediawiki
* Out-of-date
* In need of other love

Please fix it, remove this notice, and then add to `_topic_map.yml`

Pull requests accepted at https://pagure.io/fedora-docs/fedora-howto

Once that is live, go to the original wiki page and add an `{{old}}`
tag, followed by a note like

....
{{admon/note|This page has a new home!|
This wiki page is no longer maintained. Please find the up-to-date
version at: https://docs.fedoraproject.org/whatever-the-url
}}
....

======

'''


[[introduction]]
Introduction
------------

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.

[[tasks-common-issues]]
Tasks / Common issues
---------------------

[[updating-grub-2-configuration-on-bios-systems]]
Updating GRUB 2 configuration on BIOS systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The grub2 packages contain commands for installing a bootloader and for
creating a bootloader configuration file.

grub2-install will install the bootloader - usually in the MBR, in free
unpartioned space, and as files in /boot. The bootloader is installed
with something like:

....
grub2-install /dev/sda
....

grub2-mkconfig will create a new configuration based on the currently
running system, what is found in /boot, what is set in
/etc/default/grub, and the customizable scripts in /etc/grub.d/ . A new
configuration file is created with:

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

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.

The Fedora installer, anaconda, will run these grub2 commands and there
is usually no reason to run them manually.

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. (Other distributions, in particular Debian and Debian-derived
distributions provide a software patch that adds an command which is
neither included nor needed in Fedora.) Manual changes might however be
overwritten with grub2-mkconfig next time the system is upgraded with
anaconda. Some customizations can be placed in /etc/grub.d/40_custom or
/boot/grub2/custom.cfg and will survive running grub2-mkconfig.

[[updating-grub-2-configuration-on-uefi-systems]]
Updating GRUB 2 configuration on UEFI systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To install or fix GRUB 2 on a UEFI system on Fedora 18 or newer, you
need to do four things:

[[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. In `gdisk`, it looks something like this:

....
Number  Start (sector)    End (sector)  Size       Code  Name
   1            2048          264191   128.0 MiB   EF00  EFI System
....

That partition should be formatted as FAT. If in doubt, FAT32 is a good
dialect of FAT to choose.

Fedora expects this partition to be mounted at `/boot/efi`.

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

If you don't already have the relevant packages installed, do for Fedora
22 and later versions with link:dnf[DNF] or with YUM for older Fedora
releases:

....
dnf install grub2-efi grub2-efi-modules shim
yum install grub2-efi grub2-efi-modules shim
....

If you do, then try:

....
dnf reinstall grub2-efi grub2-efi-modules shim
yum reinstall grub2-efi grub2-efi-modules shim
....

instead.

Make sure that /boot/efi is mounted when you do this.

This installs the signed shim and the GRUB 2 binary.

[[create-a-grub-2-configuration]]
Create a GRUB 2 configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Under EFI, GRUB 2 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 (i.e. `/boot/efi/EFI/fedora/grub.cfg`).

If you already have a grub 2 EFI config file, you should be okay. If
not, grub2-mkconfig can help, but your mileage may vary.

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

[[create-a-boot-menu-entry]]
Create a boot menu entry
^^^^^^^^^^^^^^^^^^^^^^^^

TL;DR: This should happen automatically. If it doesn't, read on.

When you power on your system, your firmware will look for EFI variables
that tell it how to boot. If you're already booted in EFI mode and EFI
runtime services are working correctly, you can configure your boot menu
with `efibootmgr`. If not, you'll 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, *if such
entries do not already appear to exist*. `shim` provides a `BOOT.CSV`
file that will add an entry for `grub2-efi` for you. So just using the
EFI Shell to invoke `fallback.efi` should do the trick. 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 GRUB 2 menu
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

grub2-mkconfig will add entries for other operating systems it can find.
That will be done based on the output of the os-prober tool.

That might however not work so well, especially not for booting other
Linux operating systems, and especially not on UEFI systems. See
http://www.gnu.org/software/grub/manual/grub.html#Multi_002dboot-manual-config
.

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

Open `/etc/default/grub` and ensure this line exists:

....
GRUB_DEFAULT=saved
....

and ensure this line not exists:

....
GRUB_SAVEDEFAULT=true
....

or ensure this line exists:

....
GRUB_SAVEDEFAULT=false
....

Apply the change to `grub.cfg` by running:

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

Now list all possible menu entries

....
grep -P "submenu|^menuentry" /boot/grub2/grub.cfg | cut -d "'" -f2
....

Now set the desired default menu entry

....
grub2-set-default "<submenu title><menu entry title>"
....

Verify the default menu entry

....
grub2-editenv list
....

If you understand the risks involved and still want to directly modify
/boot/grub2/grub.cfg, here's how you can do it:

Edit /boot/grub2/grub.cfg, and change the line

....
set default="0" 
....

to

....
set default="5"
....

[[encountering-the-dreaded-grub-2-boot-prompt]]
Encountering the dreaded GRUB 2 boot prompt
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

\0. Load the XFS and LVM modules

....
insmod xfs
insmod lvm
....

\1. List the drives which GRUB 2 sees:

....
grub2> ls
....

\2. The output for a dos partition table /dev/sda with three partitons
will look something like this:

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

\3. While the output for a gpt partition table /dev/sda with four
partitions will look something like this:

....
(hd0) (hd0,gpt4) (hd0,gpt3)  (hd0,gpt2) (hd0,gpt1)
....

\4. With this information you can now probe each partition of the drive
and locate your vmlinuz and initramfs files:

....
ls (hd0,1)/ 
....

Will list the files on /dev/sda1. If this partition contains /boot, the
output will show the full name of vmlinuz and initramfs.

\5. Armed with the location and full name of vmlinuz and initramfs you
can now boot your system.

5a. Declare your root partition:

....
grub> set root=(hd0,3)
....

5b. Declare the kernel you wish to use:

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

5c. Declare the initrd to use:

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

5d. Instruct GRUB 2 to boot the chosen files:

....
grub> boot
....

\6. After boot, open a terminal.

\7. Issue the grub2-mkconfig command to re-create the grub.cfg file
grub2 needed to boot your system:

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

\8. Issue the grub2-install command to install grub2 to your hard drive
and make use of your config:

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

[[additional-scenario]]
Additional Scenario
~~~~~~~~~~~~~~~~~~~

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 grub rescue shell might become useful to know:

....
insmod part_msdos
insmod xfs
insmod lvm
set root='hd0,msdos1'
configfile /grub2/grub.cfg
....

Where, *hd0,msdos1* is the pertinent _boot_ partition, which holds the
grub.cfg file.

[[other-grub-2-issues]]
Other GRUB 2 issues
~~~~~~~~~~~~~~~~~~~

''' Absent Floppy Disk ''': It has been reported by some users that GRUB
2 may fail to install on a partition's boot sector if the computer
floppy controller is activated in BIOS without an actual floppy disk
drive being present. A possible workaround is to run (post OS install)
from rescue mode:

....
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 GRUB2's interactive edit mode *but* you
do not want to require users to enter a password to do a plain, simple,
ordinary boot, create /etc/grub.d/01_users with the following lines:

....
cat << EOF
set superusers="root"
export superusers
password root secret
EOF
....

To apply your changes run:

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

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

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

[[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 right variable from the description
above in /etc/default/grub

[[enable-serial-console-in-grub]]
Enable Serial Console in Grub
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To enable Serial console in grub add the following entry's to
/etc/default/grub

( Adjust baudrate/parity/bits/flow control 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"
....

And re-generate grub

`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/fedora-howto.
