grub.texi

grub4dos-0.4.4-2008- 08-src.zip

GRUB provides two second stage images, @file{nbgrub} and
@file{pxegrub} (@pxref{Images}). These 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 an NBI loader such as Etherboot, use
@file{nbgrub}. There is no difference between them except their
formats. Since the way 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 information.

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. The following is an
example with 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="(nd)/tftpboot/menu.lst.foo":
@end group
@end example

Note that you should specify the drive name @code{(nd)} in the name of
the configuration file. This is because you might change the root drive
before downloading the configuration from the TFTP server when the
preset menu feature is used (@pxref{Preset Menu}).

See the manual of your BOOTP/DHCP server for more information. The
exact syntax should differ a little from the example.


@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
could be very useful to control the computers through serial
communications. To connect one 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{serial},
for more details.

The command @command{terminal} (@pxref{terminal}) chooses which type of
terminal you want to use. In the case above, the terminal will be a
serial terminal, but you can also pass @code{console} to the command,
as @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 this option then
GRUB provides you with an alternative menu interface, because the normal
menu requires several fancy features of your terminal.


@node Preset Menu
@chapter Embedding a configuration file into GRUB

GRUB supports a @dfn{preset menu} which is to be always loaded before
starting. The preset menu feature is useful, for example, when your
computer has no console but a serial cable. In this case, it is
critical to set up the serial terminal as soon as possible, since you
cannot see any message until the serial terminal begins to work. So it
is good to run the commands @command{serial} (@pxref{serial}) and
@command{terminal} (@pxref{terminal}) before anything else at the
start-up time.

How the preset menu works is slightly complicated:

@enumerate
@item
GRUB checks if the preset menu feature is used, and loads the preset
menu, if available. This includes running commands and reading boot
entries, like an ordinary configuration file.

@item
GRUB checks if the configuration file is available. Note that this check
is performed @strong{regardless of the existence of the preset
menu}. The configuration file is loaded even if the preset menu was
loaded.

@item
If the preset menu includes any boot entries, they are cleared when
the configuration file is loaded. It doesn't matter whether the
configuration file has any entries or no entry. The boot entries in the
preset menu are used only when GRUB fails in loading the configuration
file.
@end enumerate

To enable the preset menu feature, you must rebuild GRUB specifying a
file to the configure script with the option
@option{--enable-preset-menu}. The file has the same semantics as
normal configuration files (@pxref{Configuration}).

Another point you should take care is that the diskless support
(@pxref{Diskless}) diverts the preset menu. Diskless images embed a
preset menu to execute the command @command{bootp} (@pxref{bootp})
automatically, unless you specify your own preset menu to the configure
script. This means that you must put commands to initialize a network in
the preset menu yourself, because diskless images don't set it up
implicitly, when you use the preset menu explicitly.

Therefore, a typical preset menu used with diskless support would be
like this:

@example
@group
# Set up the serial terminal, first of all.
serial --unit=0 --speed=19200
terminal --timeout=0 serial

# Initialize the network.
dhcp
@end group
@end example


@node Security
@chapter Protecting your computer from cracking

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 one to modify its configuration
and run arbitrary commands at run-time. For example, the user can even
read @file{/etc/passwd} in the command-line interface by the command
@command{cat} (@pxref{cat}). So it is necessary to disable all the
interactive operations.

