GRUB

This page is a work in progress.

This page may thus be incomplete. Its content may be changed in the near future.

GRUB 2 is the GNU Project's next-generation bootloader. It has a more complete feature set than GRUB 0.97 (commonly referred to as "GRUB Legacy"). Still, all things considered, GRUB Legacy is more mature and most of the available documentation is for GRUB Legacy (hence the brief page).

History

GRUB 2 started its life as the PUPA (note the pun) research project and was rewritten from the ground up. Since then GRUB 2 (actually at time of update 1.97) has grown more stable and even hobby operating systems are starting to make use of the new bootloader instead of GRUB Legacy.

Features

• Basic scripting support
• GUI (better bootsplash support, custom colors, custom themes, ...)
• Memory management
• Cleaner design
• Better portability
• Internationalization
• Rescue mode

Upgrading from GRUB Legacy

WARNING: These steps have not been tested very well yet. Use at your own risk!

Since GRUB 2 is very different from GRUB Legacy, the directions for getting your kernel up and running are different. GRUB 2 differs from GRUB Legacy in that to implement all but the most basic functionality, the user must load so-called "modules": little bits of code that add components (e.g. a different file system or a VGA font). This section gives you an overview of the process you need to go through when you want to have GRUB 2 load your kernel. It's actually rather simple to create a GRUB2 image (assuming you have GRUB2 either built or installed):

ISO instructions

There have been a lot of tries to make Grub2 work good with ISOs, but mostly failed. The only combination of commands that seems to work is the following.

First create a directory tree called "iso", where you put your kernel (and any other needed files) somewhere. Then in the boot/grub subdirectory create the grub.cfg file which is your configuration.

Now run:

grub-mkrescue -o bootable.iso iso

Be sure that your grub.cfg is syntactically correct. A common mistake is to put the menuentry brace on newline. It must be like:

menuentry "Place your os name here" {
}

Floppy instructions

mkdir tmp
grub-mkimage -p /boot -o tmp/core.img multiboot sh fat # This should work.. I hope :D

Explanation

Let's go through those grub-mkimage options:

-p	By default, GRUB 2 looks in /boot/grub for its configuration file. -p changes this.
-o	Like so many other GNU tools, grub-mkimage uses -o to set the output file. By default, it's stdout.
multiboot	This module is required to load multiboot-compliant kernels.
biosdisk	This module is required for GRUB 2 to be able to boot from a LiveCD.
iso9660/fat	Allows GRUB 2 to look on the image for different files.
sh	This module allows GRUB to parse the configuration file.

GRUB 2, like GRUB Legacy, needs a configuration file to find your kernel. In GRUB Legacy it's called menu.lst, but in GRUB2, it's called grub.cfg. The syntax for the configuration file is also a bit different.

Here's a sample configuration file (NOTE: This file should be placed into the /boot/grub folder of your disk image, and be named grub.cfg):

set timeout=15
set default=0 # Set the default menu entry

menuentry "OS Name" {
   multiboot /boot/kernel-file   # The multiboot command replaces the kernel command
   boot
}

That's basically it. Copy these files to a disk image, pop it in an emulator, and you're done!

Double check that you put the brace on the same line of "menuentry". It can't be on a new line. This is not C.

USB instructions

Fewer and fewer systems have a floppy disc controller these days, but USB ports are found on all. Modern BIOSes can boot from a USB device, usually by pressing some special key during startup.

Putting GRUB 2 on a bootable USB storage device is a nice way to experiment with your OS on different computers. Here's how you set this up (using Linux):

1. Create a FAT32-formatted USB disk, without partitions:

sudo mkfs.vfat -F 32 -n YourLabel -I /dev/sdX

(where sdX is your USB device)

The "-I" option is needed because we are targeting a partition-less device

2. Remove your USB device, and plug it back in. The auto-mounter on your OS should detect it now.

3. Invoke grub-install (on some systems this command is called grub2-install, located under /usr/sbin or /usr/local/sbin)

sudo grub-install --root-directory=/media/YourLabel --no-floppy --recheck --force /dev/sdX

It is important to do this as root (or sudo), else the generated device.map listing available boot devices can be empty. /media/YourLabel is the mount point under Fedora 16, it may be different for other distributions.

4. Create a grub.cfg for your kernel (see above), and copy it to your new bootable USB disk

HDD Image Instructions for OS X users

