docs/tutorial.texi

@node Overview
@chapter Overview

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

GRUB can load a wide variety of free operating systems as well as
chain-loading@footnote{@dfn{chain-load} is the mechanism for loading
unsupported operating systems by loading another boot loader.}
proprietary operating systems. The important feature in GRUB
is flexibility; GRUB can understand filesystems and kernel executable
formats, so you can load an arbitrary operating system as you like
without recording the position of your kernel on the disk.

Therefore, you have to specify the drive/partition where your kernel
resides and the filename at hand. If you don't want to type the
drive and the filename every time, the menu interface (@pxref{Menu})
will help you. GRUB loads a configuration file (@pxref{Configuration})
if found and provides the menu so that you can select which OS is booted
at ease. Of course, you can enter the command-line interface
(@pxref{Command line}) whenever you like.

In the following chapters, we teach you how to specify a
drive/partition and a filename (@pxref{Filename}), how to install GRUB
on your drive (@pxref{Installation}), and how to boot your OSes
(@pxref{Boot}), step by step.


@c @node Fundamentals
@c @chapter Introduction to the technical basic knowledge
@c
@c I'm going to include Bill White's documentation here, once his
@c copyright problem will be solved.


@node Filename
@chapter Filename

Now is the time when you should learn the device syntax used in GRUB, so
that you can specify a drive/partition. See this example:

@example
(fd0)
@end example

This means the first floppy disk drive. GRUB requires that the device
name is enclosed with @samp{(} and @samp{)}. The number @samp{0} is the
drive number, which is counted from @emph{zero}. In this case, GRUB uses
the whole floppy disk.

@example
(hd0,1)
@end example

This means the second partition of the first hard disk drive. The first
integer @samp{0} indicates the drive number, that is, the first hard
disk, while the second integer @samp{1} indicates the partition number
(or the @sc{pc} slice number in the BSD terminology). Note that the
partition numbers are counted from @emph{zero} but not from one. In this
case, GRUB uses the partition of the disk instead of the whole
disk.

@example
(hd0,4)
@end example

This specifies the first @dfn{extended partition} of the first hard disk
drive. Note that the partition numbers for extended partitions are
counted from @samp{4}, whether your disks has four primary partitions or
less.

@example
(hd1,a)
@end example

This means the BSD @samp{a} partition of the second hard disk. If you
need to specify which @sc{pc} slice number should be used, use a device
like @samp{(hd1,0,a)}. If the @sc{pc} slice number is omitted, GRUB
searches for the first @sc{pc} slice which has a BSD @samp{a} partition.

Note that GRUB does @emph{not} distinguish IDE from SCSI; just count the
drive numbers from zero. Normally, any IDE drive number is less than any
SCSI drive number, but this is not true if you exchange the boot
sequence between IDE and SCSI in your BIOS. But do not worry. In the
GRUB command-line (@pxref{Command line}), you can always use the
@key{TAB} completion which displays the list of drives, the list of the
partitions of a drive, or the list of the filenames on a partition,
depending on where you push the @key{TAB} key in the command-line. So it
should be possible to determine which drive and which partition are what
you seek for.

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

@example
(hd0,0)/vmlinuz
@end example

This specifies the file whose name is @samp{vmlinuz} on the first
partition of the first hard disk drive. Isn't that easy? All you should
do is type the absolute filename. If you are tired of typing the
whole filename, press the @key{TAB} key. @kbd{@key{TAB}}
completes the filename if it is unique. Otherwise, it displays the list
of the candidates.

OK, the next chapter introduces how to install GRUB on your drive.


@node Installation
@chapter Installation

At first, install GRUB by @code{make install} (@pxref{Obtaining and
Building GRUB}) or by the GRUB package for your OS. If this is done,
let's install GRUB on your drive. There are two ways to install GRUB:
using the grub shell (@pxref{Invoking the grub shell}) on a UNIX-like OS
and using the native Stage 2. The two ways are almost the same, but the
main difference is that the grub shell might probe a wrong BIOS drive on
a UNIX-like OS. If you install GRUB on a UNIX-like OS, make sure that
you have a boot floppy disk so that you can rescue your computer when it
crashes.

Anyhow, copy your GRUB images (@file{stage1}, @file{stage2}, and
@file{*stage1_5}) to the directory @file{/boot/grub} before staring to
install GRUB. Normally, the images are installed under the directory
@file{/usr/share/grub/i386-pc}.

@menu
* Installing GRUB on a floppy::
* Installing GRUB on a hard disk::
@end menu


@node Installing GRUB on a floppy
@section Installing GRUB on a floppy

@quotation
@strong{Caution:} This procedure will destroy any data currently stored
on the floppy.
@end quotation

It is easy to create a GRUB boot floppy. Just follow this below:

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

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


