1N/A@c %**start of header
1N/A@settitle GRUB Manual
1N/A@c Unify all our little indices for now.
1N/A@footnotestyle separate
1N/A* GRUB: (grub). The GRand Unified Bootloader
1N/A* grub-install: (grub)Invoking grub-install. Install GRUB on your drive
1N/A* grub-md5-crypt: (grub)Invoking grub-md5-crypt. Encrypt a password
1N/A* grub-terminfo: (grub)Invoking grub-terminfo. Generate a terminfo
1N/A* grub-set-default: (grub)Invoking grub-set-default. Set a default boot
1N/A* mbchk: (grub)Invoking mbchk. Check for the format of a Multiboot kernel
1N/A@setchapternewpage odd
1N/ACopyright @copyright{} 1999,2000,2001,2002,2004 Free Software Foundation, Inc.
1N/APermission is granted to make and distribute verbatim copies of
1N/Athis manual provided the copyright notice and this permission notice
1N/Aare preserved on all copies.
1N/APermission is granted to process this file through TeX and print the
1N/Aresults, provided the printed document carries a copying permission
1N/Anotice identical to this one except for the removal of this paragraph
1N/A(this paragraph not being relevant to the printed manual).
1N/APermission is granted to copy and distribute modified versions of this
1N/Amanual under the conditions for verbatim copying, provided also that
1N/Athe entire resulting derived work is distributed under the terms of a
1N/Apermission notice identical to this one.
1N/APermission is granted to copy and distribute translations of this manual
1N/Ainto another language, under the above conditions for modified versions.
1N/A@title the GRUB manual
1N/A@subtitle The GRand Unified Bootloader, version @value{VERSION}, @value{UPDATED}.
1N/A@author Gordon Matzigkeit
1N/A@author Yoshinori K. Okuji
1N/A@c The following two commands start the copyright page.
1N/A@vskip 0pt plus 1filll
1N/ACopyright @copyright{} 1999,2000,2001,2002,2004 Free Software Foundation, Inc.
1N/APermission is granted to make and distribute verbatim copies of
1N/Athis manual provided the copyright notice and this permission notice
1N/Aare preserved on all copies.
1N/APermission is granted to copy and distribute modified versions of this
1N/Amanual under the conditions for verbatim copying, provided that the entire
1N/Aresulting derived work is distributed under the terms of a permission
1N/Anotice identical to this one.
1N/APermission is granted to copy and distribute translations of this manual
1N/Ainto another language, under the above conditions for modified versions,
1N/Aexcept that this permission notice may be stated in a translation approved
1N/Aby Free Software Foundation.
1N/A@c Output the table of contents at the beginning.
1N/AThis is the documentation of GNU GRUB, the GRand Unified Bootloader,
1N/Aa flexible and powerful boot loader program for @sc{pc}s.
1N/AThis edition documents version @value{VERSION}.
1N/A* Introduction:: Capturing the spirit of GRUB
1N/A* Naming convention:: Names of your drives in GRUB
1N/A* Installation:: Installing GRUB on your drive
1N/A* Booting:: How to boot different operating systems
1N/A* Configuration:: Writing your own configuration file
1N/A* Network:: Downloading OS images from a network
1N/A* Serial terminal:: Using GRUB via a serial line
1N/A* Preset Menu:: Embedding a configuration file into GRUB
1N/A* Security:: Improving the security
1N/A* Images:: GRUB image files
1N/A* Filesystem:: Filesystem syntax and semantics
1N/A* Interface:: The menu and the command-line
1N/A* Commands:: The list of available builtin commands
1N/A* Troubleshooting:: Error messages produced by GRUB
1N/A* Invoking the grub shell:: How to use the grub shell
1N/A* Invoking grub-install:: How to use the GRUB installer
1N/A* Invoking grub-md5-crypt:: How to generate a cryptic password
1N/A* Invoking grub-terminfo:: How to generate a terminfo command
1N/A* Invoking grub-set-default:: How to set a default boot entry
1N/A* Invoking mbchk:: How to use the Multiboot checker
1N/A* Obtaining and Building GRUB:: How to obtain and build GRUB
1N/A* Reporting bugs:: Where you should send a bug report
1N/A* Future:: Some future plans on GRUB
1N/A* Internals:: Hacking GRUB
1N/A@chapter Introduction to GRUB
1N/A* Overview:: What exactly GRUB is and how to use it
1N/A* History:: From maggot to house fly
1N/A* Features:: GRUB features
1N/A* Role of a boot loader:: The role of a boot loader
1N/ABriefly, a @dfn{boot loader} is the first software program that runs when
1N/Aa computer starts. It is responsible for loading and transferring
1N/Acontrol to an operating system @dfn{kernel} software (such as Linux or
1N/AGNU Mach). The kernel, in turn, initializes the rest of the operating
1N/AGNU GRUB is a very powerful boot loader, which can load a wide variety
1N/Aof free operating systems, as well as proprietary operating systems with
1N/Achain-loading@footnote{@dfn{chain-load} is the mechanism for loading
1N/Aunsupported operating systems by loading another boot loader. It is
1N/Atypically used for loading DOS or Windows.}. GRUB is designed to
1N/Aaddress the complexity of booting a personal computer; both the
1N/Aprogram and this manual are tightly bound to that computer platform,
1N/Aalthough porting to other platforms may be addressed in the future.
1N/AOne of the important features in GRUB is flexibility; GRUB understands
1N/Afilesystems and kernel executable formats, so you can load an arbitrary
1N/Aoperating system the way you like, without recording the physical
1N/Aposition of your kernel on the disk. Thus you can load the kernel
1N/Ajust by specifying its file name and the drive and partition where the
1N/AWhen booting with GRUB, you can use either a command-line interface
1N/A(@pxref{Command-line interface}), or a menu interface (@pxref{Menu
1N/Ainterface}). Using the command-line interface, you type the drive
1N/Aspecification and file name of the kernel manually. In the menu
1N/Ainterface, you just select an OS using the arrow keys. The menu is
1N/Abased on a configuration file which you prepare beforehand
1N/A(@pxref{Configuration}). While in the menu, you can switch to the
1N/Acommand-line mode, and vice-versa. You can even edit menu entries
1N/AIn the following chapters, you will learn how to specify a drive, a
1N/Apartition, and a file name (@pxref{Naming convention}) to GRUB, how to
1N/Ainstall GRUB on your drive (@pxref{Installation}), and how to boot your
1N/AOSes (@pxref{Booting}), step by step.
1N/ABesides the GRUB boot loader itself, there is a @dfn{grub shell}
1N/A@command{grub} (@pxref{Invoking the grub shell}) which can be run when
1N/Ayou are in your operating system. It emulates the boot loader and can
1N/Abe used for installing the boot loader.
1N/A@section History of GRUB
1N/AGRUB originated in 1995 when Erich Boleyn was trying to boot the GNU
1N/AHurd with the University of Utah's Mach 4 microkernel (now known as GNU
1N/AMach). Erich and Brian Ford designed the Multiboot Specification
1N/A(@pxref{Top, Multiboot Specification, Motivation, multiboot, The Multiboot
1N/ASpecification}), because they were determined not to add to the large
1N/Anumber of mutually-incompatible PC boot methods.
1N/AErich then began modifying the FreeBSD boot loader so that it would
1N/Aunderstand Multiboot. He soon realized that it would be a lot easier
1N/Ato write his own boot loader from scratch than to keep working on the
1N/AFreeBSD boot loader, and so GRUB was born.
1N/AErich added many features to GRUB, but other priorities prevented him
1N/Afrom keeping up with the demands of its quickly-expanding user base. In
1N/A1999, Gordon Matzigkeit and Yoshinori K. Okuji adopted GRUB as an
1N/Aofficial GNU package, and opened its development by making the latest
1N/Asources available via anonymous CVS. @xref{Obtaining and Building
1N/AGRUB}, for more information.
1N/A@section GRUB features
1N/AThe primary requirement for GRUB is that it be compliant with the
1N/A@dfn{Multiboot Specification}, which is described in @ref{Top, Multiboot
1N/ASpecification, Motivation, multiboot, The Multiboot Specification}.
1N/AThe other goals, listed in approximate order of importance, are:
1N/ABasic functions must be straightforward for end-users.
1N/ARich functionality to support kernel experts and designers.
1N/ABackward compatibility for booting FreeBSD, NetBSD, OpenBSD, and
1N/ALinux. Proprietary kernels (such as DOS, Windows NT, and OS/2) are
1N/Asupported via a chain-loading function.
1N/AExcept for specific compatibility modes (chain-loading and the Linux
1N/A@dfn{piggyback} format), all kernels will be started in much the same
1N/Astate as in the Multiboot Specification. Only kernels loaded at 1 megabyte
1N/Aor above are presently supported. Any attempt to load below that
1N/Aboundary will simply result in immediate failure and an error message
1N/Areporting the problem.
1N/AIn addition to the requirements above, GRUB has the following features
1N/A(note that the Multiboot Specification doesn't require all the features
1N/A@item Recognize multiple executable formats
1N/ASupport many of the @dfn{
a.out} variants plus @dfn{ELF}. Symbol
1N/Atables are also loaded.
1N/A@item Support non-Multiboot kernels
1N/ASupport many of the various free 32-bit kernels that lack Multiboot
1N/Acompliance (primarily FreeBSD, NetBSD, OpenBSD, and
1N/ALinux). Chain-loading of other boot loaders is also supported.
1N/A@item Load multiples modules
1N/AFully support the Multiboot feature of loading multiple modules.
1N/A@item Load a configuration file
1N/ASupport a human-readable text configuration file with preset boot
1N/Acommands. You can also load another configuration file dynamically and
1N/Aembed a preset configuration file in a GRUB image file. The list of
1N/Acommands (@pxref{Commands}) are a superset of those supported on the
1N/Acommand-line. An example configuration file is provided in
1N/A@item Provide a menu interface
1N/AA menu interface listing preset boot commands, with a programmable
1N/Atimeout, is available. There is no fixed limit on the number of boot
1N/Aentries, and the current implementation has space for several hundred.
1N/A@item Have a flexible command-line interface
1N/AA fairly flexible command-line interface, accessible from the menu,
1N/Ais available to edit any preset commands, or write a new boot command
1N/Aset from scratch. If no configuration file is present, GRUB drops to
1N/AThe list of commands (@pxref{Commands}) are a subset of those supported
1N/Afor configuration files. Editing commands closely resembles the Bash
1N/Acommand-line (@pxref{Command Line Editing, Bash, Command Line Editing,
1N/Afeatures, Bash Features}), with @key{TAB}-completion of commands,
1N/Adevices, partitions, and files in a directory depending on context.
1N/A@item Support multiple filesystem types
1N/ASupport multiple filesystem types transparently, plus a useful explicit
1N/Ablocklist notation. The currently supported filesystem types are
1N/A@dfn{BSD FFS}, @dfn{DOS FAT16 and FAT32}, @dfn{Minix fs}, @dfn{Linux
1N/Aext2fs}, @dfn{ReiserFS}, @dfn{JFS}, @dfn{XFS}, and @dfn{VSTa
1N/Afs}. @xref{Filesystem}, for more information.
1N/A@item Support automatic decompression
1N/ACan decompress files which were compressed by @command{gzip}. This
1N/Afunction is both automatic and transparent to the user (
i.e. all
1N/Afunctions operate upon the uncompressed contents of the specified
1N/Afiles). This greatly reduces a file size and loading time, a
1N/Aparticularly great benefit for floppies.@footnote{There are a few
1N/Apathological cases where loading a very badly organized ELF kernel might
1N/Atake longer, but in practice this never happen.}
1N/AIt is conceivable that some kernel modules should be loaded in a
1N/Acompressed state, so a different module-loading command can be specified
1N/Ato avoid uncompressing the modules.
1N/A@item Access data on any installed device
1N/ASupport reading data from any or all floppies or hard disk(s) recognized
1N/Aby the BIOS, independent of the setting of the root device.
1N/A@item Be independent of drive geometry translations
1N/AUnlike many other boot loaders, GRUB makes the particular drive
1N/Atranslation irrelevant. A drive installed and running with one
1N/Atranslation may be converted to another translation without any adverse
1N/Aeffects or changes in GRUB's configuration.
1N/A@item Detect all installed @sc{ram}
1N/AGRUB can generally find all the installed @sc{ram} on a PC-compatible
1N/Amachine. It uses an advanced BIOS query technique for finding all
1N/Amemory regions. As described on the Multiboot Specification (@pxref{Top,
1N/AMultiboot Specification, Motivation, multiboot, The Multiboot
1N/ASpecification}), not all kernels make use of this information, but GRUB
1N/Aprovides it for those who do.
1N/A@item Support Logical Block Address mode
1N/AIn traditional disk calls (called @dfn{CHS mode}), there is a geometry
1N/Atranslation problem, that is, the BIOS cannot access over 1024
1N/Acylinders, so the accessible space is limited to at least 508 MB and to
1N/Aat most 8GB. GRUB can't universally solve this problem, as there is no
1N/Astandard interface used in all machines. However, several newer machines
1N/Ahave the new interface, Logical Block Address (@dfn{LBA}) mode. GRUB
1N/Aautomatically detects if LBA mode is available and uses it if
1N/Aavailable. In LBA mode, GRUB can access the entire disk.
1N/A@item Support network booting
1N/AGRUB is basically a disk-based boot loader but also has network
1N/Asupport. You can load OS images from a network by using the @dfn{TFTP}
1N/A@item Support remote terminals
1N/ATo support computers with no console, GRUB provides remote terminal
1N/Asupport, so that you can control GRUB from a remote host. Only serial
1N/Aterminal support is implemented at the moment.
1N/A@node Role of a boot loader
1N/A@section The role of a boot loader
1N/AThe following is a quotation from Gordon Matzigkeit, a GRUB fanatic:
1N/ASome people like to acknowledge both the operating system and kernel when
1N/Athey talk about their computers, so they might say they use
1N/Akernel is the most important part of the system, so they like to call
1N/Atheir GNU operating systems ``Linux systems.''
1N/AI, personally, believe that this is a grave injustice, because the
1N/A@emph{boot loader} is the most important software of all. I used to
1N/Arefer to the above systems as either ``LILO''@footnote{The LInux LOader,
1N/Aa boot loader that everybody uses, but nobody likes.} or ``GRUB''
1N/AUnfortunately, nobody ever understood what I was talking about; now I
1N/Ajust use the word ``GNU'' as a pseudonym for GRUB.
1N/ASo, if you ever hear people talking about their alleged ``GNU'' systems,
1N/Aremember that they are actually paying homage to the best boot loader
1N/AWe, the GRUB maintainers, do not (usually) encourage Gordon's level of
1N/Afanaticism, but it helps to remember that boot loaders deserve
1N/Arecognition. We hope that you enjoy using GNU GRUB as much as we did
1N/A@node Naming convention
1N/A@chapter Naming convention
1N/AThe device syntax used in GRUB is a wee bit different from what you may
1N/Ahave seen before in your operating system(s), and you need to know it so
1N/ALook at the following examples and explanations:
1N/AFirst of all, GRUB requires that the device name be enclosed with
1N/A@samp{(} and @samp{)}. The @samp{fd} part means that it is a floppy
1N/Adisk. The number @samp{0} is the drive number, which is counted from
1N/A@emph{zero}. This expression means that GRUB will use the whole floppy
1N/AHere, @samp{hd} means it is a hard disk drive. The first integer
1N/A@samp{0} indicates the drive number, that is, the first hard disk, while
1N/Athe second integer, @samp{1}, indicates the partition number (or the
1N/A@sc{pc} slice number in the BSD terminology). Once again, please note
1N/Athat the partition numbers are counted from @emph{zero}, not from
1N/Aone. This expression means the second partition of the first hard disk
1N/Adrive. In this case, GRUB uses one partition of the disk, instead of the
1N/AThis specifies the first @dfn{extended partition} of the first hard disk
1N/Adrive. Note that the partition numbers for extended partitions are
1N/Acounted from @samp{4}, regardless of the actual number of primary
1N/Apartitions on your hard disk.
1N/AThis means the BSD @samp{a} partition of the second hard disk. If you
1N/Aneed to specify which @sc{pc} slice number should be used, use something
1N/Alike this: @samp{(hd1,0,a)}. If the @sc{pc} slice number is omitted,
1N/AGRUB searches for the first @sc{pc} slice which has a BSD @samp{a}
1N/AOf course, to actually access the disks or partitions with GRUB, you
1N/Aneed to use the device specification in a command, like @samp{root
1N/A(fd0)} or @samp{unhide (hd0,2)}. To help you find out which number
1N/Aspecifies a partition you want, the GRUB command-line
1N/A(@pxref{Command-line interface}) options have argument
1N/Acompletion. This means that, for example, you only need to type
1N/Afollowed by a @key{TAB}, and GRUB will display the list of drives,
1N/Apartitions, or file names. So it should be quite easy to determine the
1N/Aname of your target partition, even with minimal knowledge of the
1N/ANote that GRUB does @emph{not} distinguish IDE from SCSI - it simply
1N/Acounts the drive numbers from zero, regardless of their type. Normally,
1N/Aany IDE drive number is less than any SCSI drive number, although that
1N/Ais not true if you change the boot sequence by swapping IDE and SCSI
1N/ANow the question is, how to specify a file? Again, consider an
1N/AThis specifies the file named @samp{vmlinuz}, found on the first
1N/Apartition of the first hard disk drive. Note that the argument
1N/Acompletion works with file names, too.
1N/AThat was easy, admit it. Now read the next chapter, to find out how to
1N/Aactually install GRUB on your drive.
1N/A@chapter Installation
1N/AIn order to install GRUB as your boot loader, you need to first
1N/Ainstall the GRUB system and utilities under your UNIX-like operating
1N/Asystem (@pxref{Obtaining and Building GRUB}). You can do this either
1N/Afrom the source tarball, or as a package for your OS.
1N/AAfter you have done that, you need to install the boot loader on a
1N/Adrive (floppy or hard disk). There are two ways of doing that - either
1N/Ausing the utility @command{grub-install} (@pxref{Invoking
1N/Agrub-install}) on a UNIX-like OS, or by running GRUB itself from a
1N/Afloppy. These are quite similar, however the utility might probe a
1N/Awrong BIOS drive, so you should be careful.
1N/AAlso, if you install GRUB on a UNIX-like OS, please make sure that you
1N/Ahave an emergency boot disk ready, so that you can rescue your computer
1N/Aif, by any chance, your hard drive becomes unusable (unbootable).
1N/AGRUB comes with boot images, which are normally put in the directory
1N/Ayou need to copy the files @file{stage1}, @file{stage2}, and
1N/A@command{grub-set-default} (@pxref{Invoking grub-set-default}) if you
1N/Aintend to use @samp{default saved} (@pxref{default}) in your
1N/Aconfiguration file. Hereafter, the directory where GRUB images are
1N/Acalled the @dfn{image directory}, and the directory where the boot
1N/Aloader needs to find them (usually @file{
/boot/grub}) will be called
1N/Athe @dfn{boot directory}.
1N/A* Creating a GRUB boot floppy::
1N/A* Installing GRUB natively::
1N/A* Installing GRUB using grub-install::
1N/A* Making a GRUB bootable CD-ROM::
1N/A@node Creating a GRUB boot floppy
1N/A@section Creating a GRUB boot floppy
1N/ATo create a GRUB boot floppy, you need to take the files @file{stage1}
1N/Aand @file{stage2} from the image directory, and write them to the first
1N/Aand the second block of the floppy disk, respectively.
1N/A@strong{Caution:} This procedure will destroy any data currently stored
1N/AOn a UNIX-like operating system, that is done with the following
1N/AThe device file name may be different. Consult the manual for your OS.
1N/A@node Installing GRUB natively
1N/A@section Installing GRUB natively
1N/A@strong{Caution:} Installing GRUB's stage1 in this manner will erase the
1N/Anormal boot-sector used by an OS.
1N/AGRUB can currently boot GNU Mach, Linux, FreeBSD, NetBSD, and OpenBSD
1N/Adirectly, so using it on a boot sector (the first sector of a
1N/Apartition) should be okay. But generally, it would be a good idea to
1N/Aback up the first sector of the partition on which you are installing
1N/AGRUB's stage1. This isn't as important if you are installing GRUB on
1N/Athe first sector of a hard disk, since it's easy to reinitialize it
1N/A(
e.g. by running @samp{FDISK /MBR} from DOS).
1N/AIf you decide to install GRUB in the native environment, which is
1N/Adefinitely desirable, you'll need to create a GRUB boot disk, and
1N/Areboot your computer with it. Otherwise, see @ref{Installing GRUB using
1N/AOnce started, GRUB will show the command-line interface
1N/A(@pxref{Command-line interface}). First, set the GRUB's @dfn{root
1N/Adevice}@footnote{Note that GRUB's root device doesn't necessarily mean
1N/Ayour OS's root partition; if you need to specify a root partition for
1N/Ayour OS, add the argument into the command @command{kernel}.} to the
1N/Apartition containing the boot directory, like this:
1N/Agrub> @kbd{root (hd0,0)}
1N/AIf you are not sure which partition actually holds this directory, use the
1N/Acommand @command{find} (@pxref{find}), like this:
1N/Adevices which contain the file.
1N/AOnce you've set the root device correctly, run the command
1N/A@command{setup} (@pxref{setup}):
1N/Agrub> @kbd{setup (hd0)}
1N/AThis command will install the GRUB boot loader on the Master Boot
1N/ARecord (MBR) of the first drive. If you want to put GRUB into the boot
1N/Asector of a partition instead of putting it in the MBR, specify the
1N/Apartition into which you want to install GRUB:
1N/Agrub> @kbd{setup (hd0,0)}
1N/AIf you install GRUB into a partition or a drive other than the first
1N/Aone, you must chain-load GRUB from another boot loader. Refer to the
1N/Amanual for the boot loader to know how to chain-load GRUB.
1N/AAfter using the setup command, you will boot into GRUB without the
1N/AGRUB floppy. See the chapter @ref{Booting} to find out how to boot
1N/Ayour operating systems from GRUB.
1N/A@node Installing GRUB using grub-install
1N/A@section Installing GRUB using grub-install
1N/A@strong{Caution:} This procedure is definitely less safe, because
1N/Athere are several ways in which your computer can become
1N/Aunbootable. For example, most operating systems don't tell GRUB how to
1N/Amap BIOS drives to OS devices correctly---GRUB merely @dfn{guesses}
1N/Athe mapping. This will succeed in most cases, but not
1N/Aalways. Therefore, GRUB provides you with a map file called the
1N/A@dfn{device map}, which you must fix if it is wrong. @xref{Device
1N/Amap}, for more details.
1N/AIf you still do want to install GRUB under a UNIX-like OS (such
1N/Aas @sc{gnu}), invoke the program @command{grub-install} (@pxref{Invoking
1N/Agrub-install}) as the superuser (@dfn{root}).
1N/AThe usage is basically very simple. You only need to specify one
1N/Aargument to the program, namely, where to install the boot loader. The
1N/Aargument can be either a device file (like @samp{
/dev/hda}) or a
1N/Apartition specified in GRUB's notation. For example, under Linux the
1N/Afollowing will install GRUB into the MBR of the first IDE disk:
1N/AIf it is the first BIOS drive, this is the same as well:
1N/A# @kbd{grub-install '(hd0)'}
1N/AOr you can omit the parentheses:
1N/A# @kbd{grub-install hd0}
1N/ABut all the above examples assume that GRUB should use images under
1N/Athe root directory. If you want GRUB to use images under a directory
1N/Aother than the root directory, you need to specify the option
1N/A@option{--root-directory}. The typical usage is that you create a GRUB
1N/Aboot floppy with a filesystem. Here is an example:
1N/A# @kbd{grub-install --root-directory=/mnt fd0}
1N/AAnother example is when you have a separate boot partition
1N/Awhich is mounted at @file{/boot}. Since GRUB is a boot loader, it
1N/Adoesn't know anything about mountpoints at all. Thus, you need to run
1N/A@command{grub-install} like this:
1N/ABy the way, as noted above, it is quite difficult to guess BIOS drives
1N/Acorrectly under a UNIX-like OS. Thus, @command{grub-install} will prompt
1N/Ayou to check if it could really guess the correct mappings, after the
1N/Ainstallation. The format is defined in @ref{Device map}. Please be
1N/Aquite careful. If the output is wrong, it is unlikely that your
1N/Acomputer will be able to boot with no problem.
1N/ANote that @command{grub-install} is actually just a shell script and the
1N/Areal task is done by the grub shell @command{grub} (@pxref{Invoking the
1N/Agrub shell}). Therefore, you may run @command{grub} directly to install
1N/AGRUB, without using @command{grub-install}. Don't do that, however,
1N/Aunless you are very familiar with the internals of GRUB. Installing a
1N/Aboot loader on a running OS may be extremely dangerous.
1N/A@node Making a GRUB bootable CD-ROM
1N/A@section Making a GRUB bootable CD-ROM
1N/AGRUB supports the @dfn{no emulation mode} in the El Torito
1N/Aspecification@footnote{El Torito is a specification for bootable CD
1N/Ausing BIOS functions.}. This means that you can use the whole CD-ROM
1N/Afrom GRUB and you don't have to make a floppy or hard disk image file,
1N/Awhich can cause compatibility problems.
1N/AFor booting from a CD-ROM, GRUB uses a special Stage 2 called
1N/A@file{stage2_eltorito}. The only GRUB files you need to have in your
1N/Abootable CD-ROM are this @file{stage2_eltorito} and optionally a config file
1N/A@file{
menu.lst}. You don't need to use @file{stage1} or @file{stage2},
1N/Abecause El Torito is quite different from the standard boot process.
1N/AHere is an example of procedures to make a bootable CD-ROM
1N/Aimage. First, make a top directory for the bootable image, say,
1N/AMake a directory for GRUB:
1N/ACopy the file @file{stage2_eltorito}:
1N/A(@pxref{Configuration}), and copy any files and directories for the disc to the
1N/Adirectory @file{iso/}.
1N/AFinally, make a ISO9660 image file like this:
1N/AThis produces a file named @file{
grub.iso}, which then can be burned
1N/Ainto a CD (or a DVD). @kbd{mkisofs} has already set up the disc to boot
1N/Asetup GRUB on the disc. (Note that the @kbd{-boot-load-size 4} bit is
1N/Arequired for compatibility with the BIOS on many older machines.)
1N/AYou can use the device @samp{(cd)} to access a CD-ROM in your
1N/Aconfig file. This is not required; GRUB automatically sets the root device
1N/Ato @samp{(cd)} when booted from a CD-ROM. It is only necessary to refer to
1N/A@samp{(cd)} if you want to access other drives as well.
1N/AGRUB can load Multiboot-compliant kernels in a consistent way,
1N/Abut for some free operating systems you need to use some OS-specific
1N/A* General boot methods:: How to boot OSes with GRUB generally
1N/A* OS-specific notes:: Notes on some operating systems
1N/A* Making your system robust:: How to make your system robust
1N/A@node General boot methods
1N/A@section How to boot operating systems
1N/AGRUB has two distinct boot methods. One of the two is to load an
1N/Aoperating system directly, and the other is to chain-load another boot
1N/Aloader which then will load an operating system actually. Generally
1N/Aspeaking, the former is more desirable, because you don't need to
1N/Ainstall or maintain other boot loaders and GRUB is flexible enough to
1N/Athe latter is sometimes required, since GRUB doesn't support all the
1N/Aexisting operating systems natively.
1N/A* Loading an operating system directly::
1N/A@node Loading an operating system directly
1N/A@subsection How to boot an OS directly with GRUB
1N/AMultiboot (@pxref{Top, Multiboot Specification, Motivation, multiboot,
1N/AThe Multiboot Specification}) is the native format supported by GRUB.
1N/AFor the sake of convenience, there is also support for Linux, FreeBSD,
1N/ANetBSD and OpenBSD. If you want to boot other operating systems, you
1N/Awill have to chain-load them (@pxref{Chain-loading}).
1N/AGenerally, GRUB can boot any Multiboot-compliant OS in the following
1N/ASet GRUB's root device to the drive where the OS images are stored with
1N/Athe command @command{root} (@pxref{root}).
1N/ALoad the kernel image with the command @command{kernel} (@pxref{kernel}).
1N/AIf you need modules, load them with the command @command{module}
1N/A(@pxref{module}) or @command{modulenounzip} (@pxref{modulenounzip}).
1N/ARun the command @command{boot} (@pxref{boot}).
1N/ALinux, FreeBSD, NetBSD and OpenBSD can be booted in a similar
1N/Amanner. You load a kernel image with the command @command{kernel} and
1N/Athen run the command @command{boot}. If the kernel requires some
1N/Aparameters, just append the parameters to @command{kernel}, after the
1N/Afile name of the kernel. Also, please refer to @ref{OS-specific notes},
1N/Afor information on your OS-specific issues.
1N/A@subsection Load another boot loader to boot unsupported operating systems
1N/AIf you want to boot an unsupported operating system (
e.g. Windows 95),
1N/Achain-load a boot loader for the operating system. Normally, the boot
1N/Aloader is embedded in the @dfn{boot sector} of the partition on which
1N/Athe operating system is installed.
1N/ASet GRUB's root device to the partition by the command
1N/A@command{rootnoverify} (@pxref{rootnoverify}):
1N/Agrub> @kbd{rootnoverify (hd0,0)}
1N/ASet the @dfn{active} flag in the partition using the command
1N/A@command{makeactive}@footnote{This is not necessary for most of the
1N/Amodern operating systems.} (@pxref{makeactive}):
1N/Agrub> @kbd{makeactive}
1N/ALoad the boot loader with the command @command{chainloader}
1N/A(@pxref{chainloader}):
1N/Agrub> @kbd{chainloader +1}
1N/A@samp{+1} indicates that GRUB should read one sector from the start of
1N/Athe partition. The complete description about this syntax can be found
1N/Ain @ref{Block list syntax}.
1N/ARun the command @command{boot} (@pxref{boot}).
1N/AHowever, DOS and Windows have some deficiencies, so you might have to
1N/A@node OS-specific notes
1N/A@section Some caveats on OS-specific issues
1N/AHere, we describe some caveats on several operating systems.
1N/ASince
GNU/Hurd is Multiboot-compliant, it is easy to boot it; there is
1N/Anothing special about it. But do not forget that you have to specify a
1N/Aroot partition to the kernel.
1N/ASet GRUB's root device to the same drive as
GNU/Hurd's. Probably the
1N/ALoad the kernel and the module, like this:
1N/ARun the command @command{boot} (@pxref{boot}).
1N/AIt is relatively easy to boot
GNU/Linux from GRUB, because it somewhat
1N/Aresembles to boot a Multiboot-compliant OS.
1N/ASet GRUB's root device to the same drive as
GNU/Linux's. Probably the
1N/Acommand @code{find /vmlinuz} or similar can help you (@pxref{find}).
1N/AIf you need to specify some kernel parameters, just append them to the
1N/Acommand. For example, to set @option{vga} to @samp{ext}, do this:
1N/ASee the documentation in the Linux source tree for complete
1N/Ainformation on the available options.
1N/AIf you use an initrd, execute the command @command{initrd}
1N/A(@pxref{initrd}) after @command{kernel}:
1N/Agrub> @kbd{initrd /initrd}
1N/AFinally, run the command @command{boot} (@pxref{boot}).
1N/A@strong{Caution:} If you use an initrd and specify the @samp{mem=}
1N/Aoption to the kernel to let it use less than actual memory size, you
1N/Awill also have to specify the same memory size to GRUB. To let GRUB know
1N/Athe size, run the command @command{uppermem} @emph{before} loading the
1N/Akernel. @xref{uppermem}, for more information.
1N/AGRUB can load the kernel directly, either in ELF or
a.out format. But
1N/Athis is not recommended, since FreeBSD's bootstrap interface sometimes
1N/Achanges heavily, so GRUB can't guarantee to pass kernel parameters
1N/AThus, we'd recommend loading the very flexible loader
1N/Agrub> @kbd{root (hd0,a)}
1N/AGRUB can load NetBSD
a.out and ELF directly, follow these steps:
1N/ASet GRUB's root device with @command{root} (@pxref{root}).
1N/ALoad the kernel with @command{kernel} (@pxref{kernel}). You should
1N/Aappend the ugly option @option{--type=netbsd}, if you want to load an
1N/AELF kernel, like this:
1N/Agrub> @kbd{kernel --type=netbsd /netbsd-elf}
1N/ARun @command{boot} (@pxref{boot}).
1N/AFor now, however, GRUB doesn't allow you to pass kernel parameters, so
1N/Ait may be better to chain-load it instead. For more information, please
1N/Asee @ref{Chain-loading}.
1N/AThe booting instruction is exactly the same as for NetBSD
1N/AGRUB cannot boot DOS or Windows directly, so you must chain-load them
1N/A(@pxref{Chain-loading}). However, their boot loaders have some critical
1N/Adeficiencies, so it may not work to just chain-load them. To overcome
1N/Athe problems, GRUB provides you with two helper functions.
1N/AIf you have installed DOS (or Windows) on a non-first hard disk, you
1N/Ahave to use the disk swapping technique, because that OS cannot boot
1N/Afrom any disks but the first one. The workaround used in GRUB is the
1N/Acommand @command{map} (@pxref{map}), like this:
1N/Agrub> @kbd{map (hd0) (hd1)}
1N/Agrub> @kbd{map (hd1) (hd0)}
1N/AThis performs a @dfn{virtual} swap between your first and second hard
1N/A@strong{Caution:} This is effective only if DOS (or Windows) uses BIOS
1N/Ato access the swapped disks. If that OS uses a special driver for the
1N/Adisks, this probably won't work.
1N/AAnother problem arises if you installed more than one set of
DOS/Windows 1N/Aonto one disk, because they could be confused if there are more than one
1N/Athis, but there is a solution if you do want to do so. Use the partition
1N/AIf GRUB @dfn{hide}s a DOS (or Windows) partition (@pxref{hide}), DOS (or
1N/AWindows) will ignore the partition. If GRUB @dfn{unhide}s a DOS (or
1N/AWindows) partition (@pxref{unhide}), DOS (or Windows) will detect the
1N/Apartition. Thus, if you have installed DOS (or Windows) on the first
1N/Aand the second partition of the first hard disk, and you want to boot
1N/Athe copy on the first partition, do the following:
1N/Agrub> @kbd{unhide (hd0,0)}
1N/Agrub> @kbd{hide (hd0,1)}
1N/Agrub> @kbd{rootnoverify (hd0,0)}
1N/Agrub> @kbd{chainloader +1}
1N/Agrub> @kbd{makeactive}
1N/A@subsection SCO UnixWare
1N/AIt is known that the signature in the boot loader for SCO UnixWare is
1N/Awrong, so you will have to specify the option @option{--force} to
1N/A@command{chainloader} (@pxref{chainloader}), like this:
1N/Agrub> @kbd{rootnoverify (hd1,0)}
1N/Agrub> @kbd{chainloader --force +1}
1N/Agrub> @kbd{makeactive}
1N/AQNX seems to use a bigger boot loader, so you need to boot it up, like
1N/Agrub> @kbd{rootnoverify (hd1,1)}
1N/Agrub> @kbd{chainloader +4}
1N/A@node Making your system robust
1N/A@section How to make your system robust
1N/AWhen you test a new kernel or a new OS, it is important to make sure
1N/Athat your computer can boot even if the new system is unbootable. This
1N/Ais crucial especially if you maintain servers or remote systems. To
1N/Aaccomplish this goal, you need to set up two things:
1N/AYou must maintain a system which is always bootable. For instance, if
1N/Ayou test a new kernel, you need to keep a working kernel in a
1N/Adifferent place. And, it would sometimes be very nice to even have a
1N/Acomplete copy of a working system in a different partition or disk.
1N/AYou must direct GRUB to boot a working system when the new system
1N/Afails. This is possible with the @dfn{fallback} system in GRUB.
1N/AThe former requirement is very specific to each OS, so this
1N/Adocumentation does not cover that topic. It is better to consult some
1N/ASo let's see the GRUB part. There are two possibilities: one of them
1N/Ais quite simple but not very robust, and the other is a bit complex to
1N/Aset up but probably the best solution to make sure that your system
1N/Acan start as long as GRUB itself is bootable.
1N/A* Booting once-only::
1N/A* Booting fallback systems::
1N/A@node Booting once-only
1N/A@subsection Booting once-only
1N/AYou can teach GRUB to boot an entry only at next boot time. Suppose
1N/Athat your have an old kernel @file{old_kernel} and a new kernel
1N/A@file{new_kernel}. You know that @file{old_kernel} can boot
1N/Ayour system correctly, and you want to test @file{new_kernel}.
1N/ATo ensure that your system will go back to the old kernel even if the
1N/Anew kernel fails (
e.g. it panics), you can specify that GRUB should
1N/Atry the new kernel only once and boot the old kernel after that.
1N/AFirst, modify your configuration file. Here is an example:
1N/Adefault saved # This is important!!!
1N/Asavedefault 0 # This is important!!!
1N/ANote that this configuration file uses @samp{default saved}
1N/A(@pxref{default}) at the head and @samp{savedefault 0}
1N/A(@pxref{savedefault}) in the entry for the new kernel. This means
1N/Athat GRUB boots a saved entry by default, and booting the entry for the
1N/Anew kernel saves @samp{0} as the saved entry.
1N/AWith this configuration file, after all, GRUB always tries to boot the
1N/Aold kernel after it booted the new one, because @samp{0} is the entry
1N/Aof @code{the old kernel}.
1N/AThe next step is to tell GRUB to boot the new kernel at next boot
1N/Atime. For this, execute @command{grub-set-default} (@pxref{Invoking
1N/A# @kbd{grub-set-default 1}
1N/AThis command sets the saved entry to @samp{1}, that is, to the new
1N/AThis method is useful, but still not very robust, because GRUB stops
1N/Abooting, if there is any error in the boot entry, such that the new
1N/Akernel has an invalid executable format. Thus, it it even better to
1N/Ause the @dfn{fallback} mechanism of GRUB. Look at next subsection for
1N/A@node Booting fallback systems
1N/A@subsection Booting fallback systems
1N/AGRUB supports a fallback mechanism of booting one or more other
1N/Aentries if a default boot entry fails. You can specify multiple
1N/Afallback entries if you wish.
1N/ASuppose that you have three systems, @samp{A}, @samp{B} and
1N/A@samp{C}. @samp{A} is a system which you want to boot by
1N/Adefault. @samp{B} is a backup system which is supposed to boot
1N/Asafely. @samp{C} is another backup system which is used in case where
1N/AThen you may want GRUB to boot the first system which is bootable
1N/Aamong @samp{A}, @samp{B} and @samp{C}. A configuration file can be
1N/Adefault saved # This is important!!!
1N/Afallback 1 2 # This is important!!!
1N/Asavedefault fallback # This is important!!!
1N/Asavedefault fallback # This is important!!!
1N/ANote that @samp{default saved} (@pxref{default}), @samp{fallback 1 2}
1N/Aand @samp{savedefault fallback} are used. GRUB will boot a saved entry
1N/Aby default and save a fallback entry as next boot entry with this
1N/AWhen GRUB tries to boot @samp{A}, GRUB saves @samp{1} as next boot
1N/Aentry, because the command @command{fallback} specifies that @samp{1}
1N/Ais the first fallback entry. The entry @samp{1} is @samp{B}, so GRUB
1N/Awill try to boot @samp{B} at next boot time.
1N/ALikewise, when GRUB tries to boot @samp{B}, GRUB saves @samp{2} as
1N/Anext boot entry, because @command{fallback} specifies @samp{2} as next
1N/Afallback entry. This makes sure that GRUB will boot @samp{C} after
1N/AIt is noteworthy that GRUB uses fallback entries both when GRUB
1N/Aitself fails in booting an entry and when @samp{A} or @samp{B} fails
1N/Ain starting up your system. So this solution ensures that your system
1N/Ais started even if GRUB cannot find your kernel or if your kernel
1N/AHowever, you need to run @command{grub-set-default} (@pxref{Invoking
1N/Agrub-set-default}) when @samp{A} starts correctly or you fix @samp{A}
1N/Aafter it crashes, since GRUB always sets next boot entry to a fallback
1N/Aentry. You should run this command in a startup script such as
1N/A# @kbd{grub-set-default 0}
1N/Awhere @samp{0} is the number of the boot entry for the system
1N/AIf you want to see what is current default entry, you can look at the
1N/Asome systems). Because this file is plain-text, you can just
1N/A@command{cat} this file. But it is strongly recommended @strong{not to
1N/Amodify this file directly}, because GRUB may fail in saving a default
1N/Aentry in this file, if you change this file in an unintended
1N/Amanner. Therefore, you should use @command{grub-set-default} when you
1N/Aneed to change the default entry.
1N/A@chapter Configuration
1N/AYou've probably noticed that you need to type several commands to boot your
1N/AOS. There's a solution to that - GRUB provides a menu interface
1N/A(@pxref{Menu interface}) from which you can select an item (using arrow
1N/Akeys) that will do everything to boot an OS.
1N/ATo enable the menu, you need a configuration file,
1N/A@file{
menu.lst} under the boot directory. We'll analyze an example
1N/AThe file first contains some general settings, the menu interface
1N/Arelated options. You can put these commands (@pxref{Menu-specific
1N/Acommands}) before any of the items (starting with @command{title}
1N/A# Sample boot menu configuration file
1N/AAs you may have guessed, these lines are comments. Lines starting with a
1N/Ahash character (@samp{#}), and blank lines, are ignored by GRUB.
1N/A# By default, boot the first entry.
1N/AThe first entry (here, counting starts with number zero, not one!) will
1N/Abe the default choice.
1N/A# Boot automatically after 30 secs.
1N/AAs the comment says, GRUB will boot automatically in 30 seconds, unless
1N/Ainterrupted with a keypress.
1N/A# Fallback to the second entry.
1N/AIf, for any reason, the default entry doesn't work, fall back to the
1N/Asecond one (this is rarely used, for obvious reasons).
1N/ANote that the complete descriptions of these commands, which are menu
1N/Ainterface specific, can be found in @ref{Menu-specific
1N/Acommands}. Other descriptions can be found in @ref{Commands}.
1N/ANow, on to the actual OS definitions. You will see that each entry
1N/Abegins with a special command, @command{title} (@pxref{title}), and the
1N/Aaction is described after it. Note that there is no command
1N/A@command{boot} (@pxref{boot}) at the end of each item. That is because
1N/AGRUB automatically executes @command{boot} if it loads other commands
1N/AThe argument for the command @command{title} is used to display a short
1N/Adisplays the argument as is, you can write basically anything there.
1N/A# For booting Mach (getting kernel from floppy)
1N/Atitle Utah Mach4 multiboot
1N/Apause Insert the diskette now^G!!
1N/AThis boots Mach with a kernel on a floppy, but the root filesystem at
1N/Ahd0s3. It also contains a @command{pause} line (@pxref{pause}), which
1N/Awill cause GRUB to display a prompt and delay, before actually executing
1N/Athe rest of the commands and booting.
1N/A# For booting FreeBSD
1N/AThis item will boot FreeBSD kernel loaded from the @samp{a} partition of
1N/Athe third @sc{pc} slice of the first hard disk.
1N/A# chainload OS/2 bootloader from the first sector
1N/A# This is similar to "chainload", but loads a specific file
1N/AThis will boot OS/2, using a chain-loader (@pxref{Chain-loading}).
1N/A# For booting Windows NT or Windows95
1N/Atitle Windows NT / Windows 95 boot menu
1N/A# For loading DOS if Windows NT is installed
1N/AThe same as the above, but for Windows.
1N/A# For installing GRUB into the hard disk
1N/Atitle Install GRUB into the hard disk
1N/AThis will just (re)install GRUB onto the hard disk.
1N/Atitle Change the colors
1N/AIn the last entry, the command @command{color} is used (@pxref{color}),
1N/Ato change the menu colors (try it!). This command is somewhat special,
1N/Abecause it can be used both in the command-line and in the menu. GRUB
1N/Ahas several such commands, see @ref{General commands}.
1N/AWe hope that you now understand how to use the basic features of
1N/AGRUB. To learn more about GRUB, see the following chapters.
1N/A@chapter Downloading OS images from a network
1N/AAlthough GRUB is a disk-based boot loader, it does provide network
1N/Asupport. To use the network support, you need to enable at least one
1N/Anetwork driver in the GRUB build process. For more information please
1N/A* General usage of network support::
1N/A@node General usage of network support
1N/A@section How to set up your network
1N/AGRUB requires a file server and optionally a server that will assign an
1N/AIP address to the machine on which GRUB is running. For the former, only
1N/ATFTP is supported at the moment. The latter is either BOOTP, DHCP or a
1N/ARARP server@footnote{RARP is not advised, since it cannot serve much
1N/Ainformation}. It is not necessary to run both the servers on one
1N/Acomputer. How to configure these servers is beyond the scope of this
1N/Adocument, so please refer to the manuals specific to those
1N/AIf you decided to use a server to assign an IP address, set up the
1N/Aserver and run @command{bootp} (@pxref{bootp}), @command{dhcp}
1N/A(@pxref{dhcp}) or @command{rarp} (@pxref{rarp}) for BOOTP, DHCP or RARP,
1N/Arespectively. Each command will show an assigned IP address, a netmask,
1N/Aan IP address for your TFTP server and a gateway. If any of the
1N/Aaddresses is wrong or it causes an error, probably the configuration of
1N/Ayour servers isn't set up properly.
1N/AOtherwise, run @command{ifconfig}, like this:
1N/Agrub> @kbd{ifconfig --address=192.168.110.23 --server=192.168.110.14}
1N/AYou can also use @command{ifconfig} in conjuction with @command{bootp},
1N/A@command{dhcp} or @command{rarp} (
e.g. to reassign the server address
1N/Amanually). @xref{ifconfig}, for more details.
1N/AFinally, download your OS images from your network. The network can be
1N/Aaccessed using the network drive @samp{(nd)}. Everything else is very
1N/Asimilar to the normal instructions (@pxref{Booting}).
1N/AAddress: 192.168.110.23 Netmask: 255.255.255.0
1N/AServer: 192.168.110.14 Gateway: 192.168.110.1
1N/Agrub> @kbd{root (nd)}
1N/A@section Booting from a network
1N/AIt is sometimes very useful to boot from a network, especially when you
1N/Ause a machine which has no local disk. In this case, you need to obtain
1N/Aa kind of Net Boot @sc{rom}, such as a PXE @sc{rom} or a free software
1N/Apackage like Etherboot. Such a Boot @sc{rom} first boots the machine,
1N/Asets up the network card installed into the machine, and downloads a
1N/Asecond stage boot image from the network. Then, the second image will
1N/Atry to boot an operating system actually from the network.
1N/AGRUB provides two second stage images, @file{nbgrub} and
1N/A@file{pxegrub} (@pxref{Images}). These images are the same as the
1N/Anormal Stage 2, except that they set up a network automatically, and try
1N/Ato load a configuration file from the network, if specified. The usage
1N/Ais very simple: If the machine has a PXE @sc{rom}, use
1N/A@file{pxegrub}. If the machine has an NBI loader such as Etherboot, use
1N/A@file{nbgrub}. There is no difference between them except their
1N/Aformats. Since the way to load a second stage image you want to use
1N/Ashould be described in the manual on your Net Boot @sc{rom}, please
1N/Arefer to the manual, for more information.
1N/AHowever, there is one thing specific to GRUB. Namely, how to specify a
1N/Aconfiguration file in a
BOOTP/DHCP server. For now, GRUB uses the tag
1N/A@samp{150}, to get the name of a configuration file. The following is an
1N/Aexample with a BOOTP configuration:
1N/A.allhost:hd=/tmp:bf=null:\
1N/A :ds=145.71.35.1 145.71.32.1:\
1N/Afoo:ht=1:ha=63655d0334a7:ip=145.71.35.127:\
1N/ANote that you should specify the drive name @code{(nd)} in the name of
1N/Athe configuration file. This is because you might change the root drive
1N/Abefore downloading the configuration from the TFTP server when the
1N/Apreset menu feature is used (@pxref{Preset Menu}).
1N/AGRUB sends the string "GRUBClient" as its vendor class identifier to
1N/Athe
BOOTP/DHCP server. This can be used to generate answers specific
1N/Ato GRUB clients on your network.
1N/ASee the manual of your
BOOTP/DHCP server for more information. The
1N/Aexact syntax should differ a little from the example.
1N/A@node Serial terminal
1N/A@chapter Using GRUB via a serial line
1N/AThis chapter describes how to use the serial terminal support in GRUB.
1N/Acould be very useful to control the computers through serial
1N/Acommunications. To connect one computer with another via a serial line,
1N/Ayou need to prepare a null-modem (cross) serial cable, and you may need
1N/Ato have multiport serial boards, if your computer doesn't have extra
1N/Aserial ports. In addition, a terminal emulator is also required, such as
1N/Aminicom. Refer to a manual of your operating system, for more
1N/AAs for GRUB, the instruction to set up a serial terminal is quite
1N/Asimple. First of all, make sure that you haven't specified the option
1N/A@option{--disable-serial} to the configure script when you built your
1N/AGRUB images. If you get them in binary form, probably they have serial
1N/Aterminal support already.
1N/AThen, initialize your serial terminal after GRUB starts up. Here is an
1N/Agrub> @kbd{serial --unit=0 --speed=9600}
1N/Agrub> @kbd{terminal serial}
1N/AThe command @command{serial} initializes the serial unit 0 with the
1N/Aspeed 9600bps. The serial unit 0 is usually called @samp{COM1}, so, if
1N/Ayou want to use COM2, you must specify @samp{--unit=1} instead. This
1N/Acommand accepts many other options, so please refer to @ref{serial},
1N/AThe command @command{terminal} (@pxref{terminal}) chooses which type of
1N/Aterminal you want to use. In the case above, the terminal will be a
1N/Aserial terminal, but you can also pass @code{console} to the command,
1N/Aas @samp{terminal serial console}. In this case, a terminal in which
1N/Ayou press any key will be selected as a GRUB terminal.
1N/AHowever, note that GRUB assumes that your terminal emulator is
1N/Acompatible with VT100 by default. This is true for most terminal
1N/Aemulators nowadays, but you should pass the option @option{--dumb} to
1N/Athe command if your terminal emulator is not VT100-compatible or
1N/Aimplements few VT100 escape sequences. If you specify this option then
1N/AGRUB provides you with an alternative menu interface, because the normal
1N/Amenu requires several fancy features of your terminal.
1N/A@chapter Embedding a configuration file into GRUB
1N/AGRUB supports a @dfn{preset menu} which is to be always loaded before
1N/Astarting. The preset menu feature is useful, for example, when your
1N/Acomputer has no console but a serial cable. In this case, it is
1N/Acritical to set up the serial terminal as soon as possible, since you
1N/Acannot see any message until the serial terminal begins to work. So it
1N/Ais good to run the commands @command{serial} (@pxref{serial}) and
1N/A@command{terminal} (@pxref{terminal}) before anything else at the
1N/AHow the preset menu works is slightly complicated:
1N/AGRUB checks if the preset menu feature is used, and loads the preset
1N/Amenu, if available. This includes running commands and reading boot
1N/Aentries, like an ordinary configuration file.
1N/AGRUB checks if the configuration file is available. Note that this check
1N/Ais performed @strong{regardless of the existence of the preset
1N/Amenu}. The configuration file is loaded even if the preset menu was
1N/AIf the preset menu includes any boot entries, they are cleared when
1N/Athe configuration file is loaded. It doesn't matter whether the
1N/Aconfiguration file has any entries or no entry. The boot entries in the
1N/Apreset menu are used only when GRUB fails in loading the configuration
1N/ATo enable the preset menu feature, you must rebuild GRUB specifying a
1N/Afile to the configure script with the option
1N/A@option{--enable-preset-menu}. The file has the same semantics as
1N/Anormal configuration files (@pxref{Configuration}).
1N/AAnother point you should take care is that the diskless support
1N/A(@pxref{Diskless}) diverts the preset menu. Diskless images embed a
1N/Apreset menu to execute the command @command{bootp} (@pxref{bootp})
1N/Aautomatically, unless you specify your own preset menu to the configure
1N/Ascript. This means that you must put commands to initialize a network in
1N/Athe preset menu yourself, because diskless images don't set it up
1N/Aimplicitly, when you use the preset menu explicitly.
1N/ATherefore, a typical preset menu used with diskless support would be
1N/A# Set up the serial terminal, first of all.
1N/Aserial --unit=0 --speed=19200
1N/Aterminal --timeout=0 serial
1N/A# Initialize the network.
1N/A@chapter Protecting your computer from cracking
1N/AYou may be interested in how to prevent ordinary users from doing
1N/Awhatever they like, if you share your computer with other people. So
1N/Athis chapter describes how to improve the security of GRUB.
1N/AOne thing which could be a security hole is that the user can do too
1N/Amany things with GRUB, because GRUB allows one to modify its configuration
1N/Aand run arbitrary commands at run-time. For example, the user can even
1N/A@command{cat} (@pxref{cat}). So it is necessary to disable all the
1N/Ainteractive operations.
1N/AThus, GRUB provides a @dfn{password} feature, so that only administrators
1N/Acan start the interactive operations (
i.e. editing menu entries and
1N/Aentering the command-line interface). To use this feature, you need to
1N/Arun the command @command{password} in your configuration file
1N/A(@pxref{password}), like this:
1N/Apassword --md5 PASSWORD
1N/AIf this is specified, GRUB disallows any interactive control, until you
1N/Apress the key @key{p} and enter a correct password. The option
1N/A@option{--md5} tells GRUB that @samp{PASSWORD} is in MD5 format. If it
1N/Ais omitted, GRUB assumes the @samp{PASSWORD} is in clear text.
1N/AYou can encrypt your password with the command @command{md5crypt}
1N/A(@pxref{md5crypt}). For example, run the grub shell (@pxref{Invoking the
1N/Agrub shell}), and enter your password:
1N/AEncrypted: $1$U$JK7xFegdxWH6VuppCUSIb.
1N/AThen, cut and paste the encrypted password to your configuration file.
1N/AAlso, you can specify an optional argument to @command{password}. See
1N/Aconfiguration file when you enter the valid password.
1N/AAnother thing which may be dangerous is that any user can choose any
1N/Amenu entry. Usually, this wouldn't be problematic, but you might want to
1N/Apermit only administrators to run some of your menu entries, such as an
1N/Aentry for booting an insecure OS like DOS.
1N/AGRUB provides the command @command{lock} (@pxref{lock}). This command
1N/Aalways fails until you enter the valid password, so you can use it, like
1N/AYou should insert @command{lock} right after @command{title}, because
1N/Aany user can execute commands in an entry until GRUB encounters
1N/AYou can also use the command @command{password} instead of
1N/A@command{lock}. In this case the boot process will ask for the password
1N/Aand stop if it was entered incorrectly. Since the @command{password}
1N/Atakes its own @var{PASSWORD} argument this is useful if you want
1N/Adifferent passwords for different entries.
1N/A@chapter GRUB image files
1N/AGRUB consists of several images: two essential stages, optional stages
1N/Acalled @dfn{Stage 1.5}, one image for bootable CD-ROM, and two network
1N/Aboot images. Here is a short overview of them. @xref{Internals}, for
1N/AThis is an essential image used for booting up GRUB. Usually, this is
1N/Aembedded in an MBR or the boot sector of a partition. Because a PC boot
1N/Asector is 512 bytes, the size of this image is exactly 512 bytes.
1N/AAll @file{stage1} must do is to load Stage 2 or Stage 1.5 from a local
1N/Adisk. Because of the size restriction, @file{stage1} encodes the
1N/Alocation of Stage 2 (or Stage 1.5) in a block list format, so it never
1N/Aunderstand any filesystem structure.
1N/AThis is the core image of GRUB. It does everything but booting up
1N/Aitself. Usually, this is put in a filesystem, but that is not required.
1N/A@itemx minix_stage1_5
1N/A@itemx reiserfs_stage1_5
1N/A@itemx vstafs_stage1_5
1N/AThese are called @dfn{Stage 1.5}, because they serve as a bridge
1N/Abetween @file{stage1} and @file{stage2}, that is to say, Stage 1.5 is
1N/Aloaded by Stage 1 and Stage 1.5 loads Stage 2. The difference between
1N/A@file{stage1} and @file{*_stage1_5} is that the former doesn't
1N/Aunderstand any filesystem while the latter understands one filesystem
1N/A(
e.g. @file{e2fs_stage1_5} understands ext2fs). So you can move the
1N/AStage 2 image to another location safely, even after GRUB has been
1N/AWhile Stage 2 cannot generally be embedded in a fixed area as the size
1N/Ais so large, Stage 1.5 can be installed into the area right after an MBR,
1N/Aor the boot loader area of a ReiserFS or a FFS.
1N/A@item stage2_eltorito
1N/AThis is a boot image for CD-ROMs using the @dfn{no emulation mode} in
1N/AEl Torito specification. This is identical to Stage 2, except that
1N/Athis boots up without Stage 1 and sets up a special drive @samp{(cd)}.
1N/AThis is a network boot image for the Network Image Proposal used by some
1N/Anetwork boot loaders, such as Etherboot. This is mostly the same as
1N/AStage 2, but it also sets up a network and loads a configuration file
1N/AThis is another network boot image for the Preboot Execution Environment
1N/Aused by several Netboot ROMs. This is identical to @file{nbgrub}, except
1N/A@chapter Filesystem syntax and semantics
1N/AGRUB uses a special syntax for specifying disk drives which can be
1N/Aaccessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish
1N/Abetween IDE, ESDI, SCSI, or others. You must know yourself which BIOS
1N/Adevice is equivalent to which OS device. Normally, that will be clear if
1N/Ayou see the files in a device or use the command @command{find}
1N/A* Device syntax:: How to specify devices
1N/A* File name syntax:: How to specify files
1N/A* Block list syntax:: How to specify block lists
1N/A@section How to specify devices
1N/AThe device syntax is like this:
1N/A@code{(@var{device}[,@var{part-num}][,@var{bsd-subpart-letter}])}
1N/A@samp{[]} means the parameter is optional. @var{device} should be
1N/Aeither @samp{fd} or @samp{hd} followed by a digit, like @samp{fd0}.
1N/ABut you can also set @var{device} to a hexadecimal or a decimal number
1N/Awhich is a BIOS drive number, so the following are equivalent:
1N/A@var{part-num} represents the partition number of @var{device}, starting
1N/Afrom zero for primary partitions and from four for extended partitions,
1N/Aand @var{bsd-subpart-letter} represents the BSD disklabel subpartition,
1N/Asuch as @samp{a} or @samp{e}.
1N/AA shortcut for specifying BSD subpartitions is
1N/A@code{(@var{device},@var{bsd-subpart-letter})}, in this case, GRUB
1N/Asearches for the first PC partition containing a BSD disklabel, then
1N/Afinds the subpartition @var{bsd-subpart-letter}. Here is an example:
1N/AThe syntax @samp{(hd0)} represents using the entire disk (or the
1N/AMBR when installing GRUB), while the syntax @samp{(hd0,0)}
1N/Arepresents using the first partition of the disk (or the boot sector
1N/Aof the partition when installing GRUB).
1N/AIf you enabled the network support, the special drive, @samp{(nd)}, is
1N/Aalso available. Before using the network drive, you must initialize the
1N/Anetwork. @xref{Network}, for more information.
1N/AIf you boot GRUB from a CD-ROM, @samp{(cd)} is available. @xref{Making
1N/Aa GRUB bootable CD-ROM}, for details.
1N/A@node File name syntax
1N/A@section How to specify files
1N/AThere are two ways to specify files, by @dfn{absolute file name} and by
1N/AAn absolute file name resembles a Unix absolute file name, using
1N/A@samp{/} for the directory separator (not @samp{\} as in DOS). One
1N/Adisk. If you omit the device name in an absolute file name, GRUB uses
1N/AGRUB's @dfn{root device} implicitly. So if you set the root device to,
1N/Asay, @samp{(hd1,0)} by the command @command{root} (@pxref{root}), then
1N/A@node Block list syntax
1N/A@section How to specify block lists
1N/AA block list is used for specifying a file that doesn't appear in the
1N/Afilesystem, like a chainloader. The syntax is
1N/A@code{[@var{offset}]+@var{length}[,[@var{offset}]+@var{length}]@dots{}}.
1N/A@code{0+100,200+1,300+300}
1N/AThis represents that GRUB should read blocks 0 through 99, block 200,
1N/Aand blocks 300 through 599. If you omit an offset, then GRUB assumes
1N/ALike the file name syntax (@pxref{File name syntax}), if a blocklist
1N/Adoes not contain a device name, then GRUB uses GRUB's @dfn{root
1N/Adevice}. So @code{(hd0,1)+1} is the same as @code{+1} when the root
1N/Adevice is @samp{(hd0,1)}.
1N/A@chapter GRUB's user interface
1N/AGRUB has both a simple menu interface for choosing preset entries from a
1N/Aconfiguration file, and a highly flexible command-line for performing
1N/Aany desired combination of boot commands.
1N/AGRUB looks for its configuration file as soon as it is loaded. If one
1N/Ais found, then the full menu interface is activated using whatever
1N/Aentries were found in the file. If you choose the @dfn{command-line} menu
1N/Aoption, or if the configuration file was not found, then GRUB drops to
1N/Athe command-line interface.
1N/A* Command-line interface:: The flexible command-line interface
1N/A* Menu interface:: The simple menu interface
1N/A* Menu entry editor:: Editing a menu entry
1N/A* Hidden menu interface:: The hidden menu interface
1N/A@node Command-line interface
1N/A@section The flexible command-line interface
1N/AThe command-line interface provides a prompt and after it an editable
1N/Atext area much like a command-line in Unix or DOS. Each command is
1N/Aimmediately executed after it is entered@footnote{However, this
1N/Abehavior will be changed in the future version, in a user-invisible
1N/Away.}. The commands (@pxref{Command-line and menu entry commands}) are a
1N/Asubset of those available in the configuration file, used with exactly
1N/ACursor movement and editing of the text on the line can be done via a
1N/Asubset of the functions available in the Bash shell:
1N/AMove forward one character.
1N/AMove back one character.
1N/AMove to the start of the line.
1N/AMove the the end of the line.
1N/ADelete the character underneath the cursor.
1N/ADelete the character to the left of the cursor.
1N/AKill the text from the current cursor position to the end of the line.
1N/AKill backward from the cursor to the beginning of the line.
1N/AYank the killed text back into the buffer at the cursor.
1N/AMove up through the history list.
1N/AMove down through the history list.
1N/AWhen typing commands interactively, if the cursor is within or before
1N/Athe first word in the command-line, pressing the @key{TAB} key (or
1N/A@key{C-i}) will display a listing of the available commands, and if the
1N/Acursor is after the first word, the @kbd{@key{TAB}} will provide a
1N/Acompletion listing of disks, partitions, and file names depending on the
1N/Acontext. Note that to obtain a list of drives, one must open a
1N/Aparenthesis, as @command{root (}.
1N/ANote that you cannot use the completion functionality in the TFTP
1N/Afilesystem. This is because TFTP doesn't support file name listing for
1N/A@section The simple menu interface
1N/AThe menu interface is quite easy to use. Its commands are both
1N/Areasonably intuitive and described on screen.
1N/ABasically, the menu interface provides a list of @dfn{boot entries} to
1N/Athe user to choose from. Use the arrow keys to select the entry of
1N/Achoice, then press @key{RET} to run it. An optional timeout is
1N/Aavailable to boot the default entry (the first one if not set), which is
1N/Aaborted by pressing any key.
1N/ACommands are available to enter a bare command-line by pressing @key{c}
1N/A(which operates exactly like the non-config-file version of GRUB, but
1N/Aallows one to return to the menu if desired by pressing @key{ESC}) or to
1N/Aedit any of the @dfn{boot entries} by pressing @key{e}.
1N/AIf you protect the menu interface with a password (@pxref{Security}),
1N/Aall you can do is choose an entry by pressing @key{RET}, or press
1N/A@key{p} to enter the password.
1N/A@node Menu entry editor
1N/A@section Editing a menu entry
1N/AThe menu entry editor looks much like the main menu interface, but the
1N/Alines in the menu are individual commands in the selected entry instead
1N/AIf an @key{ESC} is pressed in the editor, it aborts all the changes made
1N/Ato the configuration entry and returns to the main menu interface.
1N/AWhen a particular line is selected, the editor places the user in a
1N/Aspecial version of the GRUB command-line to edit that line. When the
1N/Auser hits @key{RET}, GRUB replaces the line in question in the boot
1N/Aentry with the changes (unless it was aborted via @key{ESC},
1N/Ain which case the changes are thrown away).
1N/AIf you want to add a new line to the menu entry, press @key{o} if adding
1N/Aa line after the current line or press @key{O} if before the current
1N/ATo delete a line, hit the key @key{d}. Although GRUB unfortunately
1N/Adoes not support @dfn{undo}, you can do almost the same thing by just
1N/Areturning to the main menu.
1N/A@node Hidden menu interface
1N/A@section The hidden menu interface
1N/AWhen your terminal is dumb or you request GRUB to hide the menu
1N/Ainterface explicitly with the command @command{hiddenmenu}
1N/A(@pxref{hiddenmenu}), GRUB doesn't show the menu interface (@pxref{Menu
1N/Ainterface}) and automatically boots the default entry, unless
1N/Ainterrupted by pressing @key{ESC}.
1N/AWhen you interrupt the timeout and your terminal is dumb, GRUB falls
1N/Aback to the command-line interface (@pxref{Command-line interface}).
1N/A@chapter The list of available commands
1N/AIn this chapter, we list all commands that are available in GRUB.
1N/ACommands belong to different groups. A few can only be used in
1N/Athe global section of the configuration file (or ``menu''); most
1N/Aof them can be entered on the command-line and can be used either
1N/Aanywhere in the menu or specifically in the menu entries.
1N/A* Menu-specific commands::
1N/A* Command-line and menu entry commands::
1N/A@node Menu-specific commands
1N/A@section The list of commands for the menu only
1N/AThe semantics used in parsing the configuration file are the following:
1N/AThe menu-specific commands have to be used before any others.
1N/AThe files @emph{must} be in plain-text format.
1N/A@samp{#} at the beginning of a line in a configuration file means it is
1N/AOptions are separated by spaces.
1N/AAll numbers can be either decimal or hexadecimal. A hexadecimal number
1N/Amust be preceded by @samp{0x}, and is case-insensitive.
1N/AExtra options or text at the end of the line are ignored unless otherwise
1N/AUnrecognized commands are added to the current entry, except before entries
1N/Astart, where they are ignored.
1N/AThese commands can only be used in the menu:
1N/A* default:: Set the default entry
1N/A* fallback:: Set the fallback entry
1N/A* hiddenmenu:: Hide the menu interface
1N/A* timeout:: Set the timeout
1N/A* title:: Start a menu entry
1N/A@deffn Command default num
1N/ASet the default entry to the entry number @var{num}. Numbering starts
1N/Afrom 0, and the entry number 0 is the default if the command is not
1N/AYou can specify @samp{saved} instead of a number. In this case, the
1N/Adefault entry is the entry saved with the command
1N/A@command{savedefault}. @xref{savedefault}, for more information.
1N/A@deffn Command fallback num...
1N/AGo into unattended boot mode: if the default boot entry has any errors,
1N/Ainstead of waiting for the user to do something, immediately start
1N/Aover using the @var{num} entry (same numbering as the @code{default}
1N/Acommand (@pxref{default})). This obviously won't help if the machine was
1N/Arebooted by a kernel that GRUB loaded. You can specify multiple
1N/Afallback entry numbers.
1N/A@subsection hiddenmenu
1N/A@deffn Command hiddenmenu
1N/ADon't display the menu. If the command is used, no menu will be
1N/Adisplayed on the control terminal, and the default entry will be
1N/Abooted after the timeout expired. The user can still request the
1N/Amenu to be displayed by pressing @key{ESC} before the timeout
1N/Aexpires. See also @ref{Hidden menu interface}.
1N/A@deffn Command timeout sec
1N/ASet a timeout, in @var{sec} seconds, before automatically booting the
1N/Adefault entry (normally the first entry defined).
1N/A@deffn Command title name @dots{}
1N/AStart a new boot entry, and set its name to the contents of the rest of
1N/Athe line, starting with the first non-space character.
1N/A@node General commands
1N/A@section The list of general commands
1N/ACommands usable anywhere in the menu and in the command-line.
1N/A* bootp:: Initialize a network device via BOOTP
1N/A* color:: Color the menu interface
1N/A* device:: Specify a file as a drive
1N/A* dhcp:: Initialize a network device via DHCP
1N/A* hide:: Hide a partition
1N/A* ifconfig:: Configure a network device manually
1N/A* pager:: Change the state of the internal pager
1N/A* partnew:: Make a primary partition
1N/A* parttype:: Change the type of a partition
1N/A* password:: Set a password for the menu interface
1N/A* rarp:: Initialize a network device via RARP
1N/A* serial:: Set up a serial device
1N/A* setkey:: Configure the key map
1N/A* terminal:: Choose a terminal
1N/A* terminfo:: Define escape sequences for a terminal
1N/A* tftpserver:: Specify a TFTP server
1N/A* unhide:: Unhide a partition
1N/A@deffn Command bootp [@option{--with-configfile}]
1N/AInitialize a network device via the @dfn{BOOTP} protocol. This command
1N/Ais only available if GRUB is compiled with netboot support. See also
1N/AIf you specify @option{--with-configfile} to this command, GRUB will
1N/Afetch and load a configuration file specified by your BOOTP server
1N/Awith the vendor tag @samp{150}.
1N/A@deffn Command color normal [highlight]
1N/AChange the menu colors. The color @var{normal} is used for most
1N/Alines in the menu (@pxref{Menu interface}), and the color
1N/A@var{highlight} is used to highlight the line where the cursor
1N/Apoints. If you omit @var{highlight}, then the inverted color of
1N/A@var{normal} is used for the highlighted line. The format of a color is
1N/A@code{@var{foreground}/@var{background}}. @var{foreground} and
1N/A@var{background} are symbolic color names. A symbolic color name must be
1N/A@strong{These below can be specified only for the foreground.}
1N/ABut only the first eight names can be used for @var{background}. You can
1N/Aprefix @code{blink-} to @var{foreground} if you want a blinking
1N/AThis command can be used in the configuration file and on the command
1N/Aline, so you may write something like this in your configuration file:
1N/A# Set default colors.
1N/A@deffn Command device drive file
1N/AIn the grub shell, specify the file @var{file} as the actual drive for a
1N/A@sc{bios} drive @var{drive}. You can use this command to create a disk
1N/Aimage,
and/or to fix the drives guessed by GRUB when GRUB fails to
1N/Adetermine them correctly, like this:
1N/Agrub> @kbd{device (fd0) /floppy-image}
1N/AThis command can be used only in the grub shell (@pxref{Invoking the
1N/A@deffn Command dhcp [--with-configfile]
1N/AInitialize a network device via the @dfn{DHCP} protocol. Currently,
1N/Athis command is just an alias for @command{bootp}, since the two
1N/Aprotocols are very similar. This command is only available if GRUB is
1N/Acompiled with netboot support. See also @ref{Network}.
1N/AIf you specify @option{--with-configfile} to this command, GRUB will
1N/Afetch and load a configuration file specified by your DHCP server
1N/Awith the vendor tag @samp{150}.
1N/A@deffn Command hide partition
1N/AHide the partition @var{partition} by setting the @dfn{hidden} bit in
1N/Aits partition type code. This is useful only when booting DOS or Windows
1N/Aand multiple primary FAT partitions exist in one disk. See also
1N/A@deffn Command ifconfig [@option{--server=server}] [@option{--gateway=gateway}] [@option{--mask=mask}] [@option{--address=address}]
1N/AConfigure the IP address, the netmask, the gateway, and the server
1N/Aaddress of a network device manually. The values must be in dotted
1N/Adecimal format, like @samp{192.168.11.178}. The order of the options is
1N/Anot important. This command shows current network configuration, if no
1N/Aoption is specified. See also @ref{Network}.
1N/A@deffn Command pager [flag]
1N/AToggle or set the state of the internal pager. If @var{flag} is
1N/A@samp{on}, the internal pager is enabled. If @var{flag} is @samp{off},
1N/Ait is disabled. If no argument is given, the state is toggled.
1N/A@deffn Command partnew part type from len
1N/ACreate a new primary partition. @var{part} is a partition specification
1N/Ain GRUB syntax (@pxref{Naming convention}); @var{type} is the partition
1N/Atype and must be a number in the range @code{0-0xff}; @var{from} is
1N/Athe starting address and @var{len} is the length, both in sector units.
1N/A@deffn Command parttype part type
1N/AChange the type of an existing partition. @var{part} is a partition
1N/Aspecification in GRUB syntax (@pxref{Naming convention}); @var{type}
1N/Ais the new partition type and must be a number in the range 0-0xff.
1N/A@deffn Command password [@option{--md5}] passwd [new-config-file]
1N/AIf used in the first section of a menu file, disable all interactive
1N/Aediting control (menu entry editor and command-line) and entries
1N/Aprotected by the command @command{lock}. If the password @var{passwd} is
1N/Aentered, it loads the @var{new-config-file} as a new config file and
1N/Arestarts the GRUB Stage 2, if @var{new-config-file} is
1N/Aspecified. Otherwise, GRUB will just unlock the privileged instructions.
1N/AYou can also use this command in the script section, in which case it
1N/Awill ask for the password, before continuing. The option
1N/A@option{--md5} tells GRUB that @var{passwd} is encrypted with
1N/A@command{md5crypt} (@pxref{md5crypt}).
1N/AInitialize a network device via the @dfn{RARP} protocol. This command
1N/Ais only available if GRUB is compiled with netboot support. See also
1N/A@deffn Command serial [@option{--unit=unit}] [@option{--port=port}] [@option{--speed=speed}] [@option{--word=word}] [@option{--parity=parity}] [@option{--stop=stop}] [@option{--device=dev}]
1N/AInitialize a serial device. @var{unit} is a number in the range 0-3
1N/Aspecifying which serial port to use; default is 0, which corresponds to
1N/Athe port often called COM1. @var{port} is the I/O port where the UART
1N/Ais to be found; if specified it takes precedence over @var{unit}.
1N/A@var{speed} is the transmission speed; default is 9600. @var{word} and
1N/A@var{stop} are the number of data bits and stop bits. Data bits must
1N/Abe in the range 5-8 and stop bits must be 1 or 2. Default is 8 data
1N/Abits and one stop bit. @var{parity} is one of @samp{no}, @samp{odd},
1N/A@samp{even} and defaults to @samp{no}. The option @option{--device}
1N/Acan only be used in the grub shell and is used to specify the
1N/Atty device to be used in the host operating system (@pxref{Invoking the
1N/AThe serial port is not used as a communication channel unless the
1N/A@command{terminal} command is used (@pxref{terminal}).
1N/AThis command is only available if GRUB is compiled with serial
1N/Asupport. See also @ref{Serial terminal}.
1N/A@deffn Command setkey [to_key from_key]
1N/AChange the keyboard map. The key @var{from_key} is mapped to the key
1N/A@var{to_key}. If no argument is specified, reset key mappings. Note that
1N/Athis command @emph{does not} exchange the keys. If you want to exchange
1N/Athe keys, run this command again with the arguments exchanged, like this:
1N/Agrub> @kbd{setkey capslock control}
1N/Agrub> @kbd{setkey control capslock}
1N/AA key must be an alphabet letter, a digit, or one of these symbols:
1N/A@samp{escape}, @samp{exclam}, @samp{at}, @samp{numbersign},
1N/A@samp{dollar}, @samp{percent}, @samp{caret}, @samp{ampersand},
1N/A@samp{asterisk}, @samp{parenleft}, @samp{parenright}, @samp{minus},
1N/A@samp{underscore}, @samp{equal}, @samp{plus}, @samp{backspace},
1N/A@samp{tab}, @samp{bracketleft}, @samp{braceleft}, @samp{bracketright},
1N/A@samp{braceright}, @samp{enter}, @samp{control}, @samp{semicolon},
1N/A@samp{colon}, @samp{quote}, @samp{doublequote}, @samp{backquote},
1N/A@samp{tilde}, @samp{shift}, @samp{backslash}, @samp{bar}, @samp{comma},
1N/A@samp{less}, @samp{period}, @samp{greater}, @samp{slash},
1N/A@samp{question}, @samp{alt}, @samp{space}, @samp{capslock}, @samp{FX}
1N/A(@samp{X} is a digit), and @samp{delete}. This table describes to which
1N/Acharacter each of the symbols corresponds:
1N/A@deffn Command terminal [@option{--dumb}] [@option{--no-echo}] [@option{--no-edit}] [@option{--timeout=secs}] [@option{--lines=lines}] [@option{--silent}] [@option{console}] [@option{serial}] [@option{hercules}]
1N/ASelect a terminal for user interaction. The terminal is assumed to be
1N/AVT100-compatible unless @option{--dumb} is specified. If both
1N/A@option{console} and @option{serial} are specified, then GRUB will use
1N/Athe one where a key is entered first or the first when the timeout
1N/Aexpires. If neither are specified, the current setting is
1N/Areported. This command is only available if GRUB is compiled with serial
1N/Asupport. See also @ref{Serial terminal}.
1N/AThis may not make sense for most users, but GRUB supports Hercules
1N/Aconsole as well. Hercules console is usable like the ordinary console,
1N/Aand the usage is quite similar to that for serial terminals: specify
1N/A@option{hercules} as the argument.
1N/AThe option @option{--lines} defines the number of lines in your
1N/Aterminal, and it is used for the internal pager function. If you don't
1N/Aspecify this option, the number is assumed as 24.
1N/AThe option @option{--silent} suppresses the message to prompt you to
1N/Ahit any key. This might be useful if your system has no terminal
1N/AThe option @option{--no-echo} has GRUB not to echo back input
1N/Acharacters. This implies the option @option{--no-edit}.
1N/AThe option @option{--no-edit} disables the BASH-like editing feature.
1N/A@deffn Command terminfo @option{--name=name} @option{--cursor-address=seq} [@option{--clear-screen=seq}] [@option{--enter-standout-mode=seq}] [@option{--exit-standout-mode=seq}]
1N/ADefine the capabilities of your terminal. Use this command to define
1N/Aescape sequences, if it is not vt100-compatible. You may use @samp{\e}
1N/Afor @key{ESC} and @samp{^X} for a control character.
1N/AYou can use the utility @command{grub-terminfo} to generate
1N/Aappropriate arguments to this command. @xref{Invoking grub-terminfo}.
1N/AIf no option is specified, the current settings are printed.
1N/A@subsection tftpserver
1N/A@deffn Command tftpserver ipaddr
1N/A@strong{Caution:} This command exists only for backward
1N/Acompatibility. Use @command{ifconfig} (@pxref{ifconfig}) instead.
1N/Aargument @var{ipaddr} must be in dotted decimal format, like
1N/A@samp{192.168.0.15}. This command is only available if GRUB is compiled
1N/Awith netboot support. See also @ref{Network}.
1N/A@deffn Command unhide partition
1N/AUnhide the partition @var{partition} by clearing the @dfn{hidden} bit in
1N/Aits partition type code. This is useful only when booting DOS or Windows
1N/Aand multiple primary partitions exist on one disk. See also
1N/A@node Command-line and menu entry commands
1N/A@section The list of command-line and menu entry commands
1N/AThese commands are usable in the command-line and in menu entries. If
1N/Ayou forget a command, you can run the command @command{help}
1N/A* blocklist:: Get the block list notation of a file
1N/A* boot:: Start up your operating system
1N/A* cat:: Show the contents of a file
1N/A* chainloader:: Chain-load another boot loader
1N/A* cmp:: Compare two files
1N/A* configfile:: Load a configuration file
1N/A* debug:: Toggle the debug flag
1N/A* displayapm:: Display APM information
1N/A* displaymem:: Display memory configuration
1N/A* embed:: Embed Stage 1.5
1N/A* fstest:: Test a filesystem
1N/A* geometry:: Manipulate the geometry of a drive
1N/A* halt:: Shut down your computer
1N/A* help:: Show help messages
1N/A* impsprobe:: Probe SMP
1N/A* initrd:: Load an initrd
1N/A* install:: Install GRUB
1N/A* ioprobe:: Probe I/O ports used for a drive
1N/A* kernel:: Load a kernel
1N/A* lock:: Lock a menu entry
1N/A* makeactive:: Make a partition active
1N/A* map:: Map a drive to another
1N/A* md5crypt:: Encrypt a password in MD5 format
1N/A* module:: Load a module
1N/A* modulenounzip:: Load a module without decompression
1N/A* pause:: Wait for a key press
1N/A* quit:: Exit from the grub shell
1N/A* reboot:: Reboot your computer
1N/A* read:: Read data from memory
1N/A* root:: Set GRUB's root device
1N/A* rootnoverify:: Set GRUB's root device without mounting
1N/A* savedefault:: Save current entry as the default entry
1N/A* setup:: Set up GRUB's installation automatically
1N/A* testload:: Load a file for testing a filesystem
1N/A* testvbe:: Test VESA BIOS EXTENSION
1N/A* uppermem:: Set the upper memory size
1N/A* vbeprobe:: Probe VESA BIOS EXTENSION
1N/A@subsection blocklist
1N/A@deffn Command blocklist file
1N/APrint the block list notation of the file @var{file}. @xref{Block list
1N/ABoot the OS or chain-loader which has been loaded. Only necessary if
1N/Arunning the fully interactive command-line (it is implicit at the end of
1N/A@deffn Command cat file
1N/ADisplay the contents of the file @var{file}. This command may be useful
1N/Ato remind you of your OS's root partition:
1N/A@subsection chainloader
1N/A@deffn Command chainloader [@option{--force}] file
1N/ALoad @var{file} as a chain-loader. Like any other file loaded by the
1N/Afilesystem code, it can use the blocklist notation to grab the first
1N/Asector of the current partition with @samp{+1}. If you specify the
1N/Aoption @option{--force}, then load @var{file} forcibly, whether it has a
1N/Acorrect signature or not. This is required when you want to load a
1N/Adefective boot loader, such as SCO UnixWare 7.1 (@pxref{SCO UnixWare}).
1N/A@deffn Command cmp file1 file2
1N/ACompare the file @var{file1} with the file @var{file2}. If they differ
1N/Ain size, print the sizes like this:
1N/ADiffer in size: 0x1234 [foo], 0x4321 [bar]
1N/AIf the sizes are equal but the bytes at an offset differ, then print the
1N/ADiffer at the offset 777: 0xbe [foo], 0xef [bar]
1N/AIf they are completely identical, nothing will be printed.
1N/A@subsection configfile
1N/A@deffn Command configfile file
1N/ALoad @var{file} as a configuration file.
1N/AToggle debug mode (by default it is off). When debug mode is on, some
1N/Aextra messages are printed to show disk activity. This global debug flag
1N/Ais mainly useful for GRUB developers when testing new code.
1N/A@subsection displayapm
1N/A@deffn Command displayapm
1N/ADisplay APM BIOS information.
1N/A@subsection displaymem
1N/A@deffn Command displaymem
1N/ADisplay what GRUB thinks the system address space map of the machine is,
1N/Aincluding all regions of physical @sc{ram} installed. GRUB's
1N/Athe available memory in the first megabyte, or @dfn{lower memory}, and a
1N/Asynthesized number from various BIOS interfaces of the memory starting
1N/Aat 1MB and going up to the first chipset hole for @dfn{upper memory}
1N/A(the standard PC @dfn{upper memory} interface is limited to reporting a
1N/A@deffn Command embed stage1_5 device
1N/AEmbed the Stage 1.5 @var{stage1_5} in the sectors after the MBR if
1N/A@var{device} is a drive, or in the @dfn{boot loader} area if @var{device}
1N/Ais a FFS partition or a ReiserFS partition.@footnote{The latter feature
1N/Ahas not been implemented yet.} Print the number of sectors which
1N/A@var{stage1_5} occupies, if successful.
1N/AUsually, you don't need to run this command directly. @xref{setup}.
1N/A@deffn Command find filename
1N/ASearch for the file name @var{filename} in all mountable partitions
1N/Aand print the list of the devices which contain the file. The file
1N/Aname @var{filename} should be an absolute file name like
1N/A@deffn Command fstest
1N/AToggle filesystem test mode.
1N/AFilesystem test mode, when turned on, prints out data corresponding to
1N/Aall the device reads and what values are being sent to the low-level
1N/Aroutines. The format is @samp{<@var{partition-offset-sector},
1N/A@var{byte-offset}, @var{byte-length}>} for high-level reads inside a
1N/Apartition, and @samp{[@var{disk-offset-sector}]} for low-level sector
1N/Arequests from the disk.
1N/AFilesystem test mode is turned off by any use of the @command{install}
1N/A(@pxref{install}) or @command{testload} (@pxref{testload}) commands.
1N/A@deffn Command geometry drive [cylinder head sector [total_sector]]
1N/APrint the information for the drive @var{drive}. In the grub shell, you
1N/Acan set the geometry of the drive arbitrarily. The number of
1N/Acylinders, the number of heads, the number of sectors and the number of
1N/Atotal sectors are set to CYLINDER, HEAD, SECTOR and TOTAL_SECTOR,
1N/Arespectively. If you omit TOTAL_SECTOR, then it will be calculated
1N/Abased on the C/H/S values automatically.
1N/A@deffn Command halt @option{--no-apm}
1N/AThe command halts the computer. If the @option{--no-apm} option
1N/Ais specified, no APM BIOS call is performed. Otherwise, the computer
1N/Ais shut down using APM.
1N/A@deffn Command help @option{--all} [pattern @dots{}]
1N/ADisplay helpful information about builtin commands. If you do not
1N/Aspecify @var{pattern}, this command shows short descriptions of most of
1N/Aavailable commands. If you specify the option @option{--all} to this
1N/Acommand, short descriptions of rarely used commands (such as
1N/A@ref{testload}) are displayed as well.
1N/AIf you specify any @var{patterns}, it displays longer information
1N/Aabout each of the commands which match those @var{patterns}.
1N/A@subsection impsprobe
1N/A@deffn Command impsprobe
1N/AProbe the Intel Multiprocessor Specification 1.1 or 1.4 configuration
1N/Atable and boot the various CPUs which are found into a tight loop. This
1N/Acommand can be used only in the Stage 2, but not in the grub shell.
1N/A@deffn Command initrd file @dots{}
1N/ALoad an initial ramdisk for a Linux format boot image and set the
1N/Aappropriate parameters in the Linux setup area in memory. See also
1N/A@deffn Command install [@option{--force-lba}] [@option{--stage2=os_stage2_file}] stage1_file [@option{d}] dest_dev stage2_file [addr] [@option{p}] [config_file] [real_config_file]
1N/AThis command is fairly complex, and you should not use this command
1N/Aunless you are familiar with GRUB. Use @command{setup} (@pxref{setup})
1N/AIn short, it will perform a full install presuming the Stage 2 or Stage
1N/A1.5@footnote{They're loaded the same way, so we will refer to the Stage
1N/A1.5 as a Stage 2 from now on.} is in its final install location.
1N/AIn slightly more detail, it will load @var{stage1_file}, validate that
1N/Ait is a GRUB Stage 1 of the right version number, install in it a
1N/Ablocklist for loading @var{stage2_file} as a Stage 2. If the option
1N/A@option{d} is present, the Stage 1 will always look for the actual
1N/Adisk @var{stage2_file} was installed on, rather than using the booting
1N/Adrive. The Stage 2 will be loaded at address @var{addr}, which must be
1N/A@samp{0x8000} for a true Stage 2, and @samp{0x2000} for a Stage 1.5. If
1N/A@var{addr} is not present, GRUB will determine the address
1N/Aautomatically. It then writes the completed Stage 1 to the first block
1N/Aof the device @var{dest_dev}. If the options @option{p} or
1N/A@var{config_file} are present, then it reads the first block of stage2,
1N/Amodifies it with the values of the partition @var{stage2_file} was found
1N/Aon (for @option{p}) or places the string @var{config_file} into the area
1N/Atelling the stage2 where to look for a configuration file at boot
1N/Atime. Likewise, if @var{real_config_file} is present and
1N/A@var{stage2_file} is a Stage 1.5, then the Stage 2 @var{config_file} is
1N/Apatched with the configuration file name @var{real_config_file}. This
1N/Acommand preserves the DOS BPB (and for hard disks, the partition table)
1N/Aof the sector the Stage 1 is to be installed into.
1N/A@strong{Caution:} Several buggy BIOSes don't pass a booting drive
1N/Aproperly when booting from a hard disk drive. Therefore, you will
1N/Aunfortunately have to specify the option @option{d}, whether your
1N/AStage2 resides at the booting drive or not, if you have such a
1N/ABIOS. We know these are defective in this way:
1N/AFujitsu LifeBook 400 BIOS version 31J0103A
1N/AHP Vectra XU 6/200 BIOS version GG.06.11
1N/A@strong{Caution2:} A number of BIOSes don't return a correct LBA support
1N/Abitmap even if they do have the support. So GRUB provides a solution to
1N/Aignore the wrong bitmap, that is, the option @option{--force-lba}. Don't
1N/Ause this option if you know that your BIOS doesn't have LBA support.
1N/A@strong{Caution3:} You must specify the option @option{--stage2} in the
1N/Agrub shell, if you cannot unmount the filesystem where your stage2 file
1N/Aresides. The argument should be the file name in your operating system.
1N/A@deffn Command ioprobe drive
1N/AProbe I/O ports used for the drive @var{drive}. This command will list
1N/Athe I/O ports on the screen. For technical information,
1N/A@deffn Command kernel [@option{--type=type}] [@option{--no-mem-option}] file @dots{}
1N/AAttempt to load the primary boot image (Multiboot
a.out or @sc{elf},
1N/A@var{file}. The rest of the line is passed verbatim as the @dfn{kernel
1N/Acommand-line}. Any modules must be reloaded after using this command.
1N/AThis command also accepts the option @option{--type} so that you can
1N/Aspecify the kernel type of @var{file} explicitly. The argument
1N/A@var{type} must be one of these: @samp{netbsd}, @samp{freebsd},
1N/A@samp{openbsd}, @samp{linux}, @samp{biglinux}, and
1N/A@samp{multiboot}. However, you need to specify it only if you want to
1N/Aload a NetBSD @sc{elf} kernel, because GRUB can automatically determine
1N/Aa kernel type in the other cases, quite safely.
1N/AThe option @option{--no-mem-option} is effective only for Linux. If the
1N/Aoption is specified, GRUB doesn't pass the option @option{mem=} to the
1N/Akernel. This option is implied for Linux kernels 2.4.18 and newer.
1N/APrevent normal users from executing arbitrary menu entries. You must use
1N/Athe command @command{password} if you really want this command to be
1N/Auseful (@pxref{password}).
1N/AThis command is used in a menu, as shown in this example:
1N/Atitle This entry is too dangerous to be executed by normal users
1N/Akernel /no-security-os
1N/ASee also @ref{Security}.
1N/A@subsection makeactive
1N/A@deffn Command makeactive
1N/ASet the active partition on the root disk to GRUB's root device.
1N/AThis command is limited to @emph{primary} PC partitions on a hard disk.
1N/A@deffn Command map to_drive from_drive
1N/AMap the drive @var{from_drive} to the drive @var{to_drive}. This is
1N/Anecessary when you chain-load some operating systems, such as DOS, if
1N/Asuch an OS resides at a non-first drive. Here is an example:
1N/Agrub> @kbd{map (hd0) (hd1)}
1N/Agrub> @kbd{map (hd1) (hd0)}
1N/AThe example exchanges the order between the first hard disk and the
1N/A@deffn Command md5crypt
1N/APrompt to enter a password, and encrypt it in MD5 format. The encrypted
1N/Apassword can be used with the command @command{password}
1N/A(@pxref{password}). See also @ref{Security}.
1N/A@deffn Command module file @dots{}
1N/ALoad a boot module @var{file} for a Multiboot format boot image (no
1N/Ainterpretation of the file contents are made, so the user of this
1N/Acommand must know what the kernel in question expects). The rest of the
1N/Aline is passed as the @dfn{module command-line}, like the
1N/A@command{kernel} command. You must load a Multiboot kernel image before
1N/Aloading any module. See also @ref{modulenounzip}.
1N/A@subsection modulenounzip
1N/A@deffn Command modulenounzip file @dots{}
1N/AThe same as @command{module} (@pxref{module}), except that automatic
1N/Adecompression is disabled.
1N/A@deffn Command pause message @dots{}
1N/APrint the @var{message}, then wait until a key is pressed. Note that
1N/Aplacing @key{^G} (ASCII code 7) in the message will cause the speaker to
1N/Aemit the standard beep sound, which is useful when prompting the user to
1N/AExit from the grub shell @command{grub} (@pxref{Invoking the grub
1N/Ashell}). This command can be used only in the grub shell.
1N/A@deffn Command reboot
1N/A@deffn Command read addr
1N/ARead a 32-bit value from memory at address @var{addr} and display it in
1N/A@deffn Command root device [hdbias]
1N/ASet the current @dfn{root device} to the device @var{device}, then
1N/Aattempt to mount it to get the partition size (for passing the partition
1N/Adescriptor in @code{ES:ESI}, used by some chain-loaded boot loaders), the
1N/ABSD drive-type (for booting BSD kernels using their native boot format),
1N/Aand correctly determine the PC partition where a BSD sub-partition is
1N/Alocated. The optional @var{hdbias} parameter is a number to tell a BSD
1N/Akernel how many BIOS drive numbers are on controllers before the current
1N/Aone. For example, if there is an IDE disk and a SCSI disk, and your
1N/AFreeBSD root partition is on the SCSI disk, then use a @samp{1} for
1N/ASee also @ref{rootnoverify}.
1N/A@subsection rootnoverify
1N/A@deffn Command rootnoverify device [hdbias]
1N/ASimilar to @command{root} (@pxref{root}), but don't attempt to mount the
1N/Apartition. This is useful for when an OS is outside of the area of the
1N/Adisk that GRUB can read, but setting the correct root device is still
1N/Adesired. Note that the items mentioned in @command{root} above which
1N/Aderived from attempting the mount will @emph{not} work correctly.
1N/A@subsection savedefault
1N/A@deffn Command savedefault num
1N/ASave the current menu entry or @var{num} if specified as a default
1N/Aentry. Here is an example:
1N/AWith this configuration, GRUB will choose the entry booted previously as
1N/AYou can specify @samp{fallback} instead of a number. Then, next
1N/Afallback entry is saved. Next fallback entry is chosen from fallback
1N/Aentries. Normally, this will be the first entry in fallback ones.
1N/ASee also @ref{default} and @ref{Invoking grub-set-default}.
1N/A@deffn Command setup [@option{--force-lba}] [@option{--stage2=os_stage2_file}] [@option{--prefix=dir}] install_device [image_device]
1N/ASet up the installation of GRUB automatically. This command uses the
1N/Amore flexible command @command{install} (@pxref{install}) in the backend
1N/Aand installs GRUB into the device @var{install_device}. If
1N/A@var{image_device} is specified, then find the GRUB images
1N/A(@pxref{Images}) in the device @var{image_device}, otherwise use the
1N/Acurrent @dfn{root device}, which can be set by the command
1N/A@command{root}. If @var{install_device} is a hard disk, then embed a
1N/AStage 1.5 in the disk if possible.
1N/AThe option @option{--prefix} specifies the directory under which GRUB
1N/Aimages are put. If it is not specified, GRUB automatically searches them
1N/AThe options @option{--force-lba} and @option{--stage2} are just passed
1N/Ato @command{install} if specified. @xref{install}, for more
1N/A@deffn Command testload file
1N/ARead the entire contents of @var{file} in several different ways and
1N/Acompare them, to test the filesystem code. The output is somewhat
1N/Acryptic, but if no errors are reported and the final @samp{i=@var{X},
1N/Afilepos=@var{Y}} reading has @var{X} and @var{Y} equal, then it is
1N/Adefinitely consistent, and very likely works correctly subject to a
1N/Aconsistent offset error. If this test succeeds, then a good next step is
1N/Ato try loading a kernel.
1N/A@deffn Command testvbe mode
1N/ATest the VESA BIOS EXTENSION mode @var{mode}. This command will switch
1N/Ayour video card to the graphics mode, and show an endless animation. Hit
1N/Aany key to return. See also @ref{vbeprobe}.
1N/A@deffn Command uppermem kbytes
1N/AForce GRUB to assume that only @var{kbytes} kilobytes of upper memory
1N/Aare installed. Any system address range maps are discarded.
1N/A@strong{Caution:} This should be used with great caution, and should
1N/Aonly be necessary on some old machines. GRUB's BIOS probe can pick up
1N/Aall @sc{ram} on all new machines the author has ever heard of. It can
1N/Aalso be used for debugging purposes to lie to an OS.
1N/A@deffn Command vbeprobe [mode]
1N/AProbe VESA BIOS EXTENSION information. If the mode @var{mode} is
1N/Aspecified, show only the information about @var{mode}. Otherwise, this
1N/Acommand lists up available VBE modes on the screen. See also
1N/A@node Troubleshooting
1N/A@chapter Error messages reported by GRUB
1N/AThis chapter describes error messages reported by GRUB when you
1N/Aencounter trouble. @xref{Invoking the grub shell}, if your problem is
1N/Aspecific to the grub shell.
1N/A* Stage1 errors:: Errors reported by the Stage 1
1N/A* Stage1.5 errors:: Errors reported by the Stage 1.5
1N/A* Stage2 errors:: Errors reported by the Stage 2
1N/A@section Errors reported by the Stage 1
1N/AThe general way that the Stage 1 handles errors is to print an error
1N/Astring and then halt. Pressing @kbd{@key{CTRL}-@key{ALT}-@key{DEL}} will
1N/AThe following is a comprehensive list of error messages for the Stage 1:
1N/A@item Hard Disk Error
1N/AThe stage2 or stage1.5 is being read from a hard disk, and the attempt
1N/Ato determine the size and geometry of the hard disk failed.
1N/AThe stage2 or stage1.5 is being read from a floppy disk, and the attempt
1N/Ato determine the size and geometry of the floppy disk failed. It's listed
1N/Aas a separate error since the probe sequence is different than for hard
1N/AA disk read error happened while trying to read the stage2 or stage1.5.
1N/AThe location of the stage2 or stage1.5 is not in the portion of the disk
1N/Asupported directly by the BIOS read calls. This could occur because the
1N/ABIOS translated geometry has been changed by the user or the disk is
1N/Amoved to another machine or controller after installation, or GRUB was
1N/Anot installed using itself (if it was, the Stage 2 version of this error
1N/Awould have been seen during that process and it would not have completed
1N/A@node Stage1.5 errors
1N/A@section Errors reported by the Stage 1.5
1N/AThe general way that the Stage 1.5 handles errors is to print an error
1N/Anumber in the form @code{Error @var{num}} and then halt. Pressing
1N/A@kbd{@key{CTRL}-@key{ALT}-@key{DEL}} will reboot.
1N/AThe error numbers correspond to the errors reported by Stage
1N/A2. @xref{Stage2 errors}.
1N/A@section Errors reported by the Stage 2
1N/AThe general way that the Stage 2 handles errors is to abort the
1N/Aoperation in question, print an error string, then (if possible) either
1N/Acontinue based on the fact that an error occurred or wait for the user to
1N/AThe following is a comprehensive list of error messages for the Stage 2
1N/A(error numbers for the Stage 1.5 are listed before the colon in each
1N/A@item 1 : Filename must be either an absolute filename or blocklist
1N/AThis error is returned if a file name is requested which doesn't fit the
1N/A@item 2 : Bad file or directory type
1N/AThis error is returned if a file requested is not a regular file, but
1N/Asomething like a symbolic link, directory, or FIFO.
1N/A@item 3 : Bad or corrupt data while decompressing file
1N/AThis error is returned if the run-length decompression code gets an
1N/Ainternal error. This is usually from a corrupt file.
1N/A@item 4 : Bad or incompatible header in compressed file
1N/AThis error is returned if the file header for a supposedly compressed
1N/A@item 5 : Partition table invalid or corrupt
1N/AThis error is returned if the sanity checks on the integrity of the
1N/Apartition table fail. This is a bad sign.
1N/AThis error is returned if the install command points to incompatible
1N/Aor corrupt versions of the stage1 or stage2. It can't detect corruption
1N/Ain general, but this is a sanity check on the version numbers, which
1N/A@item 7 : Loading below 1MB is not supported
1N/AThis error is returned if the lowest address in a kernel is below the
1N/A1MB boundary. The Linux zImage format is a special case and can be
1N/Ahandled since it has a fixed loading address and maximum size.
1N/A@item 8 : Kernel must be loaded before booting
1N/AThis error is returned if GRUB is told to execute the boot sequence
1N/Awithout having a kernel to start.
1N/A@item 9 : Unknown boot failure
1N/AThis error is returned if the boot attempt did not succeed for reasons
1N/A@item 10 : Unsupported Multiboot features requested
1N/AThis error is returned when the Multiboot features word in the Multiboot
1N/Aheader requires a feature that is not recognized. The point of this is
1N/Athat the kernel requires special handling which GRUB is probably
1N/A@item 11 : Unrecognized device string
1N/AThis error is returned if a device string was expected, and the string
1N/A@item 12 : Invalid device requested
1N/AThis error is returned if a device string is recognizable but does not
1N/Afall under the other device errors.
1N/A@item 13 : Invalid or unsupported executable format
1N/AThis error is returned if the kernel image being loaded is not
1N/Arecognized as Multiboot or one of the supported native formats (Linux
1N/AzImage or bzImage, FreeBSD, or NetBSD).
1N/A@item 14 : Filesystem compatibility error, cannot read whole file
1N/ASome of the filesystem reading code in GRUB has limits on the length of
1N/Athe files it can read. This error is returned when the user runs into
1N/A@item 15 : File not found
1N/AThis error is returned if the specified file name cannot be found, but
1N/A@item 16 : Inconsistent filesystem structure
1N/AThis error is returned by the filesystem code to denote an internal
1N/Aerror caused by the sanity checks of the filesystem structure on disk
1N/Anot matching what it expects. This is usually caused by a corrupt
1N/Afilesystem or bugs in the code handling it in GRUB.
1N/A@item 17 : Cannot mount selected partition
1N/AThis error is returned if the partition requested exists, but the
1N/Afilesystem type cannot be recognized by GRUB.
1N/A@item 18 : Selected cylinder exceeds maximum supported by BIOS
1N/AThis error is returned when a read is attempted at a linear block
1N/Aaddress beyond the end of the BIOS translated area. This generally
1N/Ahappens if your disk is larger than the BIOS can handle (512MB for
1N/A(E)IDE disks on older machines or larger than 8GB in general).
1N/A@item 19 : Linux kernel must be loaded before initrd
1N/AThis error is returned if the initrd command is used before loading a
1N/A@item 20 : Multiboot kernel must be loaded before modules
1N/AThis error is returned if the module load command is used before loading
1N/Aa Multiboot kernel. It only makes sense in this case anyway, as GRUB has
1N/Ano idea how to communicate the presence of such modules to a
1N/Anon-Multiboot-aware kernel.
1N/A@item 21 : Selected disk does not exist
1N/AThis error is returned if the device part of a device- or full file name
1N/Arefers to a disk or BIOS device that is not present or not recognized by
1N/Athe BIOS in the system.
1N/A@item 22 : No such partition
1N/AThis error is returned if a partition is requested in the device part of
1N/Aa device- or full file name which isn't on the selected disk.
1N/A@item 23 : Error while parsing number
1N/AThis error is returned if GRUB was expecting to read a number and
1N/Aencountered bad data.
1N/A@item 24 : Attempt to access block outside partition
1N/AThis error is returned if a linear block address is outside of the disk
1N/Apartition. This generally happens because of a corrupt filesystem on the
1N/Adisk or a bug in the code handling it in GRUB (it's a great debugging
1N/A@item 25 : Disk read error
1N/AThis error is returned if there is a disk read error when trying to
1N/Aprobe or read data from a particular disk.
1N/A@item 26 : Too many symbolic links
1N/AThis error is returned if the link count is beyond the maximum
1N/A(currently 5), possibly the symbolic links are looped.
1N/A@item 27 : Unrecognized command
1N/AThis error is returned if an unrecognized command is entered on the
1N/Acommand-line or in a boot sequence section of a configuration file and
1N/Athat entry is selected.
1N/A@item 28 : Selected item cannot fit into memory
1N/AThis error is returned if a kernel, module, or raw file load command is
1N/Aeither trying to load its data such that it won't fit into memory or it
1N/A@item 29 : Disk write error
1N/AThis error is returned if there is a disk write error when trying to
1N/Awrite to a particular disk. This would generally only occur during an
1N/Ainstall of set active partition command.
1N/A@item 30 : Invalid argument
1N/AThis error is returned if an argument specified to a command is invalid.
1N/A@item 31 : File is not sector aligned
1N/AThis error may occur only when you access a ReiserFS partition by
1N/Ablock-lists (
e.g. the command @command{install}). In this case, you
1N/Ashould mount the partition with the @samp{-o notail} option.
1N/A@item 32 : Must be authenticated
1N/AThis error is returned if you try to run a locked entry. You should
1N/Aenter a correct password before running such an entry.
1N/A@item 33 : Serial device not configured
1N/AThis error is returned if you try to change your terminal to a serial
1N/Aone before initializing any serial device.
1N/A@item 34 : No spare sectors on the disk
1N/AThis error is returned if a disk doesn't have enough spare space. This
1N/Ahappens when you try to embed Stage 1.5 into the unused sectors after
1N/Athe MBR, but the first partition starts right after the MBR or they are
1N/A@node Invoking the grub shell
1N/A@chapter Invoking the grub shell
1N/AThis chapter documents the grub shell @command{grub}. Note that the grub
1N/Ashell is an emulator; it doesn't run under the native environment, so it
1N/Asometimes does something wrong. Therefore, you shouldn't trust it too
1N/Amuch. If there is anything wrong with it, don't hesitate to try the
1N/Anative GRUB environment, especially when it guesses a wrong map between
1N/ABIOS drives and OS devices.
1N/A* Basic usage:: How to use the grub shell
1N/A* Installation under UNIX:: How to install GRUB via @command{grub}
1N/A* Device map:: The map between BIOS drives and OS devices
1N/A@section Introduction into the grub shell
1N/AYou can use the command @command{grub} for installing GRUB under your
1N/Aoperating systems and for a testbed when you add a new feature into GRUB
1N/Aor when fixing a bug. @command{grub} is almost the same as the Stage 2,
1N/Aand, in fact, it shares the source code with the Stage 2 and you can use
1N/Athe same commands (@pxref{Commands}) in @command{grub}. It is emulated by
1N/Areplacing BIOS calls with UNIX system calls and libc functions.
1N/AThe command @command{grub} accepts the following options:
1N/APrint a summary of the command-line options and exit.
1N/APrint the version number of GRUB and exit.
1N/APrint some verbose messages for debugging purpose.
1N/A@item --device-map=@var{file}
1N/AUse the device map file @var{file}. The format is described in
1N/ADo not probe any floppy drive. This option has no effect if the option
1N/A@option{--device-map} is specified (@pxref{Device map}).
1N/A@item --probe-second-floppy
1N/AProbe the second floppy drive. If this option is not specified, the grub
1N/Ashell does not probe it, as that sometimes takes a long time. If you
1N/Aspecify the device map file (@pxref{Device map}), the grub shell just
1N/A@item --config-file=@var{file}
1N/ARead the configuration file @var{file} instead of
1N/Asyntax. See @ref{Filesystem}, for more information.
1N/A@item --boot-drive=@var{drive}
1N/ASet the stage2 @var{boot_drive} to @var{drive}. This argument should be
1N/Aan integer (decimal, octal or hexadecimal).
1N/A@item --install-partition=@var{par}
1N/ASet the stage2 @var{install_partition} to @var{par}. This argument
1N/Ashould be an integer (decimal, octal or hexadecimal).
1N/A@item --no-config-file
1N/ADo not use the configuration file even if it can be read.
1N/ADo not use the screen handling interface by the curses even if it is
1N/AThis option has the same meaning as @samp{--no-config-file --no-curses}.
1N/ADisable writing to any disk.
1N/AWait until a debugger will attach. This option is useful when you want
1N/Ato debug the startup code.
1N/A@node Installation under UNIX
1N/A@section How to install GRUB via @command{grub}
1N/AThe installation procedure is the same as under the @dfn{native} Stage
1N/A2. @xref{Installation}, for more information. The command
1N/A@command{grub}-specific information is described here.
1N/AWhat you should be careful about is @dfn{buffer cache}. @command{grub}
1N/Amakes use of raw devices instead of filesystems that your operating
1N/Asystems serve, so there exists a potential problem that some cache
1N/Ainconsistency may corrupt your filesystems. What we recommend is:
1N/AIf you can unmount drives to which GRUB may write any amount of data,
1N/Aunmount them before running @command{grub}.
1N/AIf a drive cannot be unmounted but can be mounted with the read-only
1N/Aflag, mount it in read-only mode. That should be secure.
1N/AIf a drive must be mounted with the read-write flag, make sure that no
1N/Aactivity is being done on it while the command @command{grub} is
1N/AReboot your operating system as soon as possible. This is probably not
1N/Arequired if you follow the rules above, but reboot is the most secure
1N/AIn addition, enter the command @command{quit} when you finish the
1N/Ainstallation. That is @emph{very important} because @command{quit} makes
1N/Athe buffer cache consistent. Do not push @key{C-c}.
1N/AIf you want to install GRUB non-interactively, specify @samp{--batch}
1N/Aoption in the command-line. This is a simple example:
1N/A@section The map between BIOS drives and OS devices
1N/AWhen you specify the option @option{--device-map} (@pxref{Basic usage}),
1N/Athe grub shell creates the @dfn{device map file} automatically unless it
1N/AIf the device map file exists, the grub shell reads it to map BIOS
1N/Adrives to OS devices. This file consists of lines like this:
1N/A@var{device} @var{file}
1N/A@var{device} is a drive specified in the GRUB syntax (@pxref{Device
1N/Asyntax}), and @var{file} is an OS file, which is normally a device
1N/AThe reason why the grub shell gives you the device map file is that it
1N/Acannot guess the map between BIOS drives and OS devices correctly in
1N/Asome environments. For example, if you exchange the boot sequence
1N/Abetween IDE and SCSI in your BIOS, it gets the order wrong.
1N/AThus, edit the file if the grub shell makes a mistake. You can put any
1N/Acomments in the file if needed, as the grub shell assumes that a line is
1N/Ajust a comment if the first character is @samp{#}.
1N/A@node Invoking grub-install
1N/A@chapter Invoking grub-install
1N/AThe program @command{grub-install} installs GRUB on your drive using the
1N/Agrub shell (@pxref{Invoking the grub shell}). You must specify the
1N/Adevice name on which you want to install GRUB, like this:
1N/Agrub-install @var{install_device}
1N/AThe device name @var{install_device} is an OS device name or a GRUB
1N/A@command{grub-install} accepts the following options:
1N/APrint a summary of the command-line options and exit.
1N/APrint the version number of GRUB and exit.
1N/AForce GRUB to use LBA mode even for a buggy BIOS. Use this option only
1N/Aif your BIOS doesn't work properly in LBA mode even though it supports
1N/A@item --root-directory=@var{dir}
1N/AInstall GRUB images under the directory @var{dir} instead of the root
1N/Adirectory. This option is useful when you want to install GRUB into a
1N/Aseparate partition or a removable disk. Here is an example in which
1N/Ayou have a separate @dfn{boot} partition which is mounted on
1N/A@kbd{grub-install --root-directory=/boot hd0}
1N/A@item --grub-shell=@var{file}
1N/AUse @var{file} as the grub shell. You can append arbitrary options to
1N/A@var{file} after the file name, like this:
1N/A@kbd{grub-install --grub-shell="grub --read-only"
/dev/fd0}
1N/A@node Invoking grub-md5-crypt
1N/A@chapter Invoking grub-md5-crypt
1N/AThe program @command{grub-md5-crypt} encrypts a password in MD5 format.
1N/AThis is just a frontend of the grub shell (@pxref{Invoking the grub
1N/Ashell}). Passwords encrypted by this program can be used with the
1N/Acommand @command{password} (@pxref{password}).
1N/A@command{grub-md5-crypt} accepts the following options:
1N/APrint a summary of the command-line options and exit.
1N/APrint the version information and exit.
1N/A@item --grub-shell=@var{file}
1N/AUse @var{file} as the grub shell.
1N/A@node Invoking grub-terminfo
1N/A@chapter Invoking grub-terminfo
1N/AThe program @command{grub-terminfo} generates a terminfo command from
1N/Aa terminfo name (@pxref{terminfo}). The result can be used in the
1N/Aconfiguration file, to define escape sequences. Because GRUB assumes
1N/Athat your terminal is vt100-compatible by default, this would be
1N/Auseful only if your terminal is uncommon (such as vt52).
1N/A@command{grub-terminfo} accepts the following options:
1N/APrint a summary of the command-line options and exit.
1N/APrint the version information and exit.
1N/AYou must specify one argument to this command. For example:
1N/A@kbd{grub-terminfo vt52}
1N/A@node Invoking grub-set-default
1N/A@chapter Invoking grub-set-default
1N/AThe program @command{grub-set-default} sets the default boot entry for
1N/AGRUB. This automatically creates a file named @file{default} under
1N/Apresent. This file is used to determine the default boot entry when
1N/AGRUB boots up your system when you use @samp{default saved} in your
1N/Aconfiguration file (@pxref{default}), and to save next default boot
1N/Aentry when you use @samp{savedefault} in a boot entry
1N/A(@pxref{savedefault}).
1N/A@command{grub-set-default} accepts the following options:
1N/APrint a summary of the command-line options and exit.
1N/APrint the version information and exit.
1N/A@item --root-directory=@var{dir}
1N/AUse the directory @var{dir} instead of the root directory
1N/A(
i.e. @file{/}) to define the location of the default file. This
1N/Ais useful when you mount a disk which is used for another system.
1N/AYou must specify a single argument to @command{grub-set-default}. This
1N/Aargument is normally the number of a default boot entry. For example,
1N/Aif you have this configuration file:
1N/Aand if you want to set the next default boot entry to
GNU/Linux, you
1N/Amay execute this command:
1N/A@kbd{grub-set-default 1}
1N/ABecause the entry for
GNU/Linux is @samp{1}. Note that entries are
1N/Acounted from zero. So, if you want to specify
GNU/Hurd here, then you
1N/Ashould specify @samp{0}.
1N/AThis feature is very useful if you want to test a new kernel or to
1N/Amake your system quite robust. @xref{Making your system robust}, for
1N/Amore hints about how to set up a robust system.
1N/A@chapter Invoking mbchk
1N/AThe program @command{mbchk} checks for the format of a Multiboot
1N/Akernel. We recommend using this program before booting your own kernel
1N/A@command{mbchk} accepts the following options:
1N/APrint a summary of the command-line options and exit.
1N/APrint the version number of GRUB and exit.
1N/ASuppress all normal output.
1N/A@node Obtaining and Building GRUB
1N/A@appendix How to obtain and build GRUB
1N/A@strong{Caution:} GRUB requires binutils-2.9.1.0.23 or later because the
1N/AGNU assembler has been changed so that it can produce real 16bits
1N/Ahow to get the latest version.
1N/AGRUB is available from the GNU alpha archive site
1N/A@value{VERSION}, so the file you should grab is:
1N/ATo unbundle GRUB use the instruction:
1N/Awhich will create a directory called @file{grub-@value{VERSION}} with
1N/Aall the sources. You can look at the file @file{INSTALL} for detailed
1N/Ainstructions on how to build and install GRUB, but you should be able to
1N/A@kbd{cd grub-@value{VERSION}}
1N/AThis will install the grub shell @file{grub} (@pxref{Invoking the grub
1N/Ashell}), the Multiboot checker @file{mbchk} (@pxref{Invoking mbchk}),
1N/Aand the GRUB images. This will also install the GRUB manual.
1N/AAlso, the latest version is available from the CVS. See
1N/A@appendix Reporting bugs
1N/AThese are the guideline for how to report bugs. Take a look at this
1N/Alist below before you submit bugs:
1N/ABefore getting unsettled, read this manual through and through. Also,
1N/AAlways mention the information on your GRUB. The version number and the
1N/Aconfiguration are quite important. If you build it yourself, write the
1N/Aoptions specified to the configure script and your operating system,
1N/Aincluding the versions of gcc and binutils.
1N/AIf you have trouble with the installation, inform us of how you
1N/Ainstalled GRUB. Don't omit error messages, if any. Just @samp{GRUB hangs
1N/Aup when it boots} is not enough.
1N/AThe information on your hardware is also essential. These are especially
1N/Aimportant: the geometries and the partition tables of your hard disk
1N/Adrives and your BIOS.
1N/AIf GRUB cannot boot your operating system, write down
1N/A@emph{everything} you see on the screen. Don't paraphrase them, like
1N/A@samp{The foo OS crashes with GRUB, even though it can boot with the
1N/Abar boot loader just fine}. Mention the commands you executed, the
1N/Amessages printed by them, and information on your operating system
1N/Aincluding the version number.
1N/AExplain what you wanted to do. It is very useful to know your purpose
1N/Aand your wish, and how GRUB didn't satisfy you.
1N/AIf you can investigate the problem yourself, please do. That will give
1N/Ayou and us much more information on the problem. Attaching a patch is
1N/AWhen you attach a patch, make the patch in unified diff format, and
1N/Awrite ChangeLog entries. But, even when you make a patch, don't forget
1N/Ato explain the problem, so that we can understand what your patch is
1N/AWrite down anything that you think might be related. Please understand
1N/Athat we often need to reproduce the same problem you encounterred in our
1N/Aenvironment. So your information should be sufficient for us to do the
1N/Asame thing---Don't forget that we cannot see your computer directly. If
1N/Ayou are not sure whether to state a fact or leave it out, state it!
1N/AReporting too many things is much better than omitting something
1N/AIf you follow the guideline above, submit a report to the
1N/AAlternatively, you can submit a report via electronic mail to
1N/A@email{bug-grub@@
gnu.org}, but we strongly recommend that you use the
1N/ABug Tracking System, because e-mail can be passed over easily.
1N/AOnce we get your report, we will try to fix the bugs.
1N/A@appendix Where GRUB will go
1N/AWe started the next generation of GRUB, GRUB 2. This will include
1N/Ainternationalization, dynamic module loading, real memory management,
1N/Amultiple architecture support, a scripting language, and many other
1N/Anice feature. If you are interested in the development of GRUB 2, take
1N/A@c Separate the programming guide.
1N/A@c Currently, we use only the Concept Index.
1N/A This is the second attempt to rewrite the manual. The status is
1N/Amostly complete, but I need to check the spelling by ispell, and add
1N/Amore indices. Perhaps I also have to let some English native speakers
1N/Aproofread this manual through. My English is syntactically almost
1N/Aperfect, but sometimes (often?) awful in the nuance. Hehe, I can't be an
1N/AEnglish poet for now.