     [file version.texi not included]

Copyright © 1996 Erich Boleyn Copyright © 1999 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.

GRUB
****

This file documents GNU GRUB, the Grand Unified Bootloader.  This edition documents version VERSION.

Introduction
************

Briefly, a bootloader is the first software program that runs when a computer starts.  It is responsible for loading and transferring control to the operating system kernel software (such as the Linux or Hurd kernels).  The kernel, in turn, initializes the rest of the operating system (usually GNU).

History of GRUB
===============

GRUB originated in 1995 when Erich Boleyn was trying to boot the GNU Hurd with the University of Utah's Mach 4 microkernel (now known as GNU Mach).  Erich and Brian Ford designed the Multiboot Standard (FIXME xref), because they were determined not to add to the large number of mutually-incompatible PC boot methods.

Erich then began modifying the FreeBSD bootloader so that it would understand Multiboot.  He quickly realized that it would be a lot easier to write his own bootloader from scratch than to keep working on the FreeBSD bootloader, and so GRUB was born.

Erich added many features to GRUB, but other priorities prevented him from keeping up with the demands of its quickly-expanding user base.  In 1999, Gordon Matzigkeit and OKUJI Yoshinori adopted GRUB as an official GNU package, and opened its development by making the latest sources available via anonymous CVS. (The repository is :pserver:anoncvs@anoncvs.gnu.org:/gd/gnu/anoncvsroot, module grub.  Just hit return when prompted for a password.)

GRUB features
=============

technical.html: why another bootloader?

The role of a bootloader
========================

The following is a quotation from Gordon Matzigkeit, a GRUB fanatic:

     Some people like to acknowlege both the operating system and kernel when they talk about their computers, so they might say they use ``GNU/Linux'' or ``GNU/Hurd''.  Other people seem to think that the kernel is the most important part of the system, so they like to call their GNU operating systems ``Linux systems.''

     I, personally, believe that this is a grave injustice, because the bootloader is the most important software of all.  I used to refer to the above systems as either ``LILO'' (The LInux LOader, a bootloader that everybody uses, but nobody likes.) or ``GRUB'' systems.

     Unfortunately, nobody ever understood what I was talking about; now I just use the word ``GNU'' as a pseudonym for GRUB.

     So, if you ever hear people talking about their alleged ``GNU'' systems, remember that they are actually paying homage to the best bootloader around... GRUB!

We, the GRUB maintainers, do not (usually) encourage Gordon's level of fanaticism, but it helps to remember that bootloaders deserve careful design.  We hope at least that you enjoy using GNU GRUB as much as we did writing it.

How to install GRUB on your computer
************************************

Due to the nature of a bootloader, you need to install GRUB on bootable media, such as a floppy disk. The installation can be performed by dd or rawrite for a boot floppy, or the install= command at the GRUB command line (see Using).

Creating a GRUB boot floppy
===========================

     Caution: This procedure will destroy any data currently stored on the floppy.

If you install GRUB using this method, it will only have access to the command-line interface, since there is no filesystem in which to find a configuration file (FIXME: ref). If you want to use the menu interface, see Automated install.

Under an UNIX-like operating system, such as GNU, use dd as follows, where /dev/fd0 is the floppy device:

     dd if=stage1/stage1 of=/dev/fd0 bs=512 count=1
     dd if=stage2/stage2 of=/dev/fd0 bs=512 seek=1

Under DOS-based systems, such as Windows, use copy and rawrite:

     copy /b stage1 + stage2 grub.raw
     rawrite grub.new a:

rawrite is available as a part of the installation tools that come with many GNU and GNU/Linux distributions.

Installation via the install= command
=====================================

     Caution: Installing GRUB's stage1 in this manner will erase the normal boot-sector used by an OS.  GRUB can boot GNU Mach, Linux, FreeBSD, NetBSD, and OpenBSD directly, so this may be desired.  Generally, it is a good idea to back up the first sector of the partition on which you are installing GRUB's stage1.  This isn't as important if you are installing GRUB on the first sector of a hard disk, since it's easy to reinitialize it (by running FDISK /MBR from DOS).

GRUB has a command called install= which is described in see Using. The purpose of this section is to give examples and describe how to use the command in different situations.

First, make a GRUB boot floppy (see Boot floppy).  This is simply a way to get the process started easily; any bootable copy of the same version GRUB will work fine.

Then, make a /boot/grub directory (\boot\grub under DOS) in the install partition.  Place the GRUB stage2 file, any optional stage1.5 files, and the configuration file (menu.lst) in that directory.

