OpenSolaris_b135/grub/grub-0.97/docs/grub.info-2

This is grub.info, produced by makeinfo version 4.0 from grub.texi.

INFO-DIR-SECTION Kernel
START-INFO-DIR-ENTRY
* GRUB: (grub). The GRand Unified Bootloader
* grub-install: (grub)Invoking grub-install. Install GRUB on your drive
* grub-md5-crypt: (grub)Invoking grub-md5-crypt. Encrypt a password
in MD5 format
* grub-terminfo: (grub)Invoking grub-terminfo. Generate a terminfo
command from a
terminfo name
* grub-set-default: (grub)Invoking grub-set-default. Set a default boot
entry
* mbchk: (grub)Invoking mbchk. Check for the format of a Multiboot kernel
END-INFO-DIR-ENTRY

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

File: grub.info, Node: Diskless, Prev: General usage of network support, Up: Network

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.

File: grub.info, Node: Serial terminal, Next: Preset Menu, Prev: Network, Up: Top

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.

File: grub.info, Node: Preset Menu, Next: Security, Prev: Serial terminal, Up: Top

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

File: grub.info, Node: Security, Next: Images, Prev: Preset Menu, Up: Top

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.

File: grub.info, Node: Images, Next: Filesystem, Prev: Security, Up: Top

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.

File: grub.info, Node: Filesystem, Next: Interface, Prev: Images, Up: Top

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

* Menu:

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

File: grub.info, Node: Device syntax, Next: File name syntax, Up: Filesystem

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.

File: grub.info, Node: File name syntax, Next: Block list syntax, Prev: Device syntax, Up: Filesystem

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

File: grub.info, Node: Block list syntax, Prev: File name syntax, Up: Filesystem

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

File: grub.info, Node: Interface, Next: Commands, Prev: Filesystem, Up: Top

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.

* Menu:

* Command-line interface:: The flexible command-line interface
* Menu interface:: The simple menu interface
* Menu entry editor:: Editing a menu entry
* Hidden menu interface:: The hidden menu interface

File: grub.info, Node: Command-line interface, Next: Menu interface, Up: Interface

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.

File: grub.info, Node: Command-line interface-Footnotes, Up: Command-line interface

(1) However, this behavior will be changed in the future version, in
a user-invisible way.

File: grub.info, Node: Menu interface, Next: Menu entry editor, Prev: Command-line interface, Up: Interface

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.

File: grub.info, Node: Menu entry editor, Next: Hidden menu interface, Prev: Menu interface, Up: Interface

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.

File: grub.info, Node: Hidden menu interface, Prev: Menu entry editor, Up: Interface

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

File: grub.info, Node: Commands, Next: Troubleshooting, Prev: Interface, Up: Top

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.

* Menu:

* Menu-specific commands::
* General commands::
* Command-line and menu entry commands::

File: grub.info, Node: Menu-specific commands, Next: General commands, Up: Commands

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:

* Menu:

* default:: Set the default entry
* fallback:: Set the fallback entry
* hiddenmenu:: Hide the menu interface
* timeout:: Set the timeout
* title:: Start a menu entry

File: grub.info, Node: default, Next: fallback, Up: Menu-specific commands

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.

File: grub.info, Node: fallback, Next: hiddenmenu, Prev: default, Up: Menu-specific commands

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.

File: grub.info, Node: hiddenmenu, Next: timeout, Prev: fallback, Up: Menu-specific commands

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

File: grub.info, Node: timeout, Next: title, Prev: hiddenmenu, Up: Menu-specific commands

timeout
-------

- Command: timeout sec
Set a timeout, in SEC seconds, before automatically booting the
default entry (normally the first entry defined).

File: grub.info, Node: title, Prev: timeout, Up: Menu-specific commands

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.

File: grub.info, Node: General commands, Next: Command-line and menu entry commands, Prev: Menu-specific commands, Up: Commands

The list of general commands
============================

Commands usable anywhere in the menu and in the command-line.

* Menu:

* bootp:: Initialize a network device via BOOTP
* color:: Color the menu interface
* device:: Specify a file as a drive
* dhcp:: Initialize a network device via DHCP
* hide:: Hide a partition
* ifconfig:: Configure a network device manually
* pager:: Change the state of the internal pager
* partnew:: Make a primary partition
* parttype:: Change the type of a partition
* password:: Set a password for the menu interface
* rarp:: Initialize a network device via RARP
* serial:: Set up a serial device
* setkey:: Configure the key map
* terminal:: Choose a terminal
* terminfo:: Define escape sequences for a terminal
* tftpserver:: Specify a TFTP server
* unhide:: Unhide a partition

File: grub.info, Node: bootp, Next: color, Up: General commands

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

File: grub.info, Node: color, Next: device, Prev: bootp, Up: General commands

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

File: grub.info, Node: device, Next: dhcp, Prev: color, Up: General commands

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

File: grub.info, Node: dhcp, Next: hide, Prev: device, Up: General commands

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

File: grub.info, Node: hide, Next: ifconfig, Prev: dhcp, Up: General commands

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

