Overview
********

Briefly, a boot loader is the first software program that runs when a computer starts.  It is responsible for loading and transferring control to an operating system kernel software (such as the Linux or GNU Hurd kernel).  The kernel, in turn, initializes the rest of the operating system (e.g. a GNU system).

GNU GRUB is a very powerful boot loader, which can load a wide variety of free operating systems, as well as proprietary operating systems with chain-loading (chain-load is the mechanism for loading unsupported operating systems by loading another boot loader. It is typically used for loading DOS or Windows.).

One of the important features in GRUB is flexibility; GRUB understands filesystems and kernel executable formats, so you can load an arbitrary operating system the way you like, without recording the physical position of your kernel on the disk.

Thus you can load the kernel just by specifying its filename and the drive (and the partition) where the kernel resides. To let GRUB know the drive and the filename, you can either type in them manually via the command-line interface (see Command line), or use the nice menu interface (see Menu interface) through which you can easily select which OS it boots. To allow you to customize the menu, GRUB will load a preexisting configuration file (see Configuration). Note that you can not only enter the command-line interface whenever you like, but also you can edit specific menu entries prior to using them.

In the following chapters, you will learn how to specify a drive or a partition, and a file name (see Naming convention) to GRUB, how to install GRUB on your drive (see Installation), and how to boot your OSes (see Booting), step by step.

Naming convention
*****************

The device syntax used in GRUB is a wee bit different from what you may have seen before in your operating system(s), and you need to know it so that you can specify a drive/partition.

Look at the following examples and explanations:

     (fd0)

First of all, GRUB requires that the device name is enclosed with ( and ). The fd part means that it is a floppy disk. The number 0 is the drive number, which is counted from zero. This expression means that GRUB will use the whole floppy disk.

     (hd0,1)

Here, hd means it is a hard disk drive. The first integer 0 indicates the drive number, that is, the first hard disk, while the second integer, 1, indicates the partition number (or the PC slice number in the BSD terminology). Once again, please note that the partition numbers are counted from zero, not from one. This expression means the second partition of the first hard disk drive. In this case, GRUB uses one partition of the disk, instead of the whole disk.

     (hd0,4)

This specifies the first extended partition of the first hard disk drive. Note that the partition numbers for extended partitions are counted from 4, regardless of the actual number of primary partitions on your hard disk.

     (hd1,a)

This means the BSD a partition of the second hard disk. If you need to specify which PC slice number should be used, use something like this: (hd1,0,a). If the PC slice number is omitted, GRUB searches for the first PC slice which has a BSD a partition.

