From 446e46a7903b55d94769312f7ca532ebd34f0d14 Mon Sep 17 00:00:00 2001 From: Robert Millan Date: Fri, 7 Aug 2009 17:18:12 +0000 Subject: [PATCH] 2009-08-07 Robert Millan * docs/grub.texi: Major overhaul. Remove all sections that are specific to GRUB Legacy, or mostly composed of Legacy-specific information. git-svn-id: svn://svn.savannah.gnu.org/grub/trunk/grub2@2480 d0de0278-0dc1-4c01-8a07-af38b3205e46 --- ChangeLog | 6 + docs/grub.texi | 5368 +++++++++++++++----------------------------------------- 2 files changed, 1412 insertions(+), 3962 deletions(-) rewrite docs/grub.texi (62%) diff --git a/ChangeLog b/ChangeLog index 4767763e..a47abd4a 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,11 @@ 2009-08-07 Robert Millan + * docs/grub.texi: Major overhaul. Remove all sections that are + specific to GRUB Legacy, or mostly composed of Legacy-specific + information. + +2009-08-07 Robert Millan + * docs/version.texi: New file. Provides version information for grub.texi. diff --git a/docs/grub.texi b/docs/grub.texi dissimilarity index 62% index 1abeb242..e3f41256 100644 --- a/docs/grub.texi +++ b/docs/grub.texi @@ -1,3962 +1,1406 @@ -\input texinfo -@c -*-texinfo-*- -@c %**start of header -@setfilename grub.info -@include version.texi -@settitle GNU GRUB Manual @value{VERSION} -@c Unify all our little indices for now. -@syncodeindex fn cp -@syncodeindex vr cp -@syncodeindex ky cp -@syncodeindex pg cp -@syncodeindex tp cp -@c %**end of header - -@footnotestyle separate -@paragraphindent 3 -@finalout - -@copying -This manual is for GNU GRUB (version @value{VERSION}, -@value{UPDATED}). - -Copyright @copyright{} 1999,2000,2001,2002,2004,2006,2008 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 or -any later version published by the Free Software Foundation; with no -Invariant Sections. -@end quotation -@end copying - -@dircategory Kernel -@direntry -* GRUB: (grub). The GRand Unified Bootloader -* grub-install: (grub)Invoking grub-install. Install GRUB on your drive -* grub-md5-crypt: (grub)Invoking grub-md5-crypt. Encrypt a password - in MD5 format -* grub-terminfo: (grub)Invoking grub-terminfo. Generate a terminfo - command from a - terminfo name -* grub-set-default: (grub)Invoking grub-set-default. Set a default boot - entry -* mbchk: (grub)Invoking mbchk. Check for the format of a Multiboot kernel -@end direntry - -@setchapternewpage odd - -@titlepage -@sp 10 -@title the GNU GRUB manual -@subtitle The GRand Unified Bootloader, version @value{VERSION}, @value{UPDATED}. -@author Gordon Matzigkeit -@author Yoshinori K. Okuji -@c The following two commands start the copyright page. -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@c Output the table of contents at the beginning. -@contents - -@finalout -@headings double - -@ifnottex -@node Top -@top GNU GRUB manual - -This is the documentation of GNU GRUB, the GRand Unified Bootloader, -a flexible and powerful boot loader program for a wide range of -architectures. - -This edition documents version @value{VERSION}. - -@insertcopying -@end ifnottex - -@menu -* Introduction:: Capturing the spirit of GRUB -* Naming convention:: Names of your drives in GRUB -* Installation:: Installing GRUB on your drive -* Booting:: How to boot different operating systems -* Configuration:: Writing your own configuration file -* Network:: Downloading OS images from a network -* Serial terminal:: Using GRUB via a serial line -* Preset Menu:: Embedding a configuration file into GRUB -* Security:: Improving the security -* Images:: GRUB image files -* Filesystem:: Filesystem syntax and semantics -* Interface:: The menu and the command-line -* Commands:: The list of available builtin commands -* Troubleshooting:: Error messages produced by GRUB -* Invoking the grub shell:: How to use the grub shell -* Invoking grub-install:: How to use the GRUB installer -* Invoking grub-md5-crypt:: How to generate a cryptic password -* Invoking grub-terminfo:: How to generate a terminfo command -* Invoking grub-set-default:: How to set a default boot entry -* Invoking mbchk:: How to use the Multiboot checker -* Obtaining and Building GRUB:: How to obtain and build GRUB -* Reporting bugs:: Where you should send a bug report -* Future:: Some future plans on GRUB -* Internals:: Hacking GRUB -* Copying This Manual:: Copying This Manual -* Index:: -@end menu - - -@node Introduction -@chapter Introduction to GRUB - -@menu -* Overview:: What exactly GRUB is and how to use it -* History:: From maggot to house fly -* Features:: GRUB features -* Role of a boot loader:: The role of a boot loader -@end menu - - -@node Overview -@section Overview - -Briefly, a @dfn{boot loader} is the first software program that runs when -a computer starts. It is responsible for loading and transferring -control to an operating system @dfn{kernel} software (such as Linux or -GNU Mach). The kernel, in turn, initializes the rest of the operating -system (e.g. a GNU system). - -GNU GRUB is a very powerful boot loader, which can load a wide variety -of free operating systems, as well as proprietary operating systems with -chain-loading@footnote{@dfn{chain-load} is the mechanism for loading -unsupported operating systems by loading another boot loader. It is -typically used for loading DOS or Windows.}. GRUB is designed to -address the complexity of booting a personal computer; both the -program and this manual are tightly bound to that computer platform, -although porting to other platforms may be addressed in the future. - -One of the important features in GRUB is flexibility; GRUB understands -filesystems and kernel executable formats, so you can load an arbitrary -operating system the way you like, without recording the physical -position of your kernel on the disk. Thus you can load the kernel -just by specifying its file name and the drive and partition where the -kernel resides. - -When booting with GRUB, you can use either a command-line interface -(@pxref{Command-line interface}), or a menu interface (@pxref{Menu -interface}). Using the command-line interface, you type the drive -specification and file name of the kernel manually. In the menu -interface, you just select an OS using the arrow keys. The menu is -based on a configuration file which you prepare beforehand -(@pxref{Configuration}). While in the menu, you can switch to the -command-line mode, and vice-versa. You can even edit menu entries -before using them. - -In the following chapters, you will learn how to specify a drive, a -partition, and a file name (@pxref{Naming convention}) to GRUB, how to -install GRUB on your drive (@pxref{Installation}), and how to boot your -OSes (@pxref{Booting}), step by step. - -Besides the GRUB boot loader itself, there is a @dfn{grub shell} -@command{grub} (@pxref{Invoking the grub shell}) which can be run when -you are in your operating system. It emulates the boot loader and can -be used for installing the boot loader. - - -@node History -@section History of GRUB - -GRUB originated in 1995 when Erich Boleyn was trying to boot the GNU -Hurd with the University of Utah's Mach 4 microkernel (now known as GNU -Mach). Erich and Brian Ford designed the Multiboot Specification -(@pxref{Top, Multiboot Specification, Motivation, multiboot, The Multiboot -Specification}), because they were determined not to add to the large -number of mutually-incompatible PC boot methods. - -Erich then began modifying the FreeBSD boot loader so that it would -understand Multiboot. He soon realized that it would be a lot easier -to write his own boot loader from scratch than to keep working on the -FreeBSD boot loader, and so GRUB was born. - -Erich added many features to GRUB, but other priorities prevented him -from keeping up with the demands of its quickly-expanding user base. In -1999, Gordon Matzigkeit and Yoshinori K. Okuji adopted GRUB as an -official GNU package, and opened its development by making the latest -sources available via anonymous CVS. @xref{Obtaining and Building -GRUB}, for more information. - - -@node Features -@section GRUB features - -The primary requirement for GRUB is that it be compliant with the -@dfn{Multiboot Specification}, which is described in @ref{Top, Multiboot -Specification, Motivation, multiboot, The Multiboot Specification}. - -The other goals, listed in approximate order of importance, are: - -@itemize @bullet{} -@item -Basic functions must be straightforward for end-users. - -@item -Rich functionality to support kernel experts and designers. - -@item -Backward compatibility for booting FreeBSD, NetBSD, OpenBSD, and -Linux. Proprietary kernels (such as DOS, Windows NT, and OS/2) are -supported via a chain-loading function. -@end itemize - -Except for specific compatibility modes (chain-loading and the Linux -@dfn{piggyback} format), all kernels will be started in much the same -state as in the Multiboot Specification. Only kernels loaded at 1 megabyte -or above are presently supported. Any attempt to load below that -boundary will simply result in immediate failure and an error message -reporting the problem. - -In addition to the requirements above, GRUB has the following features -(note that the Multiboot Specification doesn't require all the features -that GRUB supports): - -@table @asis -@item Recognize multiple executable formats -Support many of the @dfn{a.out} variants plus @dfn{ELF}. Symbol -tables are also loaded. - -@item Support non-Multiboot kernels -Support many of the various free 32-bit kernels that lack Multiboot -compliance (primarily FreeBSD, NetBSD, OpenBSD, and -Linux). Chain-loading of other boot loaders is also supported. - -@item Load multiples modules -Fully support the Multiboot feature of loading multiple modules. - -@item Load a configuration file -Support a human-readable text configuration file with preset boot -commands. You can also load another configuration file dynamically and -embed a preset configuration file in a GRUB image file. The list of -commands (@pxref{Commands}) are a superset of those supported on the -command-line. An example configuration file is provided in -@ref{Configuration}. - -@item Provide a menu interface -A menu interface listing preset boot commands, with a programmable -timeout, is available. There is no fixed limit on the number of boot -entries, and the current implementation has space for several hundred. - -@item Have a flexible command-line interface -A fairly flexible command-line interface, accessible from the menu, -is available to edit any preset commands, or write a new boot command -set from scratch. If no configuration file is present, GRUB drops to -the command-line. - -The list of commands (@pxref{Commands}) are a subset of those supported -for configuration files. Editing commands closely resembles the Bash -command-line (@pxref{Command Line Editing, Bash, Command Line Editing, -features, Bash Features}), with @key{TAB}-completion of commands, -devices, partitions, and files in a directory depending on context. - -@item Support multiple filesystem types -Support multiple filesystem types transparently, plus a useful explicit -blocklist notation. The currently supported filesystem types are -@dfn{BSD FFS}, @dfn{DOS FAT16 and FAT32}, @dfn{Minix fs}, @dfn{Linux -ext2fs}, @dfn{ReiserFS}, @dfn{JFS}, @dfn{XFS}, and @dfn{VSTa -fs}. @xref{Filesystem}, for more information. - -@item Support automatic decompression -Can decompress files which were compressed by @command{gzip}. This -function is both automatic and transparent to the user (i.e. all -functions operate upon the uncompressed contents of the specified -files). This greatly reduces a file size and loading time, a -particularly great benefit for floppies.@footnote{There are a few -pathological cases where loading a very badly organized ELF kernel might -take longer, but in practice this never happen.} - -It is conceivable that some kernel modules should be loaded in a -compressed state, so a different module-loading command can be specified -to avoid uncompressing the modules. - -@item Access data on any installed device -Support reading data from any or all floppies or hard disk(s) recognized -by the BIOS, independent of the setting of the root device. - -@item Be independent of drive geometry translations -Unlike many other boot loaders, GRUB makes the particular drive -translation irrelevant. A drive installed and running with one -translation may be converted to another translation without any adverse -effects or changes in GRUB's configuration. - -@item Detect all installed @sc{ram} -GRUB can generally find all the installed @sc{ram} on a PC-compatible -machine. It uses an advanced BIOS query technique for finding all -memory regions. As described on the Multiboot Specification (@pxref{Top, -Multiboot Specification, Motivation, multiboot, The Multiboot -Specification}), not all kernels make use of this information, but GRUB -provides it for those who do. - -@item Support Logical Block Address mode -In traditional disk calls (called @dfn{CHS mode}), there is a geometry -translation problem, that is, the BIOS cannot access over 1024 -cylinders, so the accessible space is limited to at least 508 MB and to -at most 8GB. GRUB can't universally solve this problem, as there is no -standard interface used in all machines. However, several newer machines -have the new interface, Logical Block Address (@dfn{LBA}) mode. GRUB -automatically detects if LBA mode is available and uses it if -available. In LBA mode, GRUB can access the entire disk. - -@item Support network booting -GRUB is basically a disk-based boot loader but also has network -support. You can load OS images from a network by using the @dfn{TFTP} -protocol. - -@item Support remote terminals -To support computers with no console, GRUB provides remote terminal -support, so that you can control GRUB from a remote host. Only serial -terminal support is implemented at the moment. -@end table - - -@node Role of a boot loader -@section The role of a boot loader - -The following is a quotation from Gordon Matzigkeit, a GRUB fanatic: - -@quotation -Some people like to acknowledge both the operating system and kernel when -they talk about their computers, so they might say they use -``GNU/Linux'' or ``GNU/Hurd''. Other people seem to think that the -kernel is the most important part of the system, so they like to call -their GNU operating systems ``Linux systems.'' - -I, personally, believe that this is a grave injustice, because the -@emph{boot loader} is the most important software of all. I used to -refer to the above systems as either ``LILO''@footnote{The LInux LOader, -a boot loader that everybody uses, but nobody likes.} or ``GRUB'' -systems. - -Unfortunately, nobody ever understood what I was talking about; now I -just use the word ``GNU'' as a pseudonym for GRUB. - -So, if you ever hear people talking about their alleged ``GNU'' systems, -remember that they are actually paying homage to the best boot loader -around@dots{} GRUB! -@end quotation - -We, the GRUB maintainers, do not (usually) encourage Gordon's level of -fanaticism, but it helps to remember that boot loaders deserve -recognition. We hope that you enjoy using GNU GRUB as much as we did -writing it. - - -@node Naming convention -@chapter Naming convention - -The device syntax used in GRUB is a wee bit different from what you may -have seen before in your operating system(s), and you need to know it so -that you can specify a drive/partition. - -Look at the following examples and explanations: - -@example -(fd0) -@end example - -First of all, GRUB requires that the device name be enclosed with -@samp{(} and @samp{)}. The @samp{fd} part means that it is a floppy -disk. The number @samp{0} is the drive number, which is counted from -@emph{zero}. This expression means that GRUB will use the whole floppy -disk. - -@example -(hd0,1) -@end example - -Here, @samp{hd} means it is a hard disk drive. The first integer -@samp{0} indicates the drive number, that is, the first hard disk, while -the second integer, @samp{1}, indicates the partition number (or the -@sc{pc} slice number in the BSD terminology). Once again, please note -that the partition numbers are counted from @emph{zero}, not from -one. This expression means the second partition of the first hard disk -drive. In this case, GRUB uses one partition of the disk, instead of the -whole disk. - -@example -(hd0,4) -@end example - -This specifies the first @dfn{extended partition} of the first hard disk -drive. Note that the partition numbers for extended partitions are -counted from @samp{4}, regardless of the actual number of primary -partitions on your hard disk. - -@example -(hd1,a) -@end example - -This means the BSD @samp{a} partition of the second hard disk. If you -need to specify which @sc{pc} slice number should be used, use something -like this: @samp{(hd1,0,a)}. If the @sc{pc} slice number is omitted, -GRUB searches for the first @sc{pc} slice which has a BSD @samp{a} -partition. - -Of course, to actually access the disks or partitions with GRUB, you -need to use the device specification in a command, like @samp{root -(fd0)} or @samp{unhide (hd0,2)}. To help you find out which number -specifies a partition you want, the GRUB command-line -(@pxref{Command-line interface}) options have argument -completion. This means that, for example, you only need to type - -@example -root ( -@end example - -followed by a @key{TAB}, and GRUB will display the list of drives, -partitions, or file names. So it should be quite easy to determine the -name of your target partition, even with minimal knowledge of the -syntax. - -Note that GRUB does @emph{not} distinguish IDE from SCSI - it simply -counts the drive numbers from zero, regardless of their type. Normally, -any IDE drive number is less than any SCSI drive number, although that -is not true if you change the boot sequence by swapping IDE and SCSI -drives in your BIOS. - -Now the question is, how to specify a file? Again, consider an -example: - -@example -(hd0,0)/vmlinuz -@end example - -This specifies the file named @samp{vmlinuz}, found on the first -partition of the first hard disk drive. Note that the argument -completion works with file names, too. - -That was easy, admit it. Now read the next chapter, to find out how to -actually install GRUB on your drive. - - -@node Installation -@chapter Installation - -In order to install GRUB as your boot loader, you need to first -install the GRUB system and utilities under your UNIX-like operating -system (@pxref{Obtaining and Building GRUB}). You can do this either -from the source tarball, or as a package for your OS. - -After you have done that, you need to install the boot loader on a -drive (floppy or hard disk). There are two ways of doing that - either -using the utility @command{grub-install} (@pxref{Invoking -grub-install}) on a UNIX-like OS, or by running GRUB itself from a -floppy. These are quite similar, however the utility might probe a -wrong BIOS drive, so you should be careful. - -Also, if you install GRUB on a UNIX-like OS, please make sure that you -have an emergency boot disk ready, so that you can rescue your computer -if, by any chance, your hard drive becomes unusable (unbootable). - -GRUB comes with boot images, which are normally put in the directory -@file{/usr/lib/grub/i386-pc}. If you do not use grub-install, then -you need to copy the files @file{stage1}, @file{stage2}, and -@file{*stage1_5} to the directory @file{/boot/grub}, and run the -@command{grub-set-default} (@pxref{Invoking grub-set-default}) if you -intend to use @samp{default saved} (@pxref{default}) in your -configuration file. Hereafter, the directory where GRUB images are -initially placed (normally @file{/usr/lib/grub/i386-pc}) will be -called the @dfn{image directory}, and the directory where the boot -loader needs to find them (usually @file{/boot/grub}) will be called -the @dfn{boot directory}. - -@menu -* Creating a GRUB boot floppy:: -* Installing GRUB natively:: -* Installing GRUB using grub-install:: -* Making a GRUB bootable CD-ROM:: -@end menu - - -@node Creating a GRUB boot floppy -@section Creating a GRUB boot floppy - -To create a GRUB boot floppy, you need to take the files @file{stage1} -and @file{stage2} from the image directory, and write them to the first -and the second block of the floppy disk, respectively. - -@strong{Caution:} This procedure will destroy any data currently stored -on the floppy. - -On a UNIX-like operating system, that is done with the following -commands: - -@example -@group -# @kbd{cd /usr/lib/grub/i386-pc} -# @kbd{dd if=stage1 of=/dev/fd0 bs=512 count=1} -1+0 records in -1+0 records out -# @kbd{dd if=stage2 of=/dev/fd0 bs=512 seek=1} -153+1 records in -153+1 records out -# -@end group -@end example - -The device file name may be different. Consult the manual for your OS. - - -@node Installing GRUB natively -@section Installing GRUB natively - -@strong{Caution:} Installing GRUB's stage1 in this manner will erase the -normal boot-sector used by an OS. - -GRUB can currently boot GNU Mach, Linux, FreeBSD, NetBSD, and OpenBSD -directly, so using it on a boot sector (the first sector of a -partition) should be okay. But generally, it would be a good idea to -back up the first sector of the partition on which you are installing -GRUB's stage1. This isn't as important if you are installing GRUB on -the first sector of a hard disk, since it's easy to reinitialize it -(e.g. by running @samp{FDISK /MBR} from DOS). - -If you decide to install GRUB in the native environment, which is -definitely desirable, you'll need to create a GRUB boot disk, and -reboot your computer with it. Otherwise, see @ref{Installing GRUB using -grub-install}. - -Once started, GRUB will show the command-line interface -(@pxref{Command-line interface}). First, set the GRUB's @dfn{root -device}@footnote{Note that GRUB's root device doesn't necessarily mean -your OS's root partition; if you need to specify a root partition for -your OS, add the argument into the command @command{kernel}.} to the -partition containing the boot directory, like this: - -@example -grub> @kbd{root (hd0,0)} -@end example - -If you are not sure which partition actually holds this directory, use the -command @command{find} (@pxref{find}), like this: - -@example -grub> @kbd{find /boot/grub/stage1} -@end example - -This will search for the file name @file{/boot/grub/stage1} and show the -devices which contain the file. - -Once you've set the root device correctly, run the command -@command{setup} (@pxref{setup}): - -@example -grub> @kbd{setup (hd0)} -@end example - -This command will install the GRUB boot loader on the Master Boot -Record (MBR) of the first drive. If you want to put GRUB into the boot -sector of a partition instead of putting it in the MBR, specify the -partition into which you want to install GRUB: - -@example -grub> @kbd{setup (hd0,0)} -@end example - -If you install GRUB into a partition or a drive other than the first -one, you must chain-load GRUB from another boot loader. Refer to the -manual for the boot loader to know how to chain-load GRUB. - -After using the setup command, you will boot into GRUB without the -GRUB floppy. See the chapter @ref{Booting} to find out how to boot -your operating systems from GRUB. - - -@node Installing GRUB using grub-install -@section Installing GRUB using grub-install - -@strong{Caution:} This procedure is definitely less safe, because -there are several ways in which your computer can become -unbootable. For example, most operating systems don't tell GRUB how to -map BIOS drives to OS devices correctly---GRUB merely @dfn{guesses} -the mapping. This will succeed in most cases, but not -always. Therefore, GRUB provides you with a map file called the -@dfn{device map}, which you must fix if it is wrong. @xref{Device -map}, for more details. - -If you still do want to install GRUB under a UNIX-like OS (such -as @sc{gnu}), invoke the program @command{grub-install} (@pxref{Invoking -grub-install}) as the superuser (@dfn{root}). - -The usage is basically very simple. You only need to specify one -argument to the program, namely, where to install the boot loader. The -argument can be either a device file (like @samp{/dev/hda}) or a -partition specified in GRUB's notation. For example, under Linux the -following will install GRUB into the MBR of the first IDE disk: - -@example -# @kbd{grub-install /dev/hda} -@end example - -Likewise, under GNU/Hurd, this has the same effect: - -@example -# @kbd{grub-install /dev/hd0} -@end example - -If it is the first BIOS drive, this is the same as well: - -@example -# @kbd{grub-install '(hd0)'} -@end example - -Or you can omit the parentheses: - -@example -# @kbd{grub-install hd0} -@end example - -But all the above examples assume that GRUB should use images under -the root directory. If you want GRUB to use images under a directory -other than the root directory, you need to specify the option -@option{--root-directory}. The typical usage is that you create a GRUB -boot floppy with a filesystem. Here is an example: - -@example -@group -# @kbd{mke2fs /dev/fd0} -# @kbd{mount -t ext2 /dev/fd0 /mnt} -# @kbd{grub-install --root-directory=/mnt fd0} -# @kbd{umount /mnt} -@end group -@end example - -Another example is when you have a separate boot partition -which is mounted at @file{/boot}. Since GRUB is a boot loader, it -doesn't know anything about mountpoints at all. Thus, you need to run -@command{grub-install} like this: - -@example -# @kbd{grub-install --root-directory=/boot /dev/hda} -@end example - -By the way, as noted above, it is quite difficult to guess BIOS drives -correctly under a UNIX-like OS. Thus, @command{grub-install} will prompt -you to check if it could really guess the correct mappings, after the -installation. The format is defined in @ref{Device map}. Please be -quite careful. If the output is wrong, it is unlikely that your -computer will be able to boot with no problem. - -Note that @command{grub-install} is actually just a shell script and the -real task is done by the grub shell @command{grub} (@pxref{Invoking the -grub shell}). Therefore, you may run @command{grub} directly to install -GRUB, without using @command{grub-install}. Don't do that, however, -unless you are very familiar with the internals of GRUB. Installing a -boot loader on a running OS may be extremely dangerous. - - -@node Making a GRUB bootable CD-ROM -@section Making a GRUB bootable CD-ROM - -GRUB supports the @dfn{no emulation mode} in the El Torito -specification@footnote{El Torito is a specification for bootable CD -using BIOS functions.}. This means that you can use the whole CD-ROM -from GRUB and you don't have to make a floppy or hard disk image file, -which can cause compatibility problems. - -For booting from a CD-ROM, GRUB uses a special Stage 2 called -@file{stage2_eltorito}. The only GRUB files you need to have in your -bootable CD-ROM are this @file{stage2_eltorito} and optionally a config file -@file{menu.lst}. You don't need to use @file{stage1} or @file{stage2}, -because El Torito is quite different from the standard boot process. - -Here is an example of procedures to make a bootable CD-ROM -image. First, make a top directory for the bootable image, say, -@samp{iso}: - -@example -$ @kbd{mkdir iso} -@end example - -Make a directory for GRUB: - -@example -$ @kbd{mkdir -p iso/boot/grub} -@end example - -Copy the file @file{stage2_eltorito}: - -@example -$ @kbd{cp /usr/lib/grub/i386-pc/stage2_eltorito iso/boot/grub} -@end example - -If desired, make the config file @file{menu.lst} under @file{iso/boot/grub} -(@pxref{Configuration}), and copy any files and directories for the disc to the -directory @file{iso/}. - -Finally, make a ISO9660 image file like this: - -@example -$ @kbd{mkisofs -R -b boot/grub/stage2_eltorito -no-emul-boot \ - -boot-load-size 4 -boot-info-table -o grub.iso iso} -@end example - -This produces a file named @file{grub.iso}, which then can be burned -into a CD (or a DVD). @kbd{mkisofs} has already set up the disc to boot -from the @kbd{boot/grub/stage2_eltorito} file, so there is no need to -setup GRUB on the disc. (Note that the @kbd{-boot-load-size 4} bit is -required for compatibility with the BIOS on many older machines.) - -You can use the device @samp{(cd)} to access a CD-ROM in your -config file. This is not required; GRUB automatically sets the root device -to @samp{(cd)} when booted from a CD-ROM. It is only necessary to refer to -@samp{(cd)} if you want to access other drives as well. - - -@node Booting -@chapter Booting - -GRUB can load Multiboot-compliant kernels in a consistent way, -but for some free operating systems you need to use some OS-specific -magic. - -@menu -* General boot methods:: How to boot OSes with GRUB generally -* OS-specific notes:: Notes on some operating systems -* Making your system robust:: How to make your system robust -@end menu - - -@node General boot methods -@section How to boot operating systems - -GRUB has two distinct boot methods. One of the two is to load an -operating system directly, and the other is to chain-load another boot -loader which then will load an operating system actually. Generally -speaking, the former is more desirable, because you don't need to -install or maintain other boot loaders and GRUB is flexible enough to -load an operating system from an arbitrary disk/partition. However, -the latter is sometimes required, since GRUB doesn't support all the -existing operating systems natively. - -@menu -* Loading an operating system directly:: -* Chain-loading:: -@end menu - - -@node Loading an operating system directly -@subsection How to boot an OS directly with GRUB - -Multiboot (@pxref{Top, Multiboot Specification, Motivation, multiboot, -The Multiboot Specification}) is the native format supported by GRUB. -For the sake of convenience, there is also support for Linux, FreeBSD, -NetBSD and OpenBSD. If you want to boot other operating systems, you -will have to chain-load them (@pxref{Chain-loading}). - -Generally, GRUB can boot any Multiboot-compliant OS in the following -steps: - -@enumerate -@item -Set GRUB's root device to the drive where the OS images are stored with -the command @command{root} (@pxref{root}). - -@item -Load the kernel image with the command @command{kernel} (@pxref{kernel}). - -@item -If you need modules, load them with the command @command{module} -(@pxref{module}) or @command{modulenounzip} (@pxref{modulenounzip}). - -@item -Run the command @command{boot} (@pxref{boot}). -@end enumerate - -Linux, FreeBSD, NetBSD and OpenBSD can be booted in a similar -manner. You load a kernel image with the command @command{kernel} and -then run the command @command{boot}. If the kernel requires some -parameters, just append the parameters to @command{kernel}, after the -file name of the kernel. Also, please refer to @ref{OS-specific notes}, -for information on your OS-specific issues. - - -@node Chain-loading -@subsection Load another boot loader to boot unsupported operating systems - -If you want to boot an unsupported operating system (e.g. Windows 95), -chain-load a boot loader for the operating system. Normally, the boot -loader is embedded in the @dfn{boot sector} of the partition on which -the operating system is installed. - -@enumerate -@item -Set GRUB's root device to the partition by the command -@command{rootnoverify} (@pxref{rootnoverify}): - -@example -grub> @kbd{rootnoverify (hd0,0)} -@end example - -@item -Set the @dfn{active} flag in the partition using the command -@command{makeactive}@footnote{This is not necessary for most of the -modern operating systems.} (@pxref{makeactive}): - -@example -grub> @kbd{makeactive} -@end example - -@item -Load the boot loader with the command @command{chainloader} -(@pxref{chainloader}): - -@example -grub> @kbd{chainloader +1} -@end example - -@samp{+1} indicates that GRUB should read one sector from the start of -the partition. The complete description about this syntax can be found -in @ref{Block list syntax}. - -@item -Run the command @command{boot} (@pxref{boot}). -@end enumerate - -However, DOS and Windows have some deficiencies, so you might have to -use more complicated instructions. @xref{DOS/Windows}, for more -information. - - -@node OS-specific notes -@section Some caveats on OS-specific issues - -Here, we describe some caveats on several operating systems. - -@menu -* GNU/Hurd:: -* GNU/Linux:: -* FreeBSD:: -* NetBSD:: -* OpenBSD:: -* DOS/Windows:: -* SCO UnixWare:: -* QNX:: -@end menu - - -@node GNU/Hurd -@subsection GNU/Hurd - -Since GNU/Hurd is Multiboot-compliant, it is easy to boot it; there is -nothing special about it. But do not forget that you have to specify a -root partition to the kernel. - -@enumerate -@item -Set GRUB's root device to the same drive as GNU/Hurd's. Probably the -command @code{find /boot/gnumach} or similar can help you -(@pxref{find}). - -@item -Load the kernel and the module, like this: - -@example -@group -grub> @kbd{kernel /boot/gnumach root=hd0s1} -grub> @kbd{module /boot/serverboot} -@end group -@end example - -@item -Run the command @command{boot} (@pxref{boot}). -@end enumerate - - -@node GNU/Linux -@subsection GNU/Linux - -It is relatively easy to boot GNU/Linux from GRUB, because it somewhat -resembles to boot a Multiboot-compliant OS. - -@enumerate -@item -Set GRUB's root device to the same drive as GNU/Linux's. Probably the -command @code{find /vmlinuz} or similar can help you (@pxref{find}). - -@item -Load the kernel: - -@example -grub> @kbd{kernel /vmlinuz root=/dev/hda1} -@end example - -If you need to specify some kernel parameters, just append them to the -command. For example, to set @option{vga} to @samp{ext}, do this: - -@example -grub> @kbd{kernel /vmlinuz root=/dev/hda1 vga=ext} -@end example - -See the documentation in the Linux source tree for complete -information on the available options. - -@item -If you use an initrd, execute the command @command{initrd} -(@pxref{initrd}) after @command{kernel}: - -@example -grub> @kbd{initrd /initrd} -@end example - -@item -Finally, run the command @command{boot} (@pxref{boot}). -@end enumerate - -@strong{Caution:} If you use an initrd and specify the @samp{mem=} -option to the kernel to let it use less than actual memory size, you -will also have to specify the same memory size to GRUB. To let GRUB know -the size, run the command @command{uppermem} @emph{before} loading the -kernel. @xref{uppermem}, for more information. - - -@node FreeBSD -@subsection FreeBSD - -GRUB can load the kernel directly, either in ELF or a.out format. But -this is not recommended, since FreeBSD's bootstrap interface sometimes -changes heavily, so GRUB can't guarantee to pass kernel parameters -correctly. - -Thus, we'd recommend loading the very flexible loader -@file{/boot/loader} instead. See this example: - -@example -@group -grub> @kbd{root (hd0,a)} -grub> @kbd{kernel /boot/loader} -grub> @kbd{boot} -@end group -@end example - - -@node NetBSD -@subsection NetBSD - -GRUB can load NetBSD a.out and ELF directly, follow these steps: - -@enumerate -@item -Set GRUB's root device with @command{root} (@pxref{root}). - -@item -Load the kernel with @command{kernel} (@pxref{kernel}). You should -append the ugly option @option{--type=netbsd}, if you want to load an -ELF kernel, like this: - -@example -grub> @kbd{kernel --type=netbsd /netbsd-elf} -@end example - -@item -Run @command{boot} (@pxref{boot}). -@end enumerate - -For now, however, GRUB doesn't allow you to pass kernel parameters, so -it may be better to chain-load it instead. For more information, please -see @ref{Chain-loading}. - - -@node OpenBSD -@subsection OpenBSD - -The booting instruction is exactly the same as for NetBSD -(@pxref{NetBSD}). - - -@node DOS/Windows -@subsection DOS/Windows - -GRUB cannot boot DOS or Windows directly, so you must chain-load them -(@pxref{Chain-loading}). However, their boot loaders have some critical -deficiencies, so it may not work to just chain-load them. To overcome -the problems, GRUB provides you with two helper functions. - -If you have installed DOS (or Windows) on a non-first hard disk, you -have to use the disk swapping technique, because that OS cannot boot -from any disks but the first one. The workaround used in GRUB is the -command @command{map} (@pxref{map}), like this: - -@example -@group -grub> @kbd{map (hd0) (hd1)} -grub> @kbd{map (hd1) (hd0)} -@end group -@end example - -This performs a @dfn{virtual} swap between your first and second hard -drive. - -@strong{Caution:} This is effective only if DOS (or Windows) uses BIOS -to access the swapped disks. If that OS uses a special driver for the -disks, this probably won't work. - -Another problem arises if you installed more than one set of DOS/Windows -onto one disk, because they could be confused if there are more than one -primary partitions for DOS/Windows. Certainly you should avoid doing -this, but there is a solution if you do want to do so. Use the partition -hiding/unhiding technique. - -If GRUB @dfn{hide}s a DOS (or Windows) partition (@pxref{hide}), DOS (or -Windows) will ignore the partition. If GRUB @dfn{unhide}s a DOS (or -Windows) partition (@pxref{unhide}), DOS (or Windows) will detect the -partition. Thus, if you have installed DOS (or Windows) on the first -and the second partition of the first hard disk, and you want to boot -the copy on the first partition, do the following: - -@example -@group -grub> @kbd{unhide (hd0,0)} -grub> @kbd{hide (hd0,1)} -grub> @kbd{rootnoverify (hd0,0)} -grub> @kbd{chainloader +1} -grub> @kbd{makeactive} -grub> @kbd{boot} -@end group -@end example - - -@node SCO UnixWare -@subsection SCO UnixWare - -It is known that the signature in the boot loader for SCO UnixWare is -wrong, so you will have to specify the option @option{--force} to -@command{chainloader} (@pxref{chainloader}), like this: - -@example -@group -grub> @kbd{rootnoverify (hd1,0)} -grub> @kbd{chainloader --force +1} -grub> @kbd{makeactive} -grub> @kbd{boot} -@end group -@end example - - -@node QNX -@subsection QNX - -QNX seems to use a bigger boot loader, so you need to boot it up, like -this: - -@example -@group -grub> @kbd{rootnoverify (hd1,1)} -grub> @kbd{chainloader +4} -grub> @kbd{boot} -@end group -@end example - - -@node Making your system robust -@section How to make your system robust - -When you test a new kernel or a new OS, it is important to make sure -that your computer can boot even if the new system is unbootable. This -is crucial especially if you maintain servers or remote systems. To -accomplish this goal, you need to set up two things: - -@enumerate -@item -You must maintain a system which is always bootable. For instance, if -you test a new kernel, you need to keep a working kernel in a -different place. And, it would sometimes be very nice to even have a -complete copy of a working system in a different partition or disk. - -@item -You must direct GRUB to boot a working system when the new system -fails. This is possible with the @dfn{fallback} system in GRUB. -@end enumerate - -The former requirement is very specific to each OS, so this -documentation does not cover that topic. It is better to consult some -backup tools. - -So let's see the GRUB part. There are two possibilities: one of them -is quite simple but not very robust, and the other is a bit complex to -set up but probably the best solution to make sure that your system -can start as long as GRUB itself is bootable. - -@menu -* Booting once-only:: -* Booting fallback systems:: -@end menu - - -@node Booting once-only -@subsection Booting once-only - -You can teach GRUB to boot an entry only at next boot time. Suppose -that your have an old kernel @file{old_kernel} and a new kernel -@file{new_kernel}. You know that @file{old_kernel} can boot -your system correctly, and you want to test @file{new_kernel}. - -To ensure that your system will go back to the old kernel even if the -new kernel fails (e.g. it panics), you can specify that GRUB should -try the new kernel only once and boot the old kernel after that. - -First, modify your configuration file. Here is an example: - -@example -@group -default saved # This is important!!! -timeout 10 - -title the old kernel -root (hd0,0) -kernel /old_kernel -savedefault - -title the new kernel -root (hd0,0) -kernel /new_kernel -savedefault 0 # This is important!!! -@end group -@end example - -Note that this configuration file uses @samp{default saved} -(@pxref{default}) at the head and @samp{savedefault 0} -(@pxref{savedefault}) in the entry for the new kernel. This means -that GRUB boots a saved entry by default, and booting the entry for the -new kernel saves @samp{0} as the saved entry. - -With this configuration file, after all, GRUB always tries to boot the -old kernel after it booted the new one, because @samp{0} is the entry -of @code{the old kernel}. - -The next step is to tell GRUB to boot the new kernel at next boot -time. For this, execute @command{grub-set-default} (@pxref{Invoking -grub-set-default}): - -@example -# @kbd{grub-set-default 1} -@end example - -This command sets the saved entry to @samp{1}, that is, to the new -kernel. - -This method is useful, but still not very robust, because GRUB stops -booting, if there is any error in the boot entry, such that the new -kernel has an invalid executable format. Thus, it it even better to -use the @dfn{fallback} mechanism of GRUB. Look at next subsection for -this feature. - - -@node Booting fallback systems -@subsection Booting fallback systems - -GRUB supports a fallback mechanism of booting one or more other -entries if a default boot entry fails. You can specify multiple -fallback entries if you wish. - -Suppose that you have three systems, @samp{A}, @samp{B} and -@samp{C}. @samp{A} is a system which you want to boot by -default. @samp{B} is a backup system which is supposed to boot -safely. @samp{C} is another backup system which is used in case where -@samp{B} is broken. - -Then you may want GRUB to boot the first system which is bootable -among @samp{A}, @samp{B} and @samp{C}. A configuration file can be -written in this way: - -@example -@group -default saved # This is important!!! -timeout 10 -fallback 1 2 # This is important!!! - -title A -root (hd0,0) -kernel /kernel -savedefault fallback # This is important!!! - -title B -root (hd1,0) -kernel /kernel -savedefault fallback # This is important!!! - -title C -root (hd2,0) -kernel /kernel -savedefault -@end group -@end example - -Note that @samp{default saved} (@pxref{default}), @samp{fallback 1 2} -and @samp{savedefault fallback} are used. GRUB will boot a saved entry -by default and save a fallback entry as next boot entry with this -configuration. - -When GRUB tries to boot @samp{A}, GRUB saves @samp{1} as next boot -entry, because the command @command{fallback} specifies that @samp{1} -is the first fallback entry. The entry @samp{1} is @samp{B}, so GRUB -will try to boot @samp{B} at next boot time. - -Likewise, when GRUB tries to boot @samp{B}, GRUB saves @samp{2} as -next boot entry, because @command{fallback} specifies @samp{2} as next -fallback entry. This makes sure that GRUB will boot @samp{C} after -booting @samp{B}. - -It is noteworthy that GRUB uses fallback entries both when GRUB -itself fails in booting an entry and when @samp{A} or @samp{B} fails -in starting up your system. So this solution ensures that your system -is started even if GRUB cannot find your kernel or if your kernel -panics. - -However, you need to run @command{grub-set-default} (@pxref{Invoking -grub-set-default}) when @samp{A} starts correctly or you fix @samp{A} -after it crashes, since GRUB always sets next boot entry to a fallback -entry. You should run this command in a startup script such as -@file{rc.local} to boot @samp{A} by default: - -@example -# @kbd{grub-set-default 0} -@end example - -where @samp{0} is the number of the boot entry for the system -@samp{A}. - -If you want to see what is current default entry, you can look at the -file @file{/boot/grub/default} (or @file{/grub/default} in -some systems). Because this file is plain-text, you can just -@command{cat} this file. But it is strongly recommended @strong{not to -modify this file directly}, because GRUB may fail in saving a default -entry in this file, if you change this file in an unintended -manner. Therefore, you should use @command{grub-set-default} when you -need to change the default entry. - - -@node Configuration -@chapter Configuration - -You've probably noticed that you need to type several commands to boot your -OS. There's a solution to that - GRUB provides a menu interface -(@pxref{Menu interface}) from which you can select an item (using arrow -keys) that will do everything to boot an OS. - -To enable the menu, you need a configuration file, -@file{menu.lst} under the boot directory. We'll analyze an example -file. - -The file first contains some general settings, the menu interface -related options. You can put these commands (@pxref{Menu-specific -commands}) before any of the items (starting with @command{title} -(@pxref{title})). - -@example -@group -# -# Sample boot menu configuration file -# -@end group -@end example - -As you may have guessed, these lines are comments. Lines starting with a -hash character (@samp{#}), and blank lines, are ignored by GRUB. - -@example -@group -# By default, boot the first entry. -default 0 -@end group -@end example - -The first entry (here, counting starts with number zero, not one!) will -be the default choice. - -@example -@group -# Boot automatically after 30 secs. -timeout 30 -@end group -@end example - -As the comment says, GRUB will boot automatically in 30 seconds, unless -interrupted with a keypress. - -@example -@group -# Fallback to the second entry. -fallback 1 -@end group -@end example - -If, for any reason, the default entry doesn't work, fall back to the -second one (this is rarely used, for obvious reasons). - -Note that the complete descriptions of these commands, which are menu -interface specific, can be found in @ref{Menu-specific -commands}. Other descriptions can be found in @ref{Commands}. - -Now, on to the actual OS definitions. You will see that each entry -begins with a special command, @command{title} (@pxref{title}), and the -action is described after it. Note that there is no command -@command{boot} (@pxref{boot}) at the end of each item. That is because -GRUB automatically executes @command{boot} if it loads other commands -successfully. - -The argument for the command @command{title} is used to display a short -title/description of the entry in the menu. Since @command{title} -displays the argument as is, you can write basically anything there. - -@example -@group -# For booting GNU/Hurd -title GNU/Hurd -root (hd0,0) -kernel /boot/gnumach.gz root=hd0s1 -module /boot/serverboot.gz -@end group -@end example - -This boots GNU/Hurd from the first hard disk. - -@example -@group -# For booting GNU/Linux -title GNU/Linux -kernel (hd1,0)/vmlinuz root=/dev/hdb1 -@end group -@end example - -This boots GNU/Linux, but from the second hard disk. - -@example -@group -# For booting Mach (getting kernel from floppy) -title Utah Mach4 multiboot -root (hd0,2) -pause Insert the diskette now^G!! -kernel (fd0)/boot/kernel root=hd0s3 -module (fd0)/boot/bootstrap -@end group -@end example - -This boots Mach with a kernel on a floppy, but the root filesystem at -hd0s3. It also contains a @command{pause} line (@pxref{pause}), which -will cause GRUB to display a prompt and delay, before actually executing -the rest of the commands and booting. - -@example -@group -# For booting FreeBSD -title FreeBSD -root (hd0,2,a) -kernel /boot/loader -@end group -@end example - -This item will boot FreeBSD kernel loaded from the @samp{a} partition of -the third @sc{pc} slice of the first hard disk. - -@example -@group -# For booting OS/2 -title OS/2 -root (hd0,1) -makeactive -# chainload OS/2 bootloader from the first sector -chainloader +1 -# This is similar to "chainload", but loads a specific file -#chainloader /boot/chain.os2 -@end group -@end example - -This will boot OS/2, using a chain-loader (@pxref{Chain-loading}). - -@example -@group -# For booting Windows NT or Windows95 -title Windows NT / Windows 95 boot menu -root (hd0,0) -makeactive -chainloader +1 -# For loading DOS if Windows NT is installed -# chainload /bootsect.dos -@end group -@end example - -The same as the above, but for Windows. - -@example -@group -# For installing GRUB into the hard disk -title Install GRUB into the hard disk -root (hd0,0) -setup (hd0) -@end group -@end example - -This will just (re)install GRUB onto the hard disk. - -@example -# Change the colors. -title Change the colors -color light-green/brown blink-red/blue -@end example - -In the last entry, the command @command{color} is used (@pxref{color}), -to change the menu colors (try it!). This command is somewhat special, -because it can be used both in the command-line and in the menu. GRUB -has several such commands, see @ref{General commands}. - -We hope that you now understand how to use the basic features of -GRUB. To learn more about GRUB, see the following chapters. - - -@node Network -@chapter Downloading OS images from a network - -Although GRUB is a disk-based boot loader, it does provide network -support. To use the network support, you need to enable at least one -network driver in the GRUB build process. For more information please -see @file{netboot/README.netboot} in the source distribution. - -@menu -* General usage of network support:: -* Diskless:: -@end menu - - -@node General usage of network support -@section How to set up your network - -GRUB requires a file server and optionally a server that will assign an -IP address to the machine on which GRUB is running. For the former, only -TFTP is supported at the moment. The latter is either BOOTP, DHCP or a -RARP server@footnote{RARP is not advised, since it cannot serve much -information}. It is not necessary to run both the servers on one -computer. How to configure these servers is beyond the scope of this -document, so please refer to the manuals specific to those -protocols/servers. - -If you decided to use a server to assign an IP address, set up the -server and run @command{bootp} (@pxref{bootp}), @command{dhcp} -(@pxref{dhcp}) or @command{rarp} (@pxref{rarp}) for BOOTP, DHCP or RARP, -respectively. Each command will show an assigned IP address, a netmask, -an IP address for your TFTP server and a gateway. If any of the -addresses is wrong or it causes an error, probably the configuration of -your servers isn't set up properly. - -Otherwise, run @command{ifconfig}, like this: - -@example -grub> @kbd{ifconfig --address=192.168.110.23 --server=192.168.110.14} -@end example - -You can also use @command{ifconfig} in conjuction with @command{bootp}, -@command{dhcp} or @command{rarp} (e.g. to reassign the server address -manually). @xref{ifconfig}, for more details. - -Finally, download your OS images from your network. The network can be -accessed using the network drive @samp{(nd)}. Everything else is very -similar to the normal instructions (@pxref{Booting}). - -Here is an example: - -@example -@group -grub> @kbd{bootp} -Probing... [NE*000] -NE2000 base ... -Address: 192.168.110.23 Netmask: 255.255.255.0 -Server: 192.168.110.14 Gateway: 192.168.110.1 - -grub> @kbd{root (nd)} -grub> @kbd{kernel /tftproot/gnumach.gz root=sd0s1} -grub> @kbd{module /tftproot/serverboot.gz} -grub> @kbd{boot} -@end group -@end example - - -@node Diskless -@section Booting from a network - -It is sometimes very useful to boot from a network, especially when you -use a machine which has no local disk. In this case, you need to obtain -a kind of Net Boot @sc{rom}, such as a PXE @sc{rom} or a free software -package like Etherboot. Such a Boot @sc{rom} first boots the machine, -sets up the network card installed into the machine, and downloads a -second stage boot image from the network. Then, the second image will -try to boot an operating system actually from the network. - -GRUB provides two second stage images, @file{nbgrub} and -@file{pxegrub} (@pxref{Images}). These images are the same as the -normal Stage 2, except that they set up a network automatically, and try -to load a configuration file from the network, if specified. The usage -is very simple: If the machine has a PXE @sc{rom}, use -@file{pxegrub}. If the machine has an NBI loader such as Etherboot, use -@file{nbgrub}. There is no difference between them except their -formats. Since the way to load a second stage image you want to use -should be described in the manual on your Net Boot @sc{rom}, please -refer to the manual, for more information. - -However, there is one thing specific to GRUB. Namely, how to specify a -configuration file in a BOOTP/DHCP server. For now, GRUB uses the tag -@samp{150}, to get the name of a configuration file. The following is an -example with a BOOTP configuration: - -@example -@group -.allhost:hd=/tmp:bf=null:\ - :ds=145.71.35.1 145.71.32.1:\ - :sm=255.255.254.0:\ - :gw=145.71.35.1:\ - :sa=145.71.35.5: - -foo:ht=1:ha=63655d0334a7:ip=145.71.35.127:\ - :bf=/nbgrub:\ - :tc=.allhost:\ - :T150="(nd)/tftpboot/menu.lst.foo": -@end group -@end example - -Note that you should specify the drive name @code{(nd)} in the name of -the configuration file. This is because you might change the root drive -before downloading the configuration from the TFTP server when the -preset menu feature is used (@pxref{Preset Menu}). - -See the manual of your BOOTP/DHCP server for more information. The -exact syntax should differ a little from the example. - - -@node Serial terminal -@chapter Using GRUB via a serial line - -This chapter describes how to use the serial terminal support in GRUB. - -If you have many computers or computers with no display/keyboard, it -could be very useful to control the computers through serial -communications. To connect one computer with another via a serial line, -you need to prepare a null-modem (cross) serial cable, and you may need -to have multiport serial boards, if your computer doesn't have extra -serial ports. In addition, a terminal emulator is also required, such as -minicom. Refer to a manual of your operating system, for more -information. - -As for GRUB, the instruction to set up a serial terminal is quite -simple. First of all, make sure that you haven't specified the option -@option{--disable-serial} to the configure script when you built your -GRUB images. If you get them in binary form, probably they have serial -terminal support already. - -Then, initialize your serial terminal after GRUB starts up. Here is an -example: - -@example -@group -grub> @kbd{serial --unit=0 --speed=9600} -grub> @kbd{terminal serial} -@end group -@end example - -The command @command{serial} initializes the serial unit 0 with the -speed 9600bps. The serial unit 0 is usually called @samp{COM1}, so, if -you want to use COM2, you must specify @samp{--unit=1} instead. This -command accepts many other options, so please refer to @ref{serial}, -for more details. - -The command @command{terminal} (@pxref{terminal}) chooses which type of -terminal you want to use. In the case above, the terminal will be a -serial terminal, but you can also pass @code{console} to the command, -as @samp{terminal serial console}. In this case, a terminal in which -you press any key will be selected as a GRUB terminal. - -However, note that GRUB assumes that your terminal emulator is -compatible with VT100 by default. This is true for most terminal -emulators nowadays, but you should pass the option @option{--dumb} to -the command if your terminal emulator is not VT100-compatible or -implements few VT100 escape sequences. If you specify this option then -GRUB provides you with an alternative menu interface, because the normal -menu requires several fancy features of your terminal. - - -@node Preset Menu -@chapter Embedding a configuration file into GRUB - -GRUB supports a @dfn{preset menu} which is to be always loaded before -starting. The preset menu feature is useful, for example, when your -computer has no console but a serial cable. In this case, it is -critical to set up the serial terminal as soon as possible, since you -cannot see any message until the serial terminal begins to work. So it -is good to run the commands @command{serial} (@pxref{serial}) and -@command{terminal} (@pxref{terminal}) before anything else at the -start-up time. - -How the preset menu works is slightly complicated: - -@enumerate -@item -GRUB checks if the preset menu feature is used, and loads the preset -menu, if available. This includes running commands and reading boot -entries, like an ordinary configuration file. - -@item -GRUB checks if the configuration file is available. Note that this check -is performed @strong{regardless of the existence of the preset -menu}. The configuration file is loaded even if the preset menu was -loaded. - -@item -If the preset menu includes any boot entries, they are cleared when -the configuration file is loaded. It doesn't matter whether the -configuration file has any entries or no entry. The boot entries in the -preset menu are used only when GRUB fails in loading the configuration -file. -@end enumerate - -To enable the preset menu feature, you must rebuild GRUB specifying a -file to the configure script with the option -@option{--enable-preset-menu}. The file has the same semantics as -normal configuration files (@pxref{Configuration}). - -Another point you should take care is that the diskless support -(@pxref{Diskless}) diverts the preset menu. Diskless images embed a -preset menu to execute the command @command{bootp} (@pxref{bootp}) -automatically, unless you specify your own preset menu to the configure -script. This means that you must put commands to initialize a network in -the preset menu yourself, because diskless images don't set it up -implicitly, when you use the preset menu explicitly. - -Therefore, a typical preset menu used with diskless support would be -like this: - -@example -@group -# Set up the serial terminal, first of all. -serial --unit=0 --speed=19200 -terminal --timeout=0 serial - -# Initialize the network. -dhcp -@end group -@end example - - -@node Security -@chapter Protecting your computer from cracking - -You may be interested in how to prevent ordinary users from doing -whatever they like, if you share your computer with other people. So -this chapter describes how to improve the security of GRUB. - -One thing which could be a security hole is that the user can do too -many things with GRUB, because GRUB allows one to modify its configuration -and run arbitrary commands at run-time. For example, the user can even -read @file{/etc/passwd} in the command-line interface by the command -@command{cat} (@pxref{cat}). So it is necessary to disable all the -interactive operations. - -Thus, GRUB provides a @dfn{password} feature, so that only administrators -can start the interactive operations (i.e. editing menu entries and -entering the command-line interface). To use this feature, you need to -run the command @command{password} in your configuration file -(@pxref{password}), like this: - -@example -password --md5 PASSWORD -@end example - -If this is specified, GRUB disallows any interactive control, until you -press the key @key{p} and enter a correct password. The option -@option{--md5} tells GRUB that @samp{PASSWORD} is in MD5 format. If it -is omitted, GRUB assumes the @samp{PASSWORD} is in clear text. - -You can encrypt your password with the command @command{md5crypt} -(@pxref{md5crypt}). For example, run the grub shell (@pxref{Invoking the -grub shell}), and enter your password: - -@example -@group -grub> md5crypt -Password: ********** -Encrypted: $1$U$JK7xFegdxWH6VuppCUSIb. -@end group -@end example - -Then, cut and paste the encrypted password to your configuration file. - -Also, you can specify an optional argument to @command{password}. See -this example: - -@example -password PASSWORD /boot/grub/menu-admin.lst -@end example - -In this case, GRUB will load @file{/boot/grub/menu-admin.lst} as a -configuration file when you enter the valid password. - -Another thing which may be dangerous is that any user can choose any -menu entry. Usually, this wouldn't be problematic, but you might want to -permit only administrators to run some of your menu entries, such as an -entry for booting an insecure OS like DOS. - -GRUB provides the command @command{lock} (@pxref{lock}). This command -always fails until you enter the valid password, so you can use it, like -this: - -@example -@group -title Boot DOS -lock -rootnoverify (hd0,1) -makeactive -chainload +1 -@end group -@end example - -You should insert @command{lock} right after @command{title}, because -any user can execute commands in an entry until GRUB encounters -@command{lock}. - -You can also use the command @command{password} instead of -@command{lock}. In this case the boot process will ask for the password -and stop if it was entered incorrectly. Since the @command{password} -takes its own @var{PASSWORD} argument this is useful if you want -different passwords for different entries. - - -@node Images -@chapter GRUB image files - -GRUB consists of several images: two essential stages, optional stages -called @dfn{Stage 1.5}, one image for bootable CD-ROM, and two network -boot images. Here is a short overview of them. @xref{Internals}, for -more details. - -@table @file -@item stage1 -This is an essential image used for booting up GRUB. Usually, this is -embedded in an MBR or the boot sector of a partition. Because a PC boot -sector is 512 bytes, the size of this image is exactly 512 bytes. - -All @file{stage1} must do is to load Stage 2 or Stage 1.5 from a local -disk. Because of the size restriction, @file{stage1} encodes the -location of Stage 2 (or Stage 1.5) in a block list format, so it never -understand any filesystem structure. - -@item stage2 -This is the core image of GRUB. It does everything but booting up -itself. Usually, this is put in a filesystem, but that is not required. - -@item e2fs_stage1_5 -@itemx fat_stage1_5 -@itemx ffs_stage1_5 -@itemx jfs_stage1_5 -@itemx minix_stage1_5 -@itemx reiserfs_stage1_5 -@itemx vstafs_stage1_5 -@itemx xfs_stage1_5 - -These are called @dfn{Stage 1.5}, because they serve as a bridge -between @file{stage1} and @file{stage2}, that is to say, Stage 1.5 is -loaded by Stage 1 and Stage 1.5 loads Stage 2. The difference between -@file{stage1} and @file{*_stage1_5} is that the former doesn't -understand any filesystem while the latter understands one filesystem -(e.g. @file{e2fs_stage1_5} understands ext2fs). So you can move the -Stage 2 image to another location safely, even after GRUB has been -installed. - -While Stage 2 cannot generally be embedded in a fixed area as the size -is so large, Stage 1.5 can be installed into the area right after an MBR, -or the boot loader area of a ReiserFS or a FFS. - -@item stage2_eltorito -This is a boot image for CD-ROMs using the @dfn{no emulation mode} in -El Torito specification. This is identical to Stage 2, except that -this boots up without Stage 1 and sets up a special drive @samp{(cd)}. - -@item nbgrub -This is a network boot image for the Network Image Proposal used by some -network boot loaders, such as Etherboot. This is mostly the same as -Stage 2, but it also sets up a network and loads a configuration file -from the network. - -@item pxegrub -This is another network boot image for the Preboot Execution Environment -used by several Netboot ROMs. This is identical to @file{nbgrub}, except -for the format. -@end table - - -@node Filesystem -@chapter Filesystem syntax and semantics - -GRUB uses a special syntax for specifying disk drives which can be -accessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish -between IDE, ESDI, SCSI, or others. You must know yourself which BIOS -device is equivalent to which OS device. Normally, that will be clear if -you see the files in a device or use the command @command{find} -(@pxref{find}). - -@menu -* Device syntax:: How to specify devices -* File name syntax:: How to specify files -* Block list syntax:: How to specify block lists -@end menu - - -@node Device syntax -@section How to specify devices - -The device syntax is like this: - -@example -@code{(@var{device}[,@var{part-num}][,@var{bsd-subpart-letter}])} -@end example - -@samp{[]} means the parameter is optional. @var{device} should be -either @samp{fd} or @samp{hd} followed by a digit, like @samp{fd0}. -But you can also set @var{device} to a hexadecimal or a decimal number -which is a BIOS drive number, so the following are equivalent: - -@example -(hd0) -(0x80) -(128) -@end example - -@var{part-num} represents the partition number of @var{device}, starting -from zero for primary partitions and from four for extended partitions, -and @var{bsd-subpart-letter} represents the BSD disklabel subpartition, -such as @samp{a} or @samp{e}. - -A shortcut for specifying BSD subpartitions is -@code{(@var{device},@var{bsd-subpart-letter})}, in this case, GRUB -searches for the first PC partition containing a BSD disklabel, then -finds the subpartition @var{bsd-subpart-letter}. Here is an example: - -@example -(hd0,a) -@end example - -The syntax @samp{(hd0)} represents using the entire disk (or the -MBR when installing GRUB), while the syntax @samp{(hd0,0)} -represents using the first partition of the disk (or the boot sector -of the partition when installing GRUB). - -If you enabled the network support, the special drive, @samp{(nd)}, is -also available. Before using the network drive, you must initialize the -network. @xref{Network}, for more information. - -If you boot GRUB from a CD-ROM, @samp{(cd)} is available. @xref{Making -a GRUB bootable CD-ROM}, for details. - - -@node File name syntax -@section How to specify files - -There are two ways to specify files, by @dfn{absolute file name} and by -@dfn{block list}. - -An absolute file name resembles a Unix absolute file name, using -@samp{/} for the directory separator (not @samp{\} as in DOS). One -example is @samp{(hd0,0)/boot/grub/menu.lst}. This means the file -@file{/boot/grub/menu.lst} in the first partition of the first hard -disk. If you omit the device name in an absolute file name, GRUB uses -GRUB's @dfn{root device} implicitly. So if you set the root device to, -say, @samp{(hd1,0)} by the command @command{root} (@pxref{root}), then -@code{/boot/kernel} is the same as @code{(hd1,0)/boot/kernel}. - - -@node Block list syntax -@section How to specify block lists - -A block list is used for specifying a file that doesn't appear in the -filesystem, like a chainloader. The syntax is -@code{[@var{offset}]+@var{length}[,[@var{offset}]+@var{length}]@dots{}}. -Here is an example: - -@example -@code{0+100,200+1,300+300} -@end example - -This represents that GRUB should read blocks 0 through 99, block 200, -and blocks 300 through 599. If you omit an offset, then GRUB assumes -the offset is zero. - -Like the file name syntax (@pxref{File name syntax}), if a blocklist -does not contain a device name, then GRUB uses GRUB's @dfn{root -device}. So @code{(hd0,1)+1} is the same as @code{+1} when the root -device is @samp{(hd0,1)}. - - -@node Interface -@chapter GRUB's user interface - -GRUB has both a simple menu interface for choosing preset entries from a -configuration file, and a highly flexible command-line for performing -any desired combination of boot commands. - -GRUB looks for its configuration file as soon as it is loaded. If one -is found, then the full menu interface is activated using whatever -entries were found in the file. If you choose the @dfn{command-line} menu -option, or if the configuration file was not found, then GRUB drops to -the command-line interface. - -@menu -* Command-line interface:: The flexible command-line interface -* Menu interface:: The simple menu interface -* Menu entry editor:: Editing a menu entry -* Hidden menu interface:: The hidden menu interface -@end menu - - -@node Command-line interface -@section The flexible command-line interface - -The command-line interface provides a prompt and after it an editable -text area much like a command-line in Unix or DOS. Each command is -immediately executed after it is entered@footnote{However, this -behavior will be changed in the future version, in a user-invisible -way.}. The commands (@pxref{Command-line and menu entry commands}) are a -subset of those available in the configuration file, used with exactly -the same syntax. - -Cursor movement and editing of the text on the line can be done via a -subset of the functions available in the Bash shell: - -@table @key -@item C-f -@itemx PC right key -Move forward one character. - -@item C-b -@itemx PC left key -Move back one character. - -@item C-a -@itemx HOME -Move to the start of the line. - -@item C-e -@itemx END -Move the the end of the line. - -@item C-d -@itemx DEL -Delete the character underneath the cursor. - -@item C-h -@itemx BS -Delete the character to the left of the cursor. - -@item C-k -Kill the text from the current cursor position to the end of the line. - -@item C-u -Kill backward from the cursor to the beginning of the line. - -@item C-y -Yank the killed text back into the buffer at the cursor. - -@item C-p -@itemx PC up key -Move up through the history list. - -@item C-n -@itemx PC down key -Move down through the history list. -@end table - -When typing commands interactively, if the cursor is within or before -the first word in the command-line, pressing the @key{TAB} key (or -@key{C-i}) will display a listing of the available commands, and if the -cursor is after the first word, the @kbd{@key{TAB}} will provide a -completion listing of disks, partitions, and file names depending on the -context. Note that to obtain a list of drives, one must open a -parenthesis, as @command{root (}. - -Note that you cannot use the completion functionality in the TFTP -filesystem. This is because TFTP doesn't support file name listing for -the security. - - -@node Menu interface -@section The simple menu interface - -The menu interface is quite easy to use. Its commands are both -reasonably intuitive and described on screen. - -Basically, the menu interface provides a list of @dfn{boot entries} to -the user to choose from. Use the arrow keys to select the entry of -choice, then press @key{RET} to run it. An optional timeout is -available to boot the default entry (the first one if not set), which is -aborted by pressing any key. - -Commands are available to enter a bare command-line by pressing @key{c} -(which operates exactly like the non-config-file version of GRUB, but -allows one to return to the menu if desired by pressing @key{ESC}) or to -edit any of the @dfn{boot entries} by pressing @key{e}. - -If you protect the menu interface with a password (@pxref{Security}), -all you can do is choose an entry by pressing @key{RET}, or press -@key{p} to enter the password. - - -@node Menu entry editor -@section Editing a menu entry - -The menu entry editor looks much like the main menu interface, but the -lines in the menu are individual commands in the selected entry instead -of entry names. - -If an @key{ESC} is pressed in the editor, it aborts all the changes made -to the configuration entry and returns to the main menu interface. - -When a particular line is selected, the editor places the user in a -special version of the GRUB command-line to edit that line. When the -user hits @key{RET}, GRUB replaces the line in question in the boot -entry with the changes (unless it was aborted via @key{ESC}, -in which case the changes are thrown away). - -If you want to add a new line to the menu entry, press @key{o} if adding -a line after the current line or press @key{O} if before the current -line. - -To delete a line, hit the key @key{d}. Although GRUB unfortunately -does not support @dfn{undo}, you can do almost the same thing by just -returning to the main menu. - - -@node Hidden menu interface -@section The hidden menu interface - -When your terminal is dumb or you request GRUB to hide the menu -interface explicitly with the command @command{hiddenmenu} -(@pxref{hiddenmenu}), GRUB doesn't show the menu interface (@pxref{Menu -interface}) and automatically boots the default entry, unless -interrupted by pressing @key{ESC}. - -When you interrupt the timeout and your terminal is dumb, GRUB falls -back to the command-line interface (@pxref{Command-line interface}). - - -@node Commands -@chapter The list of available commands - -In this chapter, we list all commands that are available in GRUB. - -Commands belong to different groups. A few can only be used in -the global section of the configuration file (or ``menu''); most -of them can be entered on the command-line and can be used either -anywhere in the menu or specifically in the menu entries. - -@menu -* Menu-specific commands:: -* General commands:: -* Command-line and menu entry commands:: -@end menu - - -@node Menu-specific commands -@section The list of commands for the menu only - -The semantics used in parsing the configuration file are the following: - -@itemize @bullet -@item -The menu-specific commands have to be used before any others. - -@item -The files @emph{must} be in plain-text format. - -@item -@samp{#} at the beginning of a line in a configuration file means it is -only a comment. - -@item -Options are separated by spaces. - -@item -All numbers can be either decimal or hexadecimal. A hexadecimal number -must be preceded by @samp{0x}, and is case-insensitive. - -@item -Extra options or text at the end of the line are ignored unless otherwise -specified. - -@item -Unrecognized commands are added to the current entry, except before entries -start, where they are ignored. -@end itemize - -These commands can only be used in the menu: - -@menu -* default:: Set the default entry -* fallback:: Set the fallback entry -* hiddenmenu:: Hide the menu interface -* timeout:: Set the timeout -* title:: Start a menu entry -@end menu - - -@node default -@subsection default - -@deffn Command default num -Set the default entry to the entry number @var{num}. Numbering starts -from 0, and the entry number 0 is the default if the command is not -used. - -You can specify @samp{saved} instead of a number. In this case, the -default entry is the entry saved with the command -@command{savedefault}. @xref{savedefault}, for more information. -@end deffn - - -@node fallback -@subsection fallback - -@deffn Command fallback num... -Go into unattended boot mode: if the default boot entry has any errors, -instead of waiting for the user to do something, immediately start -over using the @var{num} entry (same numbering as the @code{default} -command (@pxref{default})). This obviously won't help if the machine was -rebooted by a kernel that GRUB loaded. You can specify multiple -fallback entry numbers. -@end deffn - - -@node hiddenmenu -@subsection hiddenmenu - -@deffn Command hiddenmenu -Don't display the menu. If the command is used, no menu will be -displayed on the control terminal, and the default entry will be -booted after the timeout expired. The user can still request the -menu to be displayed by pressing @key{ESC} before the timeout -expires. See also @ref{Hidden menu interface}. -@end deffn - - -@node timeout -@subsection timeout - -@deffn Command timeout sec -Set a timeout, in @var{sec} seconds, before automatically booting the -default entry (normally the first entry defined). -@end deffn - - -@node title -@subsection title - -@deffn Command title name @dots{} -Start a new boot entry, and set its name to the contents of the rest of -the line, starting with the first non-space character. -@end deffn - - -@node General commands -@section The list of general commands - -Commands usable anywhere in the menu and in the command-line. - -@menu -* bootp:: Initialize a network device via BOOTP -* color:: Color the menu interface -* device:: Specify a file as a drive -* dhcp:: Initialize a network device via DHCP -* hide:: Hide a partition -* ifconfig:: Configure a network device manually -* pager:: Change the state of the internal pager -* partnew:: Make a primary partition -* parttype:: Change the type of a partition -* password:: Set a password for the menu interface -* rarp:: Initialize a network device via RARP -* serial:: Set up a serial device -* setkey:: Configure the key map -* terminal:: Choose a terminal -* terminfo:: Define escape sequences for a terminal -* tftpserver:: Specify a TFTP server -* unhide:: Unhide a partition -@end menu - - -@node bootp -@subsection bootp - -@deffn Command bootp [@option{--with-configfile}] -Initialize a network device via the @dfn{BOOTP} protocol. This command -is only available if GRUB is compiled with netboot support. See also -@ref{Network}. - -If you specify @option{--with-configfile} to this command, GRUB will -fetch and load a configuration file specified by your BOOTP server -with the vendor tag @samp{150}. -@end deffn - - -@node color -@subsection color - -@deffn Command color normal [highlight] -Change the menu colors. The color @var{normal} is used for most -lines in the menu (@pxref{Menu interface}), and the color -@var{highlight} is used to highlight the line where the cursor -points. If you omit @var{highlight}, then the inverted color of -@var{normal} is used for the highlighted line. The format of a color is -@code{@var{foreground}/@var{background}}. @var{foreground} and -@var{background} are symbolic color names. A symbolic color name must be -one of these: - -@itemize @bullet -@item -black - -@item -blue - -@item -green - -@item -cyan - -@item -red - -@item -magenta - -@item -brown - -@item -light-gray - -@strong{These below can be specified only for the foreground.} - -@item -dark-gray - -@item -light-blue - -@item -light-green - -@item -light-cyan - -@item -light-red - -@item -light-magenta - -@item -yellow - -@item -white -@end itemize - -But only the first eight names can be used for @var{background}. You can -prefix @code{blink-} to @var{foreground} if you want a blinking -foreground color. - -This command can be used in the configuration file and on the command -line, so you may write something like this in your configuration file: - -@example -@group -# Set default colors. -color light-gray/blue black/light-gray - -# Change the colors. -title OS-BS like -color magenta/blue black/magenta -@end group -@end example -@end deffn - - -@node device -@subsection device - -@deffn Command device drive file -In the grub shell, specify the file @var{file} as the actual drive for a -@sc{bios} drive @var{drive}. You can use this command to create a disk -image, and/or to fix the drives guessed by GRUB when GRUB fails to -determine them correctly, like this: - -@example -@group -grub> @kbd{device (fd0) /floppy-image} -grub> @kbd{device (hd0) /dev/sd0} -@end group -@end example - -This command can be used only in the grub shell (@pxref{Invoking the -grub shell}). -@end deffn - - -@node dhcp -@subsection dhcp - -@deffn Command dhcp [--with-configfile] -Initialize a network device via the @dfn{DHCP} protocol. Currently, -this command is just an alias for @command{bootp}, since the two -protocols are very similar. This command is only available if GRUB is -compiled with netboot support. See also @ref{Network}. - -If you specify @option{--with-configfile} to this command, GRUB will -fetch and load a configuration file specified by your DHCP server -with the vendor tag @samp{150}. -@end deffn - - -@node hide -@subsection hide - -@deffn Command hide partition -Hide the partition @var{partition} by setting the @dfn{hidden} bit in -its partition type code. This is useful only when booting DOS or Windows -and multiple primary FAT partitions exist in one disk. See also -@ref{DOS/Windows}. -@end deffn - - -@node ifconfig -@subsection ifconfig - -@deffn Command ifconfig [@option{--server=server}] [@option{--gateway=gateway}] [@option{--mask=mask}] [@option{--address=address}] -Configure the IP address, the netmask, the gateway, and the server -address of a network device manually. The values must be in dotted -decimal format, like @samp{192.168.11.178}. The order of the options is -not important. This command shows current network configuration, if no -option is specified. See also @ref{Network}. -@end deffn - - -@node pager -@subsection pager - -@deffn Command pager [flag] -Toggle or set the state of the internal pager. If @var{flag} is -@samp{on}, the internal pager is enabled. If @var{flag} is @samp{off}, -it is disabled. If no argument is given, the state is toggled. -@end deffn - - -@node partnew -@subsection partnew - -@deffn Command partnew part type from len -Create a new primary partition. @var{part} is a partition specification -in GRUB syntax (@pxref{Naming convention}); @var{type} is the partition -type and must be a number in the range @code{0-0xff}; @var{from} is -the starting address and @var{len} is the length, both in sector units. -@end deffn - - -@node parttype -@subsection parttype - -@deffn Command parttype part type -Change the type of an existing partition. @var{part} is a partition -specification in GRUB syntax (@pxref{Naming convention}); @var{type} -is the new partition type and must be a number in the range 0-0xff. -@end deffn - - -@node password -@subsection password - -@deffn Command password [@option{--md5}] passwd [new-config-file] -If used in the first section of a menu file, disable all interactive -editing control (menu entry editor and command-line) and entries -protected by the command @command{lock}. If the password @var{passwd} is -entered, it loads the @var{new-config-file} as a new config file and -restarts the GRUB Stage 2, if @var{new-config-file} is -specified. Otherwise, GRUB will just unlock the privileged instructions. -You can also use this command in the script section, in which case it -will ask for the password, before continuing. The option -@option{--md5} tells GRUB that @var{passwd} is encrypted with -@command{md5crypt} (@pxref{md5crypt}). -@end deffn - - -@node rarp -@subsection rarp - -@deffn Command rarp -Initialize a network device via the @dfn{RARP} protocol. This command -is only available if GRUB is compiled with netboot support. See also -@ref{Network}. -@end deffn - - -@node serial -@subsection serial - -@deffn Command serial [@option{--unit=unit}] [@option{--port=port}] [@option{--speed=speed}] [@option{--word=word}] [@option{--parity=parity}] [@option{--stop=stop}] [@option{--device=dev}] -Initialize a serial device. @var{unit} is a number in the range 0-3 -specifying which serial port to use; default is 0, which corresponds to -the port often called COM1. @var{port} is the I/O port where the UART -is to be found; if specified it takes precedence over @var{unit}. -@var{speed} is the transmission speed; default is 9600. @var{word} and -@var{stop} are the number of data bits and stop bits. Data bits must -be in the range 5-8 and stop bits must be 1 or 2. Default is 8 data -bits and one stop bit. @var{parity} is one of @samp{no}, @samp{odd}, -@samp{even} and defaults to @samp{no}. The option @option{--device} -can only be used in the grub shell and is used to specify the -tty device to be used in the host operating system (@pxref{Invoking the -grub shell}). - -The serial port is not used as a communication channel unless the -@command{terminal} command is used (@pxref{terminal}). - -This command is only available if GRUB is compiled with serial -support. See also @ref{Serial terminal}. -@end deffn - - -@node setkey -@subsection setkey - -@deffn Command setkey [to_key from_key] -Change the keyboard map. The key @var{from_key} is mapped to the key -@var{to_key}. If no argument is specified, reset key mappings. Note that -this command @emph{does not} exchange the keys. If you want to exchange -the keys, run this command again with the arguments exchanged, like this: - -@example -grub> @kbd{setkey capslock control} -grub> @kbd{setkey control capslock} -@end example - -A key must be an alphabet letter, a digit, or one of these symbols: -@samp{escape}, @samp{exclam}, @samp{at}, @samp{numbersign}, -@samp{dollar}, @samp{percent}, @samp{caret}, @samp{ampersand}, -@samp{asterisk}, @samp{parenleft}, @samp{parenright}, @samp{minus}, -@samp{underscore}, @samp{equal}, @samp{plus}, @samp{backspace}, -@samp{tab}, @samp{bracketleft}, @samp{braceleft}, @samp{bracketright}, -@samp{braceright}, @samp{enter}, @samp{control}, @samp{semicolon}, -@samp{colon}, @samp{quote}, @samp{doublequote}, @samp{backquote}, -@samp{tilde}, @samp{shift}, @samp{backslash}, @samp{bar}, @samp{comma}, -@samp{less}, @samp{period}, @samp{greater}, @samp{slash}, -@samp{question}, @samp{alt}, @samp{space}, @samp{capslock}, @samp{FX} -(@samp{X} is a digit), and @samp{delete}. This table describes to which -character each of the symbols corresponds: - -@table @samp -@item exclam -@samp{!} - -@item at -@samp{@@} - -@item numbersign -@samp{#} - -@item dollar -@samp{$} - -@item percent -@samp{%} - -@item caret -@samp{^} - -@item ampersand -@samp{&} - -@item asterisk -@samp{*} - -@item parenleft -@samp{(} - -@item parenright -@samp{)} - -@item minus -@samp{-} - -@item underscore -@samp{_} - -@item equal -@samp{=} - -@item plus -@samp{+} - -@item bracketleft -@samp{[} - -@item braceleft -@samp{@{} - -@item bracketright -@samp{]} - -@item braceright -@samp{@}} - -@item semicolon -@samp{;} - -@item colon -@samp{:} - -@item quote -@samp{'} - -@item doublequote -@samp{"} - -@item backquote -@samp{`} - -@item tilde -@samp{~} - -@item backslash -@samp{\} - -@item bar -@samp{|} - -@item comma -@samp{,} - -@item less -@samp{<} - -@item period -@samp{.} - -@item greater -@samp{>} - -@item slash -@samp{/} - -@item question -@samp{?} - -@item space -@samp{ } -@end table -@end deffn - - -@node terminal -@subsection terminal - -@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}] -Select a terminal for user interaction. The terminal is assumed to be -VT100-compatible unless @option{--dumb} is specified. If both -@option{console} and @option{serial} are specified, then GRUB will use -the one where a key is entered first or the first when the timeout -expires. If neither are specified, the current setting is -reported. This command is only available if GRUB is compiled with serial -support. See also @ref{Serial terminal}. - -This may not make sense for most users, but GRUB supports Hercules -console as well. Hercules console is usable like the ordinary console, -and the usage is quite similar to that for serial terminals: specify -@option{hercules} as the argument. - -The option @option{--lines} defines the number of lines in your -terminal, and it is used for the internal pager function. If you don't -specify this option, the number is assumed as 24. - -The option @option{--silent} suppresses the message to prompt you to -hit any key. This might be useful if your system has no terminal -device. - -The option @option{--no-echo} has GRUB not to echo back input -characters. This implies the option @option{--no-edit}. - -The option @option{--no-edit} disables the BASH-like editing feature. -@end deffn - - -@node terminfo -@subsection terminfo - -@deffn Command terminfo @option{--name=name} @option{--cursor-address=seq} [@option{--clear-screen=seq}] [@option{--enter-standout-mode=seq}] [@option{--exit-standout-mode=seq}] -Define the capabilities of your terminal. Use this command to define -escape sequences, if it is not vt100-compatible. You may use @samp{\e} -for @key{ESC} and @samp{^X} for a control character. - -You can use the utility @command{grub-terminfo} to generate -appropriate arguments to this command. @xref{Invoking grub-terminfo}. - -If no option is specified, the current settings are printed. -@end deffn - - -@node tftpserver -@subsection tftpserver - -@deffn Command tftpserver ipaddr -@strong{Caution:} This command exists only for backward -compatibility. Use @command{ifconfig} (@pxref{ifconfig}) instead. - -Override a TFTP server address returned by a BOOTP/DHCP/RARP server. The -argument @var{ipaddr} must be in dotted decimal format, like -@samp{192.168.0.15}. This command is only available if GRUB is compiled -with netboot support. See also @ref{Network}. -@end deffn - - -@node unhide -@subsection unhide - -@deffn Command unhide partition -Unhide the partition @var{partition} by clearing the @dfn{hidden} bit in -its partition type code. This is useful only when booting DOS or Windows -and multiple primary partitions exist on one disk. See also -@ref{DOS/Windows}. -@end deffn - - -@node Command-line and menu entry commands -@section The list of command-line and menu entry commands - -These commands are usable in the command-line and in menu entries. If -you forget a command, you can run the command @command{help} -(@pxref{help}). - -@menu -* blocklist:: Get the block list notation of a file -* boot:: Start up your operating system -* cat:: Show the contents of a file -* chainloader:: Chain-load another boot loader -* cmp:: Compare two files -* configfile:: Load a configuration file -* debug:: Toggle the debug flag -* displayapm:: Display APM information -* displaymem:: Display memory configuration -* embed:: Embed Stage 1.5 -* find:: Find a file -* fstest:: Test a filesystem -* geometry:: Manipulate the geometry of a drive -* halt:: Shut down your computer -* help:: Show help messages -* impsprobe:: Probe SMP -* initrd:: Load an initrd -* install:: Install GRUB -* ioprobe:: Probe I/O ports used for a drive -* kernel:: Load a kernel -* lock:: Lock a menu entry -* makeactive:: Make a partition active -* map:: Map a drive to another -* md5crypt:: Encrypt a password in MD5 format -* module:: Load a module -* modulenounzip:: Load a module without decompression -* pause:: Wait for a key press -* quit:: Exit from the grub shell -* reboot:: Reboot your computer -* read:: Read data from memory -* root:: Set GRUB's root device -* rootnoverify:: Set GRUB's root device without mounting -* savedefault:: Save current entry as the default entry -* setup:: Set up GRUB's installation automatically -* testload:: Load a file for testing a filesystem -* testvbe:: Test VESA BIOS EXTENSION -* uppermem:: Set the upper memory size -* vbeprobe:: Probe VESA BIOS EXTENSION -@end menu - - -@node blocklist -@subsection blocklist - -@deffn Command blocklist file -Print the block list notation of the file @var{file}. @xref{Block list -syntax}. -@end deffn - - -@node boot -@subsection boot - -@deffn Command boot -Boot the OS or chain-loader which has been loaded. Only necessary if -running the fully interactive command-line (it is implicit at the end of -a menu entry). -@end deffn - - -@node cat -@subsection cat - -@deffn Command cat file -Display the contents of the file @var{file}. This command may be useful -to remind you of your OS's root partition: - -@example -grub> @kbd{cat /etc/fstab} -@end example -@end deffn - - -@node chainloader -@subsection chainloader - -@deffn Command chainloader [@option{--force}] file -Load @var{file} as a chain-loader. Like any other file loaded by the -filesystem code, it can use the blocklist notation to grab the first -sector of the current partition with @samp{+1}. If you specify the -option @option{--force}, then load @var{file} forcibly, whether it has a -correct signature or not. This is required when you want to load a -defective boot loader, such as SCO UnixWare 7.1 (@pxref{SCO UnixWare}). -@end deffn - - -@node cmp -@subsection cmp - -@deffn Command cmp file1 file2 -Compare the file @var{file1} with the file @var{file2}. If they differ -in size, print the sizes like this: - -@example -Differ in size: 0x1234 [foo], 0x4321 [bar] -@end example - -If the sizes are equal but the bytes at an offset differ, then print the -bytes like this: - -@example -Differ at the offset 777: 0xbe [foo], 0xef [bar] -@end example - -If they are completely identical, nothing will be printed. -@end deffn - - -@node configfile -@subsection configfile - -@deffn Command configfile file -Load @var{file} as a configuration file. -@end deffn - - -@node debug -@subsection debug - -@deffn Command debug -Toggle debug mode (by default it is off). When debug mode is on, some -extra messages are printed to show disk activity. This global debug flag -is mainly useful for GRUB developers when testing new code. -@end deffn - - -@node displayapm -@subsection displayapm - -@deffn Command displayapm -Display APM BIOS information. -@end deffn - - -@node displaymem -@subsection displaymem - -@deffn Command displaymem -Display what GRUB thinks the system address space map of the machine is, -including all regions of physical @sc{ram} installed. GRUB's -@dfn{upper/lower memory} display uses the standard BIOS interface for -the available memory in the first megabyte, or @dfn{lower memory}, and a -synthesized number from various BIOS interfaces of the memory starting -at 1MB and going up to the first chipset hole for @dfn{upper memory} -(the standard PC @dfn{upper memory} interface is limited to reporting a -maximum of 64MB). -@end deffn - - -@node embed -@subsection embed - -@deffn Command embed stage1_5 device -Embed the Stage 1.5 @var{stage1_5} in the sectors after the MBR if -@var{device} is a drive, or in the @dfn{boot loader} area if @var{device} -is a FFS partition or a ReiserFS partition.@footnote{The latter feature -has not been implemented yet.} Print the number of sectors which -@var{stage1_5} occupies, if successful. - -Usually, you don't need to run this command directly. @xref{setup}. -@end deffn - - -@node find -@subsection find - -@deffn Command find filename -Search for the file name @var{filename} in all mountable partitions -and print the list of the devices which contain the file. The file -name @var{filename} should be an absolute file name like -@code{/boot/grub/stage1}. -@end deffn - - -@node fstest -@subsection fstest - -@deffn Command fstest -Toggle filesystem test mode. -Filesystem test mode, when turned on, prints out data corresponding to -all the device reads and what values are being sent to the low-level -routines. The format is @samp{<@var{partition-offset-sector}, -@var{byte-offset}, @var{byte-length}>} for high-level reads inside a -partition, and @samp{[@var{disk-offset-sector}]} for low-level sector -requests from the disk. -Filesystem test mode is turned off by any use of the @command{install} -(@pxref{install}) or @command{testload} (@pxref{testload}) commands. -@end deffn - - -@node geometry -@subsection geometry - -@deffn Command geometry drive [cylinder head sector [total_sector]] -Print the information for the drive @var{drive}. In the grub shell, you -can set the geometry of the drive arbitrarily. The number of -cylinders, the number of heads, the number of sectors and the number of -total sectors are set to CYLINDER, HEAD, SECTOR and TOTAL_SECTOR, -respectively. If you omit TOTAL_SECTOR, then it will be calculated -based on the C/H/S values automatically. -@end deffn - - -@node halt -@subsection halt - -@deffn Command halt @option{--no-apm} -The command halts the computer. If the @option{--no-apm} option -is specified, no APM BIOS call is performed. Otherwise, the computer -is shut down using APM. -@end deffn - - -@node help -@subsection help - -@deffn Command help @option{--all} [pattern @dots{}] -Display helpful information about builtin commands. If you do not -specify @var{pattern}, this command shows short descriptions of most of -available commands. If you specify the option @option{--all} to this -command, short descriptions of rarely used commands (such as -@ref{testload}) are displayed as well. - -If you specify any @var{patterns}, it displays longer information -about each of the commands which match those @var{patterns}. -@end deffn - - -@node impsprobe -@subsection impsprobe - -@deffn Command impsprobe -Probe the Intel Multiprocessor Specification 1.1 or 1.4 configuration -table and boot the various CPUs which are found into a tight loop. This -command can be used only in the Stage 2, but not in the grub shell. -@end deffn - - -@node initrd -@subsection initrd - -@deffn Command initrd file @dots{} -Load an initial ramdisk for a Linux format boot image and set the -appropriate parameters in the Linux setup area in memory. See also -@ref{GNU/Linux}. -@end deffn - - -@node install -@subsection install - -@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] -This command is fairly complex, and you should not use this command -unless you are familiar with GRUB. Use @command{setup} (@pxref{setup}) -instead. - -In short, it will perform a full install presuming the Stage 2 or Stage -1.5@footnote{They're loaded the same way, so we will refer to the Stage -1.5 as a Stage 2 from now on.} is in its final install location. - -In slightly more detail, it will load @var{stage1_file}, validate that -it is a GRUB Stage 1 of the right version number, install in it a -blocklist for loading @var{stage2_file} as a Stage 2. If the option -@option{d} is present, the Stage 1 will always look for the actual -disk @var{stage2_file} was installed on, rather than using the booting -drive. The Stage 2 will be loaded at address @var{addr}, which must be -@samp{0x8000} for a true Stage 2, and @samp{0x2000} for a Stage 1.5. If -@var{addr} is not present, GRUB will determine the address -automatically. It then writes the completed Stage 1 to the first block -of the device @var{dest_dev}. If the options @option{p} or -@var{config_file} are present, then it reads the first block of stage2, -modifies it with the values of the partition @var{stage2_file} was found -on (for @option{p}) or places the string @var{config_file} into the area -telling the stage2 where to look for a configuration file at boot -time. Likewise, if @var{real_config_file} is present and -@var{stage2_file} is a Stage 1.5, then the Stage 2 @var{config_file} is -patched with the configuration file name @var{real_config_file}. This -command preserves the DOS BPB (and for hard disks, the partition table) -of the sector the Stage 1 is to be installed into. - -@strong{Caution:} Several buggy BIOSes don't pass a booting drive -properly when booting from a hard disk drive. Therefore, you will -unfortunately have to specify the option @option{d}, whether your -Stage2 resides at the booting drive or not, if you have such a -BIOS. We know these are defective in this way: - -@table @asis -@item -Fujitsu LifeBook 400 BIOS version 31J0103A - -@item -HP Vectra XU 6/200 BIOS version GG.06.11 -@end table - -@strong{Caution2:} A number of BIOSes don't return a correct LBA support -bitmap even if they do have the support. So GRUB provides a solution to -ignore the wrong bitmap, that is, the option @option{--force-lba}. Don't -use this option if you know that your BIOS doesn't have LBA support. - -@strong{Caution3:} You must specify the option @option{--stage2} in the -grub shell, if you cannot unmount the filesystem where your stage2 file -resides. The argument should be the file name in your operating system. -@end deffn - - -@node ioprobe -@subsection ioprobe - -@deffn Command ioprobe drive -Probe I/O ports used for the drive @var{drive}. This command will list -the I/O ports on the screen. For technical information, -@xref{Internals}. -@end deffn - - -@node kernel -@subsection kernel - -@deffn Command kernel [@option{--type=type}] [@option{--no-mem-option}] file @dots{} -Attempt to load the primary boot image (Multiboot a.out or @sc{elf}, -Linux zImage or bzImage, FreeBSD a.out, NetBSD a.out, etc.) from -@var{file}. The rest of the line is passed verbatim as the @dfn{kernel -command-line}. Any modules must be reloaded after using this command. - -This command also accepts the option @option{--type} so that you can -specify the kernel type of @var{file} explicitly. The argument -@var{type} must be one of these: @samp{netbsd}, @samp{freebsd}, -@samp{openbsd}, @samp{linux}, @samp{biglinux}, and -@samp{multiboot}. However, you need to specify it only if you want to -load a NetBSD @sc{elf} kernel, because GRUB can automatically determine -a kernel type in the other cases, quite safely. - -The option @option{--no-mem-option} is effective only for Linux. If the -option is specified, GRUB doesn't pass the option @option{mem=} to the -kernel. This option is implied for Linux kernels 2.4.18 and newer. -@end deffn - - -@node lock -@subsection lock - -@deffn Command lock -Prevent normal users from executing arbitrary menu entries. You must use -the command @command{password} if you really want this command to be -useful (@pxref{password}). - -This command is used in a menu, as shown in this example: - -@example -@group -title This entry is too dangerous to be executed by normal users -lock -root (hd0,a) -kernel /no-security-os -@end group -@end example - -See also @ref{Security}. -@end deffn - - -@node makeactive -@subsection makeactive - -@deffn Command makeactive -Set the active partition on the root disk to GRUB's root device. -This command is limited to @emph{primary} PC partitions on a hard disk. -@end deffn - - -@node map -@subsection map - -@deffn Command map to_drive from_drive -Map the drive @var{from_drive} to the drive @var{to_drive}. This is -necessary when you chain-load some operating systems, such as DOS, if -such an OS resides at a non-first drive. Here is an example: - -@example -@group -grub> @kbd{map (hd0) (hd1)} -grub> @kbd{map (hd1) (hd0)} -@end group -@end example - -The example exchanges the order between the first hard disk and the -second hard disk. See also @ref{DOS/Windows}. -@end deffn - - -@node md5crypt -@subsection md5crypt - -@deffn Command md5crypt -Prompt to enter a password, and encrypt it in MD5 format. The encrypted -password can be used with the command @command{password} -(@pxref{password}). See also @ref{Security}. -@end deffn - - -@node module -@subsection module - -@deffn Command module file @dots{} -Load a boot module @var{file} for a Multiboot format boot image (no -interpretation of the file contents are made, so the user of this -command must know what the kernel in question expects). The rest of the -line is passed as the @dfn{module command-line}, like the -@command{kernel} command. You must load a Multiboot kernel image before -loading any module. See also @ref{modulenounzip}. -@end deffn - - -@node modulenounzip -@subsection modulenounzip - -@deffn Command modulenounzip file @dots{} -The same as @command{module} (@pxref{module}), except that automatic -decompression is disabled. -@end deffn - - -@node pause -@subsection pause - -@deffn Command pause message @dots{} -Print the @var{message}, then wait until a key is pressed. Note that -placing @key{^G} (ASCII code 7) in the message will cause the speaker to -emit the standard beep sound, which is useful when prompting the user to -change floppies. -@end deffn - - -@node quit -@subsection quit - -@deffn Command quit -Exit from the grub shell @command{grub} (@pxref{Invoking the grub -shell}). This command can be used only in the grub shell. -@end deffn - - -@node reboot -@subsection reboot - -@deffn Command reboot -Reboot the computer. -@end deffn - - -@node read -@subsection read - -@deffn Command read addr -Read a 32-bit value from memory at address @var{addr} and display it in -hex format. -@end deffn - - -@node root -@subsection root - -@deffn Command root device [hdbias] -Set the current @dfn{root device} to the device @var{device}, then -attempt to mount it to get the partition size (for passing the partition -descriptor in @code{ES:ESI}, used by some chain-loaded boot loaders), the -BSD drive-type (for booting BSD kernels using their native boot format), -and correctly determine the PC partition where a BSD sub-partition is -located. The optional @var{hdbias} parameter is a number to tell a BSD -kernel how many BIOS drive numbers are on controllers before the current -one. For example, if there is an IDE disk and a SCSI disk, and your -FreeBSD root partition is on the SCSI disk, then use a @samp{1} for -@var{hdbias}. - -See also @ref{rootnoverify}. -@end deffn - - -@node rootnoverify -@subsection rootnoverify - -@deffn Command rootnoverify device [hdbias] -Similar to @command{root} (@pxref{root}), but don't attempt to mount the -partition. This is useful for when an OS is outside of the area of the -disk that GRUB can read, but setting the correct root device is still -desired. Note that the items mentioned in @command{root} above which -derived from attempting the mount will @emph{not} work correctly. -@end deffn - - -@node savedefault -@subsection savedefault - -@deffn Command savedefault num -Save the current menu entry or @var{num} if specified as a default -entry. Here is an example: - -@example -@group -default saved -timeout 10 - -title GNU/Linux -root (hd0,0) -kernel /boot/vmlinuz root=/dev/sda1 vga=ext -initrd /boot/initrd -savedefault - -title FreeBSD -root (hd0,a) -kernel /boot/loader -savedefault -@end group -@end example - -With this configuration, GRUB will choose the entry booted previously as -the default entry. - -You can specify @samp{fallback} instead of a number. Then, next -fallback entry is saved. Next fallback entry is chosen from fallback -entries. Normally, this will be the first entry in fallback ones. - -See also @ref{default} and @ref{Invoking grub-set-default}. -@end deffn - - -@node setup -@subsection setup - -@deffn Command setup [@option{--force-lba}] [@option{--stage2=os_stage2_file}] [@option{--prefix=dir}] install_device [image_device] -Set up the installation of GRUB automatically. This command uses the -more flexible command @command{install} (@pxref{install}) in the backend -and installs GRUB into the device @var{install_device}. If -@var{image_device} is specified, then find the GRUB images -(@pxref{Images}) in the device @var{image_device}, otherwise use the -current @dfn{root device}, which can be set by the command -@command{root}. If @var{install_device} is a hard disk, then embed a -Stage 1.5 in the disk if possible. - -The option @option{--prefix} specifies the directory under which GRUB -images are put. If it is not specified, GRUB automatically searches them -in @file{/boot/grub} and @file{/grub}. - -The options @option{--force-lba} and @option{--stage2} are just passed -to @command{install} if specified. @xref{install}, for more -information. -@end deffn - - -@node testload -@subsection testload - -@deffn Command testload file -Read the entire contents of @var{file} in several different ways and -compare them, to test the filesystem code. The output is somewhat -cryptic, but if no errors are reported and the final @samp{i=@var{X}, -filepos=@var{Y}} reading has @var{X} and @var{Y} equal, then it is -definitely consistent, and very likely works correctly subject to a -consistent offset error. If this test succeeds, then a good next step is -to try loading a kernel. -@end deffn - - -@node testvbe -@subsection testvbe - -@deffn Command testvbe mode -Test the VESA BIOS EXTENSION mode @var{mode}. This command will switch -your video card to the graphics mode, and show an endless animation. Hit -any key to return. See also @ref{vbeprobe}. -@end deffn - - -@node uppermem -@subsection uppermem - -@deffn Command uppermem kbytes -Force GRUB to assume that only @var{kbytes} kilobytes of upper memory -are installed. Any system address range maps are discarded. - -@strong{Caution:} This should be used with great caution, and should -only be necessary on some old machines. GRUB's BIOS probe can pick up -all @sc{ram} on all new machines the author has ever heard of. It can -also be used for debugging purposes to lie to an OS. -@end deffn - - -@node vbeprobe -@subsection vbeprobe - -@deffn Command vbeprobe [mode] -Probe VESA BIOS EXTENSION information. If the mode @var{mode} is -specified, show only the information about @var{mode}. Otherwise, this -command lists up available VBE modes on the screen. See also -@ref{testvbe}. -@end deffn - - -@node Troubleshooting -@chapter Error messages reported by GRUB - -This chapter describes error messages reported by GRUB when you -encounter trouble. @xref{Invoking the grub shell}, if your problem is -specific to the grub shell. - -@menu -* Stage1 errors:: Errors reported by the Stage 1 -* Stage1.5 errors:: Errors reported by the Stage 1.5 -* Stage2 errors:: Errors reported by the Stage 2 -@end menu - - -@node Stage1 errors -@section Errors reported by the Stage 1 - -The general way that the Stage 1 handles errors is to print an error -string and then halt. Pressing @kbd{@key{CTRL}-@key{ALT}-@key{DEL}} will -reboot. - -The following is a comprehensive list of error messages for the Stage 1: - -@table @asis -@item Hard Disk Error -The stage2 or stage1.5 is being read from a hard disk, and the attempt -to determine the size and geometry of the hard disk failed. - -@item Floppy Error -The stage2 or stage1.5 is being read from a floppy disk, and the attempt -to determine the size and geometry of the floppy disk failed. It's listed -as a separate error since the probe sequence is different than for hard -disks. - -@item Read Error -A disk read error happened while trying to read the stage2 or stage1.5. - -@item Geom Error -The location of the stage2 or stage1.5 is not in the portion of the disk -supported directly by the BIOS read calls. This could occur because the -BIOS translated geometry has been changed by the user or the disk is -moved to another machine or controller after installation, or GRUB was -not installed using itself (if it was, the Stage 2 version of this error -would have been seen during that process and it would not have completed -the install). -@end table - - -@node Stage1.5 errors -@section Errors reported by the Stage 1.5 - -The general way that the Stage 1.5 handles errors is to print an error -number in the form @code{Error @var{num}} and then halt. Pressing -@kbd{@key{CTRL}-@key{ALT}-@key{DEL}} will reboot. - -The error numbers correspond to the errors reported by Stage -2. @xref{Stage2 errors}. - - -@node Stage2 errors -@section Errors reported by the Stage 2 - -The general way that the Stage 2 handles errors is to abort the -operation in question, print an error string, then (if possible) either -continue based on the fact that an error occurred or wait for the user to -deal with the error. - -The following is a comprehensive list of error messages for the Stage 2 -(error numbers for the Stage 1.5 are listed before the colon in each -description): - -@table @asis -@item 1 : Filename must be either an absolute filename or blocklist -This error is returned if a file name is requested which doesn't fit the -syntax/rules listed in the @ref{Filesystem}. - -@item 2 : Bad file or directory type -This error is returned if a file requested is not a regular file, but -something like a symbolic link, directory, or FIFO. - -@item 3 : Bad or corrupt data while decompressing file -This error is returned if the run-length decompression code gets an -internal error. This is usually from a corrupt file. - -@item 4 : Bad or incompatible header in compressed file -This error is returned if the file header for a supposedly compressed -file is bad. - -@item 5 : Partition table invalid or corrupt -This error is returned if the sanity checks on the integrity of the -partition table fail. This is a bad sign. - -@item 6 : Mismatched or corrupt version of stage1/stage2 -This error is returned if the install command points to incompatible -or corrupt versions of the stage1 or stage2. It can't detect corruption -in general, but this is a sanity check on the version numbers, which -should be correct. - -@item 7 : Loading below 1MB is not supported -This error is returned if the lowest address in a kernel is below the -1MB boundary. The Linux zImage format is a special case and can be -handled since it has a fixed loading address and maximum size. - -@item 8 : Kernel must be loaded before booting -This error is returned if GRUB is told to execute the boot sequence -without having a kernel to start. - -@item 9 : Unknown boot failure -This error is returned if the boot attempt did not succeed for reasons -which are unknown. - -@item 10 : Unsupported Multiboot features requested -This error is returned when the Multiboot features word in the Multiboot -header requires a feature that is not recognized. The point of this is -that the kernel requires special handling which GRUB is probably -unable to provide. - -@item 11 : Unrecognized device string -This error is returned if a device string was expected, and the string -encountered didn't fit the syntax/rules listed in the @ref{Filesystem}. - -@item 12 : Invalid device requested -This error is returned if a device string is recognizable but does not -fall under the other device errors. - -@item 13 : Invalid or unsupported executable format -This error is returned if the kernel image being loaded is not -recognized as Multiboot or one of the supported native formats (Linux -zImage or bzImage, FreeBSD, or NetBSD). - -@item 14 : Filesystem compatibility error, cannot read whole file -Some of the filesystem reading code in GRUB has limits on the length of -the files it can read. This error is returned when the user runs into -such a limit. - -@item 15 : File not found -This error is returned if the specified file name cannot be found, but -everything else (like the disk/partition info) is OK. - -@item 16 : Inconsistent filesystem structure -This error is returned by the filesystem code to denote an internal -error caused by the sanity checks of the filesystem structure on disk -not matching what it expects. This is usually caused by a corrupt -filesystem or bugs in the code handling it in GRUB. - -@item 17 : Cannot mount selected partition -This error is returned if the partition requested exists, but the -filesystem type cannot be recognized by GRUB. - -@item 18 : Selected cylinder exceeds maximum supported by BIOS -This error is returned when a read is attempted at a linear block -address beyond the end of the BIOS translated area. This generally -happens if your disk is larger than the BIOS can handle (512MB for -(E)IDE disks on older machines or larger than 8GB in general). - -@item 19 : Linux kernel must be loaded before initrd -This error is returned if the initrd command is used before loading a -Linux kernel. - -@item 20 : Multiboot kernel must be loaded before modules -This error is returned if the module load command is used before loading -a Multiboot kernel. It only makes sense in this case anyway, as GRUB has -no idea how to communicate the presence of such modules to a -non-Multiboot-aware kernel. - -@item 21 : Selected disk does not exist -This error is returned if the device part of a device- or full file name -refers to a disk or BIOS device that is not present or not recognized by -the BIOS in the system. - -@item 22 : No such partition -This error is returned if a partition is requested in the device part of -a device- or full file name which isn't on the selected disk. - -@item 23 : Error while parsing number -This error is returned if GRUB was expecting to read a number and -encountered bad data. - -@item 24 : Attempt to access block outside partition -This error is returned if a linear block address is outside of the disk -partition. This generally happens because of a corrupt filesystem on the -disk or a bug in the code handling it in GRUB (it's a great debugging -tool). - -@item 25 : Disk read error -This error is returned if there is a disk read error when trying to -probe or read data from a particular disk. - -@item 26 : Too many symbolic links -This error is returned if the link count is beyond the maximum -(currently 5), possibly the symbolic links are looped. - -@item 27 : Unrecognized command -This error is returned if an unrecognized command is entered on the -command-line or in a boot sequence section of a configuration file and -that entry is selected. - -@item 28 : Selected item cannot fit into memory -This error is returned if a kernel, module, or raw file load command is -either trying to load its data such that it won't fit into memory or it -is simply too big. - -@item 29 : Disk write error -This error is returned if there is a disk write error when trying to -write to a particular disk. This would generally only occur during an -install of set active partition command. - -@item 30 : Invalid argument -This error is returned if an argument specified to a command is invalid. - -@item 31 : File is not sector aligned -This error may occur only when you access a ReiserFS partition by -block-lists (e.g. the command @command{install}). In this case, you -should mount the partition with the @samp{-o notail} option. - -@item 32 : Must be authenticated -This error is returned if you try to run a locked entry. You should -enter a correct password before running such an entry. - -@item 33 : Serial device not configured -This error is returned if you try to change your terminal to a serial -one before initializing any serial device. - -@item 34 : No spare sectors on the disk -This error is returned if a disk doesn't have enough spare space. This -happens when you try to embed Stage 1.5 into the unused sectors after -the MBR, but the first partition starts right after the MBR or they are -used by EZ-BIOS. -@end table - - -@node Invoking the grub shell -@chapter Invoking the grub shell - -This chapter documents the grub shell @command{grub}. Note that the grub -shell is an emulator; it doesn't run under the native environment, so it -sometimes does something wrong. Therefore, you shouldn't trust it too -much. If there is anything wrong with it, don't hesitate to try the -native GRUB environment, especially when it guesses a wrong map between -BIOS drives and OS devices. - -@menu -* Basic usage:: How to use the grub shell -* Installation under UNIX:: How to install GRUB via @command{grub} -* Device map:: The map between BIOS drives and OS devices -@end menu - - -@node Basic usage -@section Introduction into the grub shell - -You can use the command @command{grub} for installing GRUB under your -operating systems and for a testbed when you add a new feature into GRUB -or when fixing a bug. @command{grub} is almost the same as the Stage 2, -and, in fact, it shares the source code with the Stage 2 and you can use -the same commands (@pxref{Commands}) in @command{grub}. It is emulated by -replacing BIOS calls with UNIX system calls and libc functions. - -The command @command{grub} accepts the following options: - -@table @option -@item --help -Print a summary of the command-line options and exit. - -@item --version -Print the version number of GRUB and exit. - -@item --verbose -Print some verbose messages for debugging purpose. - -@item --device-map=@var{file} -Use the device map file @var{file}. The format is described in -@ref{Device map}. - -@item --no-floppy -Do not probe any floppy drive. This option has no effect if the option -@option{--device-map} is specified (@pxref{Device map}). - -@item --probe-second-floppy -Probe the second floppy drive. If this option is not specified, the grub -shell does not probe it, as that sometimes takes a long time. If you -specify the device map file (@pxref{Device map}), the grub shell just -ignores this option. - -@item --config-file=@var{file} -Read the configuration file @var{file} instead of -@file{/boot/grub/menu.lst}. The format is the same as the normal GRUB -syntax. See @ref{Filesystem}, for more information. - -@item --boot-drive=@var{drive} -Set the stage2 @var{boot_drive} to @var{drive}. This argument should be -an integer (decimal, octal or hexadecimal). - -@item --install-partition=@var{par} -Set the stage2 @var{install_partition} to @var{par}. This argument -should be an integer (decimal, octal or hexadecimal). - -@item --no-config-file -Do not use the configuration file even if it can be read. - -@item --no-curses -Do not use the screen handling interface by the curses even if it is -available. - -@item --batch -This option has the same meaning as @samp{--no-config-file --no-curses}. - -@item --read-only -Disable writing to any disk. - -@item --hold -Wait until a debugger will attach. This option is useful when you want -to debug the startup code. -@end table - - -@node Installation under UNIX -@section How to install GRUB via @command{grub} - -The installation procedure is the same as under the @dfn{native} Stage -2. @xref{Installation}, for more information. The command -@command{grub}-specific information is described here. - -What you should be careful about is @dfn{buffer cache}. @command{grub} -makes use of raw devices instead of filesystems that your operating -systems serve, so there exists a potential problem that some cache -inconsistency may corrupt your filesystems. What we recommend is: - -@itemize @bullet -@item -If you can unmount drives to which GRUB may write any amount of data, -unmount them before running @command{grub}. - -@item -If a drive cannot be unmounted but can be mounted with the read-only -flag, mount it in read-only mode. That should be secure. - -@item -If a drive must be mounted with the read-write flag, make sure that no -activity is being done on it while the command @command{grub} is -running. - -@item -Reboot your operating system as soon as possible. This is probably not -required if you follow the rules above, but reboot is the most secure -way. -@end itemize - -In addition, enter the command @command{quit} when you finish the -installation. That is @emph{very important} because @command{quit} makes -the buffer cache consistent. Do not push @key{C-c}. - -If you want to install GRUB non-interactively, specify @samp{--batch} -option in the command-line. This is a simple example: - -@example -@group -#!/bin/sh - -# Use /usr/sbin/grub if you are on an older system. -/sbin/grub --batch </dev/null 2>/dev/null -root (hd0,0) -setup (hd0) -quit -EOT -@end group -@end example - - -@node Device map -@section The map between BIOS drives and OS devices - -When you specify the option @option{--device-map} (@pxref{Basic usage}), -the grub shell creates the @dfn{device map file} automatically unless it -already exists. The file name @file{/boot/grub/device.map} is preferred. - -If the device map file exists, the grub shell reads it to map BIOS -drives to OS devices. This file consists of lines like this: - -@example -@var{device} @var{file} -@end example - -@var{device} is a drive specified in the GRUB syntax (@pxref{Device -syntax}), and @var{file} is an OS file, which is normally a device -file. - -The reason why the grub shell gives you the device map file is that it -cannot guess the map between BIOS drives and OS devices correctly in -some environments. For example, if you exchange the boot sequence -between IDE and SCSI in your BIOS, it gets the order wrong. - -Thus, edit the file if the grub shell makes a mistake. You can put any -comments in the file if needed, as the grub shell assumes that a line is -just a comment if the first character is @samp{#}. - - -@node Invoking grub-install -@chapter Invoking grub-install - -The program @command{grub-install} installs GRUB on your drive using the -grub shell (@pxref{Invoking the grub shell}). You must specify the -device name on which you want to install GRUB, like this: - -@example -grub-install @var{install_device} -@end example - -The device name @var{install_device} is an OS device name or a GRUB -device name. - -@command{grub-install} accepts the following options: - -@table @option -@item --help -Print a summary of the command-line options and exit. - -@item --version -Print the version number of GRUB and exit. - -@item --force-lba -Force GRUB to use LBA mode even for a buggy BIOS. Use this option only -if your BIOS doesn't work properly in LBA mode even though it supports -LBA mode. - -@item --root-directory=@var{dir} -Install GRUB images under the directory @var{dir} instead of the root -directory. This option is useful when you want to install GRUB into a -separate partition or a removable disk. Here is an example in which -you have a separate @dfn{boot} partition which is mounted on -@file{/boot}: - -@example -@kbd{grub-install --root-directory=/boot hd0} -@end example - -@item --grub-shell=@var{file} -Use @var{file} as the grub shell. You can append arbitrary options to -@var{file} after the file name, like this: - -@example -@kbd{grub-install --grub-shell="grub --read-only" /dev/fd0} -@end example - -@item --recheck -Recheck the device map, even if @file{/boot/grub/device.map} already -exists. You should use this option whenever you add/remove a disk -into/from your computer. -@end table - - -@node Invoking grub-md5-crypt -@chapter Invoking grub-md5-crypt - -The program @command{grub-md5-crypt} encrypts a password in MD5 format. -This is just a frontend of the grub shell (@pxref{Invoking the grub -shell}). Passwords encrypted by this program can be used with the -command @command{password} (@pxref{password}). - -@command{grub-md5-crypt} accepts the following options: - -@table @option -@item --help -Print a summary of the command-line options and exit. - -@item --version -Print the version information and exit. - -@item --grub-shell=@var{file} -Use @var{file} as the grub shell. -@end table - - -@node Invoking grub-terminfo -@chapter Invoking grub-terminfo - -The program @command{grub-terminfo} generates a terminfo command from -a terminfo name (@pxref{terminfo}). The result can be used in the -configuration file, to define escape sequences. Because GRUB assumes -that your terminal is vt100-compatible by default, this would be -useful only if your terminal is uncommon (such as vt52). - -@command{grub-terminfo} accepts the following options: - -@table @option -@item --help -Print a summary of the command-line options and exit. - -@item --version -Print the version information and exit. -@end table - -You must specify one argument to this command. For example: - -@example -@kbd{grub-terminfo vt52} -@end example - - -@node Invoking grub-set-default -@chapter Invoking grub-set-default - -The program @command{grub-set-default} sets the default boot entry for -GRUB. This automatically creates a file named @file{default} under -your GRUB directory (i.e. @file{/boot/grub}), if it is not -present. This file is used to determine the default boot entry when -GRUB boots up your system when you use @samp{default saved} in your -configuration file (@pxref{default}), and to save next default boot -entry when you use @samp{savedefault} in a boot entry -(@pxref{savedefault}). - -@command{grub-set-default} accepts the following options: - -@table @option -@item --help -Print a summary of the command-line options and exit. - -@item --version -Print the version information and exit. - -@item --root-directory=@var{dir} -Use the directory @var{dir} instead of the root directory -(i.e. @file{/}) to define the location of the default file. This -is useful when you mount a disk which is used for another system. -@end table - -You must specify a single argument to @command{grub-set-default}. This -argument is normally the number of a default boot entry. For example, -if you have this configuration file: - -@example -@group -default saved -timeout 10 - -title GNU/Hurd -root (hd0,0) -... - -title GNU/Linux -root (hd0,1) -... -@end group -@end example - -and if you want to set the next default boot entry to GNU/Linux, you -may execute this command: - -@example -@kbd{grub-set-default 1} -@end example - -Because the entry for GNU/Linux is @samp{1}. Note that entries are -counted from zero. So, if you want to specify GNU/Hurd here, then you -should specify @samp{0}. - -This feature is very useful if you want to test a new kernel or to -make your system quite robust. @xref{Making your system robust}, for -more hints about how to set up a robust system. - - -@node Invoking mbchk -@chapter Invoking mbchk - -The program @command{mbchk} checks for the format of a Multiboot -kernel. We recommend using this program before booting your own kernel -by GRUB. - -@command{mbchk} accepts the following options: - -@table @option -@item --help -Print a summary of the command-line options and exit. - -@item --version -Print the version number of GRUB and exit. - -@item --quiet -Suppress all normal output. -@end table - - -@node Obtaining and Building GRUB -@appendix How to obtain and build GRUB - -@quotation -@strong{Caution:} GRUB requires binutils-2.9.1.0.23 or later because the -GNU assembler has been changed so that it can produce real 16bits -machine code between 2.9.1 and 2.9.1.0.x. See -@uref{http://sources.redhat.com/binutils/}, to obtain information on -how to get the latest version. -@end quotation - -GRUB is available from the GNU alpha archive site -@uref{ftp://alpha.gnu.org/gnu/grub} or any of its mirrors. The file -will be named grub-version.tar.gz. The current version is -@value{VERSION}, so the file you should grab is: - -@uref{ftp://alpha.gnu.org/gnu/grub/grub-@value{VERSION}.tar.gz} - -To unbundle GRUB use the instruction: - -@example -@kbd{zcat grub-@value{VERSION}.tar.gz | tar xvf -} -@end example - -which will create a directory called @file{grub-@value{VERSION}} with -all the sources. You can look at the file @file{INSTALL} for detailed -instructions on how to build and install GRUB, but you should be able to -just do: - -@example -@group -@kbd{cd grub-@value{VERSION}} -@kbd{./configure} -@kbd{make install} -@end group -@end example - -Also, the latest version is available from the SVN. See -@uref{http://savannah.gnu.org/svn/?group=grub} for more information. - -@node Reporting bugs -@appendix Reporting bugs - -These are the guideline for how to report bugs. Take a look at this -list below before you submit bugs: - -@enumerate -@item -Before getting unsettled, read this manual through and through. Also, -see the @uref{http://www.gnu.org/software/grub/grub-faq.html, GNU GRUB FAQ}. - -@item -Always mention the information on your GRUB. The version number and the -configuration are quite important. If you build it yourself, write the -options specified to the configure script and your operating system, -including the versions of gcc and binutils. - -@item -If you have trouble with the installation, inform us of how you -installed GRUB. Don't omit error messages, if any. Just @samp{GRUB hangs -up when it boots} is not enough. - -The information on your hardware is also essential. These are especially -important: the geometries and the partition tables of your hard disk -drives and your BIOS. - -@item -If GRUB cannot boot your operating system, write down -@emph{everything} you see on the screen. Don't paraphrase them, like -@samp{The foo OS crashes with GRUB, even though it can boot with the -bar boot loader just fine}. Mention the commands you executed, the -messages printed by them, and information on your operating system -including the version number. - -@item -Explain what you wanted to do. It is very useful to know your purpose -and your wish, and how GRUB didn't satisfy you. - -@item -If you can investigate the problem yourself, please do. That will give -you and us much more information on the problem. Attaching a patch is -even better. - -When you attach a patch, make the patch in unified diff format, and -write ChangeLog entries. But, even when you make a patch, don't forget -to explain the problem, so that we can understand what your patch is -for. - -@item -Write down anything that you think might be related. Please understand -that we often need to reproduce the same problem you encounterred in our -environment. So your information should be sufficient for us to do the -same thing---Don't forget that we cannot see your computer directly. If -you are not sure whether to state a fact or leave it out, state it! -Reporting too many things is much better than omitting something -important. -@end enumerate - -If you follow the guideline above, submit a report to the -@uref{http://savannah.gnu.org/bugs/?group=grub, Bug Tracking System}. -Alternatively, you can submit a report via electronic mail to -@email{bug-grub@@gnu.org}, but we strongly recommend that you use the -Bug Tracking System, because e-mail can be passed over easily. - -Once we get your report, we will try to fix the bugs. - - -@node Future -@appendix Where GRUB will go - -We started the next generation of GRUB, GRUB 2. GRUB 2 includes -internationalization, dynamic module loading, real memory management, -multiple architecture support, a scripting language, and many other -nice feature. If you are interested in the development of GRUB 2, take -a look at @uref{http://www.gnu.org/software/grub/grub.html, the -homepage}. - - - -@node Copying This Manual -@appendix Copying This Manual - -@menu -* GNU Free Documentation License:: License for copying this manual. -@end menu - -@include fdl.texi - - -@node Index -@unnumbered Index - -@c Currently, we use only the Concept Index. -@printindex cp - - -@bye - -Some notes: - - This is an attempt to make a manual for GRUB 2. The contents are - copied from the GRUB manual in GRUB Legacy, so they are not always - appropriate yet for GRUB 2. +\input texinfo +@c -*-texinfo-*- +@c %**start of header +@setfilename grub.info +@include version.texi +@settitle GNU GRUB Manual @value{VERSION} +@c Unify all our little indices for now. +@syncodeindex fn cp +@syncodeindex vr cp +@syncodeindex ky cp +@syncodeindex pg cp +@syncodeindex tp cp +@c %**end of header + +@footnotestyle separate +@paragraphindent 3 +@finalout + +@copying +This manual is for GNU GRUB (version @value{VERSION}, +@value{UPDATED}). + +Copyright @copyright{} 1999,2000,2001,2002,2004,2006,2008 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections. +@end quotation +@end copying + +@dircategory Kernel +@direntry +* GRUB: (grub). The GRand Unified Bootloader +* grub-install: (grub)Invoking grub-install. Install GRUB on your drive +* grub-terminfo: (grub)Invoking grub-terminfo. Generate a terminfo + command from a + terminfo name +@end direntry + +@setchapternewpage odd + +@titlepage +@sp 10 +@title the GNU GRUB manual +@subtitle The GRand Unified Bootloader, version @value{VERSION}, @value{UPDATED}. +@author Gordon Matzigkeit +@author Yoshinori K. Okuji +@c The following two commands start the copyright page. +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@c Output the table of contents at the beginning. +@contents + +@finalout +@headings double + +@ifnottex +@node Top +@top GNU GRUB manual + +This is the documentation of GNU GRUB, the GRand Unified Bootloader, +a flexible and powerful boot loader program for a wide range of +architectures. + +This edition documents version @value{VERSION}. + +@insertcopying +@end ifnottex + +@menu +* Introduction:: Capturing the spirit of GRUB +* Naming convention:: Names of your drives in GRUB +* Installation:: Installing GRUB on your drive +* Booting:: How to boot different operating systems +* Configuration:: Writing your own configuration file +* Network:: Downloading OS images from a network +* Serial terminal:: Using GRUB via a serial line +* Preset Menu:: Embedding a configuration file into GRUB +* Images:: GRUB image files +* Filesystem:: Filesystem syntax and semantics +* Interface:: The menu and the command-line +* Commands:: The list of available builtin commands +* Troubleshooting:: Error messages produced by GRUB +* Invoking the grub shell:: How to use the grub shell +* Invoking grub-install:: How to use the GRUB installer +* Invoking grub-terminfo:: How to generate a terminfo command +* Obtaining and Building GRUB:: How to obtain and build GRUB +* Reporting bugs:: Where you should send a bug report +* Future:: Some future plans on GRUB +* Internals:: Hacking GRUB +* Copying This Manual:: Copying This Manual +* Index:: +@end menu + + +@node Introduction +@chapter Introduction to GRUB + +@menu +* Overview:: What exactly GRUB is and how to use it +* History:: From maggot to house fly +* Features:: GRUB features +* Role of a boot loader:: The role of a boot loader +@end menu + + +@node Overview +@section Overview + +Briefly, a @dfn{boot loader} is the first software program that runs when +a computer starts. It is responsible for loading and transferring +control to an operating system @dfn{kernel} software (such as Linux or +GNU Mach). The kernel, in turn, initializes the rest of the operating +system (e.g. a GNU system). + +GNU GRUB is a very powerful boot loader, which can load a wide variety +of free operating systems, as well as proprietary operating systems with +chain-loading@footnote{@dfn{chain-load} is the mechanism for loading +unsupported operating systems by loading another boot loader. It is +typically used for loading DOS or Windows.}. GRUB is designed to +address the complexity of booting a personal computer; both the +program and this manual are tightly bound to that computer platform, +although porting to other platforms may be addressed in the future. + +One of the important features in GRUB is flexibility; GRUB understands +filesystems and kernel executable formats, so you can load an arbitrary +operating system the way you like, without recording the physical +position of your kernel on the disk. Thus you can load the kernel +just by specifying its file name and the drive and partition where the +kernel resides. + +When booting with GRUB, you can use either a command-line interface +(@pxref{Command-line interface}), or a menu interface (@pxref{Menu +interface}). Using the command-line interface, you type the drive +specification and file name of the kernel manually. In the menu +interface, you just select an OS using the arrow keys. The menu is +based on a configuration file which you prepare beforehand +(@pxref{Configuration}). While in the menu, you can switch to the +command-line mode, and vice-versa. You can even edit menu entries +before using them. + +In the following chapters, you will learn how to specify a drive, a +partition, and a file name (@pxref{Naming convention}) to GRUB, how to +install GRUB on your drive (@pxref{Installation}), and how to boot your +OSes (@pxref{Booting}), step by step. + + +@node History +@section History of GRUB + +GRUB originated in 1995 when Erich Boleyn was trying to boot the GNU +Hurd with the University of Utah's Mach 4 microkernel (now known as GNU +Mach). Erich and Brian Ford designed the Multiboot Specification +(@pxref{Top, Multiboot Specification, Motivation, multiboot, The Multiboot +Specification}), because they were determined not to add to the large +number of mutually-incompatible PC boot methods. + +Erich then began modifying the FreeBSD boot loader so that it would +understand Multiboot. He soon realized that it would be a lot easier +to write his own boot loader from scratch than to keep working on the +FreeBSD boot loader, and so GRUB was born. + +Erich added many features to GRUB, but other priorities prevented him +from keeping up with the demands of its quickly-expanding user base. In +1999, Gordon Matzigkeit and Yoshinori K. Okuji adopted GRUB as an +official GNU package, and opened its development by making the latest +sources available via anonymous CVS. @xref{Obtaining and Building +GRUB}, for more information. + + +@node Features +@section GRUB features + +The primary requirement for GRUB is that it be compliant with the +@dfn{Multiboot Specification}, which is described in @ref{Top, Multiboot +Specification, Motivation, multiboot, The Multiboot Specification}. + +The other goals, listed in approximate order of importance, are: + +@itemize @bullet{} +@item +Basic functions must be straightforward for end-users. + +@item +Rich functionality to support kernel experts and designers. + +@item +Backward compatibility for booting FreeBSD, NetBSD, OpenBSD, and +Linux. Proprietary kernels (such as DOS, Windows NT, and OS/2) are +supported via a chain-loading function. +@end itemize + +Except for specific compatibility modes (chain-loading and the Linux +@dfn{piggyback} format), all kernels will be started in much the same +state as in the Multiboot Specification. Only kernels loaded at 1 megabyte +or above are presently supported. Any attempt to load below that +boundary will simply result in immediate failure and an error message +reporting the problem. + +In addition to the requirements above, GRUB has the following features +(note that the Multiboot Specification doesn't require all the features +that GRUB supports): + +@table @asis +@item Recognize multiple executable formats +Support many of the @dfn{a.out} variants plus @dfn{ELF}. Symbol +tables are also loaded. + +@item Support non-Multiboot kernels +Support many of the various free 32-bit kernels that lack Multiboot +compliance (primarily FreeBSD, NetBSD, OpenBSD, and +Linux). Chain-loading of other boot loaders is also supported. + +@item Load multiples modules +Fully support the Multiboot feature of loading multiple modules. + +@item Load a configuration file +Support a human-readable text configuration file with preset boot +commands. You can also load another configuration file dynamically and +embed a preset configuration file in a GRUB image file. The list of +commands (@pxref{Commands}) are a superset of those supported on the +command-line. An example configuration file is provided in +@ref{Configuration}. + +@item Provide a menu interface +A menu interface listing preset boot commands, with a programmable +timeout, is available. There is no fixed limit on the number of boot +entries, and the current implementation has space for several hundred. + +@item Have a flexible command-line interface +A fairly flexible command-line interface, accessible from the menu, +is available to edit any preset commands, or write a new boot command +set from scratch. If no configuration file is present, GRUB drops to +the command-line. + +The list of commands (@pxref{Commands}) are a subset of those supported +for configuration files. Editing commands closely resembles the Bash +command-line (@pxref{Command Line Editing, Bash, Command Line Editing, +features, Bash Features}), with @key{TAB}-completion of commands, +devices, partitions, and files in a directory depending on context. + +@item Support multiple filesystem types +Support multiple filesystem types transparently, plus a useful explicit +blocklist notation. The currently supported filesystem types are +@dfn{BSD FFS}, @dfn{DOS FAT16 and FAT32}, @dfn{Minix fs}, @dfn{Linux +ext2fs}, @dfn{ReiserFS}, @dfn{JFS}, @dfn{XFS}, and @dfn{VSTa +fs}. @xref{Filesystem}, for more information. + +@item Support automatic decompression +Can decompress files which were compressed by @command{gzip}. This +function is both automatic and transparent to the user (i.e. all +functions operate upon the uncompressed contents of the specified +files). This greatly reduces a file size and loading time, a +particularly great benefit for floppies.@footnote{There are a few +pathological cases where loading a very badly organized ELF kernel might +take longer, but in practice this never happen.} + +It is conceivable that some kernel modules should be loaded in a +compressed state, so a different module-loading command can be specified +to avoid uncompressing the modules. + +@item Access data on any installed device +Support reading data from any or all floppies or hard disk(s) recognized +by the BIOS, independent of the setting of the root device. + +@item Be independent of drive geometry translations +Unlike many other boot loaders, GRUB makes the particular drive +translation irrelevant. A drive installed and running with one +translation may be converted to another translation without any adverse +effects or changes in GRUB's configuration. + +@item Detect all installed @sc{ram} +GRUB can generally find all the installed @sc{ram} on a PC-compatible +machine. It uses an advanced BIOS query technique for finding all +memory regions. As described on the Multiboot Specification (@pxref{Top, +Multiboot Specification, Motivation, multiboot, The Multiboot +Specification}), not all kernels make use of this information, but GRUB +provides it for those who do. + +@item Support Logical Block Address mode +In traditional disk calls (called @dfn{CHS mode}), there is a geometry +translation problem, that is, the BIOS cannot access over 1024 +cylinders, so the accessible space is limited to at least 508 MB and to +at most 8GB. GRUB can't universally solve this problem, as there is no +standard interface used in all machines. However, several newer machines +have the new interface, Logical Block Address (@dfn{LBA}) mode. GRUB +automatically detects if LBA mode is available and uses it if +available. In LBA mode, GRUB can access the entire disk. + +@item Support network booting +GRUB is basically a disk-based boot loader but also has network +support. You can load OS images from a network by using the @dfn{TFTP} +protocol. + +@item Support remote terminals +To support computers with no console, GRUB provides remote terminal +support, so that you can control GRUB from a remote host. Only serial +terminal support is implemented at the moment. +@end table + + +@node Role of a boot loader +@section The role of a boot loader + +The following is a quotation from Gordon Matzigkeit, a GRUB fanatic: + +@quotation +Some people like to acknowledge both the operating system and kernel when +they talk about their computers, so they might say they use +``GNU/Linux'' or ``GNU/Hurd''. Other people seem to think that the +kernel is the most important part of the system, so they like to call +their GNU operating systems ``Linux systems.'' + +I, personally, believe that this is a grave injustice, because the +@emph{boot loader} is the most important software of all. I used to +refer to the above systems as either ``LILO''@footnote{The LInux LOader, +a boot loader that everybody uses, but nobody likes.} or ``GRUB'' +systems. + +Unfortunately, nobody ever understood what I was talking about; now I +just use the word ``GNU'' as a pseudonym for GRUB. + +So, if you ever hear people talking about their alleged ``GNU'' systems, +remember that they are actually paying homage to the best boot loader +around@dots{} GRUB! +@end quotation + +We, the GRUB maintainers, do not (usually) encourage Gordon's level of +fanaticism, but it helps to remember that boot loaders deserve +recognition. We hope that you enjoy using GNU GRUB as much as we did +writing it. + + +@node Naming convention +@chapter Naming convention + +The device syntax used in GRUB is a wee bit different from what you may +have seen before in your operating system(s), and you need to know it so +that you can specify a drive/partition. + +Look at the following examples and explanations: + +@example +(fd0) +@end example + +First of all, GRUB requires that the device name be enclosed with +@samp{(} and @samp{)}. The @samp{fd} part means that it is a floppy +disk. The number @samp{0} is the drive number, which is counted from +@emph{zero}. This expression means that GRUB will use the whole floppy +disk. + +@example +(hd0,1) +@end example + +Here, @samp{hd} means it is a hard disk drive. The first integer +@samp{0} indicates the drive number, that is, the first hard disk, while +the second integer, @samp{1}, indicates the partition number (or the +@sc{pc} slice number in the BSD terminology). Once again, please note +that the partition numbers are counted from @emph{zero}, not from +one. This expression means the second partition of the first hard disk +drive. In this case, GRUB uses one partition of the disk, instead of the +whole disk. + +@example +(hd0,4) +@end example + +This specifies the first @dfn{extended partition} of the first hard disk +drive. Note that the partition numbers for extended partitions are +counted from @samp{4}, regardless of the actual number of primary +partitions on your hard disk. + +@example +(hd1,a) +@end example + +This means the BSD @samp{a} partition of the second hard disk. If you +need to specify which @sc{pc} slice number should be used, use something +like this: @samp{(hd1,0,a)}. If the @sc{pc} slice number is omitted, +GRUB searches for the first @sc{pc} slice which has a BSD @samp{a} +partition. + +Of course, to actually access the disks or partitions with GRUB, you +need to use the device specification in a command, like @samp{root +(fd0)} or @samp{unhide (hd0,2)}. To help you find out which number +specifies a partition you want, the GRUB command-line +(@pxref{Command-line interface}) options have argument +completion. This means that, for example, you only need to type + +@example +root ( +@end example + +followed by a @key{TAB}, and GRUB will display the list of drives, +partitions, or file names. So it should be quite easy to determine the +name of your target partition, even with minimal knowledge of the +syntax. + +Note that GRUB does @emph{not} distinguish IDE from SCSI - it simply +counts the drive numbers from zero, regardless of their type. Normally, +any IDE drive number is less than any SCSI drive number, although that +is not true if you change the boot sequence by swapping IDE and SCSI +drives in your BIOS. + +Now the question is, how to specify a file? Again, consider an +example: + +@example +(hd0,0)/vmlinuz +@end example + +This specifies the file named @samp{vmlinuz}, found on the first +partition of the first hard disk drive. Note that the argument +completion works with file names, too. + +That was easy, admit it. Now read the next chapter, to find out how to +actually install GRUB on your drive. + + +@node Installation +@chapter Installation + +In order to install GRUB as your boot loader, you need to first +install the GRUB system and utilities under your UNIX-like operating +system (@pxref{Obtaining and Building GRUB}). You can do this either +from the source tarball, or as a package for your OS. + +After you have done that, you need to install the boot loader on a +drive (floppy or hard disk). There are two ways of doing that - either +using the utility @command{grub-install} (@pxref{Invoking +grub-install}) on a UNIX-like OS, or by running GRUB itself from a +floppy. These are quite similar, however the utility might probe a +wrong BIOS drive, so you should be careful. + +Also, if you install GRUB on a UNIX-like OS, please make sure that you +have an emergency boot disk ready, so that you can rescue your computer +if, by any chance, your hard drive becomes unusable (unbootable). + +GRUB comes with boot images, which are normally put in the directory +@file{/usr/lib/grub/i386-pc}. Hereafter, the directory where GRUB images are +initially placed (normally @file{/usr/lib/grub/i386-pc}) will be +called the @dfn{image directory}, and the directory where the boot +loader needs to find them (usually @file{/boot/grub}) will be called +the @dfn{boot directory}. + +@menu +* Installing GRUB using grub-install:: +@end menu + + +@node Installing GRUB using grub-install +@section Installing GRUB using grub-install + +@strong{Caution:} This procedure is definitely less safe, because +there are several ways in which your computer can become +unbootable. For example, most operating systems don't tell GRUB how to +map BIOS drives to OS devices correctly---GRUB merely @dfn{guesses} +the mapping. This will succeed in most cases, but not +always. Therefore, GRUB provides you with a map file called the +@dfn{device map}, which you must fix if it is wrong. @xref{Device +map}, for more details. + +If you still do want to install GRUB under a UNIX-like OS (such +as @sc{gnu}), invoke the program @command{grub-install} (@pxref{Invoking +grub-install}) as the superuser (@dfn{root}). + +The usage is basically very simple. You only need to specify one +argument to the program, namely, where to install the boot loader. The +argument can be either a device file (like @samp{/dev/hda}) or a +partition specified in GRUB's notation. For example, under Linux the +following will install GRUB into the MBR of the first IDE disk: + +@example +# @kbd{grub-install /dev/hda} +@end example + +Likewise, under GNU/Hurd, this has the same effect: + +@example +# @kbd{grub-install /dev/hd0} +@end example + +If it is the first BIOS drive, this is the same as well: + +@example +# @kbd{grub-install '(hd0)'} +@end example + +Or you can omit the parentheses: + +@example +# @kbd{grub-install hd0} +@end example + +But all the above examples assume that GRUB should use images under +the root directory. If you want GRUB to use images under a directory +other than the root directory, you need to specify the option +@option{--root-directory}. The typical usage is that you create a GRUB +boot floppy with a filesystem. Here is an example: + +@example +@group +# @kbd{mke2fs /dev/fd0} +# @kbd{mount -t ext2 /dev/fd0 /mnt} +# @kbd{grub-install --root-directory=/mnt fd0} +# @kbd{umount /mnt} +@end group +@end example + +Another example is when you have a separate boot partition +which is mounted at @file{/boot}. Since GRUB is a boot loader, it +doesn't know anything about mountpoints at all. Thus, you need to run +@command{grub-install} like this: + +@example +# @kbd{grub-install --root-directory=/boot /dev/hda} +@end example + +By the way, as noted above, it is quite difficult to guess BIOS drives +correctly under a UNIX-like OS. Thus, @command{grub-install} will prompt +you to check if it could really guess the correct mappings, after the +installation. The format is defined in @ref{Device map}. Please be +quite careful. If the output is wrong, it is unlikely that your +computer will be able to boot with no problem. + +Note that @command{grub-install} is actually just a shell script and the +real task is done by the grub shell @command{grub} (@pxref{Invoking the +grub shell}). Therefore, you may run @command{grub} directly to install +GRUB, without using @command{grub-install}. Don't do that, however, +unless you are very familiar with the internals of GRUB. Installing a +boot loader on a running OS may be extremely dangerous. + + +@node Making a GRUB bootable CD-ROM +@section Making a GRUB bootable CD-ROM + +GRUB supports the @dfn{no emulation mode} in the El Torito +specification@footnote{El Torito is a specification for bootable CD +using BIOS functions.}. This means that you can use the whole CD-ROM +from GRUB and you don't have to make a floppy or hard disk image file, +which can cause compatibility problems. + +For booting from a CD-ROM, GRUB uses a special Stage 2 called +@file{stage2_eltorito}. The only GRUB files you need to have in your +bootable CD-ROM are this @file{stage2_eltorito} and optionally a config file +@file{menu.lst}. You don't need to use @file{stage1} or @file{stage2}, +because El Torito is quite different from the standard boot process. + +Here is an example of procedures to make a bootable CD-ROM +image. First, make a top directory for the bootable image, say, +@samp{iso}: + +@example +$ @kbd{mkdir iso} +@end example + +Make a directory for GRUB: + +@example +$ @kbd{mkdir -p iso/boot/grub} +@end example + +Copy the file @file{stage2_eltorito}: + +@example +$ @kbd{cp /usr/lib/grub/i386-pc/stage2_eltorito iso/boot/grub} +@end example + +If desired, make the config file @file{menu.lst} under @file{iso/boot/grub} +(@pxref{Configuration}), and copy any files and directories for the disc to the +directory @file{iso/}. + +Finally, make a ISO9660 image file like this: + +@example +$ @kbd{mkisofs -R -b boot/grub/stage2_eltorito -no-emul-boot \ + -boot-load-size 4 -boot-info-table -o grub.iso iso} +@end example + +This produces a file named @file{grub.iso}, which then can be burned +into a CD (or a DVD). @kbd{mkisofs} has already set up the disc to boot +from the @kbd{boot/grub/stage2_eltorito} file, so there is no need to +setup GRUB on the disc. (Note that the @kbd{-boot-load-size 4} bit is +required for compatibility with the BIOS on many older machines.) + +You can use the device @samp{(cd)} to access a CD-ROM in your +config file. This is not required; GRUB automatically sets the root device +to @samp{(cd)} when booted from a CD-ROM. It is only necessary to refer to +@samp{(cd)} if you want to access other drives as well. + + +@node Booting +@chapter Booting + +GRUB can load Multiboot-compliant kernels in a consistent way, +but for some free operating systems you need to use some OS-specific +magic. + +@menu +* General boot methods:: How to boot OSes with GRUB generally +* OS-specific notes:: Notes on some operating systems +@end menu + + +@node General boot methods +@section How to boot operating systems + +GRUB has two distinct boot methods. One of the two is to load an +operating system directly, and the other is to chain-load another boot +loader which then will load an operating system actually. Generally +speaking, the former is more desirable, because you don't need to +install or maintain other boot loaders and GRUB is flexible enough to +load an operating system from an arbitrary disk/partition. However, +the latter is sometimes required, since GRUB doesn't support all the +existing operating systems natively. + +@menu +* Loading an operating system directly:: +* Chain-loading:: +@end menu + + +@node Loading an operating system directly +@subsection How to boot an OS directly with GRUB + +Multiboot (@pxref{Top, Multiboot Specification, Motivation, multiboot, +The Multiboot Specification}) is the native format supported by GRUB. +For the sake of convenience, there is also support for Linux, FreeBSD, +NetBSD and OpenBSD. If you want to boot other operating systems, you +will have to chain-load them (@pxref{Chain-loading}). + +FIXME: this section is incomplete. + +@enumerate +@item +Run the command @command{boot} (@pxref{boot}). +@end enumerate + +However, DOS and Windows have some deficiencies, so you might have to +use more complicated instructions. @xref{DOS/Windows}, for more +information. + + +@node OS-specific notes +@section Some caveats on OS-specific issues + +Here, we describe some caveats on several operating systems. + +@menu +* GNU/Hurd:: +* GNU/Linux:: +@end menu + + +@node GNU/Hurd +@subsection GNU/Hurd + +Since GNU/Hurd is Multiboot-compliant, it is easy to boot it; there is +nothing special about it. But do not forget that you have to specify a +root partition to the kernel. + +FIXME: this section is incomplete. + +@enumerate +@item +Run the command @command{boot} (@pxref{boot}). +@end enumerate + + +@node GNU/Linux +@subsection GNU/Linux + +It is relatively easy to boot GNU/Linux from GRUB, because it somewhat +resembles to boot a Multiboot-compliant OS. + +FIXME: this section is incomplete. + +@enumerate +@item +Set GRUB's root device to the same drive as GNU/Linux's. + +@item +Finally, run the command @command{boot} (@pxref{boot}). +@end enumerate + +@strong{Caution:} If you use an initrd and specify the @samp{mem=} +option to the kernel to let it use less than actual memory size, you +will also have to specify the same memory size to GRUB. To let GRUB know +the size, run the command @command{uppermem} @emph{before} loading the +kernel. @xref{uppermem}, for more information. + + +@node Serial terminal +@chapter Using GRUB via a serial line + +This chapter describes how to use the serial terminal support in GRUB. + +If you have many computers or computers with no display/keyboard, it +could be very useful to control the computers through serial +communications. To connect one computer with another via a serial line, +you need to prepare a null-modem (cross) serial cable, and you may need +to have multiport serial boards, if your computer doesn't have extra +serial ports. In addition, a terminal emulator is also required, such as +minicom. Refer to a manual of your operating system, for more +information. + +As for GRUB, the instruction to set up a serial terminal is quite +simple. First of all, make sure that you haven't specified the option +@option{--disable-serial} to the configure script when you built your +GRUB images. If you get them in binary form, probably they have serial +terminal support already. + +Then, initialize your serial terminal after GRUB starts up. Here is an +example: + +@example +@group +grub> @kbd{serial --unit=0 --speed=9600} +grub> @kbd{terminal serial} +@end group +@end example + +The command @command{serial} initializes the serial unit 0 with the +speed 9600bps. The serial unit 0 is usually called @samp{COM1}, so, if +you want to use COM2, you must specify @samp{--unit=1} instead. This +command accepts many other options, so please refer to @ref{serial}, +for more details. + +The command @command{terminal} (@pxref{terminal}) chooses which type of +terminal you want to use. In the case above, the terminal will be a +serial terminal, but you can also pass @code{console} to the command, +as @samp{terminal serial console}. In this case, a terminal in which +you press any key will be selected as a GRUB terminal. + +However, note that GRUB assumes that your terminal emulator is +compatible with VT100 by default. This is true for most terminal +emulators nowadays, but you should pass the option @option{--dumb} to +the command if your terminal emulator is not VT100-compatible or +implements few VT100 escape sequences. If you specify this option then +GRUB provides you with an alternative menu interface, because the normal +menu requires several fancy features of your terminal. + + +@node Filesystem +@chapter Filesystem syntax and semantics + +GRUB uses a special syntax for specifying disk drives which can be +accessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish +between IDE, ESDI, SCSI, or others. You must know yourself which BIOS +device is equivalent to which OS device. Normally, that will be clear if +you see the files in a device or use the command @command{find} +(@pxref{find}). + +@menu +* Device syntax:: How to specify devices +* File name syntax:: How to specify files +* Block list syntax:: How to specify block lists +@end menu + + +@node Device syntax +@section How to specify devices + +The device syntax is like this: + +@example +@code{(@var{device}[,@var{part-num}][,@var{bsd-subpart-letter}])} +@end example + +@samp{[]} means the parameter is optional. @var{device} should be +either @samp{fd} or @samp{hd} followed by a digit, like @samp{fd0}. +But you can also set @var{device} to a hexadecimal or a decimal number +which is a BIOS drive number, so the following are equivalent: + +@example +(hd0) +(0x80) +(128) +@end example + +@var{part-num} represents the partition number of @var{device}, starting +from zero for primary partitions and from four for extended partitions, +and @var{bsd-subpart-letter} represents the BSD disklabel subpartition, +such as @samp{a} or @samp{e}. + +A shortcut for specifying BSD subpartitions is +@code{(@var{device},@var{bsd-subpart-letter})}, in this case, GRUB +searches for the first PC partition containing a BSD disklabel, then +finds the subpartition @var{bsd-subpart-letter}. Here is an example: + +@example +(hd0,a) +@end example + +The syntax @samp{(hd0)} represents using the entire disk (or the +MBR when installing GRUB), while the syntax @samp{(hd0,0)} +represents using the first partition of the disk (or the boot sector +of the partition when installing GRUB). + +If you enabled the network support, the special drive, @samp{(nd)}, is +also available. Before using the network drive, you must initialize the +network. @xref{Network}, for more information. + +If you boot GRUB from a CD-ROM, @samp{(cd)} is available. @xref{Making +a GRUB bootable CD-ROM}, for details. + + +@node File name syntax +@section How to specify files + +There are two ways to specify files, by @dfn{absolute file name} and by +@dfn{block list}. + +An absolute file name resembles a Unix absolute file name, using +@samp{/} for the directory separator (not @samp{\} as in DOS). One +example is @samp{(hd0,0)/boot/grub/menu.lst}. This means the file +@file{/boot/grub/menu.lst} in the first partition of the first hard +disk. If you omit the device name in an absolute file name, GRUB uses +GRUB's @dfn{root device} implicitly. So if you set the root device to, +say, @samp{(hd1,0)} by the command @command{root} (@pxref{root}), then +@code{/boot/kernel} is the same as @code{(hd1,0)/boot/kernel}. + + +@node Block list syntax +@section How to specify block lists + +A block list is used for specifying a file that doesn't appear in the +filesystem, like a chainloader. The syntax is +@code{[@var{offset}]+@var{length}[,[@var{offset}]+@var{length}]@dots{}}. +Here is an example: + +@example +@code{0+100,200+1,300+300} +@end example + +This represents that GRUB should read blocks 0 through 99, block 200, +and blocks 300 through 599. If you omit an offset, then GRUB assumes +the offset is zero. + +Like the file name syntax (@pxref{File name syntax}), if a blocklist +does not contain a device name, then GRUB uses GRUB's @dfn{root +device}. So @code{(hd0,1)+1} is the same as @code{+1} when the root +device is @samp{(hd0,1)}. + + +@node Interface +@chapter GRUB's user interface + +GRUB has both a simple menu interface for choosing preset entries from a +configuration file, and a highly flexible command-line for performing +any desired combination of boot commands. + +GRUB looks for its configuration file as soon as it is loaded. If one +is found, then the full menu interface is activated using whatever +entries were found in the file. If you choose the @dfn{command-line} menu +option, or if the configuration file was not found, then GRUB drops to +the command-line interface. + +@menu +* Command-line interface:: The flexible command-line interface +* Menu interface:: The simple menu interface +@end menu + + +@node Command-line interface +@section The flexible command-line interface + +The command-line interface provides a prompt and after it an editable +text area much like a command-line in Unix or DOS. Each command is +immediately executed after it is entered@footnote{However, this +behavior will be changed in the future version, in a user-invisible +way.}. The commands (@pxref{Command-line and menu entry commands}) are a +subset of those available in the configuration file, used with exactly +the same syntax. + +Cursor movement and editing of the text on the line can be done via a +subset of the functions available in the Bash shell: + +@table @key +@item C-f +@itemx PC right key +Move forward one character. + +@item C-b +@itemx PC left key +Move back one character. + +@item C-a +@itemx HOME +Move to the start of the line. + +@item C-e +@itemx END +Move the the end of the line. + +@item C-d +@itemx DEL +Delete the character underneath the cursor. + +@item C-h +@itemx BS +Delete the character to the left of the cursor. + +@item C-k +Kill the text from the current cursor position to the end of the line. + +@item C-u +Kill backward from the cursor to the beginning of the line. + +@item C-y +Yank the killed text back into the buffer at the cursor. + +@item C-p +@itemx PC up key +Move up through the history list. + +@item C-n +@itemx PC down key +Move down through the history list. +@end table + +When typing commands interactively, if the cursor is within or before +the first word in the command-line, pressing the @key{TAB} key (or +@key{C-i}) will display a listing of the available commands, and if the +cursor is after the first word, the @kbd{@key{TAB}} will provide a +completion listing of disks, partitions, and file names depending on the +context. Note that to obtain a list of drives, one must open a +parenthesis, as @command{root (}. + +Note that you cannot use the completion functionality in the TFTP +filesystem. This is because TFTP doesn't support file name listing for +the security. + + +@node Menu interface +@section The simple menu interface + +The menu interface is quite easy to use. Its commands are both +reasonably intuitive and described on screen. + +Basically, the menu interface provides a list of @dfn{boot entries} to +the user to choose from. Use the arrow keys to select the entry of +choice, then press @key{RET} to run it. An optional timeout is +available to boot the default entry (the first one if not set), which is +aborted by pressing any key. + +Commands are available to enter a bare command-line by pressing @key{c} +(which operates exactly like the non-config-file version of GRUB, but +allows one to return to the menu if desired by pressing @key{ESC}) or to +edit any of the @dfn{boot entries} by pressing @key{e}. + +If you protect the menu interface with a password (@pxref{Security}), +all you can do is choose an entry by pressing @key{RET}, or press +@key{p} to enter the password. + + +@node Menu entry editor +@section Editing a menu entry + +The menu entry editor looks much like the main menu interface, but the +lines in the menu are individual commands in the selected entry instead +of entry names. + +If an @key{ESC} is pressed in the editor, it aborts all the changes made +to the configuration entry and returns to the main menu interface. + +When a particular line is selected, the editor places the user in a +special version of the GRUB command-line to edit that line. When the +user hits @key{RET}, GRUB replaces the line in question in the boot +entry with the changes (unless it was aborted via @key{ESC}, +in which case the changes are thrown away). + +If you want to add a new line to the menu entry, press @key{o} if adding +a line after the current line or press @key{O} if before the current +line. + +To delete a line, hit the key @key{d}. Although GRUB unfortunately +does not support @dfn{undo}, you can do almost the same thing by just +returning to the main menu. + + +@node Commands +@chapter The list of available commands + +In this chapter, we list all commands that are available in GRUB. + +Commands belong to different groups. A few can only be used in +the global section of the configuration file (or ``menu''); most +of them can be entered on the command-line and can be used either +anywhere in the menu or specifically in the menu entries. + +@menu +* Menu-specific commands:: +* General commands:: +* Command-line and menu entry commands:: +@end menu + + +@node Menu-specific commands +@section The list of commands for the menu only + +The semantics used in parsing the configuration file are the following: + +@itemize @bullet +@item +The menu-specific commands have to be used before any others. + +@item +The files @emph{must} be in plain-text format. + +@item +@samp{#} at the beginning of a line in a configuration file means it is +only a comment. + +@item +Options are separated by spaces. + +@item +All numbers can be either decimal or hexadecimal. A hexadecimal number +must be preceded by @samp{0x}, and is case-insensitive. + +@item +Extra options or text at the end of the line are ignored unless otherwise +specified. + +@item +Unrecognized commands are added to the current entry, except before entries +start, where they are ignored. +@end itemize + +These commands can only be used in the menu: + +@menu +* menuentry:: Start a menu entry +@end menu + + +@node menuentry +@subsection menuentry + +@deffn Command title name @dots{} +Start a new boot entry, and set its name to the contents of the rest of +the line, starting with the first non-space character. +@end deffn + + +@node General commands +@section The list of general commands + +Commands usable anywhere in the menu and in the command-line. + +@menu +* serial:: Set up a serial device +* terminfo:: Define escape sequences for a terminal +@end menu + + +@node serial +@subsection serial + +@deffn Command serial [@option{--unit=unit}] [@option{--port=port}] [@option{--speed=speed}] [@option{--word=word}] [@option{--parity=parity}] [@option{--stop=stop}] [@option{--device=dev}] +Initialize a serial device. @var{unit} is a number in the range 0-3 +specifying which serial port to use; default is 0, which corresponds to +the port often called COM1. @var{port} is the I/O port where the UART +is to be found; if specified it takes precedence over @var{unit}. +@var{speed} is the transmission speed; default is 9600. @var{word} and +@var{stop} are the number of data bits and stop bits. Data bits must +be in the range 5-8 and stop bits must be 1 or 2. Default is 8 data +bits and one stop bit. @var{parity} is one of @samp{no}, @samp{odd}, +@samp{even} and defaults to @samp{no}. The option @option{--device} +can only be used in the grub shell and is used to specify the +tty device to be used in the host operating system (@pxref{Invoking the +grub shell}). + +The serial port is not used as a communication channel unless the +@command{terminal} command is used (@pxref{terminal}). + +This command is only available if GRUB is compiled with serial +support. See also @ref{Serial terminal}. +@end deffn + + +@node terminfo +@subsection terminfo + +@deffn Command terminfo @option{--name=name} @option{--cursor-address=seq} [@option{--clear-screen=seq}] [@option{--enter-standout-mode=seq}] [@option{--exit-standout-mode=seq}] +Define the capabilities of your terminal. Use this command to define +escape sequences, if it is not vt100-compatible. You may use @samp{\e} +for @key{ESC} and @samp{^X} for a control character. + +You can use the utility @command{grub-terminfo} to generate +appropriate arguments to this command. @xref{Invoking grub-terminfo}. + +If no option is specified, the current settings are printed. +@end deffn + + +@node Command-line and menu entry commands +@section The list of command-line and menu entry commands + +These commands are usable in the command-line and in menu entries. If +you forget a command, you can run the command @command{help} +(@pxref{help}). + +@menu +* boot:: Start up your operating system +* cat:: Show the contents of a file +* chainloader:: Chain-load another boot loader +* cmp:: Compare two files +* configfile:: Load a configuration file +* halt:: Shut down your computer +* help:: Show help messages +* reboot:: Reboot your computer +@end menu + + +@node boot +@subsection boot + +@deffn Command boot +Boot the OS or chain-loader which has been loaded. Only necessary if +running the fully interactive command-line (it is implicit at the end of +a menu entry). +@end deffn + + +@node cat +@subsection cat + +@deffn Command cat file +Display the contents of the file @var{file}. This command may be useful +to remind you of your OS's root partition: + +@example +grub> @kbd{cat /etc/fstab} +@end example +@end deffn + + +@node chainloader +@subsection chainloader + +@deffn Command chainloader [@option{--force}] file +Load @var{file} as a chain-loader. Like any other file loaded by the +filesystem code, it can use the blocklist notation to grab the first +sector of the current partition with @samp{+1}. If you specify the +option @option{--force}, then load @var{file} forcibly, whether it has a +correct signature or not. This is required when you want to load a +defective boot loader, such as SCO UnixWare 7.1 (@pxref{SCO UnixWare}). +@end deffn + + +@node cmp +@subsection cmp + +@deffn Command cmp file1 file2 +Compare the file @var{file1} with the file @var{file2}. If they differ +in size, print the sizes like this: + +@example +Differ in size: 0x1234 [foo], 0x4321 [bar] +@end example + +If the sizes are equal but the bytes at an offset differ, then print the +bytes like this: + +@example +Differ at the offset 777: 0xbe [foo], 0xef [bar] +@end example + +If they are completely identical, nothing will be printed. +@end deffn + + +@node configfile +@subsection configfile + +@deffn Command configfile file +Load @var{file} as a configuration file. +@end deffn + + +@node halt +@subsection halt + +@deffn Command halt @option{--no-apm} +The command halts the computer. If the @option{--no-apm} option +is specified, no APM BIOS call is performed. Otherwise, the computer +is shut down using APM. +@end deffn + + +@node help +@subsection help + +@deffn Command help @option{--all} [pattern @dots{}] +Display helpful information about builtin commands. If you do not +specify @var{pattern}, this command shows short descriptions of most of +available commands. If you specify the option @option{--all} to this +command, short descriptions of rarely used commands (such as +@ref{testload}) are displayed as well. + +If you specify any @var{patterns}, it displays longer information +about each of the commands which match those @var{patterns}. +@end deffn + + +@node reboot +@subsection reboot + +@deffn Command reboot +Reboot the computer. +@end deffn + + +@node Invoking grub-install +@chapter Invoking grub-install + +The program @command{grub-install} installs GRUB on your drive using the +grub shell (@pxref{Invoking the grub shell}). You must specify the +device name on which you want to install GRUB, like this: + +@example +grub-install @var{install_device} +@end example + +The device name @var{install_device} is an OS device name or a GRUB +device name. + +@command{grub-install} accepts the following options: + +@table @option +@item --help +Print a summary of the command-line options and exit. + +@item --version +Print the version number of GRUB and exit. + +@item --root-directory=@var{dir} +Install GRUB images under the directory @var{dir} instead of the root +directory. This option is useful when you want to install GRUB into a +separate partition or a removable disk. Here is an example in which +you have a separate @dfn{boot} partition which is mounted on +@file{/boot}: + +@example +@kbd{grub-install --root-directory=/boot hd0} +@end example + +@item --recheck +Recheck the device map, even if @file{/boot/grub/device.map} already +exists. You should use this option whenever you add/remove a disk +into/from your computer. +@end table + + +@node Obtaining and Building GRUB +@appendix How to obtain and build GRUB + +@quotation +@strong{Caution:} GRUB requires binutils-2.9.1.0.23 or later because the +GNU assembler has been changed so that it can produce real 16bits +machine code between 2.9.1 and 2.9.1.0.x. See +@uref{http://sources.redhat.com/binutils/}, to obtain information on +how to get the latest version. +@end quotation + +GRUB is available from the GNU alpha archive site +@uref{ftp://alpha.gnu.org/gnu/grub} or any of its mirrors. The file +will be named grub-version.tar.gz. The current version is +@value{VERSION}, so the file you should grab is: + +@uref{ftp://alpha.gnu.org/gnu/grub/grub-@value{VERSION}.tar.gz} + +To unbundle GRUB use the instruction: + +@example +@kbd{zcat grub-@value{VERSION}.tar.gz | tar xvf -} +@end example + +which will create a directory called @file{grub-@value{VERSION}} with +all the sources. You can look at the file @file{INSTALL} for detailed +instructions on how to build and install GRUB, but you should be able to +just do: + +@example +@group +@kbd{cd grub-@value{VERSION}} +@kbd{./configure} +@kbd{make install} +@end group +@end example + +Also, the latest version is available from the SVN. See +@uref{http://savannah.gnu.org/svn/?group=grub} for more information. + +@node Reporting bugs +@appendix Reporting bugs + +These are the guideline for how to report bugs. Take a look at this +list below before you submit bugs: + +@enumerate +@item +Before getting unsettled, read this manual through and through. Also, +see the @uref{http://www.gnu.org/software/grub/grub-faq.html, GNU GRUB FAQ}. + +@item +Always mention the information on your GRUB. The version number and the +configuration are quite important. If you build it yourself, write the +options specified to the configure script and your operating system, +including the versions of gcc and binutils. + +@item +If you have trouble with the installation, inform us of how you +installed GRUB. Don't omit error messages, if any. Just @samp{GRUB hangs +up when it boots} is not enough. + +The information on your hardware is also essential. These are especially +important: the geometries and the partition tables of your hard disk +drives and your BIOS. + +@item +If GRUB cannot boot your operating system, write down +@emph{everything} you see on the screen. Don't paraphrase them, like +@samp{The foo OS crashes with GRUB, even though it can boot with the +bar boot loader just fine}. Mention the commands you executed, the +messages printed by them, and information on your operating system +including the version number. + +@item +Explain what you wanted to do. It is very useful to know your purpose +and your wish, and how GRUB didn't satisfy you. + +@item +If you can investigate the problem yourself, please do. That will give +you and us much more information on the problem. Attaching a patch is +even better. + +When you attach a patch, make the patch in unified diff format, and +write ChangeLog entries. But, even when you make a patch, don't forget +to explain the problem, so that we can understand what your patch is +for. + +@item +Write down anything that you think might be related. Please understand +that we often need to reproduce the same problem you encounterred in our +environment. So your information should be sufficient for us to do the +same thing---Don't forget that we cannot see your computer directly. If +you are not sure whether to state a fact or leave it out, state it! +Reporting too many things is much better than omitting something +important. +@end enumerate + +If you follow the guideline above, submit a report to the +@uref{http://savannah.gnu.org/bugs/?group=grub, Bug Tracking System}. +Alternatively, you can submit a report via electronic mail to +@email{bug-grub@@gnu.org}, but we strongly recommend that you use the +Bug Tracking System, because e-mail can be passed over easily. + +Once we get your report, we will try to fix the bugs. + + +@node Future +@appendix Where GRUB will go + +We started the next generation of GRUB, GRUB 2. GRUB 2 includes +internationalization, dynamic module loading, real memory management, +multiple architecture support, a scripting language, and many other +nice feature. If you are interested in the development of GRUB 2, take +a look at @uref{http://www.gnu.org/software/grub/grub.html, the +homepage}. + + + +@node Copying This Manual +@appendix Copying This Manual + +@menu +* GNU Free Documentation License:: License for copying this manual. +@end menu + +@include fdl.texi + + +@node Index +@unnumbered Index + +@c Currently, we use only the Concept Index. +@printindex cp + + +@bye + +Some notes: + + This is an attempt to make a manual for GRUB 2. The contents are + copied from the GRUB manual in GRUB Legacy, so they are not always + appropriate yet for GRUB 2. -- 2.11.4.GIT