@node Installing GRUB on a hard disk
@section Installing GRUB on a hard disk

@quotation
@strong{Caution:} Installing GRUB's stage1 in this manner will erase the
normal boot-sector used by an OS. GRUB can boot GNU Mach, Linux,
FreeBSD, NetBSD, and OpenBSD directly, so this may be
desired. Generally, it is 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 (by running @code{FDISK /MBR} from
DOS).
@end quotation

OK, now reboot your computer with a GRUB boot floppy inserted if you
decide to install GRUB in the native environment. That's definitely
desirable. However, if you don't want to reboot your computer, run the
program @file{/sbin/grub} (@pxref{Invoking the grub shell}).

In both, GRUB will show the command-line interface (@pxref{Command
line}). First, set the GRUB's @dfn{root device}@footnote{Note that
GRUB's root device is not your OS's root partition; if you need to
specify a root partition for your OS, add the argument into the command
@command{kernel}.} to the partition which has your GRUB images, like
this:

@example
grub> root (hd0,0)
@end example

If you are not sure where the images exist, use the command
@command{find}:

@example
grub> find /boot/grub/stage1
@end example

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

If you set the root device correctly, run the command
@command{setup}:

@example
grub> setup (hd0)
@end example

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

@example
grub> setup (hd0,0)
@end example

If you install GRUB into a partition or a drive except for the first
one, you must chain-load GRUB from another boot loader. Refer 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, so let's see
how to boot your operating systems from GRUB in the next chapter.


@node Boot
@chapter Boot

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.

@menu
* General boot methods::
* OS-specific notes::
@end menu


@node General boot methods
@section How to boot operating systems

GRUB has two distinct sets of boot methods, that is, loading an
operating system directly and chain-loading another boot loader which
then will load an operating system actually. Generally speaking, the
former is preferable, 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.

@menu
* Loading an operating system directly::
* Chain-loading::
@end menu


@node Loading an operating system directly
@subsection How to boot an OS directly by GRUB

The native format supported by GRUB is Multiboot (@pxref{Top, Multiboot
Specification, Motivation, multiboot, The Multiboot Specification}), but
Linux, FreeBSD, NetBSD and OpenBSD are also supported for
convenience. If you want to boot other operating systems, you will have
to chain-load them (@pxref{Chain-loading}).

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

@enumerate
@item
Set GRUB's root device to the drive where the OS images are stored by
the command @command{root}.

@item
Load the kernel image by the command @command{kernel}.

@item
Load the modules by the command @command{module} or
@command{modulenounzip} as you need.

@item
Run the command @command{boot}.
@end enumerate

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


@node Chain-loading
@subsection Load another boot loader to boot unsupported operating systems

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

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

@example
grub> rootnoverify (hd0,0)
@end example

Second, set the @dfn{active} flag in the partition by the command
@command{makeactive}@footnote{This is not necessary for most modern
operating systems.}:

@example
grub> makeactive
@end example

Third, load the boot loader by the command @command{chainloader}:

@example
grub> chainloader +1
@end example

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

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


@node OS-specific notes
@section Some caveats on OS-specific issues

Here, we describe some caveats on several operating systems.

@menu
* GNU/Hurd::
* GNU/Linux::
* FreeBSD::
* NetBSD::
* OpenBSD::
* DOS/Windows::
* SCO UnixWare::
@end menu


@node GNU/Hurd
@subsection GNU/Hurd

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

First, set GRUB's root device to the same drive as
GNU/Hurd's. Probably @code{find /boot/gnumach} or such will help
you.

Second, load the kernel and the module, like this:

@example
@group
grub> kernel /boot/gnumach root=hd0s1
grub> module /boot/serverboot
@end group
@end example

And, finally, run the command @command{boot}.


@node GNU/Linux
@subsection GNU/Linux

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

First, set GRUB's root device to the same drive as
GNU/Linux's. Probably @code{find /vmlinuz} or such will help
you.

Second, load the kernel:

@example
grub> kernel /vmlinuz root=/dev/hda1
@end example

If you need to specify some kernel parameters, just append them to the
command. An example is to set @option{vga} to @samp{ext}:

@example
grub> kernel /vmlinuz root=/dev/hda1 vga=ext
@end example

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

If you use initrd, execute the command @command{initrd} after
@command{kernel}:

@example
grub> initrd /initrd
@end example

And, finally, run the command @command{boot}.


@node FreeBSD
@subsection FreeBSD

GRUB can directly load both kernel formats, ELF and a.out, but this is
deprecated, since FreeBSD's bootstrap interface is sometimes changed
heavily and so GRUB can't guarantee to pass kernel parameters
correctly.

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

@example
@group
grub> root (hd0,a)
grub> kernel /boot/loader
grub> boot
@end group
@end example