Of course, to actually access the disks or partitions with GRUB, you need to use the device specification in a command, like root (fd0) or unhide (hd0,2). To help you find out which number is a partition you want, the GRUB command-line (see Command line) options have argument completion. That means that, for example, you only need to type root (, followed by a TAB, and GRUB will display the list of drives, partitions, or filenames, so it should be quite easy to determine the name of your target partition, even with minimal knowledge of the syntax.

Note that GRUB does not distinguish IDE from SCSI - it simply counts the drive numbers from zero, regardless of their type. Normally, any IDE drive number is less than any SCSI drive number, although that is not true if you change the boot sequence by swapping IDE and SCSI drives in your BIOS.

Now the question is, how to specify a file? Again, see this example:

     (hd0,0)/vmlinuz

This specifies the file named vmlinuz, found on the first partition of the first hard disk drive. Note that the argument completion works with file names, too.

That was easy, admit it. Do read the next chapter, to find out how to actually install GRUB on your drive.

Installation
************

First, you need to have GRUB itself properly installed on your system, (see Obtaining and Building GRUB) either from the source tarball, or as a package for your OS.

To use GRUB, you need to install it on your drive. There are two ways of doing that - either using the grub shell (see Invoking the grub shell) on a UNIX-like OS, or by using the native Stage 2. These are quite similar, however, the shell might probe a wrong BIOS drive, so better be careful.

Also, if you install GRUB on a UNIX-like OS, please make sure that you have an emergency boot disk ready, so that you can rescue your computer if, by any chance, your hard drive becomes unusable (unbootable).

GRUB comes with boot images, which are normally installed in the /usr/share/grub/i386-pc directory. You need to copy the files stage1, stage2, and *stage1_5 to the directory /boot/grub.

Installing GRUB on a floppy
===========================

To create a GRUB boot floppy, you need to take the files stage1 and stage2 from /boot/grub directory, and write them to the first and the second block of the floppy disk, respectively.

     Caution: This procedure will destroy any data currently stored on the floppy.

On a UNIX like operating system, that is done with the following commands:

     # cd /boot/grub
     # dd if=stage1 of=/dev/fd0 bs=512 count=1
     # dd if=stage2 of=/dev/fd0 bs=512 seek=1

The device filename may be different. Consult the manual for your OS.

Installing GRUB on a hard disk
==============================

     Caution: Installing GRUB's stage1 in this manner will erase the normal boot-sector used by an OS.

GRUB can currently boot GNU Mach, Linux, FreeBSD, NetBSD, and OpenBSD directly, so using it on a boot sector should be okay. But generally, it would be a good idea to back up the first sector of the partition on which you are installing GRUB's stage1. This isn't as important if you are installing GRUB on the first sector of a hard disk, since it's easy to reinitialize it (e.g. by running FDISK /MBR from DOS).

If you decide to install GRUB in the native environment, which is definitely desirable, you'll either need to create the GRUB boot disk, and reboot your computer with it, or run the grub shell (see Invoking the grub shell) as the super-user (root).

Once started, GRUB will show the command-line interface (see Command line). First, set the GRUB's root device (Note that GRUB's root device doesn't necessarily mean your OS's root partition; if you need to specify a root partition for your OS, add the argument into the command kernel.) to the partition which has your GRUB images, like this:

     grub> root (hd0,0)

If you are not sure which partition actually holds these files, use the find command, like this:

     grub> find /boot/grub/stage1

This will search for the filename /boot/grub/stage1 and show the devices which contain the file.

Once you've set the root device correctly, run the command setup:

     grub> setup (hd0)

This command will install GRUB on the MBR (see MBR) in the first drive. If you want to install GRUB into the boot sector of a partition instead of the MBR, specify a partition into which you want to install GRUB:

     grub> setup (hd0,0)

If you install GRUB into a partition or a drive other than the first one, you must chain-load GRUB from another boot loader. Refer to the manual for the boot loader to know how to chain-load GRUB.

That's all: now you can boot GRUB without a GRUB floppy. See the next chapter to find out how to boot your operating systems from GRUB.

Booting
*******

For Multiboot-compliant kernels, GRUB can load them in a consistent way, but, for some free operating systems, you need to use some OS-specific magic.

How to boot operating systems
=============================

GRUB has two distinct boot methods. One of the two is to load an operating system directly, and the other is to chain-load another boot loader which then will load an operating system actually. Generally speaking, the former is desirable, because you don't need to install or maintain other boot loaders and GRUB is flexible enough to load an operating system from an arbitrary disk/partition. However, the latter is sometimes required, since GRUB doesn't support all the existing operating systems natively.

How to boot an OS directly by GRUB
----------------------------------

Multiboot (see Motivation (The Multiboot Specification)) is the native format supported by GRUB. For the sake of convenience, there are also support for Linux, FreeBSD, NetBSD and OpenBSD. If you want to boot other operating systems, you will have to chain-load them (see Chain-loading).

Generally, GRUB can boot any Multiboot-compliant OS in the following steps:

 1. Set GRUB's root device to the drive where the OS images are stored by the command root.

 2. Load the kernel image by the command kernel.

 3. If you need modules, load them with the command module or modulenounzip.

 4. Run the command boot.

