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 (e.g. a GNU system).

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. It is
typically used for loading DOS or Windows.} proprietary operating
systems.

The important feature 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.

Therefore, you have to specify the drive (and the partition) where your
kernel resides and the filename at hand. If you don't want to type in
the drive and the filename every time, you can set it up in a simple
configuration file (@pxref{Configuration}). GRUB will locate and load
it, and provide a nice menu interface (@pxref{Menu interface}) through
which you can easily select which OS it boots. Of course, you can enter
the command-line interface (@pxref{Command line}) whenever you like, or
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 (@pxref{Naming convention}) to GRUB, how to
install GRUB on your drive (@pxref{Installation}), and how to boot your
OSes (@pxref{Booting}), 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 Naming convention
@chapter 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:

@example
(fd0)
@end example

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

@example
(hd0,1)
@end example

Here, @samp{hd} means it is a 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). Once again, please note
that the partition numbers are counted from @emph{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.

@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}, regardless of the actual number of primary
partitions on your hard disk.

@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 something
like this: @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.

Of course, to actually access the disks or partitions with GRUB, you
need to use the device specification in a command, like @samp{root
(fd0)} or @samp{unhide (hd0,2)}. To help you find out which number is a
partition you want, the GRUB command-line (@pxref{Command line}) options
have argument completion. That means that, for example, you only need to
type @samp{root (}, followed by a @key{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 @emph{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:

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

This specifies the file named @samp{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.


@node Installation
@chapter Installation

First, you need to have GRUB itself properly installed on your system,
(@pxref{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 (@pxref{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
@file{/usr/share/grub/i386-pc} directory. You need to copy the files
@file{stage1}, @file{stage2}, and @file{*stage1_5} to the directory
@file{/boot/grub}.

@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

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

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

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

@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.
@end quotation

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 @samp{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 (@pxref{Invoking
the grub shell}) as the super-user (@samp{root}).

Once started, 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 does not neccessarily have to be 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 which partition actually holds these files, use the
@command{find} command, like this:

@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 file.

Once you've 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.

@c FIXME: you should specify --force-lba when...

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


@node Booting
@chapter 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.

@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
If you need modules, load them with the command @command{module} or
@command{modulenounzip}.

@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 about it. But do not forget that you have to specify a
root partition to the kernel.

@enumerate
@item
Set GRUB's root device to the same drive as GNU/Hurd's. Probably the
command @code{find /boot/gnumach} or similar can help you.

@item
Load the kernel and the module, like this:

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

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


@node GNU/Linux
@subsection GNU/Linux

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

@enumerate
@item
Set GRUB's root device to the same drive as GNU/Linux's. Probably the
command @code{find /vmlinuz} or similar can help you.

@item
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. For example, to set @option{vga} to @samp{ext}, do this:

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

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

@example
grub> initrd /initrd
@end example

@item
Finally, run the command @command{boot}.
@end enumerate

@strong{Caution:} If you use an initrd and specify the @samp{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 @command{uppermem} @emph{before} loading the
kernel. @xref{Command-line-specific commands}, for more information.

@node FreeBSD
@subsection FreeBSD

GRUB can directly load both kernel formats, ELF and a.out, but this is
deprecated, 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
@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 and ELF directly, follow these steps:

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

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

@example
grub> kernel --type=netbsd /netbsd-elf
@end example

@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, for more information please
see @ref{Chain-loading}.


@node OpenBSD
@subsection OpenBSD

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


@node DOS/Windows
@subsection DOS/Windows

GRUB doesn't support booting 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, you
have to use the disk swapping technique, because that OS cannot boot
from any disks but the first one. The solution used in GRUB is the
command @command{map} (@pxref{Commands}), like this:

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

This performs a @dfn{virtual} swap between your first and second hard
drive.

@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,
it probably won't work.

Another problem arises if you install more than one sets 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 @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) on
the first partition and the second partition of the first hard disk,
to boot the first copy, do the following:

@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

It is known that the signature in the boot loader for SCO UnixWare is
wrong, so you will have 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 does provide some network
support. To using the network support, you need to enable at least one
network driver in the build process. For more information please see
@file{netboot/README.netboot} in the source distribution.

@menu
* General usage of network support::
* Diskless::
@end menu


@node General usage of network support
@section How to set up your network

First, you have to set up servers in your network. GRUB requires a
server that will assign an IP address, 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 the servers is beyond the scope of this document, so please
refer to the manuals specific to those protocols/servers.

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.

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

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 Diskless
@section 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 @sc{rom}, such as a PXE @sc{rom} or a free software
package like Etherboot. Such a Boot @sc{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, @file{nbgrub} and
@file{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 @sc{rom}, use @file{pxegrub}. If the
machine has a NBI loader such as Etherboot, use @file{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 @sc{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
@samp{150}, to get the name of a configuration file. This below is an
example about a BOOTP configuration:

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

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


@node Configuration
@chapter 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
(@pxref{Menu interface}) from which you can select an item (using arrow
keys) which will do everything to boot an OS.

To enable the menu, you need a configuration file,
@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 (@pxref{Menu-specific
commands}) before any of the items (starting with @command{title}).

@example
@group
#
# Sample boot menu configuration file
#
@end group
@end example

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

@example
@group
# By default, boot the first entry.
default 0
@end group
@end example

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

@example
# Boot automatically after 30 secs.
timeout 30
@end example

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

@example
@group
# Fallback to the second entry.
fallback 1
@end group
@end example

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 @pxref{Menu-specific
commands}. Other descriptions can be found in @ref{Commands}.

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

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

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

This boots GNU/Hurd from the first hard disk.

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

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

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

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

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

This item will boot FreeBSD kernel loaded from the @samp{a} partition of
the third @sc{pc} slice of the first hard disk.

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

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

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

The same as the above, just for Windows.

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

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

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

In the last entry, the command @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 (@pxref{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
(@pxref{Introduction}).

Have fun!

@c FIXME: I think we should write some notes on the security here, or in
@c another chapter. Perhaps we should pick up all the user-visible
@c features in this tutorial and make the reference manual just a record
@c of the pure information. - okuji
@c
@c BTW, how many people think that this tutorial is easy to read? I
@c don't know. God knows? I don't think so. :p - okuji