Now figure out how to use the install= command appropriately, and you're done!

Examples of how to use the install= command:

  * Make a hard disk bootable with GRUB's stage2 on PC partition number 2: Make a directory in the partition called /boot/grub, place the stage2 (and if desired, your configuration file called menu.lst), then run the following command at GRUB's command line (after booting from the GRUB floppy):

          install= (fd0)+1 (hd0) (hd0,2)/boot/grub/stage2 0x8000 p

     This tells GRUB to grab the first sector of the floppy and use it as the stage1, create a blocklist using the file /boot/grub/stage2 on the first hard disk (partition number 2), merge them together, set the load address correctly for a stage2 (0x8000), save the install partition in the first sector of the stage2 (the p at the end), then write the result to the first sector of the hard disk.

  * Same as above, but place the stage1 on the floppy, then have it start the stage2 on the hard disk: The difference here is you're telling GRUB's stage1 to read from the first hard disk no matter where the stage1 was loaded from:

          install= (fd0)+1 d (fd0) (hd0,2)/boot/grub/stage2 0x8000 p

     The d option near the beginning is what sets the forced loading from the disk where the stage2 was installed from.  Also, the destination device is changed to place the finished stage1 on the floppy disk.

  * Installing from an install directory to the second hard disk: Here we're loading the stage1 from a file on the first hard disk, installing stage2 from the first BSD a partition on the second hard disk, and setting the stage2's configuration file to (hd1,a)/grubdir/configfile:

          install= (hd0,2)/boot/grub/stage1 (hd1) (hd1,a)/boot/grub/stage2 0x8000 p /grubdir/configfile

You can automate these steps by using a GRUB floppy with a filesystem and a configuration file which contains entries such as:

     # Start of entries
     title= GNU/Linux installation

     # install command
     install= (fd0)+1 (hd0) (hd0,1)/boot/grub/stage2 0x8000 p

     # actually boot here
     root= (hd0,1)
     kernel= /zImage root=/dev/hda2

... then have the install script continue from there after boot of the OS.

Installation by /sbin/grub
==========================

FIXME

Booting your operating system
*****************************

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 into the command-line 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  (However, this behavaior will be changed in the future version, in an user-invisible way.). The 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 (FIXME: ref) shell (C-f forward, C-b backward, C-a beginning of line, C-e end of line, C-k delete to end, C-u delete to beginning; the PC left and right arrow keys, HOME, DEL, and END work as well).

When typing commands interactively, if the cursor is before the = character in a command being typed, pressing the TAB key will display a listing of the available commands, and if the cursor is after the = character, the TAB will provide a completion listing of disks, partitions, and filenames depending on the context.

The simple menu interface
=========================

The menu interface is quite easy to use.  It's commands are both reasonably intuitive and described onscreen.

Basically, the menu interface provides a list of boot configurations 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 (operating exactly like the non-config-file version of GRUB, but allowing one to return to the menu if desired) or to edit any of the boot configurations, respectively by pressing c or e.

Editing a menu entry
====================

This looks much like the main menu interface, but with the lines in the menu being individual commands of the selected configuration instead of configuration names.

If an ESC is pressed in the editor, it aborts all the changes made to the configuration entry and goes back to the main menu interface.

When a particular line is selected, then it places the user in a special version of the command-line for editing that line.  When the user is finished, GRUB replaces the line in question in the boot configuration with the changes (unless it was aborted via ESC, and in that case the changes are thrown away).

The list of available commands
==============================

In this section, we list the available commands, both in the configuration file and in the command-line.

The configuration file should follow these rules:

 1. The configuration file specific commands have to be used before any others.

 2. A multiboot kernel must be loaded before modules can be.

 3. A kernel must be loaded before either the configuration file entry ends, or any boot command is issued in any case.

The semantics are as follows:

  * The files must be in plain-text format.

  * # at the beginning of a line means it is a comment line in a configuration file only.

  * Options are separated by spaces.

  * All numbers can be either decimal or hexidecimal. A hexidecimal number must be preceeded by 0x, and is case insensitive.

  * Extra options/text at the end of the line is ignored unless otherwise specified.

  * Bad commands generally get included in the current entry being added to, except before entries start, where they are ignored.

Commands usable in configuration files only.

timeout= SEC
     Set a timeout, in SEC seconds, before automatically booting the default entry (normally the first entry defined).

default= NUM
     Set the default entry to entry number NUM (otherwise it is 0, the first entry).