It might be useful to create an image file for a HDD; The following instructions help you create a HDD with an MBR partition map. Based on information from <palk> on #osdev, it is slightly more complicated to create a HDD image than you'd expect.

This information might not be applicable to Linux users, who will most probably want to use a loopback device. This is for developers on OSX, which doesn't have a loopback device and has a finicky image mounter.

1. First, create a blank, raw image with DD, with the required size. Here, I'll make a 80MB image -- 163840 sectors of 512 bytes.

dd if=/dev/zero of=disk.img count=163840 bs=512

2. Next, calculate the CHS values for the disk and have them at hand. TODO: Explain this.

   Here, it's a 80MB disk, so the CHS values are 78, 32 and 63 respectively.

3. Fire up FDISK (or your tool of choice) -- I'm using the OSX version here, so commands may differ. The concept is essentially identical.

What will show on your screen (in OSX anyway) is on the left, what you enter is on the right.

fdisk -e disk.img


The signature for this MBR is invalid.
Would you like to initialize the partition table? [y]            Yes
fdisk:*1>                                                                         disk
Disk: disk.img	geometry: 650/4/63 [16340 sectors]
Change disk geometry? [n]                                               No



fdisk:*1>                                                                          edit 1                - Edit the first partition
Partition id ('0' to disable)  [0 - FF]: [B] (? for help)            0B                     - Windows 95 FAT32
Do you wish to edit in CHS mode? [n]                               No                     - No.
Partition offset [0 - 163840]: [63]                                    2047	                 - This leaves enough space (approx 1MB) for GRUB's modules
Partition size [1 - 161793]: [161793]                               <Enter>            - Just leave it as default


fdisk:*1>                                                                          write                - Write the changes
fdisk:*1>                                                                          quit                  - Quit FDisk

4. Now that the MBR Partition Table is initialised, you'll want to make a Filesystem on the disk. But first.

   Here, we separate the MBR bit, and the actual FS bit.

dd if=disk.img of=mbr.img bs=512 count=2047							- Make the MBR's image -- this will be the sector offset you put in FDisk
dd if=disk.img of=fs.img bs=512 skip=2047								- Skip 2047 sectors, which is the size of the MBR sector.

5. Now, make a FAT12/16/32 filesystem on the FS.img disk. Note that I booted up an Ubuntu VM to do this, but if you find the command to make a FAT32 FS in OSX, feel free to edit.

   Remember, use FS.img -- not disk.img

mkfs.vfat -F 32 fs.img

6. Finally, here comes the crucial part -- Installing GRUB2.

cat mbr.img fs.img > disk.img											- This makes a new disk.img (replacing the old one) with the FAT32 filesystem

grub-install --modules="part_msdos biosdisk fat multiboot configfile"			- This installs GRUB2 with the appropriate modules.
Installation finished. No error reported.

And there it is! You know have a disk.img, that will have GRUB2 installed, ready to go. It should be mountable in OSX simply by double clicking (or with the mount command). Enjoy!

Additional useful options

Whatever device you are using, you may want to have a PC partition table and create a partition you format in one of the filesystems supported by GRUB. If you do, be sure to add the following option the grub-install arguments:

--modules="part_msdos"

In general, if GRUB2 happens to fail to do what you want and you suspect that it needs some missing functionality, just try to add a module name you believe has the functionality you need to the --modules argument. The module files generally are in /boot/grub/i386-pc/.

Multiboot

Some versions of GRUB 2 like to put multiboot modules in relatively high physical memory addresses, in contrast to GRUB-legacy which loaded them into low memory. Be careful when making your kernel work with GRUB 2 that it is not making any assumptions about where the multiboot modules will appear.

When your kernel gets control, the machine state is defined as follows: Multiboot machine state. Your code should have minimal dependency on this initial state; for example, define your own GDT instead of relying on the GDT setup by GRUB.

Header

As the GRUB 2 manual puts it:

The primary requirement for GRUB is that it be compliant with the Multiboot Specification.

But the Multiboot header as used by most versions of GRUB 2 (including GRUB 1.98-2) does not include the header_length field that is specified in the Multiboot 1.6 specification.

GRUB 2 also supports the old Multiboot 0.6.96 specification. It is possible to include both headers.

See Also

Articles

• GRUB Legacy
• Bootable El-Torito CD with GRUB Legacy
• Multiboot

External Links

• GRUB 2 Homepage
• GRUB 2 Wiki