Linux, FreeBSD, NetBSD and OpenBSD can be booted in a similar manner. You can load a kernel image by the command kernel and then run the command boot. If the kernel requires some parameters, just append the parameters to kernel, after the filename of the kernel. Also, please refer to OS-specific notes, for the information on your OS-specific issues.

Load another boot loader to boot unsupported operating systems
--------------------------------------------------------------

If you want to boot an unsupported operating system (e.g. Windows 95), chain-load a boot loader for the operating system. Normally, the boot loader is embedded in the boot sector of the partition on which the operating system is installed.

First, set GRUB's root device to the partition by the command rootnoverify:

     grub> rootnoverify (hd0,0)

Second, set the active flag in the partition by the command makeactive (This is not necessary for most of the modern operating systems.):

     grub> makeactive

Third, load the boot loader by the command chainloader:

     grub> chainloader +1

+1 indicates that GRUB should read one sector from the start of the partition. The complete description about this syntax can be found in Filesystem. If this succeeds, run the command boot.

However, DOS and Windows have a deficiency, so you might have to use more complicated instructions. See OS-specific notes, for more information.

Some caveats on OS-specific issues
==================================

Here, we describe some caveats on several operating systems.

GNU/Hurd
--------

Since GNU/Hurd is Multiboot-compliant, it is easy to boot it; there is nothing special about it. But do not forget that you have to specify a root partition to the kernel.

 1. Set GRUB's root device to the same drive as GNU/Hurd's. Probably the command find /boot/gnumach or similar can help you.

 2. Load the kernel and the module, like this:

          grub> kernel /boot/gnumach root=hd0s1
          grub> module /boot/serverboot

 3. Run the command boot.

GNU/Linux
---------

It is relatively easy to boot GNU/Linux from GRUB, because it somewhat resembles to boot a Multiboot-compliant OS.

 1. Set GRUB's root device to the same drive as GNU/Linux's. Probably the command find /vmlinuz or similar can help you.

 2. Load the kernel:

          grub> kernel /vmlinuz root=/dev/hda1

     If you need to specify some kernel parameters, just append them to the command. For example, to set vga to ext, do this:

          grub> kernel /vmlinuz root=/dev/hda1 vga=ext

     See the documentation in the Linux source tree for the complete information on the available options.

 3. If you use an initrd, execute the command initrd after kernel:

          grub> initrd /initrd

 4. Finally, run the command boot.

Caution: If you use an initrd and specify the mem= option to the kernel, to let it use less than actual memory size, you will also have to specify the same memory size to GRUB. To let GRUB know the size, run the command uppermem before loading the kernel. See Command-line-specific commands, for more information.

FreeBSD
-------

GRUB can load the kernel directly, either in ELF or a.out format. But this is not recommended, since FreeBSD's bootstrap interface sometimes changes heavily, so GRUB can't guarantee to pass kernel parameters correctly.

Thus, we'd recommend loading the very flexible loader /boot/loader instead. See this example:

     grub> root (hd0,a)
     grub> kernel /boot/loader
     grub> boot

NetBSD
------

GRUB can load NetBSD a.out and ELF directly, follow these steps:

 1. Set GRUB's root device with root.

 2. Load the kernel with kernel. You should append the ugly option --type=netbsd, if you want to load an ELF kernel, like this:

          grub> kernel --type=netbsd /netbsd-elf

 3. Run boot.

For now, however, GRUB doesn't allow you to pass kernel parameters, so it may be better to chain-load it instead, for more information please see Chain-loading.

OpenBSD
-------

The booting instruction is exactly the same as for NetBSD (see NetBSD).

DOS/Windows
-----------

GRUB cannot boot DOS or Windows directly, so you must chain-load them (see Chain-loading). However, their boot loaders have some critical deficiencies, so it may not work to just chain-load them. To overcome the problems, GRUB provides you with two helper functions.

If you have installed DOS (or Windows) on a non-first hard disk, you have to use the disk swapping technique, because that OS cannot boot from any disks but the first one. The workaround used in GRUB is the command map (see Commands), like this:

     grub> map (hd0) (hd1)
     grub> map (hd1) (hd0)

