4221 lines
160 KiB
Plaintext
4221 lines
160 KiB
Plaintext
Table of Contents
|
|
*****************
|
|
|
|
GNU GRUB manual
|
|
1 Introduction to GRUB
|
|
1.1 Overview
|
|
1.2 History of GRUB
|
|
1.3 GRUB features
|
|
1.4 The role of a boot loader
|
|
2 Naming convention
|
|
3 Installation
|
|
3.1 Creating a GRUB boot floppy
|
|
3.2 Installing GRUB natively
|
|
3.3 Installing GRUB using grub-install
|
|
3.4 Making a GRUB bootable CD-ROM
|
|
4 Booting
|
|
4.1 How to boot operating systems
|
|
4.1.1 How to boot an OS directly with GRUB
|
|
4.1.2 Load another boot loader to boot unsupported operating systems
|
|
4.2 Some caveats on OS-specific issues
|
|
4.2.1 GNU/Hurd
|
|
4.2.2 GNU/Linux
|
|
4.2.3 FreeBSD
|
|
4.2.4 NetBSD
|
|
4.2.5 OpenBSD
|
|
4.2.6 DOS/Windows
|
|
4.2.7 SCO UnixWare
|
|
4.2.8 QNX
|
|
4.3 How to make your system robust
|
|
4.3.1 Booting once-only
|
|
4.3.2 Booting fallback systems
|
|
5 Configuration
|
|
6 Downloading OS images from a network
|
|
6.1 How to set up your network
|
|
6.2 Booting from a network
|
|
7 Using GRUB via a serial line
|
|
8 Embedding a configuration file into GRUB
|
|
9 Protecting your computer from cracking
|
|
10 GRUB image files
|
|
11 Filesystem syntax and semantics
|
|
11.1 How to specify devices
|
|
11.2 How to specify files
|
|
11.3 How to specify block lists
|
|
12 GRUB's user interface
|
|
12.1 The flexible command-line interface
|
|
12.2 The simple menu interface
|
|
12.3 Editing a menu entry
|
|
12.4 The hidden menu interface
|
|
13 The list of available commands
|
|
13.1 The list of commands for the menu only
|
|
13.1.1 default
|
|
13.1.2 fallback
|
|
13.1.3 hiddenmenu
|
|
13.1.4 timeout
|
|
13.1.5 title
|
|
13.2 The list of general commands
|
|
13.2.1 bootp
|
|
13.2.2 color
|
|
13.2.3 device
|
|
13.2.4 dhcp
|
|
13.2.5 hide
|
|
13.2.6 ifconfig
|
|
13.2.7 pager
|
|
13.2.8 partnew
|
|
13.2.9 parttype
|
|
13.2.10 password
|
|
13.2.11 rarp
|
|
13.2.12 serial
|
|
13.2.13 setkey
|
|
13.2.14 terminal
|
|
13.2.15 terminfo
|
|
13.2.16 tftpserver
|
|
13.2.17 unhide
|
|
13.3 The list of command-line and menu entry commands
|
|
13.3.1 blocklist
|
|
13.3.2 boot
|
|
13.3.3 cat
|
|
13.3.4 chainloader
|
|
13.3.5 cmp
|
|
13.3.6 configfile
|
|
13.3.7 debug
|
|
13.3.8 displayapm
|
|
13.3.9 displaymem
|
|
13.3.10 embed
|
|
13.3.11 find
|
|
13.3.12 fstest
|
|
13.3.13 geometry
|
|
13.3.14 halt
|
|
13.3.15 help
|
|
13.3.16 impsprobe
|
|
13.3.17 initrd
|
|
13.3.18 install
|
|
13.3.19 ioprobe
|
|
13.3.20 kernel
|
|
13.3.21 lock
|
|
13.3.22 makeactive
|
|
13.3.23 map
|
|
13.3.24 md5crypt
|
|
13.3.25 module
|
|
13.3.26 modulenounzip
|
|
13.3.27 pause
|
|
13.3.28 quit
|
|
13.3.29 reboot
|
|
13.3.30 read
|
|
13.3.31 root
|
|
13.3.32 rootnoverify
|
|
13.3.33 savedefault
|
|
13.3.34 setup
|
|
13.3.35 testload
|
|
13.3.36 testvbe
|
|
13.3.37 uppermem
|
|
13.3.38 vbeprobe
|
|
14 Error messages reported by GRUB
|
|
14.1 Errors reported by the Stage 1
|
|
14.2 Errors reported by the Stage 1.5
|
|
14.3 Errors reported by the Stage 2
|
|
15 Invoking the grub shell
|
|
15.1 Introduction into the grub shell
|
|
15.2 How to install GRUB via `grub'
|
|
15.3 The map between BIOS drives and OS devices
|
|
16 Invoking grub-install
|
|
17 Invoking grub-md5-crypt
|
|
18 Invoking grub-terminfo
|
|
19 Invoking grub-set-default
|
|
20 Invoking mbchk
|
|
Appendix A How to obtain and build GRUB
|
|
Appendix B Reporting bugs
|
|
Appendix C Where GRUB will go
|
|
Appendix D Hacking GRUB
|
|
D.1 The memory map of various components
|
|
D.2 Embedded variables in GRUB
|
|
D.3 The generic interface for filesystems
|
|
D.4 The generic interface for built-ins
|
|
D.5 The bootstrap mechanism used in GRUB
|
|
D.6 How to probe I/O ports used by INT 13H
|
|
D.7 How to detect all installed RAM
|
|
D.8 INT 13H disk I/O interrupts
|
|
D.9 The structure of Master Boot Record
|
|
D.10 The format of partition tables
|
|
D.11 Where and how you should send patches
|
|
Appendix E Copying This Manual
|
|
E.1 GNU Free Documentation License
|
|
E.1.1 ADDENDUM: How to use this License for your documents
|
|
Index
|
|
|
|
|
|
GNU GRUB manual
|
|
***************
|
|
|
|
This is the documentation of GNU GRUB, the GRand Unified Bootloader, a
|
|
flexible and powerful boot loader program for PCs.
|
|
|
|
This edition documents version 0.97.
|
|
|
|
This manual is for GNU GRUB (version 0.97, 8 May 2005).
|
|
|
|
Copyright (C) 1999,2000,2001,2002,2004,2006 Free Software
|
|
Foundation, Inc.
|
|
|
|
Permission is granted to copy, distribute and/or modify this
|
|
document under the terms of the GNU Free Documentation License,
|
|
Version 1.2 or any later version published by the Free Software
|
|
Foundation; with no Invariant Sections, with the Front-Cover Texts
|
|
being "A GNU Manual," and with the Back-Cover Texts as in (a)
|
|
below. A copy of the license is included in the section entitled
|
|
"GNU Free Documentation License."
|
|
|
|
(a) The FSF's Back-Cover Text is: "You have freedom to copy and
|
|
modify this GNU Manual, like GNU software. Copies published by
|
|
the Free Software Foundation raise funds for GNU development."
|
|
|
|
1 Introduction to GRUB
|
|
**********************
|
|
|
|
1.1 Overview
|
|
============
|
|
|
|
Briefly, a "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 "kernel" software (such as Linux or GNU
|
|
Mach). 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(1) (*note Overview-Footnote-1::). 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 file name and the drive and partition
|
|
where the kernel resides.
|
|
|
|
When booting with GRUB, you can use either a command-line interface
|
|
(*note Command-line interface::), or a menu interface (*note Menu
|
|
interface::). Using the command-line interface, you type the drive
|
|
specification and file name of the kernel manually. In the menu
|
|
interface, you just select an OS using the arrow keys. The menu is
|
|
based on a configuration file which you prepare beforehand (*note
|
|
Configuration::). While in the menu, you can switch to the command-line
|
|
mode, and vice-versa. You can even edit menu entries before using them.
|
|
|
|
In the following chapters, you will learn how to specify a drive, a
|
|
partition, and a file name (*note Naming convention::) to GRUB, how to
|
|
install GRUB on your drive (*note Installation::), and how to boot your
|
|
OSes (*note Booting::), step by step.
|
|
|
|
Besides the GRUB boot loader itself, there is a "grub shell" `grub'
|
|
(*note Invoking the grub shell::) which can be run when you are in your
|
|
operating system. It emulates the boot loader and can be used for
|
|
installing the boot loader.
|
|
|
|
(1) "chain-load" is the mechanism for loading unsupported operating
|
|
systems by loading another boot loader. It is typically used for
|
|
loading DOS or Windows.
|
|
|
|
1.2 History of GRUB
|
|
===================
|
|
|
|
GRUB originated in 1995 when Erich Boleyn was trying to boot the GNU
|
|
Hurd with the University of Utah's Mach 4 microkernel (now known as GNU
|
|
Mach). Erich and Brian Ford designed the Multiboot Specification
|
|
(*note Multiboot Specification: (multiboot)Top.), because they were
|
|
determined not to add to the large number of mutually-incompatible PC
|
|
boot methods.
|
|
|
|
Erich then began modifying the FreeBSD boot loader so that it would
|
|
understand Multiboot. He soon realized that it would be a lot easier to
|
|
write his own boot loader from scratch than to keep working on the
|
|
FreeBSD boot loader, and so GRUB was born.
|
|
|
|
Erich added many features to GRUB, but other priorities prevented him
|
|
from keeping up with the demands of its quickly-expanding user base. In
|
|
1999, Gordon Matzigkeit and Yoshinori K. Okuji adopted GRUB as an
|
|
official GNU package, and opened its development by making the latest
|
|
sources available via anonymous CVS. *Note Obtaining and Building
|
|
GRUB::, for more information.
|
|
|
|
1.3 GRUB features
|
|
=================
|
|
|
|
The primary requirement for GRUB is that it be compliant with the
|
|
"Multiboot Specification", which is described in *Note Multiboot
|
|
Specification: (multiboot)Top.
|
|
|
|
The other goals, listed in approximate order of importance, are:
|
|
|
|
* Basic functions must be straightforward for end-users.
|
|
|
|
* Rich functionality to support kernel experts and designers.
|
|
|
|
* Backward compatibility for booting FreeBSD, NetBSD, OpenBSD, and
|
|
Linux. Proprietary kernels (such as DOS, Windows NT, and OS/2) are
|
|
supported via a chain-loading function.
|
|
|
|
Except for specific compatibility modes (chain-loading and the Linux
|
|
"piggyback" format), all kernels will be started in much the same state
|
|
as in the Multiboot Specification. Only kernels loaded at 1 megabyte or
|
|
above are presently supported. Any attempt to load below that boundary
|
|
will simply result in immediate failure and an error message reporting
|
|
the problem.
|
|
|
|
In addition to the requirements above, GRUB has the following
|
|
features (note that the Multiboot Specification doesn't require all the
|
|
features that GRUB supports):
|
|
|
|
Recognize multiple executable formats
|
|
Support many of the "a.out" variants plus "ELF". Symbol tables are
|
|
also loaded.
|
|
|
|
Support non-Multiboot kernels
|
|
Support many of the various free 32-bit kernels that lack Multiboot
|
|
compliance (primarily FreeBSD, NetBSD, OpenBSD, and Linux).
|
|
Chain-loading of other boot loaders is also supported.
|
|
|
|
Load multiples modules
|
|
Fully support the Multiboot feature of loading multiple modules.
|
|
|
|
Load a configuration file
|
|
Support a human-readable text configuration file with preset boot
|
|
commands. You can also load another configuration file dynamically
|
|
and embed a preset configuration file in a GRUB image file. The
|
|
list of commands (*note Commands::) are a superset of those
|
|
supported on the command-line. An example configuration file is
|
|
provided in *Note Configuration::.
|
|
|
|
Provide a menu interface
|
|
A menu interface listing preset boot commands, with a programmable
|
|
timeout, is available. There is no fixed limit on the number of
|
|
boot entries, and the current implementation has space for several
|
|
hundred.
|
|
|
|
Have a flexible command-line interface
|
|
A fairly flexible command-line interface, accessible from the menu,
|
|
is available to edit any preset commands, or write a new boot
|
|
command set from scratch. If no configuration file is present,
|
|
GRUB drops to the command-line.
|
|
|
|
The list of commands (*note Commands::) are a subset of those
|
|
supported for configuration files. Editing commands closely
|
|
resembles the Bash command-line (*note Bash: (features)Command
|
|
Line Editing.), with <TAB>-completion of commands, devices,
|
|
partitions, and files in a directory depending on context.
|
|
|
|
Support multiple filesystem types
|
|
Support multiple filesystem types transparently, plus a useful
|
|
explicit blocklist notation. The currently supported filesystem
|
|
types are "BSD FFS", "DOS FAT16 and FAT32", "Minix fs", "Linux
|
|
ext2fs", "ReiserFS", "JFS", "XFS", and "VSTa fs". *Note
|
|
Filesystem::, for more information.
|
|
|
|
Support automatic decompression
|
|
Can decompress files which were compressed by `gzip'. This
|
|
function is both automatic and transparent to the user (i.e. all
|
|
functions operate upon the uncompressed contents of the specified
|
|
files). This greatly reduces a file size and loading time, a
|
|
particularly great benefit for floppies.(1) (*note
|
|
Features-Footnote-1::)
|
|
|
|
It is conceivable that some kernel modules should be loaded in a
|
|
compressed state, so a different module-loading command can be
|
|
specified to avoid uncompressing the modules.
|
|
|
|
Access data on any installed device
|
|
Support reading data from any or all floppies or hard disk(s)
|
|
recognized by the BIOS, independent of the setting of the root
|
|
device.
|
|
|
|
Be independent of drive geometry translations
|
|
Unlike many other boot loaders, GRUB makes the particular drive
|
|
translation irrelevant. A drive installed and running with one
|
|
translation may be converted to another translation without any
|
|
adverse effects or changes in GRUB's configuration.
|
|
|
|
Detect all installed RAM
|
|
GRUB can generally find all the installed RAM on a PC-compatible
|
|
machine. It uses an advanced BIOS query technique for finding all
|
|
memory regions. As described on the Multiboot Specification (*note
|
|
Multiboot Specification: (multiboot)Top.), not all kernels make
|
|
use of this information, but GRUB provides it for those who do.
|
|
|
|
Support Logical Block Address mode
|
|
In traditional disk calls (called "CHS mode"), there is a geometry
|
|
translation problem, that is, the BIOS cannot access over 1024
|
|
cylinders, so the accessible space is limited to at least 508 MB
|
|
and to at most 8GB. GRUB can't universally solve this problem, as
|
|
there is no standard interface used in all machines. However,
|
|
several newer machines have the new interface, Logical Block
|
|
Address ("LBA") mode. GRUB automatically detects if LBA mode is
|
|
available and uses it if available. In LBA mode, GRUB can access
|
|
the entire disk.
|
|
|
|
Support network booting
|
|
GRUB is basically a disk-based boot loader but also has network
|
|
support. You can load OS images from a network by using the "TFTP"
|
|
protocol.
|
|
|
|
Support remote terminals
|
|
To support computers with no console, GRUB provides remote terminal
|
|
support, so that you can control GRUB from a remote host. Only
|
|
serial terminal support is implemented at the moment.
|
|
|
|
(1) There are a few pathological cases where loading a very badly
|
|
organized ELF kernel might take longer, but in practice this never
|
|
happen.
|
|
|
|
1.4 The role of a boot loader
|
|
=============================
|
|
|
|
The following is a quotation from Gordon Matzigkeit, a GRUB fanatic:
|
|
|
|
Some people like to acknowledge both the operating system and
|
|
kernel when they talk about their computers, so they might say
|
|
they use "GNU/Linux" or "GNU/Hurd". Other people seem to think
|
|
that the kernel is the most important part of the system, so they
|
|
like to call their GNU operating systems "Linux systems."
|
|
|
|
I, personally, believe that this is a grave injustice, because the
|
|
_boot loader_ is the most important software of all. I used to
|
|
refer to the above systems as either "LILO"(1) (*note Role of a
|
|
boot loader-Footnote-1::) or "GRUB" systems.
|
|
|
|
Unfortunately, nobody ever understood what I was talking about;
|
|
now I just use the word "GNU" as a pseudonym for GRUB.
|
|
|
|
So, if you ever hear people talking about their alleged "GNU"
|
|
systems, remember that they are actually paying homage to the best
|
|
boot loader around... GRUB!
|
|
|
|
We, the GRUB maintainers, do not (usually) encourage Gordon's level
|
|
of fanaticism, but it helps to remember that boot loaders deserve
|
|
recognition. We hope that you enjoy using GNU GRUB as much as we did
|
|
writing it.
|
|
|
|
(1) The LInux LOader, a boot loader that everybody uses, but nobody
|
|
likes.
|
|
|
|
2 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:
|
|
|
|
(fd0)
|
|
|
|
First of all, GRUB requires that the device name be enclosed with
|
|
`(' and `)'. The `fd' part means that it is a floppy disk. The number
|
|
`0' is the drive number, which is counted from _zero_. This expression
|
|
means that GRUB will use the whole floppy disk.
|
|
|
|
(hd0,1)
|
|
|
|
Here, `hd' means it is a hard disk drive. The first integer `0'
|
|
indicates the drive number, that is, the first hard disk, while the
|
|
second integer, `1', indicates the partition number (or the PC slice
|
|
number in the BSD terminology). Once again, please note that the
|
|
partition numbers are counted from _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.
|
|
|
|
(hd0,4)
|
|
|
|
This specifies the first "extended partition" of the first hard disk
|
|
drive. Note that the partition numbers for extended partitions are
|
|
counted from `4', regardless of the actual number of primary partitions
|
|
on your hard disk.
|
|
|
|
(hd1,a)
|
|
|
|
This means the BSD `a' partition of the second hard disk. If you
|
|
need to specify which PC slice number should be used, use something
|
|
like this: `(hd1,0,a)'. If the PC slice number is omitted, GRUB
|
|
searches for the first PC slice which has a BSD `a' partition.
|
|
|
|
Of course, to actually access the disks or partitions with GRUB, you
|
|
need to use the device specification in a command, like `root (fd0)' or
|
|
`unhide (hd0,2)'. To help you find out which number specifies a
|
|
partition you want, the GRUB command-line (*note Command-line
|
|
interface::) options have argument completion. This means that, for
|
|
example, you only need to type
|
|
|
|
root (
|
|
|
|
followed by a <TAB>, and GRUB will display the list of drives,
|
|
partitions, or file names. 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 _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, consider an
|
|
example:
|
|
|
|
(hd0,0)/vmlinuz
|
|
|
|
This specifies the file named `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. Now read the next chapter, to find out how
|
|
to actually install GRUB on your drive.
|
|
|
|
3 Installation
|
|
**************
|
|
|
|
In order to install GRUB as your boot loader, you need to first install
|
|
the GRUB system and utilities under your UNIX-like operating system
|
|
(*note Obtaining and Building GRUB::). You can do this either from the
|
|
source tarball, or as a package for your OS.
|
|
|
|
After you have done that, you need to install the boot loader on a
|
|
drive (floppy or hard disk). There are two ways of doing that - either
|
|
using the utility `grub-install' (*note Invoking grub-install::) on a
|
|
UNIX-like OS, or by running GRUB itself from a floppy. These are quite
|
|
similar, however the utility might probe a wrong BIOS drive, so you
|
|
should 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 put in the directory
|
|
`/usr/lib/grub/i386-pc'. If you do not use grub-install, then you need
|
|
to copy the files `stage1', `stage2', and `*stage1_5' to the directory
|
|
`/boot/grub', and run the `grub-set-default' (*note Invoking
|
|
grub-set-default::) if you intend to use `default saved' (*note
|
|
default::) in your configuration file. Hereafter, the directory where
|
|
GRUB images are initially placed (normally `/usr/lib/grub/i386-pc')
|
|
will be called the "image directory", and the directory where the boot
|
|
loader needs to find them (usually `/boot/grub') will be called the
|
|
"boot directory".
|
|
|
|
3.1 Creating a GRUB boot floppy
|
|
===============================
|
|
|
|
To create a GRUB boot floppy, you need to take the files `stage1' and
|
|
`stage2' from the image directory, and write them to the first and the
|
|
second block of the floppy disk, respectively.
|
|
|
|
*Caution:* This procedure will destroy any data currently stored on
|
|
the floppy.
|
|
|
|
On a UNIX-like operating system, that is done with the following
|
|
commands:
|
|
|
|
# cd /usr/lib/grub/i386-pc
|
|
# dd if=stage1 of=/dev/fd0 bs=512 count=1
|
|
1+0 records in
|
|
1+0 records out
|
|
# dd if=stage2 of=/dev/fd0 bs=512 seek=1
|
|
153+1 records in
|
|
153+1 records out
|
|
#
|
|
|
|
The device file name may be different. Consult the manual for your
|
|
OS.
|
|
|
|
3.2 Installing GRUB natively
|
|
============================
|
|
|
|
*Caution:* Installing GRUB's stage1 in this manner will erase the
|
|
normal boot-sector used by an OS.
|
|
|
|
GRUB can currently boot GNU Mach, Linux, FreeBSD, NetBSD, and OpenBSD
|
|
directly, so using it on a boot sector (the first sector of a
|
|
partition) 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 `FDISK /MBR' from DOS).
|
|
|
|
If you decide to install GRUB in the native environment, which is
|
|
definitely desirable, you'll need to create a GRUB boot disk, and
|
|
reboot your computer with it. Otherwise, see *Note Installing GRUB
|
|
using grub-install::.
|
|
|
|
Once started, GRUB will show the command-line interface (*note
|
|
Command-line interface::). First, set the GRUB's "root device"(1)
|
|
(*note Installing GRUB natively-Footnote-1::) to the partition
|
|
containing the boot directory, like this:
|
|
|
|
grub> root (hd0,0)
|
|
|
|
If you are not sure which partition actually holds this directory,
|
|
use the command `find' (*note find::), like this:
|
|
|
|
grub> find /boot/grub/stage1
|
|
|
|
This will search for the file name `/boot/grub/stage1' and show the
|
|
devices which contain the file.
|
|
|
|
Once you've set the root device correctly, run the command `setup'
|
|
(*note setup::):
|
|
|
|
grub> setup (hd0)
|
|
|
|
This command will install the GRUB boot loader on the Master Boot
|
|
Record (MBR) of the first drive. If you want to put GRUB into the boot
|
|
sector of a partition instead of putting it in the MBR, specify the
|
|
partition into which you want to install GRUB:
|
|
|
|
grub> setup (hd0,0)
|
|
|
|
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.
|
|
|
|
After using the setup command, you will boot into GRUB without the
|
|
GRUB floppy. See the chapter *Note Booting:: to find out how to boot
|
|
your operating systems from GRUB.
|
|
|
|
(1) 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 `kernel'.
|
|
|
|
3.3 Installing GRUB using grub-install
|
|
======================================
|
|
|
|
*Caution:* This procedure is definitely less safe, because there are
|
|
several ways in which your computer can become unbootable. For example,
|
|
most operating systems don't tell GRUB how to map BIOS drives to OS
|
|
devices correctly--GRUB merely "guesses" the mapping. This will succeed
|
|
in most cases, but not always. Therefore, GRUB provides you with a map
|
|
file called the "device map", which you must fix if it is wrong. *Note
|
|
Device map::, for more details.
|
|
|
|
If you still do want to install GRUB under a UNIX-like OS (such as
|
|
GNU), invoke the program `grub-install' (*note Invoking grub-install::)
|
|
as the superuser ("root").
|
|
|
|
The usage is basically very simple. You only need to specify one
|
|
argument to the program, namely, where to install the boot loader. The
|
|
argument can be either a device file (like `/dev/hda') or a partition
|
|
specified in GRUB's notation. For example, under Linux the following
|
|
will install GRUB into the MBR of the first IDE disk:
|
|
|
|
# grub-install /dev/hda
|
|
|
|
Likewise, under GNU/Hurd, this has the same effect:
|
|
|
|
# grub-install /dev/hd0
|
|
|
|
If it is the first BIOS drive, this is the same as well:
|
|
|
|
# grub-install '(hd0)'
|
|
|
|
Or you can omit the parentheses:
|
|
|
|
# grub-install hd0
|
|
|
|
But all the above examples assume that GRUB should use 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
|
|
`--root-directory'. The typical usage is that you create a GRUB boot
|
|
floppy with a filesystem. Here is an example:
|
|
|
|
# mke2fs /dev/fd0
|
|
# mount -t ext2 /dev/fd0 /mnt
|
|
# grub-install --root-directory=/mnt fd0
|
|
# umount /mnt
|
|
|
|
Another example is when you have a separate boot partition which is
|
|
mounted at `/boot'. Since GRUB is a boot loader, it doesn't know
|
|
anything about mountpoints at all. Thus, you need to run `grub-install'
|
|
like this:
|
|
|
|
# grub-install --root-directory=/boot /dev/hda
|
|
|
|
By the way, as noted above, it is quite difficult to guess BIOS
|
|
drives correctly under a UNIX-like OS. Thus, `grub-install' will prompt
|
|
you to check if it could really guess the correct mappings, after the
|
|
installation. The format is defined in *Note Device map::. Please be
|
|
quite careful. If the output is wrong, it is unlikely that your
|
|
computer will be able to boot with no problem.
|
|
|
|
Note that `grub-install' is actually just a shell script and the
|
|
real task is done by the grub shell `grub' (*note Invoking the grub
|
|
shell::). Therefore, you may run `grub' directly to install GRUB,
|
|
without using `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 extremely dangerous.
|
|
|
|
3.4 Making a GRUB bootable CD-ROM
|
|
=================================
|
|
|
|
GRUB supports the "no emulation mode" in the El Torito specification(1)
|
|
(*note Making a GRUB bootable CD-ROM-Footnote-1::). This means that you
|
|
can use the whole CD-ROM from GRUB and you don't have to make a floppy
|
|
or hard disk image file, which can cause compatibility problems.
|
|
|
|
For booting from a CD-ROM, GRUB uses a special Stage 2 called
|
|
`stage2_eltorito'. The only GRUB files you need to have in your
|
|
bootable CD-ROM are this `stage2_eltorito' and optionally a config file
|
|
`menu.lst'. You don't need to use `stage1' or `stage2', because El
|
|
Torito is quite different from the standard boot process.
|
|
|
|
Here is an example of procedures to make a bootable CD-ROM image.
|
|
First, make a top directory for the bootable image, say, `iso':
|
|
|
|
$ mkdir iso
|
|
|
|
Make a directory for GRUB:
|
|
|
|
$ mkdir -p iso/boot/grub
|
|
|
|
Copy the file `stage2_eltorito':
|
|
|
|
$ cp /usr/lib/grub/i386-pc/stage2_eltorito iso/boot/grub
|
|
|
|
If desired, make the config file `menu.lst' under `iso/boot/grub'
|
|
(*note Configuration::), and copy any files and directories for the
|
|
disc to the directory `iso/'.
|
|
|
|
Finally, make a ISO9660 image file like this:
|
|
|
|
$ mkisofs -R -b boot/grub/stage2_eltorito -no-emul-boot \
|
|
-boot-load-size 4 -boot-info-table -o grub.iso iso
|
|
|
|
This produces a file named `grub.iso', which then can be burned into
|
|
a CD (or a DVD). `mkisofs' has already set up the disc to boot from
|
|
the `boot/grub/stage2_eltorito' file, so there is no need to setup GRUB
|
|
on the disc. (Note that the `-boot-load-size 4' bit is required for
|
|
compatibility with the BIOS on many older machines.)
|
|
|
|
You can use the device `(cd)' to access a CD-ROM in your config
|
|
file. This is not required; GRUB automatically sets the root device to
|
|
`(cd)' when booted from a CD-ROM. It is only necessary to refer to
|
|
`(cd)' if you want to access other drives as well.
|
|
|
|
(1) El Torito is a specification for bootable CD using BIOS
|
|
functions.
|
|
|
|
4 Booting
|
|
*********
|
|
|
|
GRUB can load Multiboot-compliant kernels in a consistent way, but for
|
|
some free operating systems you need to use some OS-specific magic.
|
|
|
|
4.1 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 more 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.
|
|
|
|
4.1.1 How to boot an OS directly with GRUB
|
|
------------------------------------------
|
|
|
|
Multiboot (*note Multiboot Specification: (multiboot)Top.) is the
|
|
native format supported by GRUB. For the sake of convenience, there is
|
|
also support for Linux, FreeBSD, NetBSD and OpenBSD. If you want to
|
|
boot other operating systems, you will have to chain-load them (*note
|
|
Chain-loading::).
|
|
|
|
Generally, GRUB can boot any Multiboot-compliant OS in the following
|
|
steps:
|
|
|
|
1. Set GRUB's root device to the drive where the OS images are stored
|
|
with the command `root' (*note root::).
|
|
|
|
2. Load the kernel image with the command `kernel' (*note kernel::).
|
|
|
|
3. If you need modules, load them with the command `module' (*note
|
|
module::) or `modulenounzip' (*note modulenounzip::).
|
|
|
|
4. Run the command `boot' (*note boot::).
|
|
|
|
Linux, FreeBSD, NetBSD and OpenBSD can be booted in a similar
|
|
manner. You load a kernel image with the command `kernel' and then run
|
|
the command `boot'. If the kernel requires some parameters, just append
|
|
the parameters to `kernel', after the file name of the kernel. Also,
|
|
please refer to *Note OS-specific notes::, for information on your
|
|
OS-specific issues.
|
|
|
|
4.1.2 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 "boot sector" of the partition on which the
|
|
operating system is installed.
|
|
|
|
1. Set GRUB's root device to the partition by the command
|
|
`rootnoverify' (*note rootnoverify::):
|
|
|
|
grub> rootnoverify (hd0,0)
|
|
|
|
2. Set the "active" flag in the partition using the command
|
|
`makeactive'(1) (*note Chain-loading-Footnote-1::) (*note
|
|
makeactive::):
|
|
|
|
grub> makeactive
|
|
|
|
3. Load the boot loader with the command `chainloader' (*note
|
|
chainloader::):
|
|
|
|
grub> chainloader +1
|
|
|
|
`+1' indicates that GRUB should read one sector from the start of
|
|
the partition. The complete description about this syntax can be
|
|
found in *Note Block list syntax::.
|
|
|
|
4. Run the command `boot' (*note boot::).
|
|
|
|
However, DOS and Windows have some deficiencies, so you might have to
|
|
use more complicated instructions. *Note DOS/Windows::, for more
|
|
information.
|
|
|
|
(1) This is not necessary for most of the modern operating systems.
|
|
|
|
4.2 Some caveats on OS-specific issues
|
|
======================================
|
|
|
|
Here, we describe some caveats on several operating systems.
|
|
|
|
4.2.1 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.
|
|
|
|
1. Set GRUB's root device to the same drive as GNU/Hurd's. Probably
|
|
the command `find /boot/gnumach' or similar can help you (*note
|
|
find::).
|
|
|
|
2. Load the kernel and the module, like this:
|
|
|
|
grub> kernel /boot/gnumach root=hd0s1
|
|
grub> module /boot/serverboot
|
|
|
|
3. Run the command `boot' (*note boot::).
|
|
|
|
4.2.2 GNU/Linux
|
|
---------------
|
|
|
|
It is relatively easy to boot GNU/Linux from GRUB, because it somewhat
|
|
resembles to boot a Multiboot-compliant OS.
|
|
|
|
1. Set GRUB's root device to the same drive as GNU/Linux's. Probably
|
|
the command `find /vmlinuz' or similar can help you (*note find::).
|
|
|
|
2. Load the kernel:
|
|
|
|
grub> kernel /vmlinuz root=/dev/hda1
|
|
|
|
If you need to specify some kernel parameters, just append them to
|
|
the command. For example, to set `vga' to `ext', do this:
|
|
|
|
grub> kernel /vmlinuz root=/dev/hda1 vga=ext
|
|
|
|
See the documentation in the Linux source tree for complete
|
|
information on the available options.
|
|
|
|
3. If you use an initrd, execute the command `initrd' (*note
|
|
initrd::) after `kernel':
|
|
|
|
grub> initrd /initrd
|
|
|
|
4. Finally, run the command `boot' (*note boot::).
|
|
|
|
*Caution:* If you use an initrd and specify the `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 `uppermem' _before_ loading the kernel. *Note uppermem::,
|
|
for more information.
|
|
|
|
4.2.3 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 `/boot/loader'
|
|
instead. See this example:
|
|
|
|
grub> root (hd0,a)
|
|
grub> kernel /boot/loader
|
|
grub> boot
|
|
|
|
4.2.4 NetBSD
|
|
------------
|
|
|
|
GRUB can load NetBSD a.out and ELF directly, follow these steps:
|
|
|
|
1. Set GRUB's root device with `root' (*note root::).
|
|
|
|
2. Load the kernel with `kernel' (*note kernel::). You should append
|
|
the ugly option `--type=netbsd', if you want to load an ELF
|
|
kernel, like this:
|
|
|
|
grub> kernel --type=netbsd /netbsd-elf
|
|
|
|
3. Run `boot' (*note boot::).
|
|
|
|
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 *Note Chain-loading::.
|
|
|
|
4.2.5 OpenBSD
|
|
-------------
|
|
|
|
The booting instruction is exactly the same as for NetBSD (*note
|
|
NetBSD::).
|
|
|
|
4.2.6 DOS/Windows
|
|
-----------------
|
|
|
|
GRUB cannot boot DOS or Windows directly, so you must chain-load them
|
|
(*note 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 `map' (*note map::), like this:
|
|
|
|
grub> map (hd0) (hd1)
|
|
grub> map (hd1) (hd0)
|
|
|
|
This performs a "virtual" swap between your first and second hard
|
|
drive.
|
|
|
|
*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 "hide"s a DOS (or Windows) partition (*note hide::), DOS (or
|
|
Windows) will ignore the partition. If GRUB "unhide"s a DOS (or
|
|
Windows) partition (*note unhide::), DOS (or Windows) will detect the
|
|
partition. Thus, if you have installed DOS (or Windows) on the first
|
|
and the second partition of the first hard disk, and you want to boot
|
|
the copy on the first partition, do the following:
|
|
|
|
grub> unhide (hd0,0)
|
|
grub> hide (hd0,1)
|
|
grub> rootnoverify (hd0,0)
|
|
grub> chainloader +1
|
|
grub> makeactive
|
|
grub> boot
|
|
|
|
4.2.7 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 `--force' to
|
|
`chainloader' (*note chainloader::), like this:
|
|
|
|
grub> rootnoverify (hd1,0)
|
|
grub> chainloader --force +1
|
|
grub> makeactive
|
|
grub> boot
|
|
|
|
4.2.8 QNX
|
|
---------
|
|
|
|
QNX seems to use a bigger boot loader, so you need to boot it up, like
|
|
this:
|
|
|
|
grub> rootnoverify (hd1,1)
|
|
grub> chainloader +4
|
|
grub> boot
|
|
|
|
4.3 How to make your system robust
|
|
==================================
|
|
|
|
When you test a new kernel or a new OS, it is important to make sure
|
|
that your computer can boot even if the new system is unbootable. This
|
|
is crucial especially if you maintain servers or remote systems. To
|
|
accomplish this goal, you need to set up two things:
|
|
|
|
1. You must maintain a system which is always bootable. For instance,
|
|
if you test a new kernel, you need to keep a working kernel in a
|
|
different place. And, it would sometimes be very nice to even have
|
|
a complete copy of a working system in a different partition or
|
|
disk.
|
|
|
|
2. You must direct GRUB to boot a working system when the new system
|
|
fails. This is possible with the "fallback" system in GRUB.
|
|
|
|
The former requirement is very specific to each OS, so this
|
|
documentation does not cover that topic. It is better to consult some
|
|
backup tools.
|
|
|
|
So let's see the GRUB part. There are two possibilities: one of them
|
|
is quite simple but not very robust, and the other is a bit complex to
|
|
set up but probably the best solution to make sure that your system can
|
|
start as long as GRUB itself is bootable.
|
|
|
|
4.3.1 Booting once-only
|
|
-----------------------
|
|
|
|
You can teach GRUB to boot an entry only at next boot time. Suppose
|
|
that your have an old kernel `old_kernel' and a new kernel
|
|
`new_kernel'. You know that `old_kernel' can boot your system
|
|
correctly, and you want to test `new_kernel'.
|
|
|
|
To ensure that your system will go back to the old kernel even if the
|
|
new kernel fails (e.g. it panics), you can specify that GRUB should try
|
|
the new kernel only once and boot the old kernel after that.
|
|
|
|
First, modify your configuration file. Here is an example:
|
|
|
|
default saved # This is important!!!
|
|
timeout 10
|
|
|
|
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!!!
|
|
|
|
Note that this configuration file uses `default saved' (*note
|
|
default::) at the head and `savedefault 0' (*note 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 `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 `0' is the entry of
|
|
`the old kernel'.
|
|
|
|
The next step is to tell GRUB to boot the new kernel at next boot
|
|
time. For this, execute `grub-set-default' (*note Invoking
|
|
grub-set-default::):
|
|
|
|
# grub-set-default 1
|
|
|
|
This command sets the saved entry to `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 "fallback" mechanism of GRUB. Look at next subsection for this
|
|
feature.
|
|
|
|
4.3.2 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, `A', `B' and `C'. `A' is a
|
|
system which you want to boot by default. `B' is a backup system which
|
|
is supposed to boot safely. `C' is another backup system which is used
|
|
in case where `B' is broken.
|
|
|
|
Then you may want GRUB to boot the first system which is bootable
|
|
among `A', `B' and `C'. A configuration file can be written in this way:
|
|
|
|
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
|
|
|
|
Note that `default saved' (*note default::), `fallback 1 2' and
|
|
`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 `A', GRUB saves `1' as next boot entry,
|
|
because the command `fallback' specifies that `1' is the first fallback
|
|
entry. The entry `1' is `B', so GRUB will try to boot `B' at next boot
|
|
time.
|
|
|
|
Likewise, when GRUB tries to boot `B', GRUB saves `2' as next boot
|
|
entry, because `fallback' specifies `2' as next fallback entry. This
|
|
makes sure that GRUB will boot `C' after booting `B'.
|
|
|
|
It is noteworthy that GRUB uses fallback entries both when GRUB
|
|
itself fails in booting an entry and when `A' or `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 `grub-set-default' (*note Invoking
|
|
grub-set-default::) when `A' starts correctly or you fix `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 `rc.local' to
|
|
boot `A' by default:
|
|
|
|
# grub-set-default 0
|
|
|
|
where `0' is the number of the boot entry for the system `A'.
|
|
|
|
If you want to see what is current default entry, you can look at the
|
|
file `/boot/grub/default' (or `/grub/default' in some systems). Because
|
|
this file is plain-text, you can just `cat' this file. But it is
|
|
strongly recommended *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
|
|
`grub-set-default' when you need to change the default entry.
|
|
|
|
5 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
|
|
(*note 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, `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 (*note Menu-specific
|
|
commands::) before any of the items (starting with `title' (*note
|
|
title::)).
|
|
|
|
#
|
|
# Sample boot menu configuration file
|
|
#
|
|
|
|
As you may have guessed, these lines are comments. Lines starting
|
|
with a hash character (`#'), and blank lines, are ignored by GRUB.
|
|
|
|
# By default, boot the first entry.
|
|
default 0
|
|
|
|
The first entry (here, counting starts with number zero, not one!)
|
|
will be the default choice.
|
|
|
|
# Boot automatically after 30 secs.
|
|
timeout 30
|
|
|
|
As the comment says, GRUB will boot automatically in 30 seconds,
|
|
unless interrupted with a keypress.
|
|
|
|
# Fallback to the second entry.
|
|
fallback 1
|
|
|
|
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 *Note Menu-specific commands::.
|
|
Other descriptions can be found in *Note Commands::.
|
|
|
|
Now, on to the actual OS definitions. You will see that each entry
|
|
begins with a special command, `title' (*note title::), and the action
|
|
is described after it. Note that there is no command `boot' (*note
|
|
boot::) at the end of each item. That is because GRUB automatically
|
|
executes `boot' if it loads other commands successfully.
|
|
|
|
The argument for the command `title' is used to display a short
|
|
title/description of the entry in the menu. Since `title' displays the
|
|
argument as is, you can write basically anything there.
|
|
|
|
# For booting GNU/Hurd
|
|
title GNU/Hurd
|
|
root (hd0,0)
|
|
kernel /boot/gnumach.gz root=hd0s1
|
|
module /boot/serverboot.gz
|
|
|
|
This boots GNU/Hurd from the first hard disk.
|
|
|
|
# For booting GNU/Linux
|
|
title GNU/Linux
|
|
kernel (hd1,0)/vmlinuz root=/dev/hdb1
|
|
|
|
This boots GNU/Linux, but from the second hard disk.
|
|
|
|
# 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
|
|
|
|
This boots Mach with a kernel on a floppy, but the root filesystem at
|
|
hd0s3. It also contains a `pause' line (*note pause::), which will
|
|
cause GRUB to display a prompt and delay, before actually executing the
|
|
rest of the commands and booting.
|
|
|
|
# For booting FreeBSD
|
|
title FreeBSD
|
|
root (hd0,2,a)
|
|
kernel /boot/loader
|
|
|
|
This item will boot FreeBSD kernel loaded from the `a' partition of
|
|
the third PC slice of the first hard disk.
|
|
|
|
# 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
|
|
|
|
This will boot OS/2, using a chain-loader (*note Chain-loading::).
|
|
|
|
# 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
|
|
|
|
The same as the above, but for Windows.
|
|
|
|
# For installing GRUB into the hard disk
|
|
title Install GRUB into the hard disk
|
|
root (hd0,0)
|
|
setup (hd0)
|
|
|
|
This will just (re)install GRUB onto the hard disk.
|
|
|
|
# Change the colors.
|
|
title Change the colors
|
|
color light-green/brown blink-red/blue
|
|
|
|
In the last entry, the command `color' is used (*note 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 *Note 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.
|
|
|
|
6 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 `netboot/README.netboot' in the source distribution.
|
|
|
|
6.1 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(1) (*note General usage of network support-Footnote-1::).
|
|
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 `bootp' (*note bootp::), `dhcp' (*note dhcp::) or `rarp'
|
|
(*note 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 `ifconfig', like this:
|
|
|
|
grub> ifconfig --address=192.168.110.23 --server=192.168.110.14
|
|
|
|
You can also use `ifconfig' in conjuction with `bootp', `dhcp' or
|
|
`rarp' (e.g. to reassign the server address manually). *Note
|
|
ifconfig::, for more details.
|
|
|
|
Finally, download your OS images from your network. The network can
|
|
be accessed using the network drive `(nd)'. Everything else is very
|
|
similar to the normal instructions (*note Booting::).
|
|
|
|
Here is an example:
|
|
|
|
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
|
|
|
|
(1) RARP is not advised, since it cannot serve much information
|
|
|
|
6.2 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 ROM, such as a PXE ROM or a free software package
|
|
like Etherboot. Such a Boot 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.
|
|
|
|
GRUB provides two second stage images, `nbgrub' and `pxegrub' (*note
|
|
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 ROM, use `pxegrub'. If the machine has an NBI loader
|
|
such as Etherboot, use `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 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
|
|
`150', to get the name of a configuration file. The following is an
|
|
example with a BOOTP configuration:
|
|
|
|
.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":
|
|
|
|
Note that you should specify the drive name `(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 (*note Preset Menu::).
|
|
|
|
See the manual of your BOOTP/DHCP server for more information. The
|
|
exact syntax should differ a little from the example.
|
|
|
|
7 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
|
|
`--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:
|
|
|
|
grub> serial --unit=0 --speed=9600
|
|
grub> terminal serial
|
|
|
|
The command `serial' initializes the serial unit 0 with the speed
|
|
9600bps. The serial unit 0 is usually called `COM1', so, if you want to
|
|
use COM2, you must specify `--unit=1' instead. This command accepts
|
|
many other options, so please refer to *Note serial::, for more details.
|
|
|
|
The command `terminal' (*note 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 `console' to the command, as
|
|
`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 `--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.
|
|
|
|
8 Embedding a configuration file into GRUB
|
|
******************************************
|
|
|
|
GRUB supports a "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 `serial' (*note serial::) and `terminal'
|
|
(*note terminal::) before anything else at the start-up time.
|
|
|
|
How the preset menu works is slightly complicated:
|
|
|
|
1. 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.
|
|
|
|
2. GRUB checks if the configuration file is available. Note that this
|
|
check is performed *regardless of the existence of the preset
|
|
menu*. The configuration file is loaded even if the preset menu was
|
|
loaded.
|
|
|
|
3. 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.
|
|
|
|
To enable the preset menu feature, you must rebuild GRUB specifying a
|
|
file to the configure script with the option `--enable-preset-menu'.
|
|
The file has the same semantics as normal configuration files (*note
|
|
Configuration::).
|
|
|
|
Another point you should take care is that the diskless support
|
|
(*note Diskless::) diverts the preset menu. Diskless images embed a
|
|
preset menu to execute the command `bootp' (*note 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:
|
|
|
|
# Set up the serial terminal, first of all.
|
|
serial --unit=0 --speed=19200
|
|
terminal --timeout=0 serial
|
|
|
|
# Initialize the network.
|
|
dhcp
|
|
|
|
9 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 `/etc/passwd' in the command-line interface by the
|
|
command `cat' (*note cat::). So it is necessary to disable all the
|
|
interactive operations.
|
|
|
|
Thus, GRUB provides a "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 `password' in your configuration file (*note
|
|
password::), like this:
|
|
|
|
password --md5 PASSWORD
|
|
|
|
If this is specified, GRUB disallows any interactive control, until
|
|
you press the key <p> and enter a correct password. The option `--md5'
|
|
tells GRUB that `PASSWORD' is in MD5 format. If it is omitted, GRUB
|
|
assumes the `PASSWORD' is in clear text.
|
|
|
|
You can encrypt your password with the command `md5crypt' (*note
|
|
md5crypt::). For example, run the grub shell (*note Invoking the grub
|
|
shell::), and enter your password:
|
|
|
|
grub> md5crypt
|
|
Password: **********
|
|
Encrypted: $1$U$JK7xFegdxWH6VuppCUSIb.
|
|
|
|
Then, cut and paste the encrypted password to your configuration
|
|
file.
|
|
|
|
Also, you can specify an optional argument to `password'. See this
|
|
example:
|
|
|
|
password PASSWORD /boot/grub/menu-admin.lst
|
|
|
|
In this case, GRUB will load `/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 `lock' (*note lock::). This command always
|
|
fails until you enter the valid password, so you can use it, like this:
|
|
|
|
title Boot DOS
|
|
lock
|
|
rootnoverify (hd0,1)
|
|
makeactive
|
|
chainload +1
|
|
|
|
You should insert `lock' right after `title', because any user can
|
|
execute commands in an entry until GRUB encounters `lock'.
|
|
|
|
You can also use the command `password' instead of `lock'. In this
|
|
case the boot process will ask for the password and stop if it was
|
|
entered incorrectly. Since the `password' takes its own PASSWORD
|
|
argument this is useful if you want different passwords for different
|
|
entries.
|
|
|
|
10 GRUB image files
|
|
*******************
|
|
|
|
GRUB consists of several images: two essential stages, optional stages
|
|
called "Stage 1.5", one image for bootable CD-ROM, and two network boot
|
|
images. Here is a short overview of them. *Note Internals::, for more
|
|
details.
|
|
|
|
`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 `stage1' must do is to load Stage 2 or Stage 1.5 from a local
|
|
disk. Because of the size restriction, `stage1' encodes the
|
|
location of Stage 2 (or Stage 1.5) in a block list format, so it
|
|
never understand any filesystem structure.
|
|
|
|
`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.
|
|
|
|
`e2fs_stage1_5'
|
|
`fat_stage1_5'
|
|
`ffs_stage1_5'
|
|
`jfs_stage1_5'
|
|
`minix_stage1_5'
|
|
`reiserfs_stage1_5'
|
|
`vstafs_stage1_5'
|
|
`xfs_stage1_5'
|
|
These are called "Stage 1.5", because they serve as a bridge
|
|
between `stage1' and `stage2', that is to say, Stage 1.5 is loaded
|
|
by Stage 1 and Stage 1.5 loads Stage 2. The difference between
|
|
`stage1' and `*_stage1_5' is that the former doesn't understand
|
|
any filesystem while the latter understands one filesystem (e.g.
|
|
`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.
|
|
|
|
`stage2_eltorito'
|
|
This is a boot image for CD-ROMs using the "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 `(cd)'.
|
|
|
|
`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.
|
|
|
|
`pxegrub'
|
|
This is another network boot image for the Preboot Execution
|
|
Environment used by several Netboot ROMs. This is identical to
|
|
`nbgrub', except for the format.
|
|
|
|
11 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 `find' (*note find::).
|
|
|
|
11.1 How to specify devices
|
|
===========================
|
|
|
|
The device syntax is like this:
|
|
|
|
`(DEVICE[,PART-NUM][,BSD-SUBPART-LETTER])'
|
|
|
|
`[]' means the parameter is optional. DEVICE should be either `fd'
|
|
or `hd' followed by a digit, like `fd0'. But you can also set DEVICE
|
|
to a hexadecimal or a decimal number which is a BIOS drive number, so
|
|
the following are equivalent:
|
|
|
|
(hd0)
|
|
(0x80)
|
|
(128)
|
|
|
|
PART-NUM represents the partition number of DEVICE, starting from
|
|
zero for primary partitions and from four for extended partitions, and
|
|
BSD-SUBPART-LETTER represents the BSD disklabel subpartition, such as
|
|
`a' or `e'.
|
|
|
|
A shortcut for specifying BSD subpartitions is
|
|
`(DEVICE,BSD-SUBPART-LETTER)', in this case, GRUB searches for the
|
|
first PC partition containing a BSD disklabel, then finds the
|
|
subpartition BSD-SUBPART-LETTER. Here is an example:
|
|
|
|
(hd0,a)
|
|
|
|
The syntax `(hd0)' represents using the entire disk (or the MBR when
|
|
installing GRUB), while the syntax `(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, `(nd)', is
|
|
also available. Before using the network drive, you must initialize the
|
|
network. *Note Network::, for more information.
|
|
|
|
If you boot GRUB from a CD-ROM, `(cd)' is available. *Note Making a
|
|
GRUB bootable CD-ROM::, for details.
|
|
|
|
11.2 How to specify files
|
|
=========================
|
|
|
|
There are two ways to specify files, by "absolute file name" and by
|
|
"block list".
|
|
|
|
An absolute file name resembles a Unix absolute file name, using `/'
|
|
for the directory separator (not `\' as in DOS). One example is
|
|
`(hd0,0)/boot/grub/menu.lst'. This means the file `/boot/grub/menu.lst'
|
|
in the first partition of the first hard disk. If you omit the device
|
|
name in an absolute file name, GRUB uses GRUB's "root device"
|
|
implicitly. So if you set the root device to, say, `(hd1,0)' by the
|
|
command `root' (*note root::), then `/boot/kernel' is the same as
|
|
`(hd1,0)/boot/kernel'.
|
|
|
|
11.3 How to specify block lists
|
|
===============================
|
|
|
|
A block list is used for specifying a file that doesn't appear in the
|
|
filesystem, like a chainloader. The syntax is
|
|
`[OFFSET]+LENGTH[,[OFFSET]+LENGTH]...'. Here is an example:
|
|
|
|
`0+100,200+1,300+300'
|
|
|
|
This represents that GRUB should read blocks 0 through 99, block 200,
|
|
and blocks 300 through 599. If you omit an offset, then GRUB assumes
|
|
the offset is zero.
|
|
|
|
Like the file name syntax (*note File name syntax::), if a blocklist
|
|
does not contain a device name, then GRUB uses GRUB's "root device". So
|
|
`(hd0,1)+1' is the same as `+1' when the root device is `(hd0,1)'.
|
|
|
|
12 GRUB's user interface
|
|
************************
|
|
|
|
GRUB has both a simple menu interface for choosing preset entries from a
|
|
configuration file, and a highly flexible command-line for performing
|
|
any desired combination of boot commands.
|
|
|
|
GRUB looks for its configuration file as soon as it is loaded. If one
|
|
is found, then the full menu interface is activated using whatever
|
|
entries were found in the file. If you choose the "command-line" menu
|
|
option, or if the configuration file was not found, then GRUB drops to
|
|
the command-line interface.
|
|
|
|
12.1 The flexible command-line interface
|
|
========================================
|
|
|
|
The command-line interface provides a prompt and after it an editable
|
|
text area much like a command-line in Unix or DOS. Each command is
|
|
immediately executed after it is entered(1) (*note Command-line
|
|
interface-Footnote-1::). The commands (*note Command-line and menu
|
|
entry commands::) are a subset of those available in the configuration
|
|
file, used with exactly the same syntax.
|
|
|
|
Cursor movement and editing of the text on the line can be done via a
|
|
subset of the functions available in the Bash shell:
|
|
|
|
<C-f>
|
|
<PC right key>
|
|
Move forward one character.
|
|
|
|
<C-b>
|
|
<PC left key>
|
|
Move back one character.
|
|
|
|
<C-a>
|
|
<HOME>
|
|
Move to the start of the line.
|
|
|
|
<C-e>
|
|
<END>
|
|
Move the the end of the line.
|
|
|
|
<C-d>
|
|
<DEL>
|
|
Delete the character underneath the cursor.
|
|
|
|
<C-h>
|
|
<BS>
|
|
Delete the character to the left of the cursor.
|
|
|
|
<C-k>
|
|
Kill the text from the current cursor position to the end of the
|
|
line.
|
|
|
|
<C-u>
|
|
Kill backward from the cursor to the beginning of the line.
|
|
|
|
<C-y>
|
|
Yank the killed text back into the buffer at the cursor.
|
|
|
|
<C-p>
|
|
<PC up key>
|
|
Move up through the history list.
|
|
|
|
<C-n>
|
|
<PC down key>
|
|
Move down through the history list.
|
|
|
|
When typing commands interactively, if the cursor is within or before
|
|
the first word in the command-line, pressing the <TAB> key (or <C-i>)
|
|
will display a listing of the available commands, and if the cursor is
|
|
after the first word, the `<TAB>' will provide a completion listing of
|
|
disks, partitions, and file names depending on the context. Note that
|
|
to obtain a list of drives, one must open a parenthesis, as `root ('.
|
|
|
|
Note that you cannot use the completion functionality in the TFTP
|
|
filesystem. This is because TFTP doesn't support file name listing for
|
|
the security.
|
|
|
|
(1) However, this behavior will be changed in the future version, in
|
|
a user-invisible way.
|
|
|
|
12.2 The simple menu interface
|
|
==============================
|
|
|
|
The menu interface is quite easy to use. Its commands are both
|
|
reasonably intuitive and described on screen.
|
|
|
|
Basically, the menu interface provides a list of "boot entries" to
|
|
the user to choose from. Use the arrow keys to select the entry of
|
|
choice, then press <RET> to run it. An optional timeout is available
|
|
to boot the default entry (the first one if not set), which is aborted
|
|
by pressing any key.
|
|
|
|
Commands are available to enter a bare command-line by pressing <c>
|
|
(which operates exactly like the non-config-file version of GRUB, but
|
|
allows one to return to the menu if desired by pressing <ESC>) or to
|
|
edit any of the "boot entries" by pressing <e>.
|
|
|
|
If you protect the menu interface with a password (*note Security::),
|
|
all you can do is choose an entry by pressing <RET>, or press <p> to
|
|
enter the password.
|
|
|
|
12.3 Editing a menu entry
|
|
=========================
|
|
|
|
The menu entry editor looks much like the main menu interface, but the
|
|
lines in the menu are individual commands in the selected entry instead
|
|
of entry names.
|
|
|
|
If an <ESC> is pressed in the editor, it aborts all the changes made
|
|
to the configuration entry and returns to the main menu interface.
|
|
|
|
When a particular line is selected, the editor places the user in a
|
|
special version of the GRUB command-line to edit that line. When the
|
|
user hits <RET>, GRUB replaces the line in question in the boot entry
|
|
with the changes (unless it was aborted via <ESC>, in which case the
|
|
changes are thrown away).
|
|
|
|
If you want to add a new line to the menu entry, press <o> if adding
|
|
a line after the current line or press <O> if before the current line.
|
|
|
|
To delete a line, hit the key <d>. Although GRUB unfortunately does
|
|
not support "undo", you can do almost the same thing by just returning
|
|
to the main menu.
|
|
|
|
12.4 The hidden menu interface
|
|
==============================
|
|
|
|
When your terminal is dumb or you request GRUB to hide the menu
|
|
interface explicitly with the command `hiddenmenu' (*note
|
|
hiddenmenu::), GRUB doesn't show the menu interface (*note Menu
|
|
interface::) and automatically boots the default entry, unless
|
|
interrupted by pressing <ESC>.
|
|
|
|
When you interrupt the timeout and your terminal is dumb, GRUB falls
|
|
back to the command-line interface (*note Command-line interface::).
|
|
|
|
13 The list of available commands
|
|
*********************************
|
|
|
|
In this chapter, we list all commands that are available in GRUB.
|
|
|
|
Commands belong to different groups. A few can only be used in the
|
|
global section of the configuration file (or "menu"); most of them can
|
|
be entered on the command-line and can be used either anywhere in the
|
|
menu or specifically in the menu entries.
|
|
|
|
13.1 The list of commands for the menu only
|
|
===========================================
|
|
|
|
The semantics used in parsing the configuration file are the following:
|
|
|
|
* The menu-specific commands have to be used before any others.
|
|
|
|
* The files _must_ be in plain-text format.
|
|
|
|
* `#' at the beginning of a line in a configuration file means it is
|
|
only a comment.
|
|
|
|
* Options are separated by spaces.
|
|
|
|
* All numbers can be either decimal or hexadecimal. A hexadecimal
|
|
number must be preceded by `0x', and is case-insensitive.
|
|
|
|
* Extra options or text at the end of the line are ignored unless
|
|
otherwise specified.
|
|
|
|
* Unrecognized commands are added to the current entry, except
|
|
before entries start, where they are ignored.
|
|
|
|
These commands can only be used in the menu:
|
|
|
|
13.1.1 default
|
|
--------------
|
|
|
|
-- Command: default num
|
|
Set the default entry to the entry number NUM. Numbering starts
|
|
from 0, and the entry number 0 is the default if the command is not
|
|
used.
|
|
|
|
You can specify `saved' instead of a number. In this case, the
|
|
default entry is the entry saved with the command `savedefault'.
|
|
*Note savedefault::, for more information.
|
|
|
|
13.1.2 fallback
|
|
---------------
|
|
|
|
-- Command: fallback num...
|
|
Go into unattended boot mode: if the default boot entry has any
|
|
errors, instead of waiting for the user to do something,
|
|
immediately start over using the NUM entry (same numbering as the
|
|
`default' command (*note default::)). This obviously won't help if
|
|
the machine was rebooted by a kernel that GRUB loaded. You can
|
|
specify multiple fallback entry numbers.
|
|
|
|
13.1.3 hiddenmenu
|
|
-----------------
|
|
|
|
-- Command: hiddenmenu
|
|
Don't display the menu. If the command is used, no menu will be
|
|
displayed on the control terminal, and the default entry will be
|
|
booted after the timeout expired. The user can still request the
|
|
menu to be displayed by pressing <ESC> before the timeout expires.
|
|
See also *Note Hidden menu interface::.
|
|
|
|
13.1.4 timeout
|
|
--------------
|
|
|
|
-- Command: timeout sec
|
|
Set a timeout, in SEC seconds, before automatically booting the
|
|
default entry (normally the first entry defined).
|
|
|
|
13.1.5 title
|
|
------------
|
|
|
|
-- Command: title name ...
|
|
Start a new boot entry, and set its name to the contents of the
|
|
rest of the line, starting with the first non-space character.
|
|
|
|
13.2 The list of general commands
|
|
=================================
|
|
|
|
Commands usable anywhere in the menu and in the command-line.
|
|
|
|
13.2.1 bootp
|
|
------------
|
|
|
|
-- Command: bootp [`--with-configfile']
|
|
Initialize a network device via the "BOOTP" protocol. This command
|
|
is only available if GRUB is compiled with netboot support. See
|
|
also *Note Network::.
|
|
|
|
If you specify `--with-configfile' to this command, GRUB will
|
|
fetch and load a configuration file specified by your BOOTP server
|
|
with the vendor tag `150'.
|
|
|
|
13.2.2 color
|
|
------------
|
|
|
|
-- Command: color normal [highlight]
|
|
Change the menu colors. The color NORMAL is used for most lines in
|
|
the menu (*note Menu interface::), and the color HIGHLIGHT is used
|
|
to highlight the line where the cursor points. If you omit
|
|
HIGHLIGHT, then the inverted color of NORMAL is used for the
|
|
highlighted line. The format of a color is
|
|
`FOREGROUND/BACKGROUND'. FOREGROUND and BACKGROUND are symbolic
|
|
color names. A symbolic color name must be one of these:
|
|
|
|
* black
|
|
|
|
* blue
|
|
|
|
* green
|
|
|
|
* cyan
|
|
|
|
* red
|
|
|
|
* magenta
|
|
|
|
* brown
|
|
|
|
* light-gray
|
|
|
|
*These below can be specified only for the foreground.*
|
|
|
|
* dark-gray
|
|
|
|
* light-blue
|
|
|
|
* light-green
|
|
|
|
* light-cyan
|
|
|
|
* light-red
|
|
|
|
* light-magenta
|
|
|
|
* yellow
|
|
|
|
* white
|
|
|
|
But only the first eight names can be used for BACKGROUND. You can
|
|
prefix `blink-' to FOREGROUND if you want a blinking foreground
|
|
color.
|
|
|
|
This command can be used in the configuration file and on the
|
|
command line, so you may write something like this in your
|
|
configuration file:
|
|
|
|
# Set default colors.
|
|
color light-gray/blue black/light-gray
|
|
|
|
# Change the colors.
|
|
title OS-BS like
|
|
color magenta/blue black/magenta
|
|
|
|
13.2.3 device
|
|
-------------
|
|
|
|
-- Command: device drive file
|
|
In the grub shell, specify the file FILE as the actual drive for a
|
|
BIOS drive DRIVE. You can use this command to create a disk image,
|
|
and/or to fix the drives guessed by GRUB when GRUB fails to
|
|
determine them correctly, like this:
|
|
|
|
grub> device (fd0) /floppy-image
|
|
grub> device (hd0) /dev/sd0
|
|
|
|
This command can be used only in the grub shell (*note Invoking
|
|
the grub shell::).
|
|
|
|
13.2.4 dhcp
|
|
-----------
|
|
|
|
-- Command: dhcp [-with-configfile]
|
|
Initialize a network device via the "DHCP" protocol. Currently,
|
|
this command is just an alias for `bootp', since the two protocols
|
|
are very similar. This command is only available if GRUB is
|
|
compiled with netboot support. See also *Note Network::.
|
|
|
|
If you specify `--with-configfile' to this command, GRUB will
|
|
fetch and load a configuration file specified by your DHCP server
|
|
with the vendor tag `150'.
|
|
|
|
13.2.5 hide
|
|
-----------
|
|
|
|
-- Command: hide partition
|
|
Hide the partition PARTITION by setting the "hidden" bit in its
|
|
partition type code. This is useful only when booting DOS or
|
|
Windows and multiple primary FAT partitions exist in one disk. See
|
|
also *Note DOS/Windows::.
|
|
|
|
13.2.6 ifconfig
|
|
---------------
|
|
|
|
-- Command: ifconfig [`--server=server'] [`--gateway=gateway']
|
|
[`--mask=mask'] [`--address=address']
|
|
Configure the IP address, the netmask, the gateway, and the server
|
|
address of a network device manually. The values must be in dotted
|
|
decimal format, like `192.168.11.178'. The order of the options is
|
|
not important. This command shows current network configuration,
|
|
if no option is specified. See also *Note Network::.
|
|
|
|
13.2.7 pager
|
|
------------
|
|
|
|
-- Command: pager [flag]
|
|
Toggle or set the state of the internal pager. If FLAG is `on',
|
|
the internal pager is enabled. If FLAG is `off', it is disabled.
|
|
If no argument is given, the state is toggled.
|
|
|
|
13.2.8 partnew
|
|
--------------
|
|
|
|
-- Command: partnew part type from len
|
|
Create a new primary partition. PART is a partition specification
|
|
in GRUB syntax (*note Naming convention::); TYPE is the partition
|
|
type and must be a number in the range `0-0xff'; FROM is the
|
|
starting address and LEN is the length, both in sector units.
|
|
|
|
13.2.9 parttype
|
|
---------------
|
|
|
|
-- Command: parttype part type
|
|
Change the type of an existing partition. PART is a partition
|
|
specification in GRUB syntax (*note Naming convention::); TYPE is
|
|
the new partition type and must be a number in the range 0-0xff.
|
|
|
|
13.2.10 password
|
|
----------------
|
|
|
|
-- Command: password [`--md5'] passwd [new-config-file]
|
|
If used in the first section of a menu file, disable all
|
|
interactive editing control (menu entry editor and command-line)
|
|
and entries protected by the command `lock'. If the password
|
|
PASSWD is entered, it loads the NEW-CONFIG-FILE as a new config
|
|
file and restarts the GRUB Stage 2, if NEW-CONFIG-FILE is
|
|
specified. Otherwise, GRUB will just unlock the privileged
|
|
instructions. You can also use this command in the script
|
|
section, in which case it will ask for the password, before
|
|
continuing. The option `--md5' tells GRUB that PASSWD is
|
|
encrypted with `md5crypt' (*note md5crypt::).
|
|
|
|
13.2.11 rarp
|
|
------------
|
|
|
|
-- Command: rarp
|
|
Initialize a network device via the "RARP" protocol. This command
|
|
is only available if GRUB is compiled with netboot support. See
|
|
also *Note Network::.
|
|
|
|
13.2.12 serial
|
|
--------------
|
|
|
|
-- Command: serial [`--unit=unit'] [`--port=port'] [`--speed=speed']
|
|
[`--word=word'] [`--parity=parity'] [`--stop=stop']
|
|
[`--device=dev']
|
|
Initialize a serial device. UNIT is a number in the range 0-3
|
|
specifying which serial port to use; default is 0, which
|
|
corresponds to the port often called COM1. PORT is the I/O port
|
|
where the UART is to be found; if specified it takes precedence
|
|
over UNIT. SPEED is the transmission speed; default is 9600. WORD
|
|
and STOP are the number of data bits and stop bits. Data bits must
|
|
be in the range 5-8 and stop bits must be 1 or 2. Default is 8 data
|
|
bits and one stop bit. PARITY is one of `no', `odd', `even' and
|
|
defaults to `no'. The option `--device' can only be used in the
|
|
grub shell and is used to specify the tty device to be used in the
|
|
host operating system (*note Invoking the grub shell::).
|
|
|
|
The serial port is not used as a communication channel unless the
|
|
`terminal' command is used (*note terminal::).
|
|
|
|
This command is only available if GRUB is compiled with serial
|
|
support. See also *Note Serial terminal::.
|
|
|
|
13.2.13 setkey
|
|
--------------
|
|
|
|
-- Command: setkey [to_key from_key]
|
|
Change the keyboard map. The key FROM_KEY is mapped to the key
|
|
TO_KEY. If no argument is specified, reset key mappings. Note that
|
|
this command _does not_ exchange the keys. If you want to exchange
|
|
the keys, run this command again with the arguments exchanged,
|
|
like this:
|
|
|
|
grub> setkey capslock control
|
|
grub> setkey control capslock
|
|
|
|
A key must be an alphabet letter, a digit, or one of these symbols:
|
|
`escape', `exclam', `at', `numbersign', `dollar', `percent',
|
|
`caret', `ampersand', `asterisk', `parenleft', `parenright',
|
|
`minus', `underscore', `equal', `plus', `backspace', `tab',
|
|
`bracketleft', `braceleft', `bracketright', `braceright', `enter',
|
|
`control', `semicolon', `colon', `quote', `doublequote',
|
|
`backquote', `tilde', `shift', `backslash', `bar', `comma',
|
|
`less', `period', `greater', `slash', `question', `alt', `space',
|
|
`capslock', `FX' (`X' is a digit), and `delete'. This table
|
|
describes to which character each of the symbols corresponds:
|
|
|
|
`exclam'
|
|
`!'
|
|
|
|
`at'
|
|
`@'
|
|
|
|
`numbersign'
|
|
`#'
|
|
|
|
`dollar'
|
|
`$'
|
|
|
|
`percent'
|
|
`%'
|
|
|
|
`caret'
|
|
`^'
|
|
|
|
`ampersand'
|
|
`&'
|
|
|
|
`asterisk'
|
|
`*'
|
|
|
|
`parenleft'
|
|
`('
|
|
|
|
`parenright'
|
|
`)'
|
|
|
|
`minus'
|
|
`-'
|
|
|
|
`underscore'
|
|
`_'
|
|
|
|
`equal'
|
|
`='
|
|
|
|
`plus'
|
|
`+'
|
|
|
|
`bracketleft'
|
|
`['
|
|
|
|
`braceleft'
|
|
`{'
|
|
|
|
`bracketright'
|
|
`]'
|
|
|
|
`braceright'
|
|
`}'
|
|
|
|
`semicolon'
|
|
`;'
|
|
|
|
`colon'
|
|
`:'
|
|
|
|
`quote'
|
|
`''
|
|
|
|
`doublequote'
|
|
`"'
|
|
|
|
`backquote'
|
|
``'
|
|
|
|
`tilde'
|
|
`~'
|
|
|
|
`backslash'
|
|
`\'
|
|
|
|
`bar'
|
|
`|'
|
|
|
|
`comma'
|
|
`,'
|
|
|
|
`less'
|
|
`<'
|
|
|
|
`period'
|
|
`.'
|
|
|
|
`greater'
|
|
`>'
|
|
|
|
`slash'
|
|
`/'
|
|
|
|
`question'
|
|
`?'
|
|
|
|
`space'
|
|
` '
|
|
|
|
13.2.14 terminal
|
|
----------------
|
|
|
|
-- Command: terminal [`--dumb'] [`--no-echo'] [`--no-edit']
|
|
[`--timeout=secs'] [`--lines=lines'] [`--silent'] [`console']
|
|
[`serial'] [`hercules']
|
|
Select a terminal for user interaction. The terminal is assumed to
|
|
be VT100-compatible unless `--dumb' is specified. If both
|
|
`console' and `serial' are specified, then GRUB will use the one
|
|
where a key is entered first or the first when the timeout
|
|
expires. If neither are specified, the current setting is
|
|
reported. This command is only available if GRUB is compiled with
|
|
serial support. See also *Note Serial terminal::.
|
|
|
|
This may not make sense for most users, but GRUB supports Hercules
|
|
console as well. Hercules console is usable like the ordinary
|
|
console, and the usage is quite similar to that for serial
|
|
terminals: specify `hercules' as the argument.
|
|
|
|
The option `--lines' defines the number of lines in your terminal,
|
|
and it is used for the internal pager function. If you don't
|
|
specify this option, the number is assumed as 24.
|
|
|
|
The option `--silent' suppresses the message to prompt you to hit
|
|
any key. This might be useful if your system has no terminal
|
|
device.
|
|
|
|
The option `--no-echo' has GRUB not to echo back input characters.
|
|
This implies the option `--no-edit'.
|
|
|
|
The option `--no-edit' disables the BASH-like editing feature.
|
|
|
|
13.2.15 terminfo
|
|
----------------
|
|
|
|
-- Command: terminfo `--name=name' `--cursor-address=seq'
|
|
[`--clear-screen=seq'] [`--enter-standout-mode=seq']
|
|
[`--exit-standout-mode=seq']
|
|
Define the capabilities of your terminal. Use this command to
|
|
define escape sequences, if it is not vt100-compatible. You may
|
|
use `\e' for <ESC> and `^X' for a control character.
|
|
|
|
You can use the utility `grub-terminfo' to generate appropriate
|
|
arguments to this command. *Note Invoking grub-terminfo::.
|
|
|
|
If no option is specified, the current settings are printed.
|
|
|
|
13.2.16 tftpserver
|
|
------------------
|
|
|
|
-- Command: tftpserver ipaddr
|
|
*Caution:* This command exists only for backward compatibility.
|
|
Use `ifconfig' (*note ifconfig::) instead.
|
|
|
|
Override a TFTP server address returned by a BOOTP/DHCP/RARP
|
|
server. The argument IPADDR must be in dotted decimal format, like
|
|
`192.168.0.15'. This command is only available if GRUB is compiled
|
|
with netboot support. See also *Note Network::.
|
|
|
|
13.2.17 unhide
|
|
--------------
|
|
|
|
-- Command: unhide partition
|
|
Unhide the partition PARTITION by clearing the "hidden" bit in its
|
|
partition type code. This is useful only when booting DOS or
|
|
Windows and multiple primary partitions exist on one disk. See also
|
|
*Note DOS/Windows::.
|
|
|
|
13.3 The list of command-line and menu entry commands
|
|
=====================================================
|
|
|
|
These commands are usable in the command-line and in menu entries. If
|
|
you forget a command, you can run the command `help' (*note help::).
|
|
|
|
13.3.1 blocklist
|
|
----------------
|
|
|
|
-- Command: blocklist file
|
|
Print the block list notation of the file FILE. *Note Block list
|
|
syntax::.
|
|
|
|
13.3.2 boot
|
|
-----------
|
|
|
|
-- Command: boot
|
|
Boot the OS or chain-loader which has been loaded. Only necessary
|
|
if running the fully interactive command-line (it is implicit at
|
|
the end of a menu entry).
|
|
|
|
13.3.3 cat
|
|
----------
|
|
|
|
-- Command: cat file
|
|
Display the contents of the file FILE. This command may be useful
|
|
to remind you of your OS's root partition:
|
|
|
|
grub> cat /etc/fstab
|
|
|
|
13.3.4 chainloader
|
|
------------------
|
|
|
|
-- Command: chainloader [`--force'] file
|
|
Load FILE as a chain-loader. Like any other file loaded by the
|
|
filesystem code, it can use the blocklist notation to grab the
|
|
first sector of the current partition with `+1'. If you specify the
|
|
option `--force', then load FILE forcibly, whether it has a
|
|
correct signature or not. This is required when you want to load a
|
|
defective boot loader, such as SCO UnixWare 7.1 (*note SCO
|
|
UnixWare::).
|
|
|
|
13.3.5 cmp
|
|
----------
|
|
|
|
-- Command: cmp file1 file2
|
|
Compare the file FILE1 with the file FILE2. If they differ in
|
|
size, print the sizes like this:
|
|
|
|
Differ in size: 0x1234 [foo], 0x4321 [bar]
|
|
|
|
If the sizes are equal but the bytes at an offset differ, then
|
|
print the bytes like this:
|
|
|
|
Differ at the offset 777: 0xbe [foo], 0xef [bar]
|
|
|
|
If they are completely identical, nothing will be printed.
|
|
|
|
13.3.6 configfile
|
|
-----------------
|
|
|
|
-- Command: configfile file
|
|
Load FILE as a configuration file.
|
|
|
|
13.3.7 debug
|
|
------------
|
|
|
|
-- Command: debug
|
|
Toggle debug mode (by default it is off). When debug mode is on,
|
|
some extra messages are printed to show disk activity. This global
|
|
debug flag is mainly useful for GRUB developers when testing new
|
|
code.
|
|
|
|
13.3.8 displayapm
|
|
-----------------
|
|
|
|
-- Command: displayapm
|
|
Display APM BIOS information.
|
|
|
|
13.3.9 displaymem
|
|
-----------------
|
|
|
|
-- Command: displaymem
|
|
Display what GRUB thinks the system address space map of the
|
|
machine is, including all regions of physical RAM installed. GRUB's
|
|
"upper/lower memory" display uses the standard BIOS interface for
|
|
the available memory in the first megabyte, or "lower memory", and
|
|
a synthesized number from various BIOS interfaces of the memory
|
|
starting at 1MB and going up to the first chipset hole for "upper
|
|
memory" (the standard PC "upper memory" interface is limited to
|
|
reporting a maximum of 64MB).
|
|
|
|
13.3.10 embed
|
|
-------------
|
|
|
|
-- Command: embed stage1_5 device
|
|
Embed the Stage 1.5 STAGE1_5 in the sectors after the MBR if
|
|
DEVICE is a drive, or in the "boot loader" area if DEVICE is a FFS
|
|
partition or a ReiserFS partition.(1) (*note embed-Footnote-1::)
|
|
Print the number of sectors which STAGE1_5 occupies, if successful.
|
|
|
|
Usually, you don't need to run this command directly. *Note
|
|
setup::.
|
|
|
|
(1) The latter feature has not been implemented yet.
|
|
|
|
13.3.11 find
|
|
------------
|
|
|
|
-- Command: find filename
|
|
Search for the file name FILENAME in all mountable partitions and
|
|
print the list of the devices which contain the file. The file
|
|
name FILENAME should be an absolute file name like
|
|
`/boot/grub/stage1'.
|
|
|
|
13.3.12 fstest
|
|
--------------
|
|
|
|
-- Command: fstest
|
|
Toggle filesystem test mode. Filesystem test mode, when turned
|
|
on, prints out data corresponding to all the device reads and what
|
|
values are being sent to the low-level routines. The format is
|
|
`<PARTITION-OFFSET-SECTOR, BYTE-OFFSET, BYTE-LENGTH>' for
|
|
high-level reads inside a partition, and `[DISK-OFFSET-SECTOR]'
|
|
for low-level sector requests from the disk. Filesystem test mode
|
|
is turned off by any use of the `install' (*note install::) or
|
|
`testload' (*note testload::) commands.
|
|
|
|
13.3.13 geometry
|
|
----------------
|
|
|
|
-- Command: geometry drive [cylinder head sector [total_sector]]
|
|
Print the information for the drive DRIVE. In the grub shell, you
|
|
can set the geometry of the drive arbitrarily. The number of
|
|
cylinders, the number of heads, the number of sectors and the
|
|
number of total sectors are set to CYLINDER, HEAD, SECTOR and
|
|
TOTAL_SECTOR, respectively. If you omit TOTAL_SECTOR, then it will
|
|
be calculated based on the C/H/S values automatically.
|
|
|
|
13.3.14 halt
|
|
------------
|
|
|
|
-- Command: halt `--no-apm'
|
|
The command halts the computer. If the `--no-apm' option is
|
|
specified, no APM BIOS call is performed. Otherwise, the computer
|
|
is shut down using APM.
|
|
|
|
13.3.15 help
|
|
------------
|
|
|
|
-- Command: help `--all' [pattern ...]
|
|
Display helpful information about builtin commands. If you do not
|
|
specify PATTERN, this command shows short descriptions of most of
|
|
available commands. If you specify the option `--all' to this
|
|
command, short descriptions of rarely used commands (such as *Note
|
|
testload::) are displayed as well.
|
|
|
|
If you specify any PATTERNS, it displays longer information about
|
|
each of the commands which match those PATTERNS.
|
|
|
|
13.3.16 impsprobe
|
|
-----------------
|
|
|
|
-- Command: impsprobe
|
|
Probe the Intel Multiprocessor Specification 1.1 or 1.4
|
|
configuration table and boot the various CPUs which are found into
|
|
a tight loop. This command can be used only in the Stage 2, but
|
|
not in the grub shell.
|
|
|
|
13.3.17 initrd
|
|
--------------
|
|
|
|
-- Command: initrd file ...
|
|
Load an initial ramdisk for a Linux format boot image and set the
|
|
appropriate parameters in the Linux setup area in memory. See also
|
|
*Note GNU/Linux::.
|
|
|
|
13.3.18 install
|
|
---------------
|
|
|
|
-- Command: install [`--force-lba'] [`--stage2=os_stage2_file']
|
|
stage1_file [`d'] dest_dev stage2_file [addr] [`p']
|
|
[config_file] [real_config_file]
|
|
This command is fairly complex, and you should not use this command
|
|
unless you are familiar with GRUB. Use `setup' (*note setup::)
|
|
instead.
|
|
|
|
In short, it will perform a full install presuming the Stage 2 or
|
|
Stage 1.5(1) (*note install-Footnote-1::) is in its final install
|
|
location.
|
|
|
|
In slightly more detail, it will load STAGE1_FILE, validate that
|
|
it is a GRUB Stage 1 of the right version number, install in it a
|
|
blocklist for loading STAGE2_FILE as a Stage 2. If the option `d'
|
|
is present, the Stage 1 will always look for the actual disk
|
|
STAGE2_FILE was installed on, rather than using the booting drive.
|
|
The Stage 2 will be loaded at address ADDR, which must be `0x8000'
|
|
for a true Stage 2, and `0x2000' for a Stage 1.5. If ADDR is not
|
|
present, GRUB will determine the address automatically. It then
|
|
writes the completed Stage 1 to the first block of the device
|
|
DEST_DEV. If the options `p' or CONFIG_FILE are present, then it
|
|
reads the first block of stage2, modifies it with the values of
|
|
the partition STAGE2_FILE was found on (for `p') or places the
|
|
string CONFIG_FILE into the area telling the stage2 where to look
|
|
for a configuration file at boot time. Likewise, if
|
|
REAL_CONFIG_FILE is present and STAGE2_FILE is a Stage 1.5, then
|
|
the Stage 2 CONFIG_FILE is patched with the configuration file
|
|
name REAL_CONFIG_FILE. This command preserves the DOS BPB (and for
|
|
hard disks, the partition table) of the sector the Stage 1 is to
|
|
be installed into.
|
|
|
|
*Caution:* Several buggy BIOSes don't pass a booting drive
|
|
properly when booting from a hard disk drive. Therefore, you will
|
|
unfortunately have to specify the option `d', whether your Stage2
|
|
resides at the booting drive or not, if you have such a BIOS. We
|
|
know these are defective in this way:
|
|
|
|
|
|
Fujitsu LifeBook 400 BIOS version 31J0103A
|
|
|
|
|
|
HP Vectra XU 6/200 BIOS version GG.06.11
|
|
|
|
*Caution2:* A number of BIOSes don't return a correct LBA support
|
|
bitmap even if they do have the support. So GRUB provides a
|
|
solution to ignore the wrong bitmap, that is, the option
|
|
`--force-lba'. Don't use this option if you know that your BIOS
|
|
doesn't have LBA support.
|
|
|
|
*Caution3:* You must specify the option `--stage2' in the grub
|
|
shell, if you cannot unmount the filesystem where your stage2 file
|
|
resides. The argument should be the file name in your operating
|
|
system.
|
|
|
|
(1) They're loaded the same way, so we will refer to the Stage 1.5
|
|
as a Stage 2 from now on.
|
|
|
|
13.3.19 ioprobe
|
|
---------------
|
|
|
|
-- Command: ioprobe drive
|
|
Probe I/O ports used for the drive DRIVE. This command will list
|
|
the I/O ports on the screen. For technical information, *Note
|
|
Internals::.
|
|
|
|
13.3.20 kernel
|
|
--------------
|
|
|
|
-- Command: kernel [`--type=type'] [`--no-mem-option'] file ...
|
|
Attempt to load the primary boot image (Multiboot a.out or ELF,
|
|
Linux zImage or bzImage, FreeBSD a.out, NetBSD a.out, etc.) from
|
|
FILE. The rest of the line is passed verbatim as the "kernel
|
|
command-line". Any modules must be reloaded after using this
|
|
command.
|
|
|
|
This command also accepts the option `--type' so that you can
|
|
specify the kernel type of FILE explicitly. The argument TYPE must
|
|
be one of these: `netbsd', `freebsd', `openbsd', `linux',
|
|
`biglinux', and `multiboot'. However, you need to specify it only
|
|
if you want to load a NetBSD ELF kernel, because GRUB can
|
|
automatically determine a kernel type in the other cases, quite
|
|
safely.
|
|
|
|
The option `--no-mem-option' is effective only for Linux. If the
|
|
option is specified, GRUB doesn't pass the option `mem=' to the
|
|
kernel. This option is implied for Linux kernels 2.4.18 and newer.
|
|
|
|
13.3.21 lock
|
|
------------
|
|
|
|
-- Command: lock
|
|
Prevent normal users from executing arbitrary menu entries. You
|
|
must use the command `password' if you really want this command to
|
|
be useful (*note password::).
|
|
|
|
This command is used in a menu, as shown in this example:
|
|
|
|
title This entry is too dangerous to be executed by normal users
|
|
lock
|
|
root (hd0,a)
|
|
kernel /no-security-os
|
|
|
|
See also *Note Security::.
|
|
|
|
13.3.22 makeactive
|
|
------------------
|
|
|
|
-- Command: makeactive
|
|
Set the active partition on the root disk to GRUB's root device.
|
|
This command is limited to _primary_ PC partitions on a hard disk.
|
|
|
|
13.3.23 map
|
|
-----------
|
|
|
|
-- Command: map to_drive from_drive
|
|
Map the drive FROM_DRIVE to the drive TO_DRIVE. This is necessary
|
|
when you chain-load some operating systems, such as DOS, if such
|
|
an OS resides at a non-first drive. Here is an example:
|
|
|
|
grub> map (hd0) (hd1)
|
|
grub> map (hd1) (hd0)
|
|
|
|
The example exchanges the order between the first hard disk and the
|
|
second hard disk. See also *Note DOS/Windows::.
|
|
|
|
13.3.24 md5crypt
|
|
----------------
|
|
|
|
-- Command: md5crypt
|
|
Prompt to enter a password, and encrypt it in MD5 format. The
|
|
encrypted password can be used with the command `password' (*note
|
|
password::). See also *Note Security::.
|
|
|
|
13.3.25 module
|
|
--------------
|
|
|
|
-- Command: module file ...
|
|
Load a boot module FILE for a Multiboot format boot image (no
|
|
interpretation of the file contents are made, so the user of this
|
|
command must know what the kernel in question expects). The rest
|
|
of the line is passed as the "module command-line", like the
|
|
`kernel' command. You must load a Multiboot kernel image before
|
|
loading any module. See also *Note modulenounzip::.
|
|
|
|
13.3.26 modulenounzip
|
|
---------------------
|
|
|
|
-- Command: modulenounzip file ...
|
|
The same as `module' (*note module::), except that automatic
|
|
decompression is disabled.
|
|
|
|
13.3.27 pause
|
|
-------------
|
|
|
|
-- Command: pause message ...
|
|
Print the MESSAGE, then wait until a key is pressed. Note that
|
|
placing <^G> (ASCII code 7) in the message will cause the speaker
|
|
to emit the standard beep sound, which is useful when prompting
|
|
the user to change floppies.
|
|
|
|
13.3.28 quit
|
|
------------
|
|
|
|
-- Command: quit
|
|
Exit from the grub shell `grub' (*note Invoking the grub shell::).
|
|
This command can be used only in the grub shell.
|
|
|
|
13.3.29 reboot
|
|
--------------
|
|
|
|
-- Command: reboot
|
|
Reboot the computer.
|
|
|
|
13.3.30 read
|
|
------------
|
|
|
|
-- Command: read addr
|
|
Read a 32-bit value from memory at address ADDR and display it in
|
|
hex format.
|
|
|
|
13.3.31 root
|
|
------------
|
|
|
|
-- Command: root device [hdbias]
|
|
Set the current "root device" to the device DEVICE, then attempt
|
|
to mount it to get the partition size (for passing the partition
|
|
descriptor in `ES:ESI', used by some chain-loaded boot loaders),
|
|
the BSD drive-type (for booting BSD kernels using their native
|
|
boot format), and correctly determine the PC partition where a BSD
|
|
sub-partition is located. The optional HDBIAS parameter is a
|
|
number to tell a BSD kernel how many BIOS drive numbers are on
|
|
controllers before the current one. For example, if there is an
|
|
IDE disk and a SCSI disk, and your FreeBSD root partition is on
|
|
the SCSI disk, then use a `1' for HDBIAS.
|
|
|
|
See also *Note rootnoverify::.
|
|
|
|
13.3.32 rootnoverify
|
|
--------------------
|
|
|
|
-- Command: rootnoverify device [hdbias]
|
|
Similar to `root' (*note root::), but don't attempt to mount the
|
|
partition. This is useful for when an OS is outside of the area of
|
|
the disk that GRUB can read, but setting the correct root device
|
|
is still desired. Note that the items mentioned in `root' above
|
|
which derived from attempting the mount will _not_ work correctly.
|
|
|
|
13.3.33 savedefault
|
|
-------------------
|
|
|
|
-- Command: savedefault num
|
|
Save the current menu entry or NUM if specified as a default
|
|
entry. Here is an example:
|
|
|
|
default saved
|
|
timeout 10
|
|
|
|
title GNU/Linux
|
|
root (hd0,0)
|
|
kernel /boot/vmlinuz root=/dev/sda1 vga=ext
|
|
initrd /boot/initrd
|
|
savedefault
|
|
|
|
title FreeBSD
|
|
root (hd0,a)
|
|
kernel /boot/loader
|
|
savedefault
|
|
|
|
With this configuration, GRUB will choose the entry booted
|
|
previously as the default entry.
|
|
|
|
You can specify `fallback' instead of a number. Then, next
|
|
fallback entry is saved. Next fallback entry is chosen from
|
|
fallback entries. Normally, this will be the first entry in
|
|
fallback ones.
|
|
|
|
See also *Note default:: and *Note Invoking grub-set-default::.
|
|
|
|
13.3.34 setup
|
|
-------------
|
|
|
|
-- Command: setup [`--force-lba'] [`--stage2=os_stage2_file']
|
|
[`--prefix=dir'] install_device [image_device]
|
|
Set up the installation of GRUB automatically. This command uses
|
|
the more flexible command `install' (*note install::) in the
|
|
backend and installs GRUB into the device INSTALL_DEVICE. If
|
|
IMAGE_DEVICE is specified, then find the GRUB images (*note
|
|
Images::) in the device IMAGE_DEVICE, otherwise use the current
|
|
"root device", which can be set by the command `root'. If
|
|
INSTALL_DEVICE is a hard disk, then embed a Stage 1.5 in the disk
|
|
if possible.
|
|
|
|
The option `--prefix' specifies the directory under which GRUB
|
|
images are put. If it is not specified, GRUB automatically
|
|
searches them in `/boot/grub' and `/grub'.
|
|
|
|
The options `--force-lba' and `--stage2' are just passed to
|
|
`install' if specified. *Note install::, for more information.
|
|
|
|
13.3.35 testload
|
|
----------------
|
|
|
|
-- Command: testload file
|
|
Read the entire contents of FILE in several different ways and
|
|
compare them, to test the filesystem code. The output is somewhat
|
|
cryptic, but if no errors are reported and the final `i=X,
|
|
filepos=Y' reading has X and Y equal, then it is definitely
|
|
consistent, and very likely works correctly subject to a
|
|
consistent offset error. If this test succeeds, then a good next
|
|
step is to try loading a kernel.
|
|
|
|
13.3.36 testvbe
|
|
---------------
|
|
|
|
-- Command: testvbe mode
|
|
Test the VESA BIOS EXTENSION mode MODE. This command will switch
|
|
your video card to the graphics mode, and show an endless
|
|
animation. Hit any key to return. See also *Note vbeprobe::.
|
|
|
|
13.3.37 uppermem
|
|
----------------
|
|
|
|
-- Command: uppermem kbytes
|
|
Force GRUB to assume that only KBYTES kilobytes of upper memory
|
|
are installed. Any system address range maps are discarded.
|
|
|
|
*Caution:* This should be used with great caution, and should only
|
|
be necessary on some old machines. GRUB's BIOS probe can pick up
|
|
all RAM on all new machines the author has ever heard of. It can
|
|
also be used for debugging purposes to lie to an OS.
|
|
|
|
13.3.38 vbeprobe
|
|
----------------
|
|
|
|
-- Command: vbeprobe [mode]
|
|
Probe VESA BIOS EXTENSION information. If the mode MODE is
|
|
specified, show only the information about MODE. Otherwise, this
|
|
command lists up available VBE modes on the screen. See also *Note
|
|
testvbe::.
|
|
|
|
14 Error messages reported by GRUB
|
|
**********************************
|
|
|
|
This chapter describes error messages reported by GRUB when you
|
|
encounter trouble. *Note Invoking the grub shell::, if your problem is
|
|
specific to the grub shell.
|
|
|
|
14.1 Errors reported by the Stage 1
|
|
===================================
|
|
|
|
The general way that the Stage 1 handles errors is to print an error
|
|
string and then halt. Pressing `<CTRL>-<ALT>-<DEL>' will reboot.
|
|
|
|
The following is a comprehensive list of error messages for the
|
|
Stage 1:
|
|
|
|
Hard Disk Error
|
|
The stage2 or stage1.5 is being read from a hard disk, and the
|
|
attempt to determine the size and geometry of the hard disk failed.
|
|
|
|
Floppy Error
|
|
The stage2 or stage1.5 is being read from a floppy disk, and the
|
|
attempt to determine the size and geometry of the floppy disk
|
|
failed. It's listed as a separate error since the probe sequence
|
|
is different than for hard disks.
|
|
|
|
Read Error
|
|
A disk read error happened while trying to read the stage2 or
|
|
stage1.5.
|
|
|
|
Geom Error
|
|
The location of the stage2 or stage1.5 is not in the portion of
|
|
the disk supported directly by the BIOS read calls. This could
|
|
occur because the BIOS translated geometry has been changed by the
|
|
user or the disk is moved to another machine or controller after
|
|
installation, or GRUB was not installed using itself (if it was,
|
|
the Stage 2 version of this error would have been seen during that
|
|
process and it would not have completed the install).
|
|
|
|
14.2 Errors reported by the Stage 1.5
|
|
=====================================
|
|
|
|
The general way that the Stage 1.5 handles errors is to print an error
|
|
number in the form `Error NUM' and then halt. Pressing
|
|
`<CTRL>-<ALT>-<DEL>' will reboot.
|
|
|
|
The error numbers correspond to the errors reported by Stage 2.
|
|
*Note Stage2 errors::.
|
|
|
|
14.3 Errors reported by the Stage 2
|
|
===================================
|
|
|
|
The general way that the Stage 2 handles errors is to abort the
|
|
operation in question, print an error string, then (if possible) either
|
|
continue based on the fact that an error occurred or wait for the user
|
|
to deal with the error.
|
|
|
|
The following is a comprehensive list of error messages for the
|
|
Stage 2 (error numbers for the Stage 1.5 are listed before the colon in
|
|
each description):
|
|
|
|
1 : Filename must be either an absolute filename or blocklist
|
|
This error is returned if a file name is requested which doesn't
|
|
fit the syntax/rules listed in the *Note Filesystem::.
|
|
|
|
2 : Bad file or directory type
|
|
This error is returned if a file requested is not a regular file,
|
|
but something like a symbolic link, directory, or FIFO.
|
|
|
|
3 : Bad or corrupt data while decompressing file
|
|
This error is returned if the run-length decompression code gets an
|
|
internal error. This is usually from a corrupt file.
|
|
|
|
4 : Bad or incompatible header in compressed file
|
|
This error is returned if the file header for a supposedly
|
|
compressed file is bad.
|
|
|
|
5 : Partition table invalid or corrupt
|
|
This error is returned if the sanity checks on the integrity of the
|
|
partition table fail. This is a bad sign.
|
|
|
|
6 : Mismatched or corrupt version of stage1/stage2
|
|
This error is returned if the install command points to
|
|
incompatible or corrupt versions of the stage1 or stage2. It can't
|
|
detect corruption in general, but this is a sanity check on the
|
|
version numbers, which should be correct.
|
|
|
|
7 : Loading below 1MB is not supported
|
|
This error is returned if the lowest address in a kernel is below
|
|
the 1MB boundary. The Linux zImage format is a special case and
|
|
can be handled since it has a fixed loading address and maximum
|
|
size.
|
|
|
|
8 : Kernel must be loaded before booting
|
|
This error is returned if GRUB is told to execute the boot sequence
|
|
without having a kernel to start.
|
|
|
|
9 : Unknown boot failure
|
|
This error is returned if the boot attempt did not succeed for
|
|
reasons which are unknown.
|
|
|
|
10 : Unsupported Multiboot features requested
|
|
This error is returned when the Multiboot features word in the
|
|
Multiboot header requires a feature that is not recognized. The
|
|
point of this is that the kernel requires special handling which
|
|
GRUB is probably unable to provide.
|
|
|
|
11 : Unrecognized device string
|
|
This error is returned if a device string was expected, and the
|
|
string encountered didn't fit the syntax/rules listed in the *Note
|
|
Filesystem::.
|
|
|
|
12 : Invalid device requested
|
|
This error is returned if a device string is recognizable but does
|
|
not fall under the other device errors.
|
|
|
|
13 : Invalid or unsupported executable format
|
|
This error is returned if the kernel image being loaded is not
|
|
recognized as Multiboot or one of the supported native formats
|
|
(Linux zImage or bzImage, FreeBSD, or NetBSD).
|
|
|
|
14 : Filesystem compatibility error, cannot read whole file
|
|
Some of the filesystem reading code in GRUB has limits on the
|
|
length of the files it can read. This error is returned when the
|
|
user runs into such a limit.
|
|
|
|
15 : File not found
|
|
This error is returned if the specified file name cannot be found,
|
|
but everything else (like the disk/partition info) is OK.
|
|
|
|
16 : Inconsistent filesystem structure
|
|
This error is returned by the filesystem code to denote an internal
|
|
error caused by the sanity checks of the filesystem structure on
|
|
disk not matching what it expects. This is usually caused by a
|
|
corrupt filesystem or bugs in the code handling it in GRUB.
|
|
|
|
17 : Cannot mount selected partition
|
|
This error is returned if the partition requested exists, but the
|
|
filesystem type cannot be recognized by GRUB.
|
|
|
|
18 : Selected cylinder exceeds maximum supported by BIOS
|
|
This error is returned when a read is attempted at a linear block
|
|
address beyond the end of the BIOS translated area. This generally
|
|
happens if your disk is larger than the BIOS can handle (512MB for
|
|
(E)IDE disks on older machines or larger than 8GB in general).
|
|
|
|
19 : Linux kernel must be loaded before initrd
|
|
This error is returned if the initrd command is used before
|
|
loading a Linux kernel.
|
|
|
|
20 : Multiboot kernel must be loaded before modules
|
|
This error is returned if the module load command is used before
|
|
loading a Multiboot kernel. It only makes sense in this case
|
|
anyway, as GRUB has no idea how to communicate the presence of
|
|
such modules to a non-Multiboot-aware kernel.
|
|
|
|
21 : Selected disk does not exist
|
|
This error is returned if the device part of a device- or full
|
|
file name refers to a disk or BIOS device that is not present or
|
|
not recognized by the BIOS in the system.
|
|
|
|
22 : No such partition
|
|
This error is returned if a partition is requested in the device
|
|
part of a device- or full file name which isn't on the selected
|
|
disk.
|
|
|
|
23 : Error while parsing number
|
|
This error is returned if GRUB was expecting to read a number and
|
|
encountered bad data.
|
|
|
|
24 : Attempt to access block outside partition
|
|
This error is returned if a linear block address is outside of the
|
|
disk partition. This generally happens because of a corrupt
|
|
filesystem on the disk or a bug in the code handling it in GRUB
|
|
(it's a great debugging tool).
|
|
|
|
25 : Disk read error
|
|
This error is returned if there is a disk read error when trying to
|
|
probe or read data from a particular disk.
|
|
|
|
26 : Too many symbolic links
|
|
This error is returned if the link count is beyond the maximum
|
|
(currently 5), possibly the symbolic links are looped.
|
|
|
|
27 : Unrecognized command
|
|
This error is returned if an unrecognized command is entered on the
|
|
command-line or in a boot sequence section of a configuration file
|
|
and that entry is selected.
|
|
|
|
28 : Selected item cannot fit into memory
|
|
This error is returned if a kernel, module, or raw file load
|
|
command is either trying to load its data such that it won't fit
|
|
into memory or it is simply too big.
|
|
|
|
29 : Disk write error
|
|
This error is returned if there is a disk write error when trying
|
|
to write to a particular disk. This would generally only occur
|
|
during an install of set active partition command.
|
|
|
|
30 : Invalid argument
|
|
This error is returned if an argument specified to a command is
|
|
invalid.
|
|
|
|
31 : File is not sector aligned
|
|
This error may occur only when you access a ReiserFS partition by
|
|
block-lists (e.g. the command `install'). In this case, you should
|
|
mount the partition with the `-o notail' option.
|
|
|
|
32 : Must be authenticated
|
|
This error is returned if you try to run a locked entry. You should
|
|
enter a correct password before running such an entry.
|
|
|
|
33 : Serial device not configured
|
|
This error is returned if you try to change your terminal to a
|
|
serial one before initializing any serial device.
|
|
|
|
34 : No spare sectors on the disk
|
|
This error is returned if a disk doesn't have enough spare space.
|
|
This happens when you try to embed Stage 1.5 into the unused
|
|
sectors after the MBR, but the first partition starts right after
|
|
the MBR or they are used by EZ-BIOS.
|
|
|
|
15 Invoking the grub shell
|
|
**************************
|
|
|
|
This chapter documents the grub shell `grub'. Note that the grub shell
|
|
is an emulator; it doesn't run under the native environment, so it
|
|
sometimes does something wrong. Therefore, you shouldn't trust it too
|
|
much. If there is anything wrong with it, don't hesitate to try the
|
|
native GRUB environment, especially when it guesses a wrong map between
|
|
BIOS drives and OS devices.
|
|
|
|
15.1 Introduction into the grub shell
|
|
=====================================
|
|
|
|
You can use the command `grub' for installing GRUB under your operating
|
|
systems and for a testbed when you add a new feature into GRUB or when
|
|
fixing a bug. `grub' is almost the same as the Stage 2, and, in fact,
|
|
it shares the source code with the Stage 2 and you can use the same
|
|
commands (*note Commands::) in `grub'. It is emulated by replacing BIOS
|
|
calls with UNIX system calls and libc functions.
|
|
|
|
The command `grub' accepts the following options:
|
|
|
|
`--help'
|
|
Print a summary of the command-line options and exit.
|
|
|
|
`--version'
|
|
Print the version number of GRUB and exit.
|
|
|
|
`--verbose'
|
|
Print some verbose messages for debugging purpose.
|
|
|
|
`--device-map=FILE'
|
|
Use the device map file FILE. The format is described in *Note
|
|
Device map::.
|
|
|
|
`--no-floppy'
|
|
Do not probe any floppy drive. This option has no effect if the
|
|
option `--device-map' is specified (*note Device map::).
|
|
|
|
`--probe-second-floppy'
|
|
Probe the second floppy drive. If this option is not specified,
|
|
the grub shell does not probe it, as that sometimes takes a long
|
|
time. If you specify the device map file (*note Device map::), the
|
|
grub shell just ignores this option.
|
|
|
|
`--config-file=FILE'
|
|
Read the configuration file FILE instead of `/boot/grub/menu.lst'.
|
|
The format is the same as the normal GRUB syntax. See *Note
|
|
Filesystem::, for more information.
|
|
|
|
`--boot-drive=DRIVE'
|
|
Set the stage2 BOOT_DRIVE to DRIVE. This argument should be an
|
|
integer (decimal, octal or hexadecimal).
|
|
|
|
`--install-partition=PAR'
|
|
Set the stage2 INSTALL_PARTITION to PAR. This argument should be
|
|
an integer (decimal, octal or hexadecimal).
|
|
|
|
`--no-config-file'
|
|
Do not use the configuration file even if it can be read.
|
|
|
|
`--no-curses'
|
|
Do not use the screen handling interface by the curses even if it
|
|
is available.
|
|
|
|
`--batch'
|
|
This option has the same meaning as `--no-config-file --no-curses'.
|
|
|
|
`--read-only'
|
|
Disable writing to any disk.
|
|
|
|
`--hold'
|
|
Wait until a debugger will attach. This option is useful when you
|
|
want to debug the startup code.
|
|
|
|
15.2 How to install GRUB via `grub'
|
|
===================================
|
|
|
|
The installation procedure is the same as under the "native" Stage 2.
|
|
*Note Installation::, for more information. The command `grub'-specific
|
|
information is described here.
|
|
|
|
What you should be careful about is "buffer cache". `grub' makes use
|
|
of raw devices instead of filesystems that your operating systems
|
|
serve, so there exists a potential problem that some cache
|
|
inconsistency may corrupt your filesystems. What we recommend is:
|
|
|
|
* If you can unmount drives to which GRUB may write any amount of
|
|
data, unmount them before running `grub'.
|
|
|
|
* If a drive cannot be unmounted but can be mounted with the
|
|
read-only flag, mount it in read-only mode. That should be secure.
|
|
|
|
* If a drive must be mounted with the read-write flag, make sure
|
|
that no activity is being done on it while the command `grub' is
|
|
running.
|
|
|
|
* Reboot your operating system as soon as possible. This is probably
|
|
not required if you follow the rules above, but reboot is the most
|
|
secure way.
|
|
|
|
In addition, enter the command `quit' when you finish the
|
|
installation. That is _very important_ because `quit' makes the buffer
|
|
cache consistent. Do not push <C-c>.
|
|
|
|
If you want to install GRUB non-interactively, specify `--batch'
|
|
option in the command-line. This is a simple example:
|
|
|
|
#!/bin/sh
|
|
|
|
# Use /usr/sbin/grub if you are on an older system.
|
|
/sbin/grub --batch <<EOT 1>/dev/null 2>/dev/null
|
|
root (hd0,0)
|
|
setup (hd0)
|
|
quit
|
|
EOT
|
|
|
|
15.3 The map between BIOS drives and OS devices
|
|
===============================================
|
|
|
|
When you specify the option `--device-map' (*note Basic usage::), the
|
|
grub shell creates the "device map file" automatically unless it
|
|
already exists. The file name `/boot/grub/device.map' is preferred.
|
|
|
|
If the device map file exists, the grub shell reads it to map BIOS
|
|
drives to OS devices. This file consists of lines like this:
|
|
|
|
DEVICE FILE
|
|
|
|
DEVICE is a drive specified in the GRUB syntax (*note Device
|
|
syntax::), and FILE is an OS file, which is normally a device file.
|
|
|
|
The reason why the grub shell gives you the device map file is that
|
|
it cannot guess the map between BIOS drives and OS devices correctly in
|
|
some environments. For example, if you exchange the boot sequence
|
|
between IDE and SCSI in your BIOS, it gets the order wrong.
|
|
|
|
Thus, edit the file if the grub shell makes a mistake. You can put
|
|
any comments in the file if needed, as the grub shell assumes that a
|
|
line is just a comment if the first character is `#'.
|
|
|
|
16 Invoking grub-install
|
|
************************
|
|
|
|
The program `grub-install' installs GRUB on your drive using the grub
|
|
shell (*note Invoking the grub shell::). You must specify the device
|
|
name on which you want to install GRUB, like this:
|
|
|
|
grub-install INSTALL_DEVICE
|
|
|
|
The device name INSTALL_DEVICE is an OS device name or a GRUB device
|
|
name.
|
|
|
|
`grub-install' accepts the following options:
|
|
|
|
`--help'
|
|
Print a summary of the command-line options and exit.
|
|
|
|
`--version'
|
|
Print the version number of GRUB and exit.
|
|
|
|
`--force-lba'
|
|
Force GRUB to use LBA mode even for a buggy BIOS. Use this option
|
|
only if your BIOS doesn't work properly in LBA mode even though it
|
|
supports LBA mode.
|
|
|
|
`--root-directory=DIR'
|
|
Install GRUB images under the directory DIR instead of the root
|
|
directory. This option is useful when you want to install GRUB
|
|
into a separate partition or a removable disk. Here is an example
|
|
in which you have a separate "boot" partition which is mounted on
|
|
`/boot':
|
|
|
|
grub-install --root-directory=/boot hd0
|
|
|
|
`--grub-shell=FILE'
|
|
Use FILE as the grub shell. You can append arbitrary options to
|
|
FILE after the file name, like this:
|
|
|
|
grub-install --grub-shell="grub --read-only" /dev/fd0
|
|
|
|
`--recheck'
|
|
Recheck the device map, even if `/boot/grub/device.map' already
|
|
exists. You should use this option whenever you add/remove a disk
|
|
into/from your computer.
|
|
|
|
17 Invoking grub-md5-crypt
|
|
**************************
|
|
|
|
The program `grub-md5-crypt' encrypts a password in MD5 format. This
|
|
is just a frontend of the grub shell (*note Invoking the grub shell::).
|
|
Passwords encrypted by this program can be used with the command
|
|
`password' (*note password::).
|
|
|
|
`grub-md5-crypt' accepts the following options:
|
|
|
|
`--help'
|
|
Print a summary of the command-line options and exit.
|
|
|
|
`--version'
|
|
Print the version information and exit.
|
|
|
|
`--grub-shell=FILE'
|
|
Use FILE as the grub shell.
|
|
|
|
18 Invoking grub-terminfo
|
|
*************************
|
|
|
|
The program `grub-terminfo' generates a terminfo command from a
|
|
terminfo name (*note terminfo::). The result can be used in the
|
|
configuration file, to define escape sequences. Because GRUB assumes
|
|
that your terminal is vt100-compatible by default, this would be useful
|
|
only if your terminal is uncommon (such as vt52).
|
|
|
|
`grub-terminfo' accepts the following options:
|
|
|
|
`--help'
|
|
Print a summary of the command-line options and exit.
|
|
|
|
`--version'
|
|
Print the version information and exit.
|
|
|
|
You must specify one argument to this command. For example:
|
|
|
|
grub-terminfo vt52
|
|
|
|
19 Invoking grub-set-default
|
|
****************************
|
|
|
|
The program `grub-set-default' sets the default boot entry for GRUB.
|
|
This automatically creates a file named `default' under your GRUB
|
|
directory (i.e. `/boot/grub'), if it is not present. This file is used
|
|
to determine the default boot entry when GRUB boots up your system when
|
|
you use `default saved' in your configuration file (*note default::),
|
|
and to save next default boot entry when you use `savedefault' in a
|
|
boot entry (*note savedefault::).
|
|
|
|
`grub-set-default' accepts the following options:
|
|
|
|
`--help'
|
|
Print a summary of the command-line options and exit.
|
|
|
|
`--version'
|
|
Print the version information and exit.
|
|
|
|
`--root-directory=DIR'
|
|
Use the directory DIR instead of the root directory (i.e. `/') to
|
|
define the location of the default file. This is useful when you
|
|
mount a disk which is used for another system.
|
|
|
|
You must specify a single argument to `grub-set-default'. This
|
|
argument is normally the number of a default boot entry. For example,
|
|
if you have this configuration file:
|
|
|
|
default saved
|
|
timeout 10
|
|
|
|
title GNU/Hurd
|
|
root (hd0,0)
|
|
...
|
|
|
|
title GNU/Linux
|
|
root (hd0,1)
|
|
...
|
|
|
|
and if you want to set the next default boot entry to GNU/Linux, you
|
|
may execute this command:
|
|
|
|
grub-set-default 1
|
|
|
|
Because the entry for GNU/Linux is `1'. Note that entries are
|
|
counted from zero. So, if you want to specify GNU/Hurd here, then you
|
|
should specify `0'.
|
|
|
|
This feature is very useful if you want to test a new kernel or to
|
|
make your system quite robust. *Note Making your system robust::, for
|
|
more hints about how to set up a robust system.
|
|
|
|
20 Invoking mbchk
|
|
*****************
|
|
|
|
The program `mbchk' checks for the format of a Multiboot kernel. We
|
|
recommend using this program before booting your own kernel by GRUB.
|
|
|
|
`mbchk' accepts the following options:
|
|
|
|
`--help'
|
|
Print a summary of the command-line options and exit.
|
|
|
|
`--version'
|
|
Print the version number of GRUB and exit.
|
|
|
|
`--quiet'
|
|
Suppress all normal output.
|
|
|
|
Appendix A How to obtain and build GRUB
|
|
***************************************
|
|
|
|
*Caution:* GRUB requires binutils-2.9.1.0.23 or later because the
|
|
GNU assembler has been changed so that it can produce real 16bits
|
|
machine code between 2.9.1 and 2.9.1.0.x. See
|
|
`http://sources.redhat.com/binutils/', to obtain information on
|
|
how to get the latest version.
|
|
|
|
GRUB is available from the GNU alpha archive site
|
|
`ftp://alpha.gnu.org/gnu/grub' or any of its mirrors. The file will be
|
|
named grub-version.tar.gz. The current version is 0.97, so the file you
|
|
should grab is:
|
|
|
|
`ftp://alpha.gnu.org/gnu/grub/grub-0.97.tar.gz'
|
|
|
|
To unbundle GRUB use the instruction:
|
|
|
|
zcat grub-0.97.tar.gz | tar xvf -
|
|
|
|
which will create a directory called `grub-0.97' with all the
|
|
sources. You can look at the file `INSTALL' for detailed instructions
|
|
on how to build and install GRUB, but you should be able to just do:
|
|
|
|
cd grub-0.97
|
|
./configure
|
|
make install
|
|
|
|
This will install the grub shell `grub' (*note Invoking the grub
|
|
shell::), the Multiboot checker `mbchk' (*note Invoking mbchk::), and
|
|
the GRUB images. This will also install the GRUB manual.
|
|
|
|
Also, the latest version is available from the CVS. See
|
|
`http://savannah.gnu.org/cvs/?group=grub' for more information.
|
|
|
|
Appendix B Reporting bugs
|
|
*************************
|
|
|
|
These are the guideline for how to report bugs. Take a look at this
|
|
list below before you submit bugs:
|
|
|
|
1. Before getting unsettled, read this manual through and through.
|
|
Also, see the GNU GRUB FAQ
|
|
(http://www.gnu.org/software/grub/grub-faq.html).
|
|
|
|
2. Always mention the information on your GRUB. The version number
|
|
and the configuration are quite important. If you build it
|
|
yourself, write the options specified to the configure script and
|
|
your operating system, including the versions of gcc and binutils.
|
|
|
|
3. If you have trouble with the installation, inform us of how you
|
|
installed GRUB. Don't omit error messages, if any. Just `GRUB hangs
|
|
up when it boots' is not enough.
|
|
|
|
The information on your hardware is also essential. These are
|
|
especially important: the geometries and the partition tables of
|
|
your hard disk drives and your BIOS.
|
|
|
|
4. If GRUB cannot boot your operating system, write down _everything_
|
|
you see on the screen. Don't paraphrase them, like `The foo OS
|
|
crashes with GRUB, even though it can boot with the bar boot
|
|
loader just fine'. Mention the commands you executed, the messages
|
|
printed by them, and information on your operating system
|
|
including the version number.
|
|
|
|
5. Explain what you wanted to do. It is very useful to know your
|
|
purpose and your wish, and how GRUB didn't satisfy you.
|
|
|
|
6. If you can investigate the problem yourself, please do. That will
|
|
give you and us much more information on the problem. Attaching a
|
|
patch is even better.
|
|
|
|
When you attach a patch, make the patch in unified diff format, and
|
|
write ChangeLog entries. But, even when you make a patch, don't
|
|
forget to explain the problem, so that we can understand what your
|
|
patch is for.
|
|
|
|
7. Write down anything that you think might be related. Please
|
|
understand that we often need to reproduce the same problem you
|
|
encounterred in our environment. So your information should be
|
|
sufficient for us to do the same thing--Don't forget that we
|
|
cannot see your computer directly. If you are not sure whether to
|
|
state a fact or leave it out, state it! Reporting too many things
|
|
is much better than omitting something important.
|
|
|
|
If you follow the guideline above, submit a report to the Bug
|
|
Tracking System (http://savannah.gnu.org/bugs/?group=grub).
|
|
Alternatively, you can submit a report via electronic mail to
|
|
<bug-grub@gnu.org>, but we strongly recommend that you use the Bug
|
|
Tracking System, because e-mail can be passed over easily.
|
|
|
|
Once we get your report, we will try to fix the bugs.
|
|
|
|
Appendix C Where GRUB will go
|
|
*****************************
|
|
|
|
We started the next generation of GRUB, GRUB 2. This will include
|
|
internationalization, dynamic module loading, real memory management,
|
|
multiple architecture support, a scripting language, and many other
|
|
nice feature. If you are interested in the development of GRUB 2, take
|
|
a look at the homepage (http://www.gnu.org/software/grub/grub.html).
|
|
|
|
Appendix D Hacking GRUB
|
|
***********************
|
|
|
|
This chapter documents the user-invisible aspect of GRUB.
|
|
|
|
As a general rule of software development, it is impossible to keep
|
|
the descriptions of the internals up-to-date, and it is quite hard to
|
|
document everything. So refer to the source code, whenever you are not
|
|
satisfied with this documentation. Please assume that this gives just
|
|
hints to you.
|
|
|
|
D.1 The memory map of various components
|
|
========================================
|
|
|
|
GRUB consists of two distinct components, called "stages", which are
|
|
loaded at different times in the boot process. Because they run
|
|
mutual-exclusively, sometimes a memory area overlaps with another
|
|
memory area. And, even in one stage, a single memory area can be used
|
|
for various purposes, because their usages are mutually exclusive.
|
|
|
|
Here is the memory map of the various components:
|
|
|
|
0 to 4K-1
|
|
BIOS and real mode interrupts
|
|
|
|
0x07BE to 0x07FF
|
|
Partition table passed to another boot loader
|
|
|
|
down from 8K-1
|
|
Real mode stack
|
|
|
|
0x2000 to ?
|
|
The optional Stage 1.5 is loaded here
|
|
|
|
0x2000 to 0x7FFF
|
|
Command-line buffer for Multiboot kernels and modules
|
|
|
|
0x7C00 to 0x7DFF
|
|
Stage 1 is loaded here by BIOS or another boot loader
|
|
|
|
0x7F00 to 0x7F42
|
|
LBA drive parameters
|
|
|
|
0x8000 to ?
|
|
Stage2 is loaded here
|
|
|
|
The end of Stage 2 to 416K-1
|
|
Heap, in particular used for the menu
|
|
|
|
down from 416K-1
|
|
Protected mode stack
|
|
|
|
416K to 448K-1
|
|
Filesystem buffer
|
|
|
|
448K to 479.5K-1
|
|
Raw device buffer
|
|
|
|
479.5K to 480K-1
|
|
512-byte scratch area
|
|
|
|
480K to 512K-1
|
|
Buffers for various functions, such as password, command-line, cut
|
|
and paste, and completion.
|
|
|
|
The last 1K of lower memory
|
|
Disk swapping code and data
|
|
|
|
See the file `stage2/shared.h', for more information.
|
|
|
|
D.2 Embedded variables in GRUB
|
|
==============================
|
|
|
|
Stage 1 and Stage 2 have embedded variables whose locations are
|
|
well-defined, so that the installation can patch the binary file
|
|
directly without recompilation of the stages.
|
|
|
|
In Stage 1, these are defined:
|
|
|
|
`0x3E'
|
|
The version number (not GRUB's, but the installation mechanism's).
|
|
|
|
`0x40'
|
|
The boot drive. If it is 0xFF, use a drive passed by BIOS.
|
|
|
|
`0x41'
|
|
The flag for if forcing LBA.
|
|
|
|
`0x42'
|
|
The starting address of Stage 2.
|
|
|
|
`0x44'
|
|
The first sector of Stage 2.
|
|
|
|
`0x48'
|
|
The starting segment of Stage 2.
|
|
|
|
`0x1FE'
|
|
The signature (`0xAA55').
|
|
|
|
See the file `stage1/stage1.S', for more information.
|
|
|
|
In the first sector of Stage 1.5 and Stage 2, the block lists are
|
|
recorded between `firstlist' and `lastlist'. The address of `lastlist'
|
|
is determined when assembling the file `stage2/start.S'.
|
|
|
|
The trick here is that it is actually read backward, and the first
|
|
8-byte block list is not read here, but after the pointer is decremented
|
|
8 bytes, then after reading it, it decrements again, reads, and so on,
|
|
until it is finished. The terminating condition is when the number of
|
|
sectors to be read in the next block list is zero.
|
|
|
|
The format of a block list can be seen from the example in the code
|
|
just before the `firstlist' label. Note that it is always from the
|
|
beginning of the disk, but _not_ relative to the partition boundaries.
|
|
|
|
In the second sector of Stage 1.5 and Stage 2, these are defined:
|
|
|
|
`0x6'
|
|
The version number (likewise, the installation mechanism's).
|
|
|
|
`0x8'
|
|
The installed partition.
|
|
|
|
`0xC'
|
|
The saved entry number.
|
|
|
|
`0x10'
|
|
The identifier.
|
|
|
|
`0x11'
|
|
The flag for if forcing LBA.
|
|
|
|
`0x12'
|
|
The version string (GRUB's).
|
|
|
|
`0x12' + "the length of the version string"
|
|
The name of a configuration file.
|
|
|
|
See the file `stage2/asm.S', for more information.
|
|
|
|
D.3 The generic interface for filesystems
|
|
=========================================
|
|
|
|
For any particular partition, it is presumed that only one of the
|
|
"normal" filesystems such as FAT, FFS, or ext2fs can be used, so there
|
|
is a switch table managed by the functions in `disk_io.c'. The notation
|
|
is that you can only "mount" one at a time.
|
|
|
|
The block list filesystem has a special place in the system. In
|
|
addition to the "normal" filesystem (or even without one mounted), you
|
|
can access disk blocks directly (in the indicated partition) via the
|
|
block list notation. Using the block list filesystem doesn't effect any
|
|
other filesystem mounts.
|
|
|
|
The variables which can be read by the filesystem backend are:
|
|
|
|
`current_drive'
|
|
The current BIOS drive number (numbered from 0, if a floppy, and
|
|
numbered from 0x80, if a hard disk).
|
|
|
|
`current_partition'
|
|
The current partition number.
|
|
|
|
`current_slice'
|
|
The current partition type.
|
|
|
|
`saved_drive'
|
|
The "drive" part of the root device.
|
|
|
|
`saved_partition'
|
|
The "partition" part of the root device.
|
|
|
|
`part_start'
|
|
The current partition starting address, in sectors.
|
|
|
|
`part_length'
|
|
The current partition length, in sectors.
|
|
|
|
`print_possibilities'
|
|
True when the `dir' function should print the possible completions
|
|
of a file, and false when it should try to actually open a file of
|
|
that name.
|
|
|
|
`FSYS_BUF'
|
|
Filesystem buffer which is 32K in size, to use in any way which the
|
|
filesystem backend desires.
|
|
|
|
The variables which need to be written by a filesystem backend are:
|
|
|
|
`filepos'
|
|
The current position in the file, in sectors.
|
|
|
|
*Caution:* the value of FILEPOS can be changed out from under the
|
|
filesystem code in the current implementation. Don't depend on it
|
|
being the same for later calls into the backend code!
|
|
|
|
`filemax'
|
|
The length of the file.
|
|
|
|
`disk_read_func'
|
|
The value of DISK_READ_HOOK _only_ during reading of data for the
|
|
file, not any other fs data, inodes, FAT tables, whatever, then
|
|
set to `NULL' at all other times (it will be `NULL' by default).
|
|
If this isn't done correctly, then the `testload' and `install'
|
|
commands won't work correctly.
|
|
|
|
The functions expected to be used by the filesystem backend are:
|
|
|
|
`devread'
|
|
Only read sectors from within a partition. Sector 0 is the first
|
|
sector in the partition.
|
|
|
|
`grub_read'
|
|
If the backend uses the block list code, then `grub_read' can be
|
|
used, after setting BLOCK_FILE to 1.
|
|
|
|
`print_a_completion'
|
|
If PRINT_POSSIBILITIES is true, call `print_a_completion' for each
|
|
possible file name. Otherwise, the file name completion won't work.
|
|
|
|
The functions expected to be defined by the filesystem backend are
|
|
described at least moderately in the file `filesys.h'. Their usage is
|
|
fairly evident from their use in the functions in `disk_io.c', look for
|
|
the use of the FSYS_TABLE array.
|
|
|
|
*Caution:* The semantics are such that then `mount'ing the
|
|
filesystem, presume the filesystem buffer `FSYS_BUF' is corrupted, and
|
|
(re-)load all important contents. When opening and reading a file,
|
|
presume that the data from the `mount' is available, and doesn't get
|
|
corrupted by the open/read (i.e. multiple opens and/or reads will be
|
|
done with only one mount if in the same filesystem).
|
|
|
|
D.4 The generic interface for built-ins
|
|
=======================================
|
|
|
|
GRUB built-in commands are defined in a uniformal interface, whether
|
|
they are menu-specific or can be used anywhere. The definition of a
|
|
builtin command consists of two parts: the code itself and the table of
|
|
the information.
|
|
|
|
The code must be a function which takes two arguments, a command-line
|
|
string and flags, and returns an `int' value. The "flags" argument
|
|
specifies how the function is called, using a bit mask. The return
|
|
value must be zero if successful, otherwise non-zero. So it is normally
|
|
enough to return ERRNUM.
|
|
|
|
The table of the information is represented by the structure `struct
|
|
builtin', which contains the name of the command, a pointer to the
|
|
function, flags, a short description of the command and a long
|
|
description of the command. Since the descriptions are used only for
|
|
help messages interactively, you don't have to define them, if the
|
|
command may not be called interactively (such as `title').
|
|
|
|
The table is finally registered in the table BUILTIN_TABLE, so that
|
|
`run_script' and `enter_cmdline' can find the command. See the files
|
|
`cmdline.c' and `builtins.c', for more details.
|
|
|
|
D.5 The bootstrap mechanism used in GRUB
|
|
========================================
|
|
|
|
The disk space can be used in a boot loader is very restricted because
|
|
a MBR (*note MBR::) is only 512 bytes but it also contains a partition
|
|
table (*note Partition table::) and a BPB. So the question is how to
|
|
make a boot loader code enough small to be fit in a MBR.
|
|
|
|
However, GRUB is a very large program, so we break GRUB into 2 (or 3)
|
|
distinct components, "Stage 1" and "Stage 2" (and optionally "Stage
|
|
1.5"). *Note Memory map::, for more information.
|
|
|
|
We embed Stage 1 in a MBR or in the boot sector of a partition, and
|
|
place Stage 2 in a filesystem. The optional Stage 1.5 can be installed
|
|
in a filesystem, in the "boot loader" area in a FFS or a ReiserFS, and
|
|
in the sectors right after a MBR, because Stage 1.5 is enough small and
|
|
the sectors right after a MBR is normally an unused region. The size of
|
|
this region is the number of sectors per head minus 1.
|
|
|
|
Thus, all Stage1 must do is just load Stage2 or Stage1.5. But even if
|
|
Stage 1 needs not to support the user interface or the filesystem
|
|
interface, it is impossible to make Stage 1 less than 400 bytes, because
|
|
GRUB should support both the CHS mode and the LBA mode (*note Low-level
|
|
disk I/O::).
|
|
|
|
The solution used by GRUB is that Stage 1 loads only the first
|
|
sector of Stage 2 (or Stage 1.5) and Stage 2 itself loads the rest. The
|
|
flow of Stage 1 is:
|
|
|
|
1. Initialize the system briefly.
|
|
|
|
2. Detect the geometry and the accessing mode of the "loading drive".
|
|
|
|
3. Load the first sector of Stage 2.
|
|
|
|
4. Jump to the starting address of the Stage 2.
|
|
|
|
The flow of Stage 2 (and Stage 1.5) is:
|
|
|
|
1. Load the rest of itself to the real starting address, that is, the
|
|
starting address plus 512 bytes. The block lists are stored in the
|
|
last part of the first sector.
|
|
|
|
2. Long jump to the real starting address.
|
|
|
|
Note that Stage 2 (or Stage 1.5) does not probe the geometry or the
|
|
accessing mode of the "loading drive", since Stage 1 has already probed
|
|
them.
|
|
|
|
D.6 How to probe I/O ports used by INT 13H
|
|
==========================================
|
|
|
|
FIXME: I will write this chapter after implementing the new technique.
|
|
|
|
D.7 How to detect all installed RAM
|
|
===================================
|
|
|
|
FIXME: I doubt if Erich didn't write this chapter only himself wholly,
|
|
so I will rewrite this chapter.
|
|
|
|
D.8 INT 13H disk I/O interrupts
|
|
===============================
|
|
|
|
FIXME: I'm not sure where some part of the original chapter is derived,
|
|
so I will rewrite this chapter.
|
|
|
|
D.9 The structure of Master Boot Record
|
|
=======================================
|
|
|
|
FIXME: Likewise.
|
|
|
|
D.10 The format of partition tables
|
|
===================================
|
|
|
|
FIXME: Probably the original chapter is derived from "How It Works", so
|
|
I will rewrite this chapter.
|
|
|
|
D.11 Where and how you should send patches
|
|
==========================================
|
|
|
|
When you write patches for GRUB, please send them to the mailing list
|
|
<bug-grub@gnu.org>. Here is the list of items of which you should take
|
|
care:
|
|
|
|
* Please make your patch as small as possible. Generally, it is not
|
|
a good thing to make one big patch which changes many things.
|
|
Instead, segregate features and produce many patches.
|
|
|
|
* Use as late code as possible, for the original code. The CVS
|
|
repository always has the current version (*note Obtaining and
|
|
Building GRUB::).
|
|
|
|
* Write ChangeLog entries. *Note Change Logs: (standards)Change
|
|
Logs, if you don't know how to write ChangeLog.
|
|
|
|
* Make patches in unified diff format. `diff -urN' is appropriate in
|
|
most cases.
|
|
|
|
* Don't make patches reversely. Reverse patches are difficult to
|
|
read and use.
|
|
|
|
* Be careful enough of the license term and the copyright. Because
|
|
GRUB is under GNU General Public License, you may not steal code
|
|
from software whose license is incompatible against GPL. And, if
|
|
you copy code written by others, you must not ignore their
|
|
copyrights. Feel free to ask GRUB maintainers, whenever you are
|
|
not sure what you should do.
|
|
|
|
* If your patch is too large to send in e-mail, put it at somewhere
|
|
we can see. Usually, you shouldn't send e-mail over 20K.
|
|
|
|
Appendix E Copying This Manual
|
|
******************************
|
|
|
|
E.1 GNU Free Documentation License
|
|
==================================
|
|
|
|
Version 1.2, November 2002
|
|
|
|
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
|
|
51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
|
|
|
|
Everyone is permitted to copy and distribute verbatim copies
|
|
of this license document, but changing it is not allowed.
|
|
|
|
0. PREAMBLE
|
|
|
|
The purpose of this License is to make a manual, textbook, or other
|
|
functional and useful document "free" in the sense of freedom: to
|
|
assure everyone the effective freedom to copy and redistribute it,
|
|
with or without modifying it, either commercially or
|
|
noncommercially. Secondarily, this License preserves for the
|
|
author and publisher a way to get credit for their work, while not
|
|
being considered responsible for modifications made by others.
|
|
|
|
This License is a kind of "copyleft", which means that derivative
|
|
works of the document must themselves be free in the same sense.
|
|
It complements the GNU General Public License, which is a copyleft
|
|
license designed for free software.
|
|
|
|
We have designed this License in order to use it for manuals for
|
|
free software, because free software needs free documentation: a
|
|
free program should come with manuals providing the same freedoms
|
|
that the software does. But this License is not limited to
|
|
software manuals; it can be used for any textual work, regardless
|
|
of subject matter or whether it is published as a printed book.
|
|
We recommend this License principally for works whose purpose is
|
|
instruction or reference.
|
|
|
|
1. APPLICABILITY AND DEFINITIONS
|
|
|
|
This License applies to any manual or other work, in any medium,
|
|
that contains a notice placed by the copyright holder saying it
|
|
can be distributed under the terms of this License. Such a notice
|
|
grants a world-wide, royalty-free license, unlimited in duration,
|
|
to use that work under the conditions stated herein. The
|
|
"Document", below, refers to any such manual or work. Any member
|
|
of the public is a licensee, and is addressed as "you". You
|
|
accept the license if you copy, modify or distribute the work in a
|
|
way requiring permission under copyright law.
|
|
|
|
A "Modified Version" of the Document means any work containing the
|
|
Document or a portion of it, either copied verbatim, or with
|
|
modifications and/or translated into another language.
|
|
|
|
A "Secondary Section" is a named appendix or a front-matter section
|
|
of the Document that deals exclusively with the relationship of the
|
|
publishers or authors of the Document to the Document's overall
|
|
subject (or to related matters) and contains nothing that could
|
|
fall directly within that overall subject. (Thus, if the Document
|
|
is in part a textbook of mathematics, a Secondary Section may not
|
|
explain any mathematics.) The relationship could be a matter of
|
|
historical connection with the subject or with related matters, or
|
|
of legal, commercial, philosophical, ethical or political position
|
|
regarding them.
|
|
|
|
The "Invariant Sections" are certain Secondary Sections whose
|
|
titles are designated, as being those of Invariant Sections, in
|
|
the notice that says that the Document is released under this
|
|
License. If a section does not fit the above definition of
|
|
Secondary then it is not allowed to be designated as Invariant.
|
|
The Document may contain zero Invariant Sections. If the Document
|
|
does not identify any Invariant Sections then there are none.
|
|
|
|
The "Cover Texts" are certain short passages of text that are
|
|
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
|
|
that says that the Document is released under this License. A
|
|
Front-Cover Text may be at most 5 words, and a Back-Cover Text may
|
|
be at most 25 words.
|
|
|
|
A "Transparent" copy of the Document means a machine-readable copy,
|
|
represented in a format whose specification is available to the
|
|
general public, that is suitable for revising the document
|
|
straightforwardly with generic text editors or (for images
|
|
composed of pixels) generic paint programs or (for drawings) some
|
|
widely available drawing editor, and that is suitable for input to
|
|
text formatters or for automatic translation to a variety of
|
|
formats suitable for input to text formatters. A copy made in an
|
|
otherwise Transparent file format whose markup, or absence of
|
|
markup, has been arranged to thwart or discourage subsequent
|
|
modification by readers is not Transparent. An image format is
|
|
not Transparent if used for any substantial amount of text. A
|
|
copy that is not "Transparent" is called "Opaque".
|
|
|
|
Examples of suitable formats for Transparent copies include plain
|
|
ASCII without markup, Texinfo input format, LaTeX input format,
|
|
SGML or XML using a publicly available DTD, and
|
|
standard-conforming simple HTML, PostScript or PDF designed for
|
|
human modification. Examples of transparent image formats include
|
|
PNG, XCF and JPG. Opaque formats include proprietary formats that
|
|
can be read and edited only by proprietary word processors, SGML or
|
|
XML for which the DTD and/or processing tools are not generally
|
|
available, and the machine-generated HTML, PostScript or PDF
|
|
produced by some word processors for output purposes only.
|
|
|
|
The "Title Page" means, for a printed book, the title page itself,
|
|
plus such following pages as are needed to hold, legibly, the
|
|
material this License requires to appear in the title page. For
|
|
works in formats which do not have any title page as such, "Title
|
|
Page" means the text near the most prominent appearance of the
|
|
work's title, preceding the beginning of the body of the text.
|
|
|
|
A section "Entitled XYZ" means a named subunit of the Document
|
|
whose title either is precisely XYZ or contains XYZ in parentheses
|
|
following text that translates XYZ in another language. (Here XYZ
|
|
stands for a specific section name mentioned below, such as
|
|
"Acknowledgements", "Dedications", "Endorsements", or "History".)
|
|
To "Preserve the Title" of such a section when you modify the
|
|
Document means that it remains a section "Entitled XYZ" according
|
|
to this definition.
|
|
|
|
The Document may include Warranty Disclaimers next to the notice
|
|
which states that this License applies to the Document. These
|
|
Warranty Disclaimers are considered to be included by reference in
|
|
this License, but only as regards disclaiming warranties: any other
|
|
implication that these Warranty Disclaimers may have is void and
|
|
has no effect on the meaning of this License.
|
|
|
|
2. VERBATIM COPYING
|
|
|
|
You may copy and distribute the Document in any medium, either
|
|
commercially or noncommercially, provided that this License, the
|
|
copyright notices, and the license notice saying this License
|
|
applies to the Document are reproduced in all copies, and that you
|
|
add no other conditions whatsoever to those of this License. You
|
|
may not use technical measures to obstruct or control the reading
|
|
or further copying of the copies you make or distribute. However,
|
|
you may accept compensation in exchange for copies. If you
|
|
distribute a large enough number of copies you must also follow
|
|
the conditions in section 3.
|
|
|
|
You may also lend copies, under the same conditions stated above,
|
|
and you may publicly display copies.
|
|
|
|
3. COPYING IN QUANTITY
|
|
|
|
If you publish printed copies (or copies in media that commonly
|
|
have printed covers) of the Document, numbering more than 100, and
|
|
the Document's license notice requires Cover Texts, you must
|
|
enclose the copies in covers that carry, clearly and legibly, all
|
|
these Cover Texts: Front-Cover Texts on the front cover, and
|
|
Back-Cover Texts on the back cover. Both covers must also clearly
|
|
and legibly identify you as the publisher of these copies. The
|
|
front cover must present the full title with all words of the
|
|
title equally prominent and visible. You may add other material
|
|
on the covers in addition. Copying with changes limited to the
|
|
covers, as long as they preserve the title of the Document and
|
|
satisfy these conditions, can be treated as verbatim copying in
|
|
other respects.
|
|
|
|
If the required texts for either cover are too voluminous to fit
|
|
legibly, you should put the first ones listed (as many as fit
|
|
reasonably) on the actual cover, and continue the rest onto
|
|
adjacent pages.
|
|
|
|
If you publish or distribute Opaque copies of the Document
|
|
numbering more than 100, you must either include a
|
|
machine-readable Transparent copy along with each Opaque copy, or
|
|
state in or with each Opaque copy a computer-network location from
|
|
which the general network-using public has access to download
|
|
using public-standard network protocols a complete Transparent
|
|
copy of the Document, free of added material. If you use the
|
|
latter option, you must take reasonably prudent steps, when you
|
|
begin distribution of Opaque copies in quantity, to ensure that
|
|
this Transparent copy will remain thus accessible at the stated
|
|
location until at least one year after the last time you
|
|
distribute an Opaque copy (directly or through your agents or
|
|
retailers) of that edition to the public.
|
|
|
|
It is requested, but not required, that you contact the authors of
|
|
the Document well before redistributing any large number of
|
|
copies, to give them a chance to provide you with an updated
|
|
version of the Document.
|
|
|
|
4. MODIFICATIONS
|
|
|
|
You may copy and distribute a Modified Version of the Document
|
|
under the conditions of sections 2 and 3 above, provided that you
|
|
release the Modified Version under precisely this License, with
|
|
the Modified Version filling the role of the Document, thus
|
|
licensing distribution and modification of the Modified Version to
|
|
whoever possesses a copy of it. In addition, you must do these
|
|
things in the Modified Version:
|
|
|
|
A. Use in the Title Page (and on the covers, if any) a title
|
|
distinct from that of the Document, and from those of
|
|
previous versions (which should, if there were any, be listed
|
|
in the History section of the Document). You may use the
|
|
same title as a previous version if the original publisher of
|
|
that version gives permission.
|
|
|
|
B. List on the Title Page, as authors, one or more persons or
|
|
entities responsible for authorship of the modifications in
|
|
the Modified Version, together with at least five of the
|
|
principal authors of the Document (all of its principal
|
|
authors, if it has fewer than five), unless they release you
|
|
from this requirement.
|
|
|
|
C. State on the Title page the name of the publisher of the
|
|
Modified Version, as the publisher.
|
|
|
|
D. Preserve all the copyright notices of the Document.
|
|
|
|
E. Add an appropriate copyright notice for your modifications
|
|
adjacent to the other copyright notices.
|
|
|
|
F. Include, immediately after the copyright notices, a license
|
|
notice giving the public permission to use the Modified
|
|
Version under the terms of this License, in the form shown in
|
|
the Addendum below.
|
|
|
|
G. Preserve in that license notice the full lists of Invariant
|
|
Sections and required Cover Texts given in the Document's
|
|
license notice.
|
|
|
|
H. Include an unaltered copy of this License.
|
|
|
|
I. Preserve the section Entitled "History", Preserve its Title,
|
|
and add to it an item stating at least the title, year, new
|
|
authors, and publisher of the Modified Version as given on
|
|
the Title Page. If there is no section Entitled "History" in
|
|
the Document, create one stating the title, year, authors,
|
|
and publisher of the Document as given on its Title Page,
|
|
then add an item describing the Modified Version as stated in
|
|
the previous sentence.
|
|
|
|
J. Preserve the network location, if any, given in the Document
|
|
for public access to a Transparent copy of the Document, and
|
|
likewise the network locations given in the Document for
|
|
previous versions it was based on. These may be placed in
|
|
the "History" section. You may omit a network location for a
|
|
work that was published at least four years before the
|
|
Document itself, or if the original publisher of the version
|
|
it refers to gives permission.
|
|
|
|
K. For any section Entitled "Acknowledgements" or "Dedications",
|
|
Preserve the Title of the section, and preserve in the
|
|
section all the substance and tone of each of the contributor
|
|
acknowledgements and/or dedications given therein.
|
|
|
|
L. Preserve all the Invariant Sections of the Document,
|
|
unaltered in their text and in their titles. Section numbers
|
|
or the equivalent are not considered part of the section
|
|
titles.
|
|
|
|
M. Delete any section Entitled "Endorsements". Such a section
|
|
may not be included in the Modified Version.
|
|
|
|
N. Do not retitle any existing section to be Entitled
|
|
"Endorsements" or to conflict in title with any Invariant
|
|
Section.
|
|
|
|
O. Preserve any Warranty Disclaimers.
|
|
|
|
If the Modified Version includes new front-matter sections or
|
|
appendices that qualify as Secondary Sections and contain no
|
|
material copied from the Document, you may at your option
|
|
designate some or all of these sections as invariant. To do this,
|
|
add their titles to the list of Invariant Sections in the Modified
|
|
Version's license notice. These titles must be distinct from any
|
|
other section titles.
|
|
|
|
You may add a section Entitled "Endorsements", provided it contains
|
|
nothing but endorsements of your Modified Version by various
|
|
parties--for example, statements of peer review or that the text
|
|
has been approved by an organization as the authoritative
|
|
definition of a standard.
|
|
|
|
You may add a passage of up to five words as a Front-Cover Text,
|
|
and a passage of up to 25 words as a Back-Cover Text, to the end
|
|
of the list of Cover Texts in the Modified Version. Only one
|
|
passage of Front-Cover Text and one of Back-Cover Text may be
|
|
added by (or through arrangements made by) any one entity. If the
|
|
Document already includes a cover text for the same cover,
|
|
previously added by you or by arrangement made by the same entity
|
|
you are acting on behalf of, you may not add another; but you may
|
|
replace the old one, on explicit permission from the previous
|
|
publisher that added the old one.
|
|
|
|
The author(s) and publisher(s) of the Document do not by this
|
|
License give permission to use their names for publicity for or to
|
|
assert or imply endorsement of any Modified Version.
|
|
|
|
5. COMBINING DOCUMENTS
|
|
|
|
You may combine the Document with other documents released under
|
|
this License, under the terms defined in section 4 above for
|
|
modified versions, provided that you include in the combination
|
|
all of the Invariant Sections of all of the original documents,
|
|
unmodified, and list them all as Invariant Sections of your
|
|
combined work in its license notice, and that you preserve all
|
|
their Warranty Disclaimers.
|
|
|
|
The combined work need only contain one copy of this License, and
|
|
multiple identical Invariant Sections may be replaced with a single
|
|
copy. If there are multiple Invariant Sections with the same name
|
|
but different contents, make the title of each such section unique
|
|
by adding at the end of it, in parentheses, the name of the
|
|
original author or publisher of that section if known, or else a
|
|
unique number. Make the same adjustment to the section titles in
|
|
the list of Invariant Sections in the license notice of the
|
|
combined work.
|
|
|
|
In the combination, you must combine any sections Entitled
|
|
"History" in the various original documents, forming one section
|
|
Entitled "History"; likewise combine any sections Entitled
|
|
"Acknowledgements", and any sections Entitled "Dedications". You
|
|
must delete all sections Entitled "Endorsements."
|
|
|
|
6. COLLECTIONS OF DOCUMENTS
|
|
|
|
You may make a collection consisting of the Document and other
|
|
documents released under this License, and replace the individual
|
|
copies of this License in the various documents with a single copy
|
|
that is included in the collection, provided that you follow the
|
|
rules of this License for verbatim copying of each of the
|
|
documents in all other respects.
|
|
|
|
You may extract a single document from such a collection, and
|
|
distribute it individually under this License, provided you insert
|
|
a copy of this License into the extracted document, and follow
|
|
this License in all other respects regarding verbatim copying of
|
|
that document.
|
|
|
|
7. AGGREGATION WITH INDEPENDENT WORKS
|
|
|
|
A compilation of the Document or its derivatives with other
|
|
separate and independent documents or works, in or on a volume of
|
|
a storage or distribution medium, is called an "aggregate" if the
|
|
copyright resulting from the compilation is not used to limit the
|
|
legal rights of the compilation's users beyond what the individual
|
|
works permit. When the Document is included in an aggregate, this
|
|
License does not apply to the other works in the aggregate which
|
|
are not themselves derivative works of the Document.
|
|
|
|
If the Cover Text requirement of section 3 is applicable to these
|
|
copies of the Document, then if the Document is less than one half
|
|
of the entire aggregate, the Document's Cover Texts may be placed
|
|
on covers that bracket the Document within the aggregate, or the
|
|
electronic equivalent of covers if the Document is in electronic
|
|
form. Otherwise they must appear on printed covers that bracket
|
|
the whole aggregate.
|
|
|
|
8. TRANSLATION
|
|
|
|
Translation is considered a kind of modification, so you may
|
|
distribute translations of the Document under the terms of section
|
|
4. Replacing Invariant Sections with translations requires special
|
|
permission from their copyright holders, but you may include
|
|
translations of some or all Invariant Sections in addition to the
|
|
original versions of these Invariant Sections. You may include a
|
|
translation of this License, and all the license notices in the
|
|
Document, and any Warranty Disclaimers, provided that you also
|
|
include the original English version of this License and the
|
|
original versions of those notices and disclaimers. In case of a
|
|
disagreement between the translation and the original version of
|
|
this License or a notice or disclaimer, the original version will
|
|
prevail.
|
|
|
|
If a section in the Document is Entitled "Acknowledgements",
|
|
"Dedications", or "History", the requirement (section 4) to
|
|
Preserve its Title (section 1) will typically require changing the
|
|
actual title.
|
|
|
|
9. TERMINATION
|
|
|
|
You may not copy, modify, sublicense, or distribute the Document
|
|
except as expressly provided for under this License. Any other
|
|
attempt to copy, modify, sublicense or distribute the Document is
|
|
void, and will automatically terminate your rights under this
|
|
License. However, parties who have received copies, or rights,
|
|
from you under this License will not have their licenses
|
|
terminated so long as such parties remain in full compliance.
|
|
|
|
10. FUTURE REVISIONS OF THIS LICENSE
|
|
|
|
The Free Software Foundation may publish new, revised versions of
|
|
the GNU Free Documentation License from time to time. Such new
|
|
versions will be similar in spirit to the present version, but may
|
|
differ in detail to address new problems or concerns. See
|
|
`http://www.gnu.org/copyleft/'.
|
|
|
|
Each version of the License is given a distinguishing version
|
|
number. If the Document specifies that a particular numbered
|
|
version of this License "or any later version" applies to it, you
|
|
have the option of following the terms and conditions either of
|
|
that specified version or of any later version that has been
|
|
published (not as a draft) by the Free Software Foundation. If
|
|
the Document does not specify a version number of this License,
|
|
you may choose any version ever published (not as a draft) by the
|
|
Free Software Foundation.
|
|
|
|
E.1.1 ADDENDUM: How to use this License for your documents
|
|
----------------------------------------------------------
|
|
|
|
To use this License in a document you have written, include a copy of
|
|
the License in the document and put the following copyright and license
|
|
notices just after the title page:
|
|
|
|
Copyright (C) YEAR YOUR NAME.
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.2
|
|
or any later version published by the Free Software Foundation;
|
|
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
|
|
Texts. A copy of the license is included in the section entitled ``GNU
|
|
Free Documentation License''.
|
|
|
|
If you have Invariant Sections, Front-Cover Texts and Back-Cover
|
|
Texts, replace the "with...Texts." line with this:
|
|
|
|
with the Invariant Sections being LIST THEIR TITLES, with
|
|
the Front-Cover Texts being LIST, and with the Back-Cover Texts
|
|
being LIST.
|
|
|
|
If you have Invariant Sections without Cover Texts, or some other
|
|
combination of the three, merge those two alternatives to suit the
|
|
situation.
|
|
|
|
If your document contains nontrivial examples of program code, we
|
|
recommend releasing these examples in parallel under your choice of
|
|
free software license, such as the GNU General Public License, to
|
|
permit their use in free software.
|
|
|
|
Index
|
|
*****
|
|
|
|
blocklist: See 13.3.1. (line 2252)
|
|
boot: See 13.3.2. (line 2259)
|
|
bootp: See 13.2.1. (line 1862)
|
|
cat: See 13.3.3. (line 2267)
|
|
chainloader: See 13.3.4. (line 2276)
|
|
cmp: See 13.3.5. (line 2288)
|
|
color: See 13.2.2. (line 1874)
|
|
configfile: See 13.3.6. (line 2304)
|
|
current_drive: See D.3. (line 3498)
|
|
current_partition: See D.3. (line 3502)
|
|
current_slice: See D.3. (line 3505)
|
|
debug: See 13.3.7. (line 2310)
|
|
default: See 13.1.1. (line 1810)
|
|
device: See 13.2.3. (line 1935)
|
|
devread: See D.3. (line 3550)
|
|
dhcp: See 13.2.4. (line 1950)
|
|
disk_read_func: See D.3. (line 3541)
|
|
displayapm: See 13.3.8. (line 2319)
|
|
displaymem: See 13.3.9. (line 2325)
|
|
embed: See 13.3.10. (line 2338)
|
|
fallback: See 13.1.2. (line 1822)
|
|
FDL, GNU Free Documentation License: See E.1. (line 3716)
|
|
filemax: See D.3. (line 3538)
|
|
filepos: See D.3. (line 3531)
|
|
find: See 13.3.11. (line 2352)
|
|
fstest: See 13.3.12. (line 2361)
|
|
FSYS_BUF: See D.3. (line 3525)
|
|
geometry: See 13.3.13. (line 2374)
|
|
grub_read: See D.3. (line 3554)
|
|
halt: See 13.3.14. (line 2385)
|
|
help: See 13.3.15. (line 2393)
|
|
hiddenmenu: See 13.1.3. (line 1833)
|
|
hide: See 13.2.5. (line 1963)
|
|
ifconfig: See 13.2.6. (line 1973)
|
|
impsprobe: See 13.3.16. (line 2406)
|
|
initrd: See 13.3.17. (line 2415)
|
|
install: See 13.3.18. (line 2425)
|
|
ioprobe: See 13.3.19. (line 2483)
|
|
kernel: See 13.3.20. (line 2491)
|
|
lock: See 13.3.21. (line 2513)
|
|
makeactive: See 13.3.22. (line 2530)
|
|
map: See 13.3.23. (line 2537)
|
|
md5crypt: See 13.3.24. (line 2551)
|
|
module: See 13.3.25. (line 2559)
|
|
modulenounzip: See 13.3.26. (line 2570)
|
|
pager: See 13.2.7. (line 1983)
|
|
part_length: See D.3. (line 3517)
|
|
part_start: See D.3. (line 3514)
|
|
partnew: See 13.2.8. (line 1991)
|
|
parttype: See 13.2.9. (line 2000)
|
|
password: See 13.2.10. (line 2008)
|
|
pause: See 13.3.27. (line 2577)
|
|
print_a_completion: See D.3. (line 3558)
|
|
print_possibilities: See D.3. (line 3520)
|
|
quit: See 13.3.28. (line 2586)
|
|
rarp: See 13.2.11. (line 2023)
|
|
read: See 13.3.30. (line 2599)
|
|
reboot: See 13.3.29. (line 2593)
|
|
root: See 13.3.31. (line 2606)
|
|
rootnoverify: See 13.3.32. (line 2623)
|
|
saved_drive: See D.3. (line 3508)
|
|
saved_partition: See D.3. (line 3511)
|
|
savedefault: See 13.3.33. (line 2633)
|
|
serial: See 13.2.12. (line 2033)
|
|
setkey: See 13.2.13. (line 2055)
|
|
setup: See 13.3.34. (line 2665)
|
|
terminal: See 13.2.14. (line 2180)
|
|
terminfo: See 13.2.15. (line 2212)
|
|
testload: See 13.3.35. (line 2685)
|
|
testvbe: See 13.3.36. (line 2697)
|
|
tftpserver: See 13.2.16. (line 2225)
|
|
timeout: See 13.1.4. (line 1843)
|
|
title: See 13.1.5. (line 1850)
|
|
unhide: See 13.2.17. (line 2237)
|
|
uppermem: See 13.3.37. (line 2705)
|
|
vbeprobe: See 13.3.38. (line 2717)
|