x86-bare-metal-examples/grub/README.adoc

= GRUB
:idprefix:
:idseparator: -
:sectanchors:
:sectlinks:
:sectnumlevels: 6
:sectnums:
:toc: macro
:toclevels: 6
:toc-title:

toc::[]

== Symlinks

This directory relies on the following symlinks to make directory structure modifiable in the future:

. mbrs: directory that contains the Makefile for `bios_hello_world.img` and other MBRs
. bios_hello_world.img.sym: boot sector that says hello world with BIOS
+
The `.sym` extension must be used because otherwise this symlink would be gitignored.

=== Introduction

If you have a Linux dual boot, and you see a menu prompting you to choose the OS, there is a good chance that this is GRUB, since it is the most popular bootloader today.

It allows you basic graphical interaction even before starting any OS.

Everything is configurable, from the menu entries to the background image. This is why Ubuntu's GRUB is purple.

The main job for GRUB userspace utilities such as `grub-install` and `update-grub` is to look at the input configuration files, interpret them and write the output configuration information to the correct locations on the hard disk so that they can be found at boot time.

GRUB has knowledge about filesystems, and is able to read configuration files and the disk image from it.

=== GRUB versions

GRUB has 2 versions

* 0.97, usually known just as GRUB, or Legacy GRUB.
* GRUB >= 2, which is backwards incompatible, and has more features.
+
GRUB 2 is still beta.

Some distros like Ubuntu have already adopted GRUB 2, while others are still using GRUB for stability concerns.

Determine your GRUB version with:

....
grub-install -v
....

Here we discuss GRUB 2.

=== Supported architectures

x86 is of course the primary... ARM was recently added in 2.0.2 it seems: https://wiki.linaro.org/LEG/Engineering/Kernel/GRUB

=== Configuration files

Input files:

* `/etc/grub.d/*`
* `/etc/default/grub`

Generated files and data after `sudo update-grub`:

* `/boot/grub/grub.cfg`
* MBR bootstrap code

==== /etc/default/grub

Shell script sourced by `grub-mkconfig`.

Can defined some variables which configure grub, but is otherwise an arbitrary shell script:

....
sudo vim /etc/default/grub
....

* `GRUB_DEFAULT`: default OS choice if cursor is not moved:
+
Starts from 0, the order is the same as shown at grub OS choice menu:
+
....
GRUB_DEFAULT=0
....
+
The order can be found on the generated `/boot/grub/grub.cfg`: you have to count the number of `menuentry` calls.
+
To select sub-menus, which are created with the `submenu` call on `/boot/grub/grub.cfg`, use:
+
....
GRUB_DEFAULT='0>1'
....
+
You can also use OS name instead of a number, e.g.:
+
....
GRUB_DEFAULT='Ubuntu'
....
+
For a line from `/boot/grub/grub.cfg` of type:
+
....
menuentry 'Ubuntu'
....
* `GRUB_TIMEOUT` : time before auto OS choice in seconds
* `GRUB_CMDLINE_LINUX_DEFAULT`: space separated list of Kernel boot parameters.
+
Sample:
+
....
GRUB_CMDLINE_LINUX_DEFAULT="quiet splash"
....
+
The parameters will not be discussed here.
+
Those parameters can also be edited from the boot menu for a single session by selecting the partition and clicking `e`.
** useless options on by default on Ubuntu 12.04 which you should really remove because they hide kernel state and potentially useful debug information:
*** `quiet`: suppress kernel messages.
*** `splash`: shows nice and useless image while the kernel is booting. On by default on Ubuntu 12.04. Remove this useless option,

==== /etc/grub.d/

Contains executables.

Each one is called in alphabetical order, and its stdout is used by GRUB.

A common choice for custom scripts in Ubuntu 14.04 is `40_custom`.

Create a menu entry:

....
#!/bin/sh -e
echo "stdout"
echo "stderr" >&2
cat << EOF
menuentry "menuentry title" {
set root=(hd0,1)
-- boot parameters --
}
EOF
....

You will see `stdout` when running `update-grub`. stderr is ignored.

`set root=(hd0,1)` specifies the partition, here `sda1`. `hd0` means first device, `1` means first partition. Yes, one if 0 based, and the other is 1 based.

`-- boot parameters --` depends on your OS.

Linux example:

....
linux /boot/vmlinuz
initrd /boot/initrd.img
....

