4.4 GRUB Commands

The following sections describe two sets of commands. Both can be used at the GRUB command line. In addition, the first set can be used in the global section of the menu, and the second can be used in individual menu entries. A few commands can be used only on the GRUB shell command line; this is noted in the command entry. The commands default, fallback, hiddenmenu, timeout, and title are available only in the configuration file, for use with the menu interface. They are described in Section 4.3.2.

When running commands, if you find that you aren't sure how to complete a pathname, you can use the Tab key to find the possible completions. For example:

grub> blocklist (hd0,1)/grub/[Tab]
Possible files are: grub.conf splash.xpm.gz menu.lst device.map stage1 
stage2 e2fs_stage1_5 fat_stage1_5 ffs_stage1_5 jfs_stage1_5 minix_stage1_5 
reiserfs_stage1_5 vstafs_stage1_5 xfs_stage1_5
grub> blocklist (hd0,1)/grub/stage2
(hd0,1)33306+24,33332+231

4.4.1 Command-Line and Global Menu Commands

The commands available at the command line and in the global section of the configuration file are as follows.

bootp [--with-configfile]

Initialize a network device via the Bootstrap Protocol (BOOTP). This command is available only if GRUB was compiled with netboot support. If --with-configfile is specified, GRUB automatically loads a configuration file specified by your BOOTP server.

color normal [highlight]

Specify colors for the menu. normal represents the color used for normal menu text, while highlight represents the color used to highlight the line the cursor is on. Both normal and highlight are specified as two symbolic color names, for foreground and background color, separated by a slash. For example:

color light-gray/blue cyan/black

You can prefix the foreground color with blink- (e.g., blink-cyan/red) to get a blinking foreground. The colors black, blue, green, cyan, red, magenta, brown, and light-gray can be specified for foreground or background. Additional colors that can be used only for the foreground are dark-gray, light-blue, light-green, light-cyan, light-red, light-magenta, yellow, and white.

device drive file

Specify a file to be used as a BIOS drive. This command is useful for creating a disk image and/or for fixing the drives when GRUB fails to determine them correctly. The device command is available only from within the grub shell, not from the native command line. For example:

grub> device (fd0) /floppy-image
grub> device (hd0) /dev/sd0

dhcp [--with-configfile]

Initialize a network device via the DHCP protocol. Currently, this command is just an alias for bootp and is available only if GRUB was compiled with netboot support. If specified with --with-configfile, GRUB will fetch and load a configuration file specified by your DHCP server.

hide partition

Hide the specified partition. This is useful when you are booting DOS or Windows and there are multiple primary partitions on one disk. Hide all but the one you want to boot. Also see unhide.

ifconfig [--server=server] [--gateway=gateway] [--mask=mask] 
[--address=address]

Configure a network device manually. If no options are specified, displays the current network configuration. With the server address, gateway, netmask, and IP address specified, ifconfig configures the device. The addresses must be in dotted decimal format (e.g., 192.168.0.4) and the options can be specified in any order.

pager [flag]

Enable or disable the internal pager by setting flag to on (enable) or off (disable).

partnew part type from to

Make a new primary partition, part, specified in GRUB syntax. type is the partition type, specified as a number in the range 0-0xff. from and to are the starting and ending sectors, specified as absolute numbers. Some of the common partition types are:

None	0
FAT 16, lt 32M	4
FAT 16, gt 32M	6
FAT 32	0xb
FAT 32, with LBA	0xc
WIN 95, extended	0xf
EXT2FS	0x83
Linux extended	0x85
Linux RAID	0xfd
FreeBSD	0xa5
OpenBSD	0xa6
NetBSD	0xfd

parttype part type

Change the type of partition part to type. The type must be a number in the range 0-0xff. See partnew for a list of partition types.

password [--md5] passwd [file]

Set a password for the menu interface. If used in the global section of the configuration file, outside the menu entries, GRUB prompts for a password before processing an a, e, or c entered by the user. Once the password passwd has been entered, if no file was specified, GRUB allows the user to proceed. Otherwise, GRUB loads the file as a new configuration file and restarts Stage 2. If password appears in an individual menu entry, GRUB prompts for the password before continuing. Specify --md5 to tell GRUB that the password was encrypted with the md5crypt command.

