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 an 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).

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@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.}. GRUB is designed to
address the complexity of booting a personal computer; both the
program and this manual are tightly bound to that computer platform,
although porting to other platforms may be addressed in the future.

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 (@pxref{Command line}), or use the nice menu
interface (@pxref{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 (@pxref{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 (@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 utility @command{grub-install}
(@pxref{Invoking grub-install}) on a UNIX-like OS, or by using the
native Stage 2. These are quite similar, however, the utility 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
* Creating a GRUB boot floppy::
* Installing GRUB natively::
* Installing GRUB using grub-install::
@end menu


@node Creating a GRUB boot floppy
@section Creating a GRUB boot floppy

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

@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
# @kbd{cd /boot/grub}
# @kbd{dd if=stage1 of=/dev/fd0 bs=512 count=1}
1+0 records in
1+0 records out
# @kbd{dd if=stage2 of=/dev/fd0 bs=512 seek=1}
153+1 records in
153+1 records out
#
@end group
@end example

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


@node Installing GRUB natively
@section Installing GRUB natively

@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 need to create the GRUB boot disk, and
reboot your computer with it. Otherwise, see @ref{Installing GRUB using
grub-install}, for more details.

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 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 @command{kernel}.} to the partition which has your GRUB
images, like this:

@example
grub> @kbd{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> @kbd{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> @kbd{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> @kbd{setup (hd0,0)}
@end example

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.

Now you can boot GRUB without a GRUB floppy. See the chapter
@ref{Booting} to find out how to boot your operating systems from GRUB.


@node Installing GRUB using grub-install
@section Installing GRUB using grub-install

Unfortunately, if you do want to install GRUB under a UNIX-like OS (such
as @sc{gnu}), invoke the program @command{grub-install} as the superuser
(@dfn{root}).

The usage is basically very easy. You only need to specify one argument
to the program, namely, where to install GRUB. The argument can be
either of a device file or a GRUB's drive/partition. So, this will
install GRUB into the MBR of the first IDE disk under Linux:

@example
# @kbd{grub-install /dev/hda}
@end example

Likewise, under Hurd, this has the same effect:

@example
# @kbd{grub-install /dev/hd0}
@end example

If it is the first BIOS drive, this is the same as well:

@example
# @kbd{grub-install '(hd0)'}
@end example

But all the above examples assume that you use GRUB images under
the root directory. If you want GRUB to use images under a directory
other than the root directory, you need to specify the option
@option{--root-directory}. The typical usage is that you create a GRUB
boot floppy with a filesystem. Here is an example:

@example
@group
# @kbd{mke2fs /dev/fd0}
# @kbd{mount -t ext2 /dev/fd0 /mnt}
# @kbd{grub-install --root-directory=/mnt '(fd0)'}
# @kbd{umount /mnt}
@end group
@end example

Another example is in case that you have a separate boot partition
which is mounted at @file{/boot}. Since GRUB is a boot loader, it
doesn't know anything about mountpoints at all. Thus, you need to run
@command{grub-install} like this:

@example
# @kbd{grub-install --root-directory=/boot /dev/hda}
@end example

By the way, as you may already know, it is quite difficult to guess BIOS
drives correctly under a UNIX-like OS. Thus, @command{grub-install} will
prompt you to check if it could really guess the correct mappings, after
the installation. The format is defined in @ref{Device map}. Please be
careful enough. If the output is wrong, it is unlikely that your
computer can boot with no problem.

Note that @command{grub-install} is actually just a shell script and the
real task is done by the grub shell @command{grub} (@pxref{Invoking the
grub shell}). Therefore, you may run @command{grub} directly to install
GRUB, without using @command{grub-install}. Don't do that, however,
unless you are very familiar with the internals of GRUB. Installing a
boot loader on a running OS may be dangerous.


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

@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

Multiboot (@pxref{Top, Multiboot Specification, Motivation, multiboot,
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 (@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 a 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> @kbd{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 of the
modern operating systems.}:

@example
grub> @kbd{makeactive}
@end example

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

@example
grub> @kbd{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> @kbd{kernel /boot/gnumach root=hd0s1}
grub> @kbd{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 to boot 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> @kbd{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> @kbd{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> @kbd{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 and menu entry commands}, for more information.

@node FreeBSD
@subsection 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
@file{/boot/loader} instead. See this example:

@example
@group
grub> @kbd{root (hd0,a)}
grub> @kbd{kernel /boot/loader}
grub> @kbd{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> @kbd{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 instruction is exactly the same as for NetBSD
(@pxref{NetBSD}).


@node DOS/Windows
@subsection DOS/Windows

GRUB cannot boot DOS or Windows directly, so you must chain-load them
(@pxref{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 @command{map} (@pxref{Commands}), like this:

@example
@group
grub> @kbd{map (hd0) (hd1)}
grub> @kbd{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 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 @dfn{hide}s a DOS (or Windows) partition, 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 of the first hard disk, and boot the
first copy, do the following:

@example
@group
grub> @kbd{unhide (hd0,0)}
grub> @kbd{hide (hd0,1)}
grub> @kbd{rootnoverify (hd0,0)}
grub> @kbd{chainloader +1}
grub> @kbd{makeactive}
grub> @kbd{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> @kbd{rootnoverify (hd1,0)}
grub> @kbd{chainloader --force +1}
grub> @kbd{makeactive}
grub> @kbd{boot}
@end group
@end example


@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) that 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, but 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 onto 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{Command-line
and menu 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 following chapters and the User
Reference Manual (@pxref{Introduction}).


@node Network
@chapter Downloading OS images from a network

Although GRUB is a disk-based boot loader, it does provide 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 @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

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 @command{bootp}, @command{dhcp}
or @command{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 @samp{(nd)}. Everything else is very
similar to the normal instructions (@pxref{Booting}).

Here is an example:

@example
@group
grub> @kbd{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> @kbd{root (nd)}
grub> @kbd{kernel /tftproot/gnumach.gz root=sd0s1}
grub> @kbd{module /tftproot/serverboot.gz}
grub> @kbd{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 Serial terminal
@chapter Using GRUB via a serial line

This chapter describes how to use the serial terminal support in GRUB.

If you have many computers or computers with no display/keyboard, it
would be very useful to control the computers with serial
communications. To connect a computer with another via a serial line,
you need to prepare a null-modem (cross) serial cable, and you may need
to have multiport serial boards, if your computer doesn't have extra
serial ports. In addition, a terminal emulator is also required, such as
minicom. Refer to a manual of your operating system, for more
information.

As for GRUB, the instruction to set up a serial terminal is quite
simple. First of all, make sure that you haven't specified the option
@option{--disable-serial} to the configure script when you built your
GRUB images. If you get them in binary form, probably they have serial
terminal support already.

Then, initialize your serial terminal after GRUB starts up. Here is an
example:

@example
@group
grub> @kbd{serial --unit=0 --speed=9600}
grub> @kbd{terminal serial}
@end group
@end example

The command @command{serial} initializes the serial unit 0 with the
speed 9600bps. The serial unit 0 is usually called @samp{COM1}, so, if
you want to use COM2, you must specify @samp{--unit=1} instead. This
command accepts many other options, so please refer to @ref{Commands},
for more details.

The command @command{terminal} chooses which type of terminal you want
to use. In that case above, the terminal will be a serial terminal, but
you can also pass @code{console} to the command, like @samp{terminal
serial console}. In this case, a terminal in which you press any key
will be selected as a GRUB terminal.

However, note that GRUB assumes that your terminal emulator is
compatible with VT100 by default. This is true for most terminal
emulators nowadays, but you should pass the option @option{--dumb} to
the command, if your terminal emulator is not VT100-compatible or
implements few VT100 escape sequences. If you specify the option, then
GRUB doesn't provide you with the menu interface, because the menu
requires several fancy features for your terminal. Instead, GRUB only
gives you the hidden menu interface and the command-line interface.


@node Security
@chapter Security

You may be interested in how to prevent ordinary users from doing
whatever they like, if you share your computer with other people. So
this chapter describes how to improve the security of GRUB.

One thing which could be a security hole is that the user can do too
many things with GRUB, because GRUB allows to modify its configuration
and run arbitrary commands at run-time. For example, the user can read
even @file{/etc/passwd} in the command-line interface by the command
@command{cat}. So it is necessary to disable all the interactive
operations.

Thus, GRUB provides @dfn{password} feature, so that only administrators
can start the interactive operations (i.e. editing menu entries and
entering the command-line interface). To use this feature, you need to
run the command @command{password} in your configuration file, like
this:

@example
password --md5 PASSWORD
@end example

If this is specified, GRUB disallows any interactive control, until you
press the key @key{p} and enter a correct password.  The option
@option{--md5} tells GRUB that @samp{PASSWORD} is in MD5 format.  If it
is omitted, GRUB assumes the @samp{PASSWORD} is in clear text.

You can encrypt your password with the command @command{md5crypt}. For
example, run the grub shell (@pxref{Invoking the grub shell}), and enter
your password:

@example
@group
grub> md5crypt
Password: **********
Encrypted: $1$U$JK7xFegdxWH6VuppCUSIb.
@end group
@end example

Then, cut and paste the encrypted password to your configuration file.

Also, you can specify an optional argument to @command{password}. See
this example:

@example
password PASSWORD /boot/grub/menu-admin.lst
@end example

In this case, GRUB will load @file{/boot/grub/menu-admin.lst} as the
configuration file when you enter the valid password.

Another thing which may be dangerous is that any user can choose any
menu entry. Usually, this wouldn't be problematic, but you might want to
permit only administrators to run some of your menu entries, such as an
entry for booting an insecure OS like DOS.

GRUB provides the command @command{lock}. This command always fails
until you enter a valid password, so you can use it, like this:

@example
@group
title Boot DOS
lock
rootnoverify (hd0,1)
makeactive
chainload +1
@end group
@end example

You should insert @command{lock} right after @command{title}, because
any user can execute commands in an entry, until GRUB encounters
@command{lock}.

You can also use the command @command{password} instead of
@command{lock}. In this case the boot process will ask for the password
and stop if it was entered incorrectly.  Since the @command{password}
takes its own @var{PASSWORD} argument this is useful if you want
different passwords for different entries.