Windows example:

....
chainloader (hdX,Y)+1
....

It is common to add one OS menu entry per file so that it is easy to change their order (just change alphabetical order).

=== Configuration scripts

==== update-grub

Just calls:

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

==== grub-mkconfig

Called by `update-grub` as:

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

Important actions:

* sources `/etc/default/grub`
* sources `/etc/default/grub.d/*.cfg`, which may override options in `/etc/default/grub`
* runs scripts under `/etc/grub.d`, which use the variables defined in the above sourced files

==== grub-install

Given a `/boot/grub/grub.cfg` in some filesystem, install GRUB to some hard disk.

Interpret input configuration files and update the MBR on the given disk:

....
sudo grub-install /dev/sda
....

If for example you install a new Linux distro, and you want to restore your old distro's GRUB configuration, you must log into the old distro and do `grub-install`, therefore telling your system via the MBR to use the installation parameters given on the old distro.

TODO get a minimal example working using a minimal kernel from: https://github.com/cirosantilli/x86-bare-metal-examples:

....
img="a.img"
dd if=/dev/zero of="$img" bs=1024 count=64
loop="$(sudo losetup -f --show "$img")"
printf 'o\nn\np\n1\n\n\nw\n' | sudo fdisk "$loop"

sudo kpartx -av "$img"
ls /dev/mapper

echo y | mke2fs -t ext4
sudo mount "/dev/mapper/${loop}p1" d

# Need a new Ubuntu.
#sudo losetup --show -f -P test.img

sudo grub-install /dev/loop0

mkdir -p d
mount /dev/loop0 d

#grub-install --boot-directory=d /dev/sdb
....

==== grub-mkrescue

Generates a rescue image from a root filesystem.

Example: https://github.com/cirosantilli/x86-bare-metal-examples/blob/48614b45fa6edeb97adbaad942595a4c25216113/multiboot/hello-world/Makefile#L6

You can then burn the output to an USB or CD

Vs `grub-install`: generates a live boot USB / CD, but does not use the USB as a filesystem.

Easier to setup however.

==== os_prober

Looks for several OS and adds them automatically to GRUB menu.

Recognizes Linux and Windows.

TODO how to use it

=== rescue prompt

If things fail really badly, you may be put on a `rescue >` prompt.

You are likely better off reinstalling things correctly in practice. But here go a few commands you can use from there.

https://www.linux.com/learn/tutorials/776643-how-to-rescue-a-non-booting-grub-2-on-linux/

* `ls`
* `ls (hd0,1)/`
* `cat (hd0,1)/etc/issue`
* Boot:
+
....
set root=(hd0,1)
linux /boot/vmlinuz-3.13.0-29-generic root=/dev/sda1
initrd /boot/initrd.img-3.13.0-29-generic
boot
....

==== timeout

No timeout on boot menu:

....
set timeout=0
....

==== default

Default no Nth (zero based) entry of boot menu:

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

==== menuentry

The following commands can be used inside a menu entry, e.g.:

....
menuentry "main" {
}
....

Point to a multiboot file:

....
multiboot /boot/main.elf
....

E.g.: https://github.com/cirosantilli/x86-bare-metal-examples/blob/48614b45fa6edeb97adbaad942595a4c25216113/multiboot/hello-world/iso/boot/grub/grub.cfg

Load a linux kernel with a given root filesystem:

....
linux /boot/bzImage
initrd /boot/rootfs.cpio.gz
....

You can pass kernel command line arguments with:

....
linux /boot/bzImage BOOT_IMAGE=/boot/vmlinuz-3.19.0-28-generic root=UUID=2a49bac4-b9dd-466d-9c0c-c432aa4ca086 ro loop.max_part=15
....

You can then check that they've appeared under `cat /proc/cmdline`.

=== Alternatives

* `syslinux`: Linux specific. Used by default by the kernel, e.g. on 4.2 `make isoimage`.
* LILO: old popular bootloader, largely replaced by GRUB now.

=== Legacy

Documentation: http://www.gnu.org/software/grub/manual/legacy/grub.html

==== kernel

Directive used to boot _both_ multiboot and Linux.

Got split up more or less into `multiboot` and `linux` directives.

=== Bibliography

* https://www.gnu.org/software/grub/grub-documentation.html
* http://www.dedoimedo.com/computers/grub-2.html
+
Great configuration tutorial.