rarp

Initialize a network device via the Reverse Address Resolution Protocol (RARP). This command is available only if GRUB was compiled with netboot support. The use of RARP is deprecated.

serial [options]

Initialize a serial device. The serial port is not used for communication unless terminal is also specified. This command is available only if GRUB was compiled with serial support.

Options

--device=device

Specify the tty device to be used in the host operating system. This option can be used only in the grub shell.

--parity=parity

Specify the parity. The possible values are no, odd, and even; the default is no.

--port=port

Specify the I/O port. The value of port overrides any value specified for --unit.

--speed=speed

Specify the transmission speed (default is 9600).

--stop=num

Specify the number of stop bits. The value of num is either 1 or 2 (default is 1).

--unit=num

Specify the serial port to use. The value of num is a number in the range 0-3; the default is 0, corresponding to COM1.

--word=num

Specify the number of data bits. The value of num is a number in the range 5-8 (default is 8).

setkey [to-key from-key]

Configure the keyboard map for GRUB by mapping the key from-key to the key to-key. With no mappings specified, reset the keyboard map. setkey is useful for setting up international keyboards. Possible key values are letters, digits, one of the strings "alt", "backspace", "capslock", "control", "delete", "enter", "escape", "Fn" (where n is one of the function key numbers), "shift", "tab", or one of the strings in the Key Value columns of the following table:

Key Value	Character		Key Value	Character
ampersand	&		asterisk	*
at	@		backquote	`
backslash	\		bar	|
braceleft	{		braceright	}
bracketleft	[		bracketright	]
caret	^		colon	:
comma	,		dollar	$
doublequote	"		equal	=
exclam	!		greater	>
less	<		minus	-
numbersign	#		parenleft	(
parenright	)		percent	%
period	.		plus	+
question	?		quote	`
semicolon	;		slash	/
space			tilde	~
underscore	_

splashimage file

Use the image in file as the background (splash) image. The file should be a gzipped .xpm (X pixmap) file, created with a 14-color palette at 640 x 480 resolution and specified with standard GRUB device syntax:

splashimage=(hd0,0)/grub/splash.xpm.gz

Programs that you can use to create .xpm files include the GIMP, xv, and xpaint.

terminal [options] [console] [serial]

Specify a terminal for user interaction. This command is available only if GRUB was compiled with serial support. If both console and serial are specified, GRUB uses the first terminal where a key is pressed, or the first after the timeout has expired. If neither is specified, GRUB displays the current setting.

Options

--dumb

The terminal is a dumb terminal; if this option is not specified, the terminal is assumed to be VT100-compatible.

--lines=num

The terminal has num lines. The default is 24.

--silent

Suppress the prompt to hit any key (useful if your system does not have a terminal).

--timeout=secs

Specify the timeout in seconds.

tftpserver ipaddress

Specify a TFTP server, overriding the address returned by a BOOTP, DHCP, or RARP server. The IP address must be specified in dotted decimal format. This command is available only if GRUB was compiled with netboot support. This command is deprecated; use ifconfig instead.

unhide partition

Unhide the specified partition. This is useful when booting DOS or Windows and there are multiple primary partitions on one disk. You can unhide the partition you want to boot and hide the others.

4.4.2 Command-Line and Menu Entry Commands

The commands available at the command line and in the individual menu entries of the configuration file are as follows.

blocklist file

Print the specified file in blocklist notation, where file is an absolute pathname or a blocklist. For example:

grub> blocklist (hd0,1)/grub/grub.conf
(hd0,1)33746+2

boot

Boot the operating system or chainloader that has been loaded. You need to run this command only if you are in the interactive command-line mode.

cat file

Display the contents of the specified file.

chainloader [--force] file

Load file as a chainloader. You can use blocklist notation to specifiy the first sector of the current partition with +1. If --force is specified, the file is loaded forcibly.