fallback= NUM
     Go into unattended boot mode: if the default boot entry has any errors, instead of waiting for the user to do anything, it immediately starts over using the NUM entry (same numbering as the default= command). This obviously doesn't help if the machine was in the middle of the boot process (after leaving GRUB's code) and rebooted.

password= PASSWD NEW_CONFIG_FILE
     Disable all interactive editing control (menu entry editor and command-line). If the password PASSWD is entered, it loads the NEW_CONFIG_FILE as a new config file and restarts the GRUB Stage 2.

title= ...
     Start a new menu entry, and set its name to the contents of the rest of the line, starting with the first non-space character.

Commands usable in configuration files and interactively.

pause= ...
     Print the entirety to the end of its line, then wait until a key is pressed. Note that placing a ^G in it will cause the speaker to emit the standard beep sound, which is useful when asking the user to change floppies, etc.

uppermem= KBYTES
     Force GRUB to ignore what it found during the autoprobe of the memory available to the system, and to use KBYTES as the number of kilobytes of upper memory installed. Any address range maps of the system are discarded.

     Caution: This should be used with great caution, and should only be necessary on some old machines. GRUB's BIOS probe can pick up all RAM on all new machines the author has ever heard of. It can also be used for debugging purposes to lie to an OS.

root= DEVICE [HDBIAS]
     Set the current root partition to the device DEVICE, then attempt to mount it to get the partition size (for passing the partition descriptor in ES:ESI, used by some chainloaded bootloaders), the BSD drive-type (for booting BSD kernels using their native boot format), and fixup automatic determination of the PC partition where a BSD sub-partition is located. The optional HDBIAS parameter is a number to tell a kernel which is using one of the BSD boot methodologies how many BIOS drive numbers are on controllers before the current one. An example is if there is an IDE disk and a SCSI disk, then set the root partition normally, except for a kernel using a BSD boot methodology (FreeBSD or NetBSD), then use a 1 for HDBIAS.

rootnoverify= DEVICE [HDBIAS]
     Similar to root=, but don't attempt to mount the partition. This is useful for when an OS is outside of the area of the disk that GRUB can read, but setting the correct root partition is still desired. Note that the items mentioned in root= above which derived from attempting the mount will NOT work correctly.

chainloader= FILE
     Load FILE as a chainloader. 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.

kernel= FILE ...
     Attempt to load the primary boot image (Multiboot a.out or ELF, Linux zImage or bzImage, FreeBSD-a.out, or NetBSD-a.out) from FILE. This command ignores the rest of the contents of the line, except that the entire line starting with the kernel filename is passed varbatim as the kernel command-line. The module state is reset by this (i.e. reload any modules).

module= FILE ...
     Load a boot module for a Multiboot format boot image (no interpretation of the file contents are made, so that user of this command/writer of the configurtion file must know what the kernel in question works with). The rest of the line is passed as the module command-line much like with the kernel= command.

modulenounzip= FILE ...
     Exactly like module=, except that automatic decompress is disabled.

initrd= FILE ...
     Load an initial ramdisk for a Linux format boot image and set the appropriate parameters in the Linux setup area in memory.

install= STAGE1_FILE [d] DEST_DEV FILE ADDR [p] [CONFIG_FILE]
     This command is fairly complex, and for detailed examples one should look at Automated install. In short, it will perform a full install presuming the stage1.5 or stage2 (they're loaded the same way, I'll just refer to it as a stage2 from now on) is in its final install location (pretty much all other edits are performed by the install= command).

     In slightly more detail, it will load STAGE1_FILE, validate that it is a GRUB stage1 of the right version number, install blocklist for loading FILE (if the option d is present, the stage1 will always look for the actual disk FILE was installed on, rather than using the booting drive) as a stage2 into memory at address ADDR (for a stage1.5, an address of 0x2000 should be used, and for a stage2, an address of 0x8000 should be used), then write the completed stage1 to the first block of the device DEST_DEV. If the options p or CONFIG_FILE are present, then it reads the first block of stage2, modifies it with the values of the partition FILE was found on (for p) or places the string CONFIG_FILE into the area telling the stage2 where to look for a configuration file at boot time. Finally, it preserves the DOS BPB (and for hard disks, the partition table) of the sector the stage1 is to be installed into.

makeactive
     Set the active partition on the root disk to GRUB's root partition (on a floppy this is a NO-OP). This is limited to working with primary PC partitions.

boot
     This boots the OS/chainloader which has been loaded. Only necessary if running the fully interactive command-line (it is implicit at the end of a config-file entry).

Commands usable in configuraton files and interactively which are only available in the debug version of the GRUB Stage 2.

