GRUB: Difference between revisions

{{TutorialTone}}

'''GRUB''' is the GNU project's bootloader. The current version 2 series have a more complete feature set than [[GRUB Legacy|GRUB 0.97]] (commonly referred to as "GRUB Legacy").

== History ==

GRUB version 2 started its life as the [http://www.nongnu.org/pupa/ 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 use of the new bootloader instead of GRUB Legacy.

== Features ==

* Basic scripting support

* GUI (better bootsplash support, custom colors, custom themes, ...)

* Internationalization

* Rescue mode

A complete list of features can be found on the GNU mailing lists [https://lists.gnu.org/archive/html/grub-devel/2012-06/msg00093.html]

== Using GRUB to boot your OS==

Complete example code for booting your operating system with GRUB can be found in the [[Bare_Bones#Booting_the_Operating_System|Bare Bones tutorial]]. The general idea is that you want to create a file that has [[Multiboot#Header_Format|Multiboot header]] which GRUB can use to identity your program as a kernel and boot it.

== Upgrading from GRUB Legacy ==

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

 

Since modern GRUB 2 is very different from GRUB Legacy, the directions for getting your kernel up and running are different. Modern GRUB 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 GRUB 2 image (assuming you have GRUB 2 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.

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" {

}

grub-mkrescue depends on program '''xorriso''' with version '''0.5.6 or higher'''.

 

GNU xorriso can be used where it gets built, without further installation:

grub-mkrescue --xorriso=/...full.path.../xorriso/xorriso -o bootable.iso iso

=== Floppy instructions ===

<syntaxhighlight lang="bash">

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

</syntaxhighlight>

==== Explanation ====

Let's go through those <tt>grub-mkimage</tt> options:

{| {{wikitable}}

|-

| '''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 <tt>/boot/grub</tt> folder of your disk image, and be named '''grub.cfg'''):

<syntaxhighlight lang="bash">

set timeout=15

}

</syntaxhighlight>

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.

'''Warning: the following command uses superuser privileges (sudo). E.g. just typing the wrong character for X could cause severe troubles for your current system'''

<pre>sudo mkfs.vfat -F 32 -n YourLabel -I /dev/sdX</pre> (where sdX is your USB device)

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

 

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

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

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

=== Disk image instructions ===

For a more detailed tutorial, see [[Bootable_Disk|bootable disk]] creation.

67108864 bytes (67 MB) copied, 0.349436 s, 192 MB/s

</pre>

2. Create new DOS partition table with bootable entry for your filesystem

<pre>$ fdisk disk.img</pre>

Syncing disks.

</pre>

3. Setup two loop devices. One will be used for writing GRUB and its additional codes to MBR, and the second will be used for mounting filesystem of your operating system.

<pre>

<pre>$ sudo mke2fs /dev/loop1</pre>

<pre>$ sudo mkdosfs -F32 -f 2 /dev/loop1</pre>

5. Mount your newly formatted partition

<pre>$ sudo mount /dev/loop1 /mnt</pre>

 

Don't forget to flush the filesystem buffers when manipulating with files on mounted disk image. On a Unix-like system, this can be simply done by executing the <tt>sync</tt> program in your shell.

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

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

</syntaxhighlight>

2. For an explaination on calculating the CHS values from the LBA / size see [[Floppy_Disk_Controller#CHS]]

Since we have a 80MB disk, the CHS values are 78, 32 and 63 respectively.

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

 

fdisk:*1> quit

</syntaxhighlight>

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=fs.img bs=512 skip=2047

</syntaxhighlight>

5. Because we're on OS X, we need to attach the disk image first, without actually mounting it.

<syntaxhighlight lang="bash">

hdiutil attach -nomount fs.img

</syntaxhighlight>

6. Use 'diskutil list' to find out which device your image is, use that below.

 

newfs_msdos -F 32 /dev/diskX

</syntaxhighlight>

8. Now you'll want to unmount it, then recombine the two images, then install GRUB.

<syntaxhighlight lang="bash">

Installation finished. No error reported.

</syntaxhighlight>

And there it is! You know have a disk.img, that will have GRUB 2 installed, ready to go. It should be mountable in OS X 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 GRUB 2 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 ==

 

When your kernel gets control, the machine state is defined as follows: [http://www.gnu.org/software/grub/manual/multiboot/html_node/Machine-state.html 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:

{{quote|The primary requirement for GRUB is that it be compliant with the ''Multiboot Specification''.}}

But the Multiboot header as used by older versions of GRUB 2 (field is present in GRUB 1.99 and newer) did ''not'' include the ''header_length'' field that is specified in the [http://nongnu.askapache.com/grub/phcoder/multiboot.pdf Multiboot 1.6 specification].

 

GRUB 2 also supports the old [https://www.gnu.org/software/grub/manual/multiboot/multiboot.html Multiboot 0.6.96 specification]. It is possible to include both headers.

== Installing GRUB 2 on OS X ==

The installation of GRUB 2 on OS X is a little tricky. The latest released version 2.00 (as of 7th of October, 2014) doesn't seem to work with any configuration. The developer team fixed this in the newer revisions.

 

'''1.''' Clone the developer version of the sources:

(This was tested on revision: 77063f4cb672f423272db7e21ca448cf3de98dcf)

 

 

'''4.''' Create a seperate build directory, switch to it, and run GRUB's configure script ''(insert your target-specific tools!)'':

../grub/configure --disable-werror TARGET_CC=i386-elf-gcc TARGET_OBJCOPY=i386-elf-objcopy \

TARGET_STRIP=i386-elf-strip TARGET_NM=i386-elf-nm TARGET_RANLIB=i386-elf-ranlib --target=i386-elf

'''5.''' Run "make" and "make install"

 

Now you have a working GRUB 2 that has the required files to build an image that boots on i386 platforms.

==GRUB for UEFI==

===Compiling GRUB===

../grub-2.02~rc2/configure --prefix="$HOME/opt/grub" --target=x86_64 --with-platform=efi

</syntaxhighlight>

After completing the build, GRUB refused to do anything as it was missing a font file. To fix this, run

<syntaxhighlight lang="text">

bin/grub-mkfont -o share/grub/unicode.pf2 /usr/share/fonts/truetype/unifont/unifont.ttf

</syntaxhighlight>

GRUB might warn you about share/locale/ missing. To solution is to create the missing directory.

===Building a GRUB UEFI binary (BOOTX64.EFI)===

This method builds a standalone GRUB binary you can copy to a FAT partition. However, note that some UEFI implementations assume that it is located at <code>/EFI/BOOT/BOOTX64.EFI</code> for x86_64 platforms.

bin/grub-mkstandalone -O x86_64-efi -o BOOTX64.EFI "boot/grub/grub.cfg=build/grub.cfg"

</syntaxhighlight>

===Blessing the binary on macOS===

Macs require bootable binaries to be 'blessed' by a utility:

bless --verbose --folder=/Volumes/EFI --file=/Volumes/EFI/EFI/BOOT/BOOTX64.EFI --setBoot

</syntaxhighlight>

== See Also ==

=== Articles ===

* [[GRUB Legacy]]

* [[Bootable El-Torito CD with GRUB Legacy]]

* [[BOOTBOOT]] an alternative boot loader with exactly the opposite philosophy as GRUB's

* [[Limine]] another boot loader supporting Multiboot

=== External Links ===

* [http://www.gnu.org/software/grub/ GRUB 2 Homepage]

[[Category:Bootloaders]]

[[Category:GRUB]]

[[Category:UEFI]]

[[de:Grand_Unified_Bootloader]]