@node NetBSD
@subsection NetBSD

GRUB can load NetBSD a.out directly, by the following steps:

@enumerate
@item
Set GRUB's root device by @command{root}.

@item
Load the kernel by @command{kernel}.

@item
Run @command{boot}.
@end enumerate

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


@node OpenBSD
@subsection OpenBSD

The boot instructions are exactly the same as NetBSD (@pxref{NetBSD}).


@node DOS/Windows
@subsection DOS/Windows

GRUB doesn't support DOS or Windows directly, so you must chain-load
them (@pxref{Chain-loading}). However, their boot loaders have some
critical deficiencies, so the general methods may not be enough.

If you have installed DOS (or Windows) on a non-first hard disk, the
disk swapping technique is necessary, because it cannot boot any disks
but the first one. The solution used in GRUB is the command
@command{map} (@pxref{Command}). For example, if the installed disk is
the second hard disk, swap it for the first hard disk:

@example
@group
grub> map (hd0) (hd1)
grub> map (hd1) (hd0)
@end group
@end example

This performs the @dfn{virtual} exchange between the two disks.

@strong{Caution:} This is effective only if DOS (or Windows) uses BIOS
to access the swapped disks. If it uses a special driver for them,
probably this doesn't work.

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

If GRUB @dfn{hide}s a DOS (or Windows) partition, then it ignores the
partition. If GRUB @dfn{unhide}s a DOS (or Windows) partition, it
detects the partition. Thus, if you have installed DOS (or Windows) into
the first partition and the second partition of the first hard disk,
follow these below when booting the first:

@example
@group
grub> unhide (hd0,0)
grub> hide (hd0,1)
grub> rootnoverify (hd0,0)
grub> chainloader +1
grub> makeactive
grub> boot
@end group
@end example


@node SCO UnixWare
@subsection SCO UnixWare

The boot loader in SCO UnixWare is known by the fact that its signature
is wrong. So you will need to specify the option @option{--force} to
@command{chainloader}, like this:

@example
@group
grub> rootnoverify (hd1,0)
grub> chainloader --force +1
grub> makeactive
grub> boot
@end group
@end example


@node Network
@chapter Downloading OS images from a network

Although GRUB is a disk-based boot loader, it provides you some network
support. To using the network support, you need to enable at least one
network driver in the build process. See the file
@file{netboot/README.netboot} in the source distribution, for more
information.

First, you have to set up servers in your network. The servers GRUB
requires are a server which assigns an IP address and a file server. The
former is one of a BOOTP server, a DHCP server and 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 the servers is beyond the
scope of this document, so please refer to their own manuals.

Second, run @command{bootp}, @command{dhcp} and @command{rarp} for
BOOTP, DHCP and 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.

Lastly, download your OS images from your network. The network can be
accessed by the network drive @samp{(nd)}. Everything else is similar to
the normal instructions (@pxref{Boot}).

Here is an example:

@example
@group
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
@end group
@end example


@node Configuration
@chapter Configuration

Probably it is bothersome to type the commands to boot your OS. So
GRUB provides the menu interface (@pxref{Menu}) so that you can just
select an item from the menu.

To enable the menu, write a configuration file and save it in
@file{/boot/grub/menu.lst}. Here is a sample configuration file:

@example
@include menu.lst
@end example

As you see, each entry begins with the special command @command{title} and
the action is described after it. Note that you may not write the
command @command{boot} at each of the entries, since GRUB automatically
executes the command @command{boot} if it loads an OS successfully.

The argument for the command @command{title} is used to display the
message about the entry. Since @command{title} displays the argument as
it is, you can write any words as you like.

You can write the menu interface specific commands (@pxref{Menu-specific
commands}) before any @command{title}. There are several commands you
can use in there, but we describe a few of them. The complete
descriptions can be found in @ref{Command}.

The command @command{default} specifies which entry will be selected
when you do not select an entry explicitly. The argument is the entry
number. GRUB counts the entries from zero, so the number of the first
entry is @samp{0}, the number of the second entry is @samp{1}, @dots{}

The default entry will be executed when you do not select any entry
during certain seconds, which is defined by the command
@command{timeout}. So in the example above, the timeout is 30 seconds.

The command @command{fallback} is used only if the default entry
fails. If GRUB executes the default entry and it fails, then it executes
the @dfn{fallback} entry. The argument is the same meaning as the one
for @command{default}. This command is rarely used.

In the last entry, @command{color} is used. This command is somewhat
special because it can be used both in the command-line and in the
menu (@pxref{General commands}). GRUB has such several commands. The
command @command{color} changes the menu colors. It is best to run the
command actually to understand what happens.

We hope that you now understand how to use GRUB. To understand more
about GRUB, see the User Reference Manual (@pxref{Introduction}). Have
fun!