testload= FILE
     Read the entire contents of FILE in several different ways and compares them, to test the filesystem code. The output is somewhat cryptic (see the T subcommand of syscmd= below), but if no errors are reported and the part right at the end which reads i=X, filepos=Y has X and Y equal, then it is definitely consistent, and very likely works correctly subject to a consistent offset error. A good idea if this works is then to try loading a kernel with your code.

read= ADDR
     Read a 32-bit unsigned value at address ADDR and displays it in hex format.

displaymem
     Display what GRUB thinks the system address space map of the machine is, including all regions of physical RAM installed. The upper/lower memory thing GRUB has 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).

impsprobe
     Probe Intel MPS spec 1.1 or 1.4 configuration table and boot the various other CPUs which are found into a tight loop.

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 <SECTOR, BYTE_OFFSET, BYTE_LEN> for high-level reads inside a partition (so SECTOR is an offset from the start of the partition), and [SECTOR] for low-level sector requests from the disk (so SECTOR is offset from the start of the disk).

     Filesystem test mode is turned off by any uses of the install= or testload= commands.

Filesystem syntax and semantics
*******************************

GRUB uses special syntax for specifying disk drives, that can be accessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish IDE, ESDI, SCSI, etc. So you must know which BIOS device is equivalent to which OS device.

How to specify devices
======================

The device syntax is like this:

     (BIOS_DEVICE[,PART_NUM][,BSD_SUBPART_LETTER])

[] means the parameter is optional. BIOS_DEVICE should be either fd or hd followed by a digit, like fd0. But you can also set BIOS_DEVICE to a hexidecimal or a decimal, which is a BIOS drive number, so these are equivalent:

     (hd0)
     (0x80)
     (128)

PART_NUM represents the partition number of BIOS_DEVICE, starting from zero, and BSD_SUBPART_LETTER represents the BSD sub-partition, like a or e.

A shortcut for specifying BSD sub-partitions is (BIOS_DEVICE,BSD_SUBPART_LETTER), in this case, GRUB searches for the first PC partition containing BSD sub-partitions, then finds the subparitition BSD_SUBPART_LETTER. Here is an example:

     (hd0,a)

How to specify files
====================

There are two ways to specify files, absolute pathname and blocklist.

Absolute pathname resembles a Unix absolute pathname. Use / for the directory separator but not \ like DOS. For example, /boot/grub/menu.lst.

Blocklist is used for specifying a file that doesn't appear in the filesystem, like a chainloader. The syntax is a bit complex, like this:

     1+100,200+1,300+300

This represents that GRUB should read 100 blocks from the offset 1, 1 block from the offset 200, and 300 blocks from the offset 300. The offset is counted from the start of a partition, so the length must be within the partition size. If you omit a offset, then GRUB assumes the offset is zero.

Error messages reported by GRUB
*******************************

This chapter describes the meanings of the error messages reported by GRUB when you encounter some troubles.

Errors reported by the Stage 1
==============================

The general way that the Stage 1 handles errors is to print an error string and then halt. Pressing CTRL-ALT-DEL will reboot.

The following is a comprehensive list of error messages for the Stage 1:

Hard Disk Error
     This error message will occur if the Stage 2 or Stage 1.5 is being read from a hard disk, and the attempt to determine the size and geometry of the hard disk fails.

Floppy Error
     This error message will occur if the Stage 2 or Stage 1.5 is being read from a floppy disk, and the attempt to determine the size and geometry of the floppy disk fails. It's listed as a different error since the probe sequence is different than for hard disks.

Read Error
     This error message will occur if a disk read error happens while trying to read the Stage 2 or Stage 1.5.

Geom Error
     This error message will occur if the location of the Stage 2 or Stage 1.5 is not in the area supported by reading the disk with the BIOS directly. This could occur because the BIOS translated geometry has been changed by the user or the disk is moved to another machine or controller after installation, or GRUB was not installed using itself (if it was, the Stage 2 version of this error would have been seen during that process and it would not have completed the install).

Errors reported by the Stage 1.5
================================

The general way that the Stage 1.5 handles errors is to print an error number in the form Error: NUM and then halt. Pressing CTRL-ALT-DEL will reboot.

The error numbers correspond to the Stage2 errors in the listed sequence.

Errors reported by the Stage 2
==============================

The general way that the Stage 2 handles errors is to abort the operation in question, print an error strng, then (if possible) either continue based on the fact that an error occured or wait for the user to deal with the error.

The followng is a comprehensive list of error messages for the Stage 2 (error numbers for the Stage 1.5 are listed before the colon in each description):

