Merge branch 'master' of git://github.com/illumos/illumos-gate

[unleashed.git] / usr / src / 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

   Copyright (C) 1999,2000,2001,2002,2004 Free Software Foundation, Inc.

   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.

\x1f
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.

\x1f
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.

\x1f
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

\x1f
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.

\x1f
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.

\x1f
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

\x1f
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.

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

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

\x1f
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

\x1f
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.

\x1f
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.

\x1f
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.

\x1f
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.

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

\x1f
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::

\x1f
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

\x1f
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.

\x1f
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.

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

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

\x1f
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.

\x1f
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

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

\x1f
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

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

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

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

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

\x1f
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.

\x1f
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.

\x1f
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.

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

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

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

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

\x1f
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.

\x1f
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.

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

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

\x1f
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

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

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

\x1f
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

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

\x1f
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.

\x1f
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.

\x1f
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.

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

displayapm
----------

 - Command: displayapm
     Display APM BIOS information.

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

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

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

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

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

\x1f
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.

\x1f
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.

\x1f
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.

\x1f
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.

\x1f
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.

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