15. Invoking the grub shell

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

15.1 Introduction into the grub shell

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

The command grub accepts the following options:

‘--help’

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

‘--version’

Print the version number of GRUB and exit.

‘--verbose’

Print some verbose messages for debugging purpose.

‘--device-map=file’

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

‘--no-floppy’

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

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

‘--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 Filesystem syntax and semantics, for more information.

‘--boot-drive=drive’

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

‘--install-partition=par’

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

‘--no-config-file’

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

‘--no-curses’

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

‘--batch’

This option has the same meaning as ‘--no-config-file --no-curses’.

‘--read-only’

Disable writing to any disk.

‘--hold’

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

15.2 How to install GRUB via grub

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

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

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

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

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

#!/bin/sh

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

15.3 The map between BIOS drives and OS devices

When you specify the option ‘--device-map’ (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 specified in the GRUB syntax (see section How to specify devices), and file is an OS file, which is normally a device file.

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

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

This document was generated on January 3, 2022 using texi2html 1.82.