1 : Selected item won't fit into memory
     This error is returned if a kernel, module, or raw file load command is either trying to load its data such that it won't fit into memory or it is simply too big.

2 : Selected disk doesn't exist
     This error is returned if the device part of a device- or full filename refers to a disk or BIOS device that is not present or not recognized by the BIOS in the system.

3 : Disk read error
     This error is returned if there is a disk read error when trying to probe or read data from a particular disk.

4 : Disk write error
     This error is returned if there is a disk write error when trying to write to a particular disk. This would generally only occur during an install of set active partition command.

5 : Disk geometry error
     This error is returned when a read is attempted at a linear block address beyond the end of the BIOS translated area. This generally happens if your disk is larger than the BIOS can handle (512MB for (E)IDE disks on older machines or larger than 8GB in general).

6 : Attempt to access block outside partition
     This error is returned if a linear block address is outside of the disk partition. This generally happens because of a corrupt filesystem on the disk or a bug in the code handling it in GRUB (it's a great debugging tool).

7 : Partition table invalid or corrupt
     This error s returned if the sanity checks on the integrity of the partition table fail. This is a bad sign.

8 : No such partition
     This error is returned if a partition is requested in the device part of a device- or full filename which isn't on the selected disk.

9 : Bad filename (must be absolute pathname or blocklist)
     This error is returned if a filename is requested which doesn't fit the syntax/rules listed in the Filesystems.

10 : Bad file or directory type
     This error is returned if a file requested is not a regular file, but something like a symbolic link, directory, or FIFO.

11 : File not found
     This error is returned if the specified filename cannot be found, but everything else (like the disk/partition info) is OK.

12 : Cannot mount selected partition
     This error is returned if the partition requested exists, but the filesystem type cannot be recognized by GRUB.

13 : Inconsistent filesystem structure
     This error is returned by the filesystem code to denote an internal error caused by the sanity checks of the filesystem structure on disk not matching what it expects. This is usually caused by a corrupt filesystem or bugs in the code handling it in GRUB.

14 : Filesystem compatibility error, can't read whole file
     Some of the filesystem reading code in GRUB has limits on the length of the files it can read. This error is returned when the user runs into such a limit.

15 : Error while parsing number
     This error is returned if GRUB was expecting to read a number and encountered bad data.

16 : Device string unrecoginizable
     This error is returned if a device string was expected, and the string encountered didn't fit the syntax/rules listed in the Filesystems.

17 : Invald device requested
     This error is returned if a device string is recognizable but does not fall under the other device errors.

18 : Invalid or unsupported executable format
     This error is returned if the kernel image being loaded is not recognized as Multiboot or one of the supported native formats (Linux zImage or bzImage, FreeBSD, or NetBSD).

19 : Loading below 1MB is not supported
     This error is returned if the lowest address in a kernel is below the 1MB boundary. The Linux zImage format is a special case and can be handled since it has a fixed loading address and maximum size.

20 : Unsupported Multiboot features requested
     This error is returned when the Multiboot features word in the Multiboot header requires a feature that is not recognized. The point of this is that the kernel requires special handling which GRUB is likely usable to provide.

21 : Unknow boot failure
     This error is returned if the boot attempt did not suceed for reasons which are unknown.

22 : Must load Multiboot kernel before modules
     This error is returned if the module load command is used before loading a Multiboot kernel. It only makes sense in this case anyway, as GRUB has no idea how to communicate the presense of location of such modules to a non-Multiboot-aware kernel.

23 : Must load Linux kernel before initrd
     This error is returned if the initrd command is used before loading a Linux kernel. Similar to the above error, it only makes sense in that case anyway.

24 : Cannot boot without kernel loaded
     This error is returned if GRUB is told to execute the boot sequence without having a kernel to start.

25 : Unrecognized command
     This error is returned if an unrecognized command is entered into the command-line or in a boot sequence section of a configuration file and that entry is selected.

26 : Bad or incompatible header on compressed file
     This error is returned if the file header for a supposedly compressed file is bad.

27 : Bad or corrupt data while decompressing file
     This error is returned the run-length decompression code gets an internal error. This is usually from a corrupt file.

28 : Bad or corrupt version of stage1/stage2
     This error is returned if the install command is pointed to incompatible or corrupt versions of the stage1 or stage2. It can't detect corruption in general, but this is a sanity check on the version numbers, which should be correct.

Standard booting interface
**************************

boot-proposal.html

Implementation details
**********************

technical.html embedded_data.txt PC_partitioning.txt