Thus, GRUB provides a @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
(@pxref{password}), 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}
(@pxref{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 a
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} (@pxref{lock}). This command
always fails until you enter the 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.


@node Images
@chapter GRUB image files

GRUB consists of several images: two essential stages, optional stages
called @dfn{Stage 1.5}, one image for bootable CD-ROM, and two network
boot images. Here is a short overview of them. @xref{Internals}, for
more details.

@table @file
@item stage1
This is an essential image used for booting up GRUB. Usually, this is
embedded in an MBR or the boot sector of a partition. Because a PC boot
sector is 512 bytes, the size of this image is exactly 512 bytes.

All @file{stage1} must do is to load Stage 2 or Stage 1.5 from a local
disk. Because of the size restriction, @file{stage1} encodes the
location of Stage 2 (or Stage 1.5) in a block list format, so it never
understand any filesystem structure.

@item stage2
This is the core image of GRUB. It does everything but booting up
itself. Usually, this is put in a filesystem, but that is not required.

@item e2fs_stage1_5
@itemx fat_stage1_5
@itemx ffs_stage1_5
@itemx jfs_stage1_5
@itemx minix_stage1_5
@itemx reiserfs_stage1_5
@itemx vstafs_stage1_5
@itemx xfs_stage1_5

These are called @dfn{Stage 1.5}, because they serve as a bridge
between @file{stage1} and @file{stage2}, that is to say, Stage 1.5 is
loaded by Stage 1 and Stage 1.5 loads Stage 2. The difference between
@file{stage1} and @file{*_stage1_5} is that the former doesn't
understand any filesystem while the latter understands one filesystem
(e.g. @file{e2fs_stage1_5} understands ext2fs). So you can move the
Stage 2 image to another location safely, even after GRUB has been
installed.

While Stage 2 cannot generally be embedded in a fixed area as the size
is so large, Stage 1.5 can be installed into the area right after an MBR,
or the boot loader area of a ReiserFS or a FFS.

@item stage2_eltorito
This is a boot image for CD-ROMs using the @dfn{no emulation mode} in
El Torito specification. This is identical to Stage 2, except that
this boots up without Stage 1 and sets up a special drive @samp{(cd)}.

@item nbgrub
This is a network boot image for the Network Image Proposal used by some
network boot loaders, such as Etherboot. This is mostly the same as
Stage 2, but it also sets up a network and loads a configuration file
from the network.

@item pxegrub
This is another network boot image for the Preboot Execution Environment
used by several Netboot ROMs. This is identical to @file{nbgrub}, except
for the format.
@end table


@node Filesystem
@chapter Filesystem syntax and semantics

GRUB uses a special syntax for specifying disk drives which can be
accessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish
between IDE, ESDI, SCSI, or others. You must know yourself which BIOS
device is equivalent to which OS device. Normally, that will be clear if
you see the files in a device or use the command @command{find}
(@pxref{find}).

@menu
* Device syntax::               How to specify devices
* File name syntax::            How to specify files
* Block list syntax::           How to specify block lists
@end menu


@node Device syntax
@section How to specify devices

The device syntax is like this:

@example
@code{(@var{device}[,@var{part-num}][,@var{bsd-subpart-letter}])}
@end example

@samp{[]} means the parameter is optional. @var{device} should be
either @samp{fd} or @samp{hd} followed by a digit, like @samp{fd0}.
But you can also set @var{device} to a hexadecimal or a decimal number
which is a BIOS drive number, so the following are equivalent:

@example
(hd0)
(0x80)
(128)
@end example

@var{part-num} represents the partition number of @var{device}, starting
from zero for primary partitions and from four for extended partitions,
and @var{bsd-subpart-letter} represents the BSD disklabel subpartition,
such as @samp{a} or @samp{e}.

A shortcut for specifying BSD subpartitions is
@code{(@var{device},@var{bsd-subpart-letter})}, in this case, GRUB
searches for the first PC partition containing a BSD disklabel, then
finds the subpartition @var{bsd-subpart-letter}. Here is an example:

@example
(hd0,a)
@end example

The syntax @samp{(hd0)} represents using the entire disk (or the
MBR when installing GRUB), while the syntax @samp{(hd0,0)}
represents using the first partition of the disk (or the boot sector
of the partition when installing GRUB).

If you enabled the network support, the special drive, @samp{(nd)}, is
also available. Before using the network drive, you must initialize the
network. @xref{Network}, for more information.

If you boot GRUB from a CD-ROM, @samp{(cd)} is available. @xref{Making
a GRUB bootable CD-ROM}, for details.


@node File name syntax
@section How to specify files

There are two ways to specify files, by @dfn{absolute file name} and by
@dfn{block list}.

An absolute file name resembles a Unix absolute file name, using
@samp{/} for the directory separator (not @samp{\} as in DOS). One
example is @samp{(hd0,0)/boot/grub/menu.lst}. This means the file
@file{/boot/grub/menu.lst} in the first partition of the first hard
disk. If you