cmp file1 file2

Compare the two files file1 and file2. Report differences by printing nothing if the files are identical, the sizes if they are different, or the bytes at an offset if they differ at that offset.

configfile file

Load file as the configuration file.

debug

Toggle debug mode, which prints extra messages to show disk activity. The default debug mode is off.

displayapm

Display Advanced Power Management (APM) BIOS information.

displaymem

Display the system address space map of the machine, including all regions of physical RAM installed. For example:

grub> displaymem
 EISA Memory BIOS Interface is present
 Address Map BIOS Interface is present
 Lower memory: 640K, Upper memory (to first chipset hole): 3072K
 [Address Range Descriptor entries immediately follow (values are 64-bit)]
   Usable RAM:  Base Address:  0x0 X 4GB + 0x0,
      Length:   0x0 X 4GB + 0xa0000 bytes
   Reserved:  Base Address:  0x0 X 4GB + 0xa0000,
      Length:   0x0 X 4GB + 0x60000 bytes
   Usable RAM:  Base Address:  0x0 X 4GB + 0x100000,
      Length:   0x0 X 4GB + 0x300000 bytes

dump from to

Dump the contents of one file into another. The file you're dumping from is a GRUB file, and the file you're dumping to is an operating system file.

embed stage1.5 device

Embed the specified Stage 1.5 file in the sectors following the MBR if device is a drive, or in the boot loader area if it is an FFS (Berkeley Fast File System) partition (or, in the future, a ReiserFS partition). If successful, print the number of sectors the Stage 1.5 file occupies. You don't usually need to run this command directly.

find file

Search all partitions for the specified file and print the list of devices where it was found. The filename specified should be an absolute filename such as /boot/grub/stage1 or a blocklist.

fstest

Toggle the filesystem test mode, which prints data for device reads and the values being sent to the low-level routines. The install and testload commands turn off filesystem test mode. The test output is in the following format:

<partition-offset-sector, byte-offset, byte-length>

for high-level reads in a partition, and:

[disk-offset-sector]

for low-level sector requests from the disk.

geometry drive [cylinder head sector [total_sector]]

Print geometry information for drive. From the GRUB shell, you can specify the number of cylinders, heads, sectors, and total sectors to set the drive's geometry. If total_sector is omitted, it is calculated from the other values.

halt [--no-apm]

Shut down the computer. The computer is halted with an APM BIOS call unless the option --noapm is specified.

help [--all] [patterns]

Provide help for built-in commands. With no options, show the command and any options or parameters for the most common commands. With --all, show the same information for all possible commands. If you specify a pattern (i.e., a partial command name) or a full command name, a more complete description of the command or commands matching the pattern is displayed.

impsprobe

Probe the Intel Multiprocessor Specification 1.1 or 1.4 configuration table and boot the CPUs that are found into a tight loop. This command can be used only in Stage 2.

initrd file [args]

Load an initial ramdisk file and pass any arguments.

install [options] stage1_file [d] dest_dev stage2_file [addr] [p] 
[config_file] [real_config_file]

Perform a full GRUB install. See also the setup command, which acts as a frontend to install and is easier to use. The Stage 2 or Stage 1.5 file (both referred to as stage2_file here because they are loaded the same way) must be in its final install location (e.g., in the /boot/grub directory). install loads and validates stage1_file, installs a blocklist in the Stage 1 file for loading stage2_file as Stage 2 or Stage 1.5, and writes the completed Stage 1 file to the first block of the device dest_dev.

Options

--force-lba

If the BIOS has LBA support but might return the incorrect LBA bitmap (which sometimes happens), --force-lba forces install to ignore the incorrect bitmap.

--stage2=os_stage2_file

This option is required to specify the operating system name of the Stage 2 file if the filesystem where it is located cannot be unmounted.

Parameters

addr

Specify the address at which Stage 1 is to load Stage 2 or Stage 1.5. The possible values are 0x8000 for Stage 2 and 0x2000 for Stage 1.5. If omitted, GRUB determines the address automatically.

config_file

Specify the location of the configuration file for Stage 2.

