From 006737bcc65def6292ba06a8651447a29ea8a12f Mon Sep 17 00:00:00 2001 From: okuji Date: Tue, 16 Jan 2001 07:27:44 +0000 Subject: [PATCH] start the second attempt to rewrite the manual. --- docs/grub-new.texi | 3695 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 3695 insertions(+) create mode 100644 docs/grub-new.texi diff --git a/docs/grub-new.texi b/docs/grub-new.texi new file mode 100644 index 000000000..af31e5be9 --- /dev/null +++ b/docs/grub-new.texi @@ -0,0 +1,3695 @@ +\input texinfo +@c -*-texinfo-*- +@c %**start of header +@setfilename grub-new.info +@settitle GRUB Manual +@c %**end of header + +@include version.texi + +@c Unify all our little indices for now. +@syncodeindex fn cp +@syncodeindex vr cp +@syncodeindex ky cp +@syncodeindex pg cp +@syncodeindex tp cp + +@footnotestyle separate +@paragraphindent 3 +@finalout + +@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 +* mbchk: (grub)Invoking mbchk. Check for the format of a Multiboot kernel +@end direntry + +@setchapternewpage off + +@ifinfo +Copyright @copyright{} 1996 Erich Boleyn +Copyright @copyright{} 1999, 2000, 2001 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries a copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ifinfo + +@titlepage +@sp 10 +@title the GRUB manual +@subtitle The GRand Unified Bootloader, version @value{VERSION}, @value{UPDATED}. +@author Gordon Matzigkeit +@author OKUJI Yoshinori +@c The following two commands start the copyright page. +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1996 Erich Boleyn +Copyright @copyright{} 1999, 2000, 2001 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by Free Software Foundation. +@end titlepage + +@finalout +@headings double + +@ifnottex +@node Top +@top Using GRUB + +This is the documentation of GNU GRUB, the GRand Unified Bootloader, +a flexible and powerful boot loader program for @sc{pc}s. + +This edition documents version @value{VERSION}. +@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 +* 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 mbchk:: How to use the Multiboot checker +* FAQ:: Frequently asked questions +* 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 +* Index:: +@end menu + + +@node Introduction +@chapter Introduction to GRUB + +This manual documents the user-visible aspect of GRUB. If you are +looking for the information on the internals, @xref{Top, , Hacking GRUB, +grub-internals, the GRUB internals}. + +@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 the Linux +or GNU Hurd kernel). 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 the partition) where the kernel resides. To let GRUB know the +drive and the file name, you can either type in them manually via the +command-line interface (@pxref{Command-line interface}), or use the nice +menu interface (@pxref{Menu interface}) through which you can easily +select which OS it boots. To allow you to customize the menu, GRUB will +load a preexisting configuration file (@pxref{Configuration}). Note that +you can not only enter the command-line interface whenever you like, but +also you can edit specific menu entries prior to using them. + +In the following chapters, you will learn how to specify a drive or 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 OKUJI Yoshinori 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 the 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}, and @dfn{ReiserFS}. @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 the loading time, a +particularly major 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 floppy 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 is 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 is a +partition you want, the GRUB command-line (@pxref{Command-line +interface}) options have argument completion. That means that, for +example, you only need to type @samp{root (}, 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, see this 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. Do read the next chapter, to find out how to +actually install GRUB on your drive. + + +@node Installation +@chapter Installation + +First, you need to have GRUB itself properly installed on your system, +(@pxref{Obtaining and Building GRUB}) either from the source tarball, or +as a package for your OS. + +To use GRUB, you need to install it on your drive. 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 using the +native Stage 2. These are quite similar, however, the utility might +probe a wrong BIOS drive, so better 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 installed in the +directory @file{/usr/share/grub/i386-pc}. You need to copy the files +@file{stage1}, @file{stage2}, and @file{*stage1_5} to the directory +@file{/boot/grub}. Here the directory where GRUB images are installed +and the directory where GRUB will use to find them are called @dfn{image +directory} and @dfn{boot directory}, respectively. + +@menu +* Creating a GRUB boot floppy:: +* Installing GRUB natively:: +* Installing GRUB using grub-install:: +@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/share/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 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 the GRUB boot disk, and +reboot your computer with it. Otherwise, see @ref{Installing GRUB using +grub-install}, for more details. + +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 +boot directory, like this: + +@example +grub> @kbd{root (hd0,0)} +@end example + +If you are not sure which partition actually holds these files, 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 GRUB on the MBR in the first drive. If you +want to install GRUB into the @dfn{boot sector} of a partition instead +of the MBR, specify a 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. + +Now you can boot GRUB without a 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 deprecated, because there +are several posibilities that your computer can be 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. So GRUB provides you with a +user-defined map file called @dfn{device map}, which you must fix, if it +is wrong. @xref{Device map}, for more details. + +Unfortunately, if you 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 easy. You only need to specify one argument +to the program, namely, where to install GRUB. The argument can be +either of a device file or a GRUB's drive/partition. So, this will +install GRUB into the MBR of the first IDE disk under Linux: + +@example +# @kbd{grub-install /dev/hda} +@end example + +Likewise, under 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 + +But all the above examples assume that you use GRUB 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 in case that 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 +careful enough. If the output is wrong, it is unlikely that your +computer can 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 Booting +@chapter Booting + +For Multiboot-compliant kernels, GRUB can load them 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 genenerally +* 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 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 are 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 by +the command @command{root} (@pxref{root}). + +@item +Load the kernel image by 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 can load a kernel image by 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 the 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 by 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 by 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:: +@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 the 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}), it +ignores the partition. If GRUB @dfn{unhide}s a DOS (or Windows) +partition (@pxref{unhide}), it detects the partition. Thus, if you have +installed DOS (or Windows) on the first partition and the second of the +first hard disk, and boot the first copy, 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 Configuration +@chapter Configuration + +You 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 @pxref{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 in there. + +@example +@group +# For booting the 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 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 +(@pxref{Command-line and menu commands}). GRUB has several such +commands, see the user reference. + +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 deprecated, 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 conjugation 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 from the network actually. + +GRUB provides two second stage images, @file{nbgrub} and +@file{pxegrub} (@pxref{Images}). Those 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 a NBI loader such as Etherboot, use +@file{nbgrub}. There is no difference between them but their formats. As +how 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. This below is an +example about 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="/tftpboot/menu.lst.foo": +@end group +@end example + +See the manual about your BOOTP/DHCP server, for more information. The +exact syntax should differ from the example, more or less. + + +@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 +would be very useful to control the computers with serial +communications. To connect a 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 that case above, the terminal will be a +serial terminal, but you can also pass @code{console} to the command, +like @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 the option, then +GRUB doesn't provide you with the menu interface, because the menu +requires several fancy features for your terminal. Instead, GRUB only +gives you the hidden menu interface and the command-line interface +(@pxref{Interface}). + + +@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 to modify its configuration +and run arbitrary commands at run-time. For example, the user can read +even @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 @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 a 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}, and two network boot images. Here is a short +overview of them. @xref{Top, , Hacking GRUB, grub-internals, the GRUB +internals}, for more details. + +@table @file +@item stage1 +This is an essential image used for booting up GRUB. Usually, this is +embedded in a 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. This does all things but booting up +itself. Usually, this is put in a filesystem, but that is not required. + +@item e2fs_stage1_5 +@itemx ffs_stage1_5 +@itemx reiserfs_stage1_5 +@itemx fat_stage1_5 +@itemx minix_stage1_5 + +These are called @dfn{Stage 1.5}, because the purpose is 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 but the latter does an filesystem +(e.g. @file{e2fs_stage1_5} understands ext2fs). So you can move the +location of Stage 2 to another 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 a MBR, +or the boot loader area of a ReiserFS or a FFS. + +@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 this 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, 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 like @samp{(hd0)} represents using the entire disk (or the +MBR when installing GRUB), while the syntax like @samp{(hd0,0)} +represents using the 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. + + +@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 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 at 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 does not support +@dfn{undo} unfortunately, 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 of hiding 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 either used +in the menu or in the menu entries. + +@menu +* Menu-specific commands:: +* Command-line and menu 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 is 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 anything, 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. +@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 Command-line and menu commands +@section The list of command-line and menu commands + +Commands usable both 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 +* 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 +* tftpserver:: Specify a TFTP server +* unhide:: Unhide a partition +@end menu + + +@node bootp +@subsection bootp + +@deffn Command bootp +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}. +@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 +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}. +@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 partnew +@subsection partnew + +@deffn Command partnew part type from to +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} and +@var{to} are the starting and ending sectors, expressed as an absolute +sector number. +@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 continueing. 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, that corresponds +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 are 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, 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{--timeout=secs}] [@option{console}] [@option{serial}] +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}. +@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 in 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}. + +@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/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 of 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 the +cylinders, the one of the heads, the one of the sectors and the one of +the 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 [pattern @dots{}] +Display helpful information about builtin commands. If you do not +specify @var{pattern}, this command shows short descriptions of all +available commands. 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. +@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 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 have +to specify the option @option{d}, whether your Stage2 resides at the +booting drive or not, if you have such a BIOS unfortunately. We know +these are defective in that: + +@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{Top, , +Hacking GRUB, grub-internals, the GRUB 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. +@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 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 that 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 +Save the current menu entry 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. See also @ref{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 +compares 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 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 s 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 is pointed to incompatible +or corrupt versions of the stage1 or stage2. It can't detect corruption +in general, but this is a sanity check on the version numbers, which +should be correct. + +@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 likely 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. Similar to the above error, it only makes sense in that +case anyway. + +@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 location 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 into 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. +@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 fix 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 curses interface 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 any +activity is not being done on it during running the command +@command{grub}. + +@item +Reboot your operating system as soon as possible. Probably that is not +required if you follow these 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, which syntax is the same as the one in GRUB +(@pxref{Device syntax}), and @var{file} is an OS's 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 mistakes the order. + +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 by 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 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 when 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{Command-line and menu commands}). + +@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 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 FAQ +@appendix Frequently asked questions + +@table @asis +@item How does GNU GRUB differ from Erich's original GRUB? + +GNU GRUB is the successor of Erich's great GRUB. He couldn't work on +GRUB because of some other tasks, so the current maintainers OKUJI +Yoshinori and Gordon Matzigkeit took over the maintainership, and opened +the development in order for everybody to participate it. + +Technically speaking, GNU GRUB has many features that are not seen in +the original GRUB. For example, GNU GRUB can be installed on UNIX-like +operating system (such as GNU/Hurd) via the grub shell +@file{/sbin/grub} (or @file{/usr/sbin/grub} on older systems), it +supports Logical Block Address (LBA) mode that solves the 1024 cylinders +problem, and @kbd{@key{TAB}} completes a file name when it's unique. Of +course, many bug fixes are done as well, so it is recommended to use GNU +GRUB. + +@item Can GRUB boot my operating system from over 8GB hard disks? + +That depends on your BIOS and your operating system. You must make +sure that your drive is accessible in LBA mode. Generally, that is +configurable in BIOS setting utility. Read the manual for your BIOS +for more information. + +Furthermore, some operating systems (i.e. DOS) cannot access any large +disk, so the problem is not solved by any kind of boot loader. GNU/Hurd +and GNU/Linux can surely boot from such a large disk. + +@item Can I put Stage2 into a partition which is over 1024 cylinders? + +Yes, if your BIOS supports the LBA mode. + +@item How to create a GRUB boot floppy with the menu interface? + +The easiest way is: + +@enumerate +@item +Create filesystem in your floppy disk. For example: + +@example +$ mke2fs /dev/fd0 +@end example + +@item +Mount it on somewhere, say, @file{/mnt}. + +@item +Copy the GRUB images to @file{/mnt/boot/grub}. Only @file{stage1}, +@file{stage2} and @file{menu.lst} are necessary. You may not copy +@dfn{stage1.5}s. + +@item +Run the following command (substitute @file{/usr/sbin/grub} for +@file{/sbin/grub} if you are using an older system): + +@example +@group +$ /sbin/grub --batch <&1 | grep "GNU ld"} +@end example + +If this is not identical with the result above, you should specify the +directory where you have installed binutils for the script configure, +like this: + +@example +@kbd{./configure --with-binutils=/usr/local/bin} +@end example + +If you follow the instructions above but GRUB still crashes, probably +there is a serious bug in GRUB. @xref{Reporting bugs}. + +@item GRUB hangs up when accessing my SCSI disk. + +Check if you have turned on the support for INT 13 extension (LBA). If +so, disable the support and see if GRUB can now access your SCSI +disk. This will make it clear that your SCSI BIOS sucks. + +For now, we know the following doesn't provide working LBA mode: + +@table @asis +@item +Adaptec AIC-7880 +@end table + +In the case where you have such a SCSI controller unfortunately, you +cannot use the LBA mode, though GRUB still works fine in the CHS mode +(so the well-known 1024 cylinders problem comes again to you). + +@strong{Caution:} Actually it has not been verified yet if this bug is +due to the SCSI BIOS or GRUB itself, frankly speaking. Because the +developers haven't seen it by their own eyes. This is why it is +desirable that you investigate the cause seriously if you have the +skill. + +@item How can I specify an arbitrary memory size to Linux? + +Pass a @samp{mem=} option to your Linux kernel, like this: + +@example +grub> @kbd{kernel /vmlinuz mem=128M} +@end example + +You may pass other options in the same way. See @xref{GNU/Linux}, for +more details. + +@item I have a separate boot partition and GRUB doesn't recognize it. + +This is often reported as a @dfn{bug}, but this is not a bug +really. This is a feature. + +Because GRUB is a boot loader and it normally runs under no operating +system, it doesn't know where a partition is mounted under your +operating systems. So, if you have the partition @file{/boot} and you +install GRUB images into the directory @file{/boot/grub}, GRUB +recognizes that the images lies under the directory @file{/grub} but not +@file{/boot/grub}. That's fine, since there is no guarantee that all of +your operating systems mount the same partition as @file{/boot}. + +There are several solutions for this situation. + +@enumerate +@item +Install GRUB into the directory @file{/boot/boot/grub} instead of +@file{/boot/grub}. This may sound ugly but should work fine. + +@item +Create a symbolic link before installing GRUB, like @samp{cd /boot && ln +-s . boot}. This works only if the filesystem of the boot partition +supports symbolic links and GRUB supports the feature as well. + +@item +Install GRUB with the command @command{install}, to specify the paths of +GRUB images explicitly. Here is an example: + +@example +@group +grub> @kbd{root (hd0,1)} +grub> @kbd{install /grub/stage1 d (hd0) /grub/stage2 p /grub/menu.lst} +@end group +@end example +@end enumerate + +@item How to uninstall GRUB from my hard disk drive? + +There is no concept @dfn{uninstall} in boot loaders, because if you +@dfn{uninstall} a boot loader, an unbootable machine would simply +remain. So all you need to do is overwrite another boot loader you like +to your disk, that is, install the boot loader without uninstalling +GRUB. + +For example, if you want to install the boot loader for Windows, just +run @code{FDISK /MBR} on Windows. If you want to install LILO@footnote{I +can't imagine why you want to do such a thing, though}, run +@code{/sbin/lilo} on GNU/Linux. + +@item GRUB hangs when accessing my large IDE disk. + +If your disk is bigger than 32GB, probably updating your mainboard BIOS +will solve your problem. This bug is well-known and most vendors should +provide fixed versions. For example, if you have ASUS-P3BF, upgrading +the BIOS to V1007beta1 or later can fix it. Please ask your vendor, for +more information. + +@item Why don't Linux, FreeBSD, NetBSD, etc. become Multiboot-compliant? + +Please ask the relevant maintainers. If all free kernels were +Multiboot-compliant (@pxref{Top, Multiboot Specification, Motivation, +multiboot, The Multiboot Specification}), the world would be an +utopia@dots{} +@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://sourceware.cygnus.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 + +This will install the grub shell @file{grub} (@pxref{Invoking the grub +shell}), the Multiboot checker @file{mbchk} (@pxref{Invoking mbchk}), +and the GRUB images. This will also install the GRUB manual. + +Also, the latest version is available from the CVS. The repository is: + +@code{:pserver:anoncvs@@subversions.gnu.org:/home/cvs} + +and the module is: + +@code{grub} + +The password for anoncvs is empty. So the instruction is: + +@example +@group +@kbd{cvs -d :pserver:anoncvs@@subversions.gnu.org:/home/cvs login} +@kbd{Password: @key{ENTER}} +@kbd{cvs -d :pserver:anoncvs@@subversions.gnu.org:/home/cvs co grub} +@end group +@end example + + +@node Reporting bugs +@appendix Reporting bugs + +This is the guideline of how to report bugs. Take a look at this list +below before you send e-mail to @email{bug-grub@@gnu.org}: + +@enumerate +@item +Before unsettled, read this manual through and through, in particular +@xref{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 get troubled 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{all} 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 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 quite better than omitting an important +thing. +@end enumerate + +If you realize the guideline above, send e-mail to +@email{bug-grub@@gnu.org}, and we will try to fix the bugs. + + +@node Future +@chapter Where GRUB will go + +Here are some ideas that might happen in the future: + +@itemize @bullet +@item +Support dynamic loading. + +@item +Add real memory management. + +@item +Add a real scripting language. + +@item +Support internationalization. + +@item +Support other architectures than i386-pc. +@end itemize + +See the file @file{TODO} in the source distribution, for more +information. + + +@node Index +@unnumbered Index + +@c Currently, we use only the Concept Index. +@printindex cp + + +@contents +@bye + +Some notes: + + This is the second attempt to rewrite the manual. The status is +mostly complete, but I need to check the spelling by ispell, and add +more indices. Perhaps I also have to let some English native speakers to +proofread this manual through. My English is syntactically almost +perfect, but sometimes (often?) awful in the nuance. Hehe, I can't be an +English poet for now. + + Because I haven't written ``the GRUB internals'' yet, the cross +references to the manual are broken. I will have to write it based on +the old ``GRUB Programmers Manual''. Don't forget that I should rewrite +the chapter about Partition Table from scratch. + + Rename this file to "grub.texi", once this manual is finished. Don't +forget that it is necessary to change the argument to @settitle.