grub.texi

grub4dos-0.4.4-2008- 08-src.zip

title the old kernel
root (hd0,0)
kernel /old_kernel
savedefault

title the new kernel
root (hd0,0)
kernel /new_kernel
savedefault 0         # This is important!!!
@end group
@end example

Note that this configuration file uses @samp{default saved}
(@pxref{default}) at the head and @samp{savedefault 0}
(@pxref{savedefault}) in the entry for the new kernel. This means
that GRUB boots a saved entry by default, and booting the entry for the
new kernel saves @samp{0} as the saved entry.

With this configuration file, after all, GRUB always tries to boot the
old kernel after it booted the new one, because @samp{0} is the entry
of @code{the old kernel}.

The next step is to tell GRUB to boot the new kernel at next boot
time. For this, execute @command{grub-set-default} (@pxref{Invoking
grub-set-default}):

@example
# @kbd{grub-set-default 1}
@end example

This command sets the saved entry to @samp{1}, that is, to the new
kernel.

This method is useful, but still not very robust, because GRUB stops
booting, if there is any error in the boot entry, such that the new
kernel has an invalid executable format. Thus, it it even better to
use the @dfn{fallback} mechanism of GRUB. Look at next subsection for
this feature.


@node Booting fallback systems
@subsection Booting fallback systems

GRUB supports a fallback mechanism of booting one or more other
entries if a default boot entry fails. You can specify multiple
fallback entries if you wish.

Suppose that you have three systems, @samp{A}, @samp{B} and
@samp{C}. @samp{A} is a system which you want to boot by
default. @samp{B} is a backup system which is supposed to boot
safely. @samp{C} is another backup system which is used in case where
@samp{B} is broken.

Then you may want GRUB to boot the first system which is bootable
among @samp{A}, @samp{B} and @samp{C}. A configuration file can be
written in this way:

@example
@group
default saved        # This is important!!!
timeout 10
fallback 1 2         # This is important!!!

title A
root (hd0,0)
kernel /kernel
savedefault fallback # This is important!!!

title B
root (hd1,0)
kernel /kernel
savedefault fallback # This is important!!!

title C
root (hd2,0)
kernel /kernel
savedefault
@end group
@end example

Note that @samp{default saved} (@pxref{default}), @samp{fallback 1 2}
and @samp{savedefault fallback} are used. GRUB will boot a saved entry
by default and save a fallback entry as next boot entry with this
configuration.

When GRUB tries to boot @samp{A}, GRUB saves @samp{1} as next boot
entry, because the command @command{fallback} specifies that @samp{1}
is the first fallback entry. The entry @samp{1} is @samp{B}, so GRUB
will try to boot @samp{B} at next boot time.

Likewise, when GRUB tries to boot @samp{B}, GRUB saves @samp{2} as
next boot entry, because @command{fallback} specifies @samp{2} as next
fallback entry. This makes sure that GRUB will boot @samp{C} after
booting @samp{B}.

It is noteworthy that GRUB uses fallback entries both when GRUB
itself fails in booting an entry and when @samp{A} or @samp{B} fails
in starting up your system. So this solution ensures that your system
is started even if GRUB cannot find your kernel or if your kernel
panics.

However, you need to run @command{grub-set-default} (@pxref{Invoking
grub-set-default}) when @samp{A} starts correctly or you fix @samp{A}
after it crashes, since GRUB always sets next boot entry to a fallback
entry. You should run this command in a startup script such as
@file{rc.local} to boot @samp{A} by default:

@example
# @kbd{grub-set-default 0}
@end example

where @samp{0} is the number of the boot entry for the system
@samp{A}.

If you want to see what is current default entry, you can look at the
file @file{/boot/grub/default} (or @file{/grub/default} in
some systems). Because this file is plain-text, you can just
@command{cat} this file. But it is strongly recommended @strong{not to
modify this file directly}, because GRUB may fail in saving a default
entry in this file, if you change this file in an unintended
manner. Therefore, you should use @command{grub-set-default} when you
need to change the default entry.


@node Configuration
@chapter Configuration

You've 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{menu.lst} under the boot directory. 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}
(@pxref{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
@group
# Boot automatically after 30 secs.
timeout 30
@end group
@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 @ref{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} (@pxref{title}), and the
action is described after it. Note that there is no command
@command{boot} (@pxref{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 there.

@example
@group
# For booting 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 GNU/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 (@pxref{pause}), 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 (@pxref{Chain-loading}).

@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 (@pxref{color}),
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. GRUB
has several such commands, see @ref{General commands}.

We hope that you now understand how to use the basic features of
GRUB. To learn more about GRUB, see the following chapters.


@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 file server and optionally a server that will assign an
IP address to the machine on which GRUB is running. For the former, only
TFTP is supported at the moment. The latter is either BOOTP, DHCP or a
RARP server@footnote{RARP is not advised, since it cannot serve much
information}. 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.

If you decided to use a server to assign an IP address, set up the
server and run @command{bootp} (@pxref{bootp}), @command{dhcp}
(@pxref{dhcp}) or @command{rarp} (@pxref{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.

Otherwise, run @command{ifconfig}, like this:

@example
grub> @kbd{ifconfig --address=192.168.110.23 --server=192.168.110.14}
@end example

You can also use @command{ifconfig} in conjuction with @command{bootp},
@command{dhcp} or @command{rarp} (e.g. to reassign the server address
manually). @xref{ifconfig}, for more details.

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 actually from the network.