d

Tell Stage 1 to look for the actual disk on which stage2_file was installed if it's not on the boot drive.

dest_dev

Specify the destination device. The final Stage 1 file is written to this device.

p

If present, the partition where stage2_file is located is written into the first block of Stage 2.

real_config_file

If stage2_file is really a Stage 1.5 file, real_config_file specifies the real configuration file name and is written into the Stage 2 configuration file.

stage1_file

Specify the Stage 1 file to be written.

stage2_file

Specify the file that Stage 1 is to load for Stage 2.

ioprobe drive

Probe the I/O ports used for drive and write the results to standard output.

kernel [--non-mem-option] file [...]

Load the kernel image from file. Any text following file is passed on as the kernel command line. After running this command, you must reload any modules. The option --type specifies the kernel type and is required only for loading a NetBSD ELF kernel; GRUB automatically determines other types. The possible values of type are linux, biglinux, freebsd, multiboot, netbsd, and openbsd. For Linux, --no-mem-option tells GRUB not to pass the mem= option to the kernel.

lock

Lock the entry until a valid password is entered. This is used in a menu entry immediately after title to prevent nonroot users from executing the entry. This command is most useful in conjunction with the password command.

makeactive

Set the active partition on the root disk to GRUB's root device. Use only on primary PC hard disk partitions.

map to from

Map the from drive to the to drive. You need to do this when chainloading an operating system such as Windows, if it is not on the first drive. For example, if Windows is on (hd1):

grub> map (hd0) (hd1)
grub> map (hd1) (hd0)

This swaps the mappings of the first and second hard drives, tricking Windows into thinking it's on the first drive so it can boot.

md5crypt

Prompt for a password and encrypt it in MD5 format for use with the password command.

module file [...]

Load the boot module file for a multiboot format boot image. Anything after the filename is passed as the module command line.

modulenounzip files

Like module, except that automatic decompression is disabled.

pause messages

Print the specified message and wait for a key to be pressed before continuing.

quit

Used only from within the grub shell to exit from the shell. In the native command environment, use reboot instead, to reboot the computer.

read addr

Read a 32-bit value from memory at the specified address and display it in hex.

reboot

Reboot the system.

root device [hdbias]

Set the root device to the specified device and attempt to mount it to get the partition size (and some additional information for booting BSD kernels). If you are booting a BSD kernel, you can specify hdbias to tell the kernel how many BIOS drive numbers are before the current one.

rootnoverify device [hdbias]

Similar to root, but don't attempt to mount the partition. Used when you are booting a non-GRUB-readable partition such as Windows.

savedefault

Save the current menu entry as the default. GRUB will default to that entry the next time you boot the system.

setup [options] install_device [image_device]

Set up installation of GRUB and run the install command to actually install GRUB onto the device install_device. Find the GRUB images on image_device if it is specified, otherwise use the current root device as set by the root command. If install_device is a hard disk, embed a Stage 1.5 file in the disk if possible.

Options

--force-lba

Force install to use LBA mode. Specify this option if your BIOS supports LBA mode but you find that GRUB isn't working in LBA mode without it.

--prefix=dir

Specify the directory where the GRUB images are located. If not specified, GRUB searches for them in /boot/grub and /grub.

--stage2=os_stage2_file

Passed to install to tell GRUB the operating system name of the Stage 2 file.

testload file

Read the contents of a file in different ways and compare the results to test the filesystem code. If no errors are reported and the final output reports an equal value for the reported variables i and filepos, then the filesystem is consistent and you can try loading a kernel.

testvbe mode

For a VBE (VESA BIOS Extension) BIOS, test the specified VESA BIOS extension mode. You should see an animation loop, which you can cancel by pressing any key.

uppermem kbytes

Tell GRUB to assume that only the specified number of kilobytes of upper memory are installed. You should need to use this command only for old systems where not all the memory may be recognized.

vbeprobe [mode]

For a VBE BIOS, probe VESA BIOS extension information. If mode is specified, the output shows only information for that mode; otherwise, all available VBE modes are listed.