Go to the first, previous, next, last section, table of contents.

Invoking the grub shell

This chapter documents the grub shell @command{grub}. Note that the grub shell is an emulator; it doesn't run under the native environment, so it sometimes does something wrong. Therefore, you shouldn't trust it too much. If there is anything wrong with it, don't hesitate to try the native GRUB environment, especially when it guesses a wrong map between BIOS drives and OS devices.

Introduction into the grub shell

You can use the command @command{grub} for installing GRUB under your operating systems and for a testbed when you add a new feature into GRUB or when fix a bug. @command{grub} is almost the same as the Stage 2, and, in fact, it shares the source code with the Stage 2 and you can use the same commands (see section The list of available commands) in @command{grub}. It is emulated by replacing BIOS calls with UNIX system calls and libc functions.

The command @command{grub} accepts the following options:

@option{--help}

Print a summary of the command-line options and exit.

@option{--version}

Print the version number of GRUB and exit.

@option{--verbose}

Print some verbose messages for debugging purpose.

@option{--device-map=file}

Use the device map file file. The format is described in section The map between BIOS drives and OS devices.

@option{--no-floppy}

Do not probe any floppy drive. This option has no effect if the option @option{--device-map} is specified (see section The map between BIOS drives and OS devices).

@option{--probe-second-floppy}

Probe the second floppy drive. If this option is not specified, the grub shell does not probe it, as that sometimes takes a long time. If you specify the device map file (see section The map between BIOS drives and OS devices), the grub shell just ignores this option.

@option{--config-file=file}

Read the configuration file file instead of `/boot/grub/menu.lst'. The format is the same as the normal GRUB syntax. See section Filesystem syntax and semantics, for more information.

@option{--boot-drive=drive}

Set the stage2 boot_drive to drive. This argument should be an integer (decimal, octal or hexadecimal).

@option{--install-partition=par}

Set the stage2 install_partition to par. This argument should be an integer (decimal, octal or hexadecimal).

@option{--no-config-file}

Do not use the configuration file even if it can be read.

@option{--no-curses}

Do not use the curses interface even if it is available.

@option{--batch}

This option has the same meaning as `--no-config-file --no-curses'.

@option{--read-only}

Disable writing to any disk.

@option{--hold}

Wait until a debugger will attach. This option is useful when you want to debug the startup code.

How to install GRUB via @command{grub}

The installation procedure is the same as under the native Stage 2. See section Installation, for more information. The command @command{grub}-specific information is described here.

What you should be careful about is buffer cache. @command{grub} makes use of raw devices instead of filesystems that your operating systems serve, so there exists a potential problem that some cache inconsistency may corrupt your filesystems. What we recommend is:

• If you can unmount drives to which GRUB may write any amount of data, unmount them before running @command{grub}.
• If a drive cannot be unmounted but can be mounted with the read-only flag, mount it in read-only mode. That should be secure.
• If a drive must be mounted with the read-write flag, make sure that any activity is not being done on it during running the command @command{grub}.
• Reboot your operating system as soon as possible. Probably that is not required if you follow these rules above, but reboot is the most secure way.

In addition, enter the command @command{quit} when you finish the installation. That is very important because @command{quit} makes the buffer cache consistent. Do not push C-c.

If you want to install GRUB non-interactively, specify `--batch' option in the command-line. This is a simple example:

#!/bin/sh

# Use /usr/sbin/grub if you are on an older system.
/sbin/grub --batch <<EOT 1>/dev/null 2>/dev/null
root (hd0,0)
setup (hd0)
quit
EOT

The map between BIOS drives and OS devices

When you specify the option @option{--device-map} (see section Introduction into the grub shell), the grub shell creates the device map file automatically unless it already exists. The file name `/boot/grub/device.map' is preferred.

If the device map file exists, the grub shell reads it to map BIOS drives to OS devices. This file consists of lines like this:

device file

device is a drive, which syntax is the same as the one in GRUB (see section How to specify devices), and file is an OS's file, which is normally a device file.

The reason why the grub shell gives you the device map file is that it cannot guess the map between BIOS drives and OS devices correctly in some environments. For example, if you exchange the boot sequence between IDE and SCSI in your BIOS, it mistakes the order.

Thus, edit the file if the grub shell makes a mistake. You can put any comments in the file if needed, as the grub shell assumes that a line is just a comment if the first character is `#'.

Go to the first, previous, next, last section, table of contents.