File: grub.info, Node: ifconfig, Next: pager, Prev: hide, Up: General commands

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

File: grub.info, Node: pager, Next: partnew, Prev: ifconfig, Up: General commands

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.

File: grub.info, Node: partnew, Next: parttype, Prev: pager, Up: General commands

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.

File: grub.info, Node: parttype, Next: password, Prev: partnew, Up: General commands

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.

File: grub.info, Node: password, Next: rarp, Prev: parttype, Up: General commands

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

File: grub.info, Node: rarp, Next: serial, Prev: password, Up: General commands

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

File: grub.info, Node: serial, Next: setkey, Prev: rarp, Up: General commands

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

File: grub.info, Node: setkey, Next: terminal, Prev: serial, Up: General commands

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'
` '

File: grub.info, Node: terminal, Next: terminfo, Prev: setkey, Up: General commands

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.

File: grub.info, Node: terminfo, Next: tftpserver, Prev: terminal, Up: General commands

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.

File: grub.info, Node: tftpserver, Next: unhide, Prev: terminfo, Up: General commands

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

File: grub.info, Node: unhide, Prev: tftpserver, Up: General commands

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

File: grub.info, Node: Command-line and menu entry commands, Prev: General commands, Up: Commands

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

* Menu:

* blocklist:: Get the block list notation of a file
* boot:: Start up your operating system
* cat:: Show the contents of a file
* chainloader:: Chain-load another boot loader
* cmp:: Compare two files
* configfile:: Load a configuration file
* debug:: Toggle the debug flag
* displayapm:: Display APM information
* displaymem:: Display memory configuration
* embed:: Embed Stage 1.5
* find:: Find a file
* fstest:: Test a filesystem
* geometry:: Manipulate the geometry of a drive
* halt:: Shut down your computer
* help:: Show help messages
* impsprobe:: Probe SMP
* initrd:: Load an initrd
* install:: Install GRUB
* ioprobe:: Probe I/O ports used for a drive
* kernel:: Load a kernel
* lock:: Lock a menu entry
* makeactive:: Make a partition active
* map:: Map a drive to another
* md5crypt:: Encrypt a password in MD5 format
* module:: Load a module
* modulenounzip:: Load a module without decompression
* pause:: Wait for a key press
* quit:: Exit from the grub shell
* reboot:: Reboot your computer
* read:: Read data from memory
* root:: Set GRUB's root device
* rootnoverify:: Set GRUB's root device without mounting
* savedefault:: Save current entry as the default entry
* setup:: Set up GRUB's installation automatically
* testload:: Load a file for testing a filesystem
* testvbe:: Test VESA BIOS EXTENSION
* uppermem:: Set the upper memory size
* vbeprobe:: Probe VESA BIOS EXTENSION

File: grub.info, Node: blocklist, Next: boot, Up: Command-line and menu entry commands

blocklist
---------

- Command: blocklist file
Print the block list notation of the file FILE. *Note Block list
syntax::.

File: grub.info, Node: boot, Next: cat, Prev: blocklist, Up: Command-line and menu entry commands

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

File: grub.info, Node: cat, Next: chainloader, Prev: boot, Up: Command-line and menu entry commands

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

File: grub.info, Node: chainloader, Next: cmp, Prev: cat, Up: Command-line and menu entry commands

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

File: grub.info, Node: cmp, Next: configfile, Prev: chainloader, Up: Command-line and menu entry commands

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.

File: grub.info, Node: configfile, Next: debug, Prev: cmp, Up: Command-line and menu entry commands

configfile
----------

- Command: configfile file
Load FILE as a configuration file.

File: grub.info, Node: debug, Next: displayapm, Prev: configfile, Up: Command-line and menu entry commands

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.

File: grub.info, Node: displayapm, Next: displaymem, Prev: debug, Up: Command-line and menu entry commands

displayapm
----------

- Command: displayapm
Display APM BIOS information.

File: grub.info, Node: displaymem, Next: embed, Prev: displayapm, Up: Command-line and menu entry commands

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

File: grub.info, Node: embed, Next: find, Prev: displaymem, Up: Command-line and menu entry commands

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

File: grub.info, Node: embed-Footnotes, Up: embed

(1) The latter feature has not been implemented yet.

File: grub.info, Node: find, Next: fstest, Prev: embed, Up: Command-line and menu entry commands

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

File: grub.info, Node: fstest, Next: geometry, Prev: find, Up: Command-line and menu entry commands

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.

File: grub.info, Node: geometry, Next: halt, Prev: fstest, Up: Command-line and menu entry commands

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.

File: grub.info, Node: halt, Next: help, Prev: geometry, Up: Command-line and menu entry commands

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.

File: grub.info, Node: help, Next: impsprobe, Prev: halt, Up: Command-line and menu entry commands

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.

File: grub.info, Node: impsprobe, Next: initrd, Prev: help, Up: Command-line and menu entry commands

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.

File: grub.info, Node: initrd, Next: install, Prev: impsprobe, Up: Command-line and menu entry commands

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