This performs a virtual swap between your first and second hard drive.

Caution: This is effective only if DOS (or Windows) uses BIOS to access the swapped disks. If that OS uses a special driver for the disks, this probably won't work.

Another problem arises if you installed more than one set of DOS/Windows onto one disk, because they could be confused if there are more than one primary partitions for DOS/Windows. Certainly you should avoid doing this, but there is a solution if you do want to do so. Use the partition hiding/unhiding technique.

If GRUB hides a DOS (or Windows) partition, it ignores the partition. If GRUB unhides a DOS (or Windows) partition, it detects the partition. Thus, if you have installed DOS (or Windows) on the first partition and the second of the first hard disk, and boot the first copy, do the following:

     grub> unhide (hd0,0)
     grub> hide (hd0,1)
     grub> rootnoverify (hd0,0)
     grub> chainloader +1
     grub> makeactive
     grub> boot

SCO UnixWare
------------

It is known that the signature in the boot loader for SCO UnixWare is wrong, so you will have to specify the option --force to chainloader, like this:

     grub> rootnoverify (hd1,0)
     grub> chainloader --force +1
     grub> makeactive
     grub> boot

Downloading OS images from a network
************************************

Although GRUB is a disk-based boot loader, it does provide some network support. To use the network support, you need to enable at least one network driver in the GRUB build process. For more information please see netboot/README.netboot in the source distribution.

How to set up your network
==========================

GRUB requires a server that will assign an IP address to the machine on which GRUB is running, and a file server. The former is either BOOTP, DHCP or a RARP server (RARP is deprecated, since it cannot serve much information). For the latter, only TFTP is supported at the moment. It is not necessary to run both the servers on one computer. How to configure these servers is beyond the scope of this document, so please refer to the manuals specific to those protocols/servers.

Once you have set up the servers, run bootp, dhcp or rarp for BOOTP, DHCP or RARP, respectively. Each command will show an assigned IP address, a netmask, an IP address for your TFTP server and a gateway. If any of the addresses is wrong or it causes an error, probably the configuration of your servers isn't set up properly.

Finally, download your OS images from your network. The network can be accessed using the network drive (nd). Everything else is very similar to the normal instructions (see Booting).

Here is an example:

     grub> bootp
     Probing... [NE*000]
     NE2000 base ...
     Address: 192.168.110.23    Netmask: 255.255.255.0
     Server: 192.168.110.14     Gateway: 192.168.110.1

     grub> root (nd)
     grub> kernel /tftproot/gnumach.gz root=sd0s1
     grub> module /tftproot/serverboot.gz
     grub> boot

Booting from a network
======================

It is sometimes very useful to boot from a network, especially, when you use a machine which has no local disk. In this case, you need to obtain a kind of Net Boot ROM, such as a PXE ROM or a free software package like Etherboot. Such a Boot ROM first boots the machine, sets up the network card installed into the machine, and downloads a second stage boot image from the network. Then, the second image will try to boot an operating system from the network actually.

GRUB provides two second stage images, nbgrub and pxegrub. Those images are the same as the normal Stage 2, except that they set up a network automatically, and try to load a configuration file from the network, if specified. The usage is very simple: If the machine has a PXE ROM, use pxegrub. If the machine has a NBI loader such as Etherboot, use nbgrub. There is no difference between them but their formats. As how to load a second stage image you want to use should be described in the manual on your Net Boot ROM, please refer to the manual, for more details. The topic is beyond the scope of this documentation.

However, there is one thing specific to GRUB. Namely, how to specify a configuration file in a BOOTP/DHCP server. For now, GRUB uses the tag 150, to get the name of a configuration file. This below is an example about a BOOTP configuration:

     allhost:hd=/tmp:bf=null:\
             :ds=145.71.35.1 145.71.32.1:\
             :sm=255.255.254.0:\
             :gw=145.71.35.1:\
             :sa=145.71.35.5:

     foo:ht=1:ha=63655d0334a7:ip=145.71.35.127:\
             :bf=/nbgrub:\
             :tc=allhost:\
             :T150="/tftpboot/menu.lst.foo":

See the manual about your BOOTP/DHCP server, for more information. The exact syntax should differ from the example, more or less.

Configuration
*************

You probably noticed that you need to type several commands to boot your OS. There's a solution to that - GRUB provides a menu interface (see Menu interface) from which you can select an item (using arrow keys) that will do everything to boot an OS.

To enable the menu, you need a configuration file, /boot/grub/menu.lst. We'll analyze an example file.

The file first contains some general settings, the menu interface related options. You can put these commands (see Menu-specific commands) before any of the items (starting with title).

     #
     # Sample boot menu configuration file
     #

As you may have guessed, these lines are comments. Lines starting with a hash character (#), and blank lines, are ignored by GRUB.

     # By default, boot the first entry.
     default 0

The first entry (here, counting starts with number zero, not one!) will be the default choice.

     # Boot automatically after 30 secs.
     timeout 30

As the comment says, GRUB will boot automatically in 30 seconds, unless interrupted with a keypress.

     # Fallback to the second entry.
     fallback 1

If, for any reason, the default entry doesn't work, fall back to the second one (this is rarely used, for obvious reasons).

Note that the complete descriptions of these commands, which are menu interface specific, can be found in see Menu-specific commands. Other descriptions can be found in Commands.

Now, on to the actual OS definitions. You will see that each entry begins with a special command, title, and the action is described after it. Note that there is no command boot at the end of each item. That is because GRUB automatically executes boot if it loads other commands successfully.

The argument for the command title is used to display a short title/description of the entry in the menu. Since title displays the argument as is, you can write basically anything in there.

     # For booting the GNU Hurd
     title  GNU/Hurd
     root   (hd0,0)
     kernel /boot/gnumach.gz root=hd0s1
     module /boot/serverboot.gz

This boots GNU/Hurd from the first hard disk.

     # For booting Linux
     title  GNU/Linux
     kernel (hd1,0)/vmlinuz root=/dev/hdb1

This boots GNU/Linux, but from the second hard disk.

     # For booting Mach (getting kernel from floppy)
     title  Utah Mach4 multiboot
     root   (hd0,2)
     pause  Insert the diskette now^G!!
     kernel (fd0)/boot/kernel root=hd0s3
     module (fd0)/boot/bootstrap

This boots Mach with a kernel on a floppy, but the root filesystem at hd0s3. It also contains a pause line, which will cause GRUB to display a prompt and delay, before actually executing the rest of the commands and booting.

     # For booting FreeBSD
     title  FreeBSD
     root   (hd0,2,a)
     kernel /boot/loader

This item will boot FreeBSD kernel loaded from the a partition of the third PC slice of the first hard disk.

     # For booting OS/2
     title OS/2
     root  (hd0,1)
     makeactive
     # chainload OS/2 bootloader from the first sector
     chainloader +1
     # This is similar to "chainload", but loads a specific file
     #chainloader /boot/chain.os2

This will boot OS/2, using a chain-loader.

     # For booting Windows NT or Windows95
     title Windows NT / Windows 95 boot menu
     root        (hd0,0)
     makeactive
     chainloader +1
     # For loading DOS if Windows NT is installed
     # chainload /bootsect.dos

The same as the above, but for Windows.

     # For installing GRUB into the hard disk
     title Install GRUB into the hard disk
     root    (hd0,0)
     setup   (hd0)

This will just (re)install GRUB onto the hard disk.

     # Change the colors.
     title Change the colors
     color light-green/brown blink-red/blue

In the last entry, the command color is used, to change the menu colors (try it!). This command is somewhat special, because it can be used both in the command-line and in the menu (see General commands). GRUB has several such commands, see the user reference.

We hope that you now understand how to use the basic features of GRUB. To learn more about GRUB, see the User Reference Manual (see Introduction).

Have fun!