From d20f9609ce17a6ee5af3027b984d812164df76e2 Mon Sep 17 00:00:00 2001 From: okuji Date: Wed, 7 Feb 2001 20:26:29 +0000 Subject: [PATCH] The new grub manual is made official. --- ChangeLog | 13 + docs/Makefile.am | 3 +- docs/Makefile.in | 4 +- docs/appendices.texi | 324 ---- docs/grub-new.texi | 3696 ------------------------------------------ docs/grub.texi | 3613 ++++++++++++++++++++++++++++++++++++++++- docs/internals.texi | 427 +++++ docs/prog-ref.texi | 1700 ------------------- docs/stamp-vti | 2 +- docs/tutorial.texi | 1040 ------------ docs/user-ref.texi | 1702 ------------------- docs/version.texi | 2 +- 12 files changed, 4009 insertions(+), 8517 deletions(-) delete mode 100644 docs/appendices.texi delete mode 100644 docs/grub-new.texi create mode 100644 docs/internals.texi delete mode 100644 docs/prog-ref.texi delete mode 100644 docs/tutorial.texi delete mode 100644 docs/user-ref.texi diff --git a/ChangeLog b/ChangeLog index e2e3d65fb..3b699c412 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,16 @@ +2001-02-08 OKUJI Yoshinori + + * docs/grub-new.texi: Moved to ... + * docs/grub.texi: ... here. And, include internals.texi. + * docs/internals.texi: New file. + * docs/prog-ref.texi: Removed. + * docs/user-ref.texi: Likewise. + * docs/tutorial.texi: Likewise. + * docs/appendices.texi: Likewise. + * docs/Makefile.am (grub_TEXINFOS): Removed prog-ref.texi, + user-ref.texi, tutorial.texi, and appendices.texi. Added + internals.texi. + 2001-02-03 OKUJI Yoshinori From Erik Schoenfelder : diff --git a/docs/Makefile.am b/docs/Makefile.am index 4e988f009..3251c4caa 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -1,6 +1,5 @@ info_TEXINFOS = grub.texi multiboot.texi -grub_TEXINFOS = tutorial.texi user-ref.texi prog-ref.texi \ - appendices.texi +grub_TEXINFOS = internals.texi EXAMPLES = boot.S kernel.c multiboot.h multiboot_TEXINFOS = boot.S.texi kernel.c.texi multiboot.h.texi man_MANS = grub.8 mbchk.1 grub-install.8 grub-md5-crypt.8 diff --git a/docs/Makefile.in b/docs/Makefile.in index 37667f460..638774d55 100644 --- a/docs/Makefile.in +++ b/docs/Makefile.in @@ -88,9 +88,7 @@ install_sh = @install_sh@ info_TEXINFOS = grub.texi multiboot.texi -grub_TEXINFOS = tutorial.texi user-ref.texi prog-ref.texi \ - appendices.texi - +grub_TEXINFOS = internals.texi EXAMPLES = boot.S kernel.c multiboot.h multiboot_TEXINFOS = boot.S.texi kernel.c.texi multiboot.h.texi man_MANS = grub.8 mbchk.1 grub-install.8 grub-md5-crypt.8 diff --git a/docs/appendices.texi b/docs/appendices.texi deleted file mode 100644 index 0717fee27..000000000 --- a/docs/appendices.texi +++ /dev/null @@ -1,324 +0,0 @@ -@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 filename 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 -$ ./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> 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> root (hd0,1) -grub> 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 -@url{http://sourceware.cygnus.com/binutils/}, to obtain information on -how to get the latest version. -@end quotation - -@c Do not change alpha.gnu.org:/gnu/grub to the URI, since TeX does -@c not format it well. -GRUB is available from the GNU alpha archive site -@url{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: - -@url{ftp://alpha.gnu.org/gnu/grub/grub-@value{VERSION}.tar.gz} - -To unbundle GRUB use the instruction: - -@example -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 -$ cd grub-@value{VERSION} -$ ./configure -$ 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 It 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 -$ cvs -d :pserver:anoncvs@@subversions.gnu.org:/home/cvs \ - login -Password: @key{ENTER} -$ cvs -d :pserver:anoncvs@@subversions.gnu.org:/home/cvs \ - checkout grub -@end group -@end example - -Get the recent version of GNU Automake from the CVS to regenerate -@file{Makefile.in}s. See @url{http://sourceware.cygnus.com/automake/}, -for more information. - - -@node Reporting bugs -@appendix Reporting bugs - -When you encounter any problem or bug, please submit it to -@email{bug-grub@@gnu.org} with information about your computer and what -you did @emph{as much as possible}. Take a look at this list before you -send e-mail to the address: - -@itemize @bullet -@item -Write what you did and what messages were printed on the screen in -detail. Don't paraphrase them. Please describe them as they were. - -@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 -Inform us of the information about your GRUB. What version were you -using? Which were you using the grub shell or the boot images? If using -the grub shell, tell us what operating system was used to run it. And, -if you ran @command{configure} with some options when building GRUB, it -would be a good thing to let us know how to build it. - -@item -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 -Write down anything that you think might be related. 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 itemize - - -@node Index -@unnumbered Index - -@c Currently, we use only the Concept Index. -@printindex cp diff --git a/docs/grub-new.texi b/docs/grub-new.texi deleted file mode 100644 index ab6312732..000000000 --- a/docs/grub-new.texi +++ /dev/null @@ -1,3696 +0,0 @@ -\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}), DOS (or -Windows) will ignore the partition. If GRUB @dfn{unhide}s a DOS (or -Windows) partition (@pxref{unhide}), DOS (or Windows) will detect the -partition. Thus, if you have installed DOS (or Windows) on the first -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 @ref{Menu-specific -commands}. Other descriptions can be found in @ref{Commands}. - -Now, on to the actual OS definitions. You will see that each entry -begins with a special command, @command{title} (@pxref{title}), and the -action is described after it. Note that there is no command -@command{boot} (@pxref{boot}) at the end of each item. That is because -GRUB automatically executes @command{boot} if it loads other commands -successfully. - -The argument for the command @command{title} is used to display a short -title/description of the entry in the menu. Since @command{title} -displays the argument as is, you can write basically anything 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. diff --git a/docs/grub.texi b/docs/grub.texi index 64ec979e3..2248882d0 100644 --- a/docs/grub.texi +++ b/docs/grub.texi @@ -31,7 +31,7 @@ @ifinfo Copyright @copyright{} 1996 Erich Boleyn -Copyright @copyright{} 1999, 2000 Free Software Foundation, Inc. +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 @@ -56,7 +56,7 @@ into another language, under the above conditions for modified versions. @titlepage @sp 10 -@title The GRUB Manual +@title the GRUB manual @subtitle The GRand Unified Bootloader, version @value{VERSION}, @value{UPDATED}. @author Gordon Matzigkeit @author OKUJI Yoshinori @@ -64,7 +64,7 @@ into another language, under the above conditions for modified versions. @page @vskip 0pt plus 1filll Copyright @copyright{} 1996 Erich Boleyn -Copyright @copyright{} 1999, 2000 Free Software Foundation, Inc. +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 @@ -85,7 +85,7 @@ by Free Software Foundation. @ifnottex @node Top -@top GRUB +@top GRUB manual This is the documentation of GNU GRUB, the GRand Unified Bootloader, a flexible and powerful boot loader program for @sc{pc}s. @@ -94,9 +94,7 @@ This edition documents version @value{VERSION}. @end ifnottex @menu -Part I: The Tutorial Manual - -* Overview:: What exactly GRUB is and how to use it +* 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 @@ -104,11 +102,7 @@ Part I: The Tutorial Manual * Network:: Downloading OS images from a network * Serial terminal:: Using GRUB via a serial line * Security:: Improving the security - -Part II: The User Reference Manual - -* Introduction:: Capturing the spirit of GRUB -* GRUB images:: GRUB images +* Images:: GRUB image files * Filesystem:: Filesystem syntax and semantics * Interface:: The menu and the command-line * Commands:: The list of available builtin commands @@ -117,55 +111,3578 @@ Part II: The User Reference Manual * 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 - -Part III: The Programmer Reference Manual - -* Hacking:: Implementation details -* Memory map:: The memory map of various components -* Embedded data:: Embedded variables in GRUB -* Filesystem interface:: The generic interface for the fs code -* Bootstrap tricks:: The bootstrap mechanism used in GRUB -* I/O ports detection:: INT 13H tracking technique -* Memory detection:: How to detect all installed @sc{ram} -* Low-level disk I/O:: INT 13H disk I/O interrupts -* MBR:: The structure of Master Boot Record -* Partition table:: The format of partition table - -Appendices and Indices - * 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 +* Internals:: Hacking GRUB * Index:: @end menu -@iftex -@page -@unnumbered Part I: The Tutorial Manual -@end iftex -@include tutorial.texi +@node Introduction +@chapter Introduction to GRUB -@iftex -@page -@unnumbered Part II: The User Reference Manual -@end iftex +@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 -@include user-ref.texi -@iftex -@page -@unnumbered Part III: The Programmer Reference Manual -@end iftex +@node Overview +@section Overview -@include prog-ref.texi +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). -@iftex -@page -@unnumbered Appendices and Indices -@end iftex +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}), DOS (or +Windows) will ignore the partition. If GRUB @dfn{unhide}s a DOS (or +Windows) partition (@pxref{unhide}), DOS (or Windows) will detect the +partition. Thus, if you have installed DOS (or Windows) on the first +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 @ref{Menu-specific +commands}. Other descriptions can be found in @ref{Commands}. + +Now, on to the actual OS definitions. You will see that each entry +begins with a special command, @command{title} (@pxref{title}), and the +action is described after it. Note that there is no command +@command{boot} (@pxref{boot}) at the end of each item. That is because +GRUB automatically executes @command{boot} if it loads other commands +successfully. + +The argument for the command @command{title} is used to display a short +title/description of the entry in the menu. Since @command{title} +displays the argument as is, you can write basically anything 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{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{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. + + +@c Seperate the programming guide. +@include internals.texi + + +@node Index +@unnumbered Index + +@c Currently, we use only the Concept Index. +@printindex cp -@include appendices.texi @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. diff --git a/docs/internals.texi b/docs/internals.texi new file mode 100644 index 000000000..effdfa4b9 --- /dev/null +++ b/docs/internals.texi @@ -0,0 +1,427 @@ +@node Internals +@chapter Hacking GRUB + +This chapter documents the user-invisible aspect of GRUB. + +As a general rule of software development, it is impossible to keep the +descriptions of the internals up-to-date, and it is quite hard to +document everything. So refer to the source code, whenever you are not +satisfied with this documentation. Please assume that this gives just +hints to you. + +@menu +* Memory map:: The memory map of various components +* Embedded data:: Embedded variables in GRUB +* Filesystem interface:: The generic interface for filesystems +* Command interface:: The generic interface for built-ins +* Bootstrap tricks:: The bootstrap mechanism used in GRUB +* I/O ports detection:: How to probe I/O ports used by INT 13H +* Memory detection:: How to detect all installed RAM +* Low-level disk I/O:: INT 13H disk I/O interrupts +* MBR:: The structure of Master Boot Record +* Partition table:: The format of partition tables +* Submitting patches:: Where and how you should send patches +@end menu + + +@node Memory map +@section The memory map of various components + +GRUB consists of two distinct components, called @dfn{stages}, which are +loaded at different times in the boot process. Because they run +mutual-exclusively, sometimes a memory area overlaps with another +memory area. And, even in one stage, a single memory area can be used +for various purposes, because their usages are mutually exclusive. + +Here is the memory map of the various components: + +@table @asis +@item 0 to 4K-1 +BIOS and real mode interrupts + +@item 0x07BE to 0x07FF +Partition table passed to another boot loader + +@item down from 8K-1 +Real mode stack + +@item 0x2000 to ? +The optional Stage 1.5 is loaded here + +@item 0x2000 to 0x7FFF +Command-line buffer for Multiboot kernels and modules + +@item 0x7C00 to 0x7DFF +Stage 1 is loaded here by BIOS or another boot loader + +@item 0x7F00 to 0x7F42 +LBA drive parameters + +@item 0x8000 to ? +Stage2 is loaded here + +@item The end of Stage 2 to 416K-1 +Heap, in particular used for the menu + +@item down from 416K-1 +Protected mode stack + +@item 416K to 448K-1 +Filesystem buffer + +@item 448K to 479.5K-1 +Raw device buffer + +@item 479.5K to 480K-1 +512-byte scratch area + +@item 480K to 512K-1 +Buffers for various functions, such as password, command-line, cut and +paste, and completion. + +@item The last 1K of lower memory +Disk swapping code and data +@end table + +See the file @file{stage2/shared.h}, for more information. + + +@node Embedded data +@section Embedded variables in GRUB + +Stage 1 and Stage 2 have embedded variables whose locations are +well-defined, so that the installation can patch the binary file +directly without recompilation of the stages. + +In Stage 1, these are defined: + +@table @code +@item 0x3E +The version number (not GRUB's, but the installation mechanism's). + +@item 0x40 +The boot drive. If it is 0xFF, use a drive passed by BIOS. + +@item 0x41 +The flag for if forcing LBA. + +@item 0x42 +The starting address of Stage 2. + +@item 0x44 +The first sector of Stage 2. + +@item 0x48 +The starting segment of Stage 2. + +@item 0x1FE +The signature (@code{0xAA55}). +@end table + +See the file @file{stage1/stage1.S}, for more information. + +In the first sector of Stage 1.5 and Stage 2, the block lists are +recorded between @code{firstlist} and @code{lastlist}. The address of +@code{lastlist} is determined when assembling the file +@file{stage2/start.S}. + +The trick here is that it is actually read backward, and the first +8-byte block list is not read here, but after the pointer is decremented +8 bytes, then after reading it, it decrements again, reads, and so on, +until it is finished. The terminating condition is when the number of +sectors to be read in the next block list is zero. + +The format of a block list can be seen from the example in the code just +before the @code{firstlist} label. Note that it is always from the +beginning of the disk, but @emph{not} relative to the partition +boundaries. + +In the second sector of Stage 1.5 and Stage 2, these are defined: + +@table @asis +@item @code{0x6} +The version number (likewise, the installation mechanism's). + +@item @code{0x8} +The installed partition. + +@item @code{0xC} +The saved entry number. + +@item @code{0x10} +The identifier. + +@item @code{0x11} +The flag for if forcing LBA. + +@item @code{0x12} +The version string (GRUB's). + +@item @code{0x12} + @dfn{the length of the version string} +The name of a configuration file. +@end table + +See the file @file{stage2/asm.S}, for more information. + + +@node Filesystem interface +@section The generic interface for filesystems + +For any particular partition, it is presumed that only one of the +@dfn{normal} filesystems such as FAT, FFS, or ext2fs can be used, so +there is a switch table managed by the functions in +@file{disk_io.c}. The notation is that you can only @dfn{mount} one at a +time. + +The block list filesystem has a special place in the system. In addition +to the @dfn{normal} filesystem (or even without one mounted), you can +access disk blocks directly (in the indicated partition) via the block +list notation. Using the block list filesystem doesn't effect any other +filesystem mounts. + +The variables which can be read by the filesystem backend are: + +@vtable @code +@item current_drive +The current BIOS drive number (numbered from 0, if a floppy, and +numbered from 0x80, if a hard disk). + +@item current_partition +The current partition number. + +@item current_slice +The current partition type. + +@item saved_drive +The @dfn{drive} part of the root device. + +@item saved_partition +The @dfn{partition} part of the root device. + +@item part_start +The current partition starting address, in sectors. + +@item part_length +The current partition length, in sectors. + +@item print_possibilities +True when the @code{dir} function should print the possible completions +of a file, and false when it should try to actually open a file of that +name. + +@item FSYS_BUF +Filesystem buffer which is 32K in size, to use in any way which the +filesystem backend desires. +@end vtable + +The variables which need to be written by a filesystem backend are: + +@vtable @code +@item filepos +The current position in the file, in sectors. + +@strong{Caution:} the value of @var{filepos} can be changed out from +under the filesystem code in the current implementation. Don't depend on +it being the same for later calls into the backend code! + +@item filemax +The length of the file. + +@item disk_read_func +The value of @var{disk_read_hook} @emph{only} during reading of data +for the file, not any other fs data, inodes, FAT tables, whatever, then +set to @code{NULL} at all other times (it will be @code{NULL} by +default). If this isn't done correctly, then the @command{testload} and +@command{install} commands won't work correctly. +@end vtable + +The functions expected to be used by the filesystem backend are: + +@ftable @code +@item devread +Only read sectors from within a partition. Sector 0 is the first sector +in the partition. + +@item grub_read +If the backend uses the block list code, then @code{grub_read} can be +used, after setting @var{block_file} to 1. + +@item print_a_completion +If @var{print_possibilities} is true, call @code{print_a_completion} for +each possible file name. Otherwise, the file name completion won't work. +@end ftable + +The functions expected to be defined by the filesystem backend are +described at least moderately in the file @file{filesys.h}. Their usage +is fairly evident from their use in the functions in @file{disk_io.c}, +look for the use of the @var{fsys_table} array. + +@strong{Caution:} The semantics are such that then @samp{mount}ing the +filesystem, presume the filesystem buffer @code{FSYS_BUF} is corrupted, +and (re-)load all important contents. When opening and reading a file, +presume that the data from the @samp{mount} is available, and doesn't +get corrupted by the open/read (i.e. multiple opens and/or reads will be +done with only one mount if in the same filesystem). + + +@node Command interface +@section The generic interface for built-ins + +GRUB built-in commands are defined in a uniformal interface, whether +they are menu-specific or can be used anywhere. The definition of a +builtin command consists of two parts: the code itself and the table of +the information. + +The code must be a function which takes two arguments, a command-line +string and flags, and returns an @samp{int} value. The @dfn{flags} +argument specifies how the function is called, using a bit mask. The +return value must be zero if successful, otherwise non-zero. So it is +normally enough to return @var{errnum}. + +The table of the information is represented by the structure +@code{struct builtin}, which contains the name of the command, a pointer +to the function, flags, a short description of the command and a long +description of the command. Since the descriptions are used only for +help messages interactively, you don't have to define them, if the +command may not be called interactively (such as @command{title}). + +The table is finally registered in the table @var{builtin_table}, so +that @code{run_script} and @code{enter_cmdline} can find the +command. See the files @file{cmdline.c} and @file{builtins.c}, for more +details. + + +@node Bootstrap tricks +@section The bootstrap mechanism used in GRUB + +The disk space can be used in a boot loader is very restricted because +a MBR (@pxref{MBR}) is only 512 bytes but it also contains a partition +table (@pxref{Partition table}) and a BPB. So the question is how to +make a boot loader code enough small to be fit in a MBR. + +However, GRUB is a very large program, so we break GRUB into 2 (or 3) +distinct components, @dfn{Stage 1} and @dfn{Stage 2} (and optionally +@dfn{Stage 1.5}). @xref{Memory map}, for more information. + +We embed Stage 1 in a MBR or in the boot sector of a partition, and +place Stage 2 in a filesystem. The optional Stage 1.5 can be installed +in a filesystem, in the @dfn{boot loader} area in a FFS or a ReiserFS, +and in the sectors right after a MBR, because Stage 1.5 is enough small +and the sectors right after a MBR is normally an unused region. The size +of this region is the number of sectors per head minus 1. + +Thus, all Stage1 must do is just load Stage2 or Stage1.5. But even if +Stage 1 needs not to support the user interface or the filesystem +interface, it is impossible to make Stage 1 less than 400 bytes, because +GRUB should support both the CHS mode and the LBA mode (@pxref{Low-level +disk I/O}). + +The solution used by GRUB is that Stage 1 loads only the first sector of +Stage 2 (or Stage 1.5) and Stage 2 itself loads the rest. The flow of +Stage 1 is: + +@enumerate +@item +Initialize the system briefly. + +@item +Detect the geometry and the accessing mode of the @dfn{loading drive}. + +@item +Load the first sector of Stage 2. + +@item +Jump to the starting address of the Stage 2. +@end enumerate + +The flow of Stage 2 (and Stage 1.5) is: + +@enumerate +@item +Load the rest of itself to the real starting address, that is, the +starting address plus 512 bytes. The block lists are stored in the last +part of the first sector. + +@item +Long jump to the real starting address. +@end enumerate + +Note that Stage 2 (or Stage 1.5) does not probe the geometry +or the accessing mode of the @dfn{loading drive}, since Stage 1 has +already probed them. + + +@node I/O ports detection +@section How to probe I/O ports used by INT 13H + +FIXME: I will write this chapter after implementing the new technique. + + + +@node Memory detection +@section How to detect all installed RAM + +FIXME: I doubt if Erich didn't write this chapter only himself wholly, +so I will rewrite this chapter. + + +@node Low-level disk I/O +@section INT 13H disk I/O interrupts + +FIXME: I'm not sure where some part of the original chapter is derived, +so I will rewrite this chapter. + + +@node MBR +@section The structure of Master Boot Record + +FIXME: Likewise. + + +@node Partition table +@section The format of partition tables + +FIXME: Probably the original chapter is derived from "How It Works", so +I will rewrite this chapter. + + +@node Submitting patches +@section Where and how you should send patches + +When you write patches for GRUB, please send them to the mailing list +@email{bug-grub@@gnu.org}. Here is the list of items of which you +should take care: + +@itemize @bullet +@item +Please make your patch as small as possible. Generally, it is not a good +thing to make one big patch which changes many things. Instead, +segregate features and produce many patches. + +@item +Use as late code as possible, for the original code. The CVS repository +always has the current version (@pxref{Obtaining and Building GRUB}). + +@item +Write ChangeLog entries. @xref{Change Logs, , Change Logs, standards, +GNU Coding Standards}, if you don't know how to write ChangeLog. + +@item +Make patches in unified diff format. @samp{diff -urN} is appropriate in +most cases. + +@item +Don't make patches reversely. Reverse patches are difficult to read and +use. + +@item +Be careful enough of the license term and the copyright. Because GRUB +is under GNU General Public License, you may not steal code from +software whose license is incompatible against GPL. And, if you copy +code written by others, you must not ignore their copyrights. Feel free +to ask GRUB maintainers, whenever you are not sure what you should do. + +@item +If your patch is too large to send in e-mail, put it at somewhere we can +see. Usually, you shouldn't send e-mail over 20K. +@end itemize diff --git a/docs/prog-ref.texi b/docs/prog-ref.texi deleted file mode 100644 index 79b55ee11..000000000 --- a/docs/prog-ref.texi +++ /dev/null @@ -1,1700 +0,0 @@ -@node Hacking -@chapter Implementation details - -This part describes the GRUB internals so that developers can -understand the implementation and start to hack GRUB. Of course, the -source code has the complete information, so refer to it when you are -not satisfied with this documentation. - - -@node Memory map -@chapter The memory map of various components - -GRUB is broken into 2 distinct components, or @dfn{stages}, which are -loaded at different times in the boot process. The Stage 1 has to know -where to find Stage 2, and the Stage 2 has to know where to find its -configuration file (if Stage 2 doesn't have a configuration file, it -drops into the command line interface and waits for a user command). - -Here is the memory map of the various components -@footnote{Currently GRUB does not use the extended memory for itself, -since it is used to load an operating system. But we are planning to use -it for GRUB itself in the future by @dfn{lazy loading}. Ask okuji for -more information.}: - -@table @asis -@item 0 to 4K-1 -Interrupt & BIOS area - -@item down from 8K-1 -16-bit stack area - -@item 8K to (ebss1.5) -Stage 1.5 (optionally) loaded here by Stage 1 - -@item 0x7c00 to 0x7dff -Stage 1 loaded here by the BIOS - -@item 0x7e00 to 0x7e08 -Scratch space used by Stage 1 - -@item 32K to (ebss2) -Stage 2 loaded here by Stage 1.5 or Stage 1 - -@item (middle area) -Heap used for random memory allocation - -@item down from 416K-1 -32-bit stack area - -@item 416K to 448K-1 -Filesystem info buffer (when reading a filesystem) - -@item 448K to 479.5K-1 -BIOS track read buffer - -@item 479.5K to 480K-1 -512 byte fixed SCRATCH area - -@item 480K to 511K-1 -General storage heap -@end table - -See the file @file{stage2/shared.h}, for more information. - - -@node Embedded data -@chapter Embedded variables in GRUB - -GRUB's @dfn{stage1} and @dfn{stage2} have embedded variables whose -locations are well-defined, so that the installation can patch the -binary file directly without recompilation of the modules. - -In @dfn{stage1}, these are defined (The number in the parenthesis of -each entry is an offset number): - -@table @asis -@item @dfn{stage1 version} (0x3e) -This is the version bytes (should 03:00). - -@item @dfn{loading drive} (0x40) -This is the BIOS drive number to load the block from. If the number -is 0xff, then load from the booting drive. - -@item @dfn{stage2 sector} (0x41) -This is the location of the first sector of the @dfn{stage2}. - -@item @dfn{stage2 address} (0x45) -This is the data for the @code{jmp} command to the starting address of -the component loaded by the stage1. - -A @dfn{stage1.5} should be loaded at address 0x2000, and a @dfn{stage2} -should be loaded at address 0x8000. Both use a CS of 0. - -@item @dfn{stage2 segment} (0x47) -This is the segment of the starting address of the component loaded by -the @dfn{stage1}. -@end table - -In the first sector of @dfn{stage1.5} and @dfn{stage2}, the blocklists -are recorded between @dfn{firstlist} (0x200) and @dfn{lastlist} -(determined when assembling the file @file{stage2/start.S}). - -The trick here is that it is actually read backward, and the first -8-byte blocklist is not read here, but after the pointer is decremented -8 bytes, then after reading it, it decrements again, reads, decrements, -reads, etc. until it is finished. The terminating condition is when the -number of sectors to be read in the next blocklist is 0. - -The format of a blocklist can be seen from the example in the code just -before the @code{firstlist} label. Note that it is always from the -beginning of the disk, and @emph{not} relative to the partition -boundaries. - -In @dfn{stage1.5} and @dfn{stage2} (these are all defined at the -beginning of @file{shared_src/asm.S}): - -@table @asis -@item @dfn{major version} (0x6) -This is the major version byte (should be 3). - -@item @dfn{minor version} (0x7) -This is the minor version byte (should be 0). - -@item @dfn{install_partition} (0x8) -This is an unsigned long representing the partition on the currently -booted disk which GRUB should expect to find it's data files and treat -as the default root partition. - -The format of is exactly the same as the @dfn{partition} part (the -@dfn{disk} part is ignored) of the data passed to an OS by a -Multiboot-compliant boot loader in the @dfn{boot_device} data element, -with one exception. - -The exception is that if the first level of disk partitioning is left as -0xFF (decimal 255, which is marked as no partitioning being used), but -the second level does have a partition number, it looks for the first -BSD-style PC partition, and finds the numbered BSD sub-partition in it. -The default @dfn{install_partition} 0xFF00FF, would then find the first -BSD-style PC partition, and use the @samp{a} partition in it, and -0xFF01FF would use the @samp{b} partition, etc. - -If an explicit first-level partition is given, then no search is -performed, and it will expect that the BSD-style PC partition is in the -appropriate location, else a @samp{no such partition} error will be -returned. - -If a @dfn{stage1.5} is being used, it will pass its own -@dfn{install_partition} to any @dfn{stage2} it loads, therefore -overwriting the one present in the @dfn{stage2}. - -@item @dfn{stage2_id} (0xc) -This is the @dfn{stage1.5} or @dfn{stage2} identifier. - -@item @dfn{version_string} (0xd) -This is the @dfn{stage1.5} or @dfn{stage2} version string. It isn't -meant to be changed, simply easy to find. - -@item @dfn{config_file} (after the terminating zero of @dfn{version_string}) -This is the location, using the GRUB filesystem syntax, of the config -file. It will, by default, look in the @dfn{install_partition} of the -disk GRUB was loaded from, though one can use any valid GRUB filesystem -string, up to and including making it look on other disks. - -The boot loader itself doesn't search for the end of -@dfn{version_string}, it simply knows where @dfn{config_file} is, so the -beginning of the string cannot be moved after compile-time. This should -be OK, since the @dfn{version_string} is meant to be static. - -The code of @dfn{stage2} starts again at offset 0x70, so -@dfn{config_file} string obviously can't go past there. Also, remember -to terminate the string with a 0. - -Note that @dfn{stage1.5} uses a tricky internal representation for -@dfn{config_file}, which is the format of -@code{@var{device}:@var{filename}} (@samp{:} is not present actually). -@var{device} is an unsigned long like @dfn{install_partition}, and -@var{filename} is an absolute filename or a blocklist. If @var{device} -is disabled, that is, the drive number is 0xff, then @dfn{stage1.5} uses -the @dfn{boot drive} and the @dfn{install partition} instead. -@end table - - -@node Filesystem interface -@chapter The generic interface for the fs code - -For any particular partition, it is presumed that only one of the -@dfn{normal} filesystems such as FAT, FFS, or ext2fs can be used, so -there is a switch table managed by the functions in -@file{disk_io.c}. The notation is that you can only @dfn{mount} one at a -time. - -The blocklist filesystem has a special place in the system. In addition -to the @dfn{normal} filesystem (or even without one mounted), you can -access disk blocks directly (in the indicated partition) via the -blocklist notation. Using the blocklist filesystem doesn't effect any -other filesystem mounts. - -The variables which can be read by the filesystem backend are: - -@vtable @code -@item current_drive -Contain the current BIOS drive number (numbered from 0, if a floppy, -and numbered from 0x80, if a hard disk). - -@item current_partition -Contain the current partition number. - -@item current_slice -Contain the current partition type. - -@item saved_drive -Contain the @dfn{drive} part of the root device. - -@item saved_partition -Contain the @dfn{partition} part of the root device. - -@item part_start -Contain the current partition starting address. - -@item part_length -Contain the current partition length, in sectors. - -@item print_possibilities -True when the @code{dir} function should print the possible completions -of a file, and false when it should try to actually open a file of that -name. - -@item FSYS_BUF -Point to a filesystem buffer which is 32K in size, to use in any way -which the filesystem backend desires. -@end vtable - -The variables which need to be written by a filesystem backend are: - -@vtable @code -@item filepos -Should be the current position in the file. - -@strong{Caution:} the value of @var{filepos} can be changed out from -under the filesystem code in the current implementation. Don't depend on -it being the same for later calls into the back-end code! - -@item filemax -Should be the length of the file. - -@item disk_read_func -Should be set to the value of @samp{disk_read_hook} @emph{only} during -reading of data for the file, not any other fs data, inodes, FAT tables, -whatever, then set to @code{NULL} at all other times (it will be -@code{NULL} by default). If this isn't done correctly, then the -@command{testload} and @command{install} commands won't work -correctly. -@end vtable - -The functions expected to be used by the filesystem backend are: - -@ftable @code -@item devread -Only read sectors from within a partition. Sector 0 is the first sector -in the partition. - -@item grub_read -If the backend uses the blocklist code (like the FAT filesystem backend -does), then @code{grub_read} can be used, after setting @var{block_file} -to 1. -@end ftable - -The functions expected to be defined by the filesystem backend are -described at least moderately in the file @file{filesys.h}. Their usage -is fairly evident from their use in the functions in @file{disk_io.c}, -look for the use of the @var{fsys_table} array. - -@strong{Caution:} The semantics are such that then @samp{mount}ing the -filesystem, presume the filesystem buffer @var{FSYS_BUF} is corrupted, -and (re-)load all important contents. When opening and reading a file, -presume that the data from the @samp{mount} is available, and doesn't -get corrupted by the open/read (i.e. multiple opens and/or reads will be -done with only one mount if in the same filesystem). - - -@node Bootstrap tricks -@chapter The bootstrap mechanism used in GRUB - -The disk space can be used in a boot loader is very restricted because -a MBR (@pxref{MBR}) is only 512 bytes but it also contains a partition -table (@pxref{Partition table}) and a BPB. So the question is how to -make a boot loader code enough small to be fit in a MBR. - -However, GRUB is a very large program, so we break GRUB into 2 (or 3) -distinct components, @dfn{stage1} and @dfn{stage2} (and optionally -@dfn{stage1.5}). @xref{Memory map}, for more information. - -We embed @dfn{stage1} in a MBR or in the boot sector of a partition -, and place @dfn{stage2} in a filesystem. The optional -@dfn{stage1.5} can be installed in a filesystem, in the @dfn{boot loader} -area in a FFS, and in the sectors right after a MBR, because -@dfn{stage1.5} is enough small and the sectors right after a MBR is -normally an unused region. The size of this region is the number of -sectors per head minus 1. - -Thus, all the @dfn{stage1} must do is just load a @dfn{stage2} or -@dfn{stage1.5}. But even if @dfn{stage1} needs not to support the user -interface or the filesystem interface, it is impossible to make -@dfn{stage1} less than 400 bytes, because GRUB should support both the -CHS mode and the LBA mode (@pxref{Low-level disk I/O}). - -The solution used by GRUB is that @dfn{stage1} loads only the first -sector of a @dfn{stage2} (or a @dfn{stage1.5}) and @dfn{stage2} itself -loads the rest. The flow of @dfn{stage1} is: - -@enumerate -@item -Initialize the system briefly. - -@item -Detect the geometry and the accessing mode of the @dfn{loading drive}. - -@item -Load the first sector of the @dfn{stage2}. - -@item -Jump to the starting address of the @dfn{stage2}. -@end enumerate - -The flow of @dfn{stage2} (and @dfn{stage1.5}) is: - -@enumerate -@item -Load the rest of itself to the real starting address, that is, the -starting address plus 512 bytes. The blocklists are stored in the last -part of the first sector. - -@item -Long jump to the real starting address. -@end enumerate - -Note that @dfn{stage2} (or @dfn{stage1.5}) does not probe the geometry -or the accessing mode of the @dfn{loading drive}, since @dfn{stage1} has -already probed them. - - -@node I/O ports detection -@chapter How to detect I/O ports used for a BIOS drive - -In the @sc{pc} world, BIOS cannot detect if a hard disk drive is SCSI or -IDE, generally speaking. Thus, it is not trivial to know which BIOS -drive corresponds to an OS device. So the Multiboot Specification -describes some techniques on how to guess mappings (@pxref{BIOS device -mapping techniques, Multiboot Specification, BIOS device mapping -techniques, multiboot, The Multiboot Specification}). - -However, the techniques described are unreliable or difficult to be -implemented, so we use a different technique from them in GRUB. Our -technique is @dfn{INT 13H tracking technique}. More precisely, it runs -the INT 13 call (@pxref{Low-level disk I/O}) in single-step mode just -like a debugger and parses the instructions. - -To execute the call one instruction at a time, set the TF (trap flag) -flag in the register @dfn{FLAGS}. By this, your CPU generates @dfn{Break -Point Trap} after each instruction is executed and call INT 1. In the -stack in the interrupt handler, callee's FLAGS and the far pointer which -points to the next instruction to be executed are pushed, so we can know -what instruction will be executed in the next time and the current -contents of all the registers. If the next instruction is an I/O -operation, the interrupt handler adds the I/O port into the @dfn{I/O -map}. - -If the INT 13 handler returns, the TF flag is cleared automatically by -the instruction @code{iret}, and then output the I/O map on the screen. -See the source code for the command @command{ioprobe} -(@pxref{Command-line and menu entry commands}), for more information. - - -@node Memory detection -@chapter How to detect all installed @sc{ram} - -There are three BIOS calls which return the information of installed -@sc{ram}. GRUB uses these calls to detect all installed @sc{ram} and -which address range should be treated by operating systems. - -@menu -* Query System Address Map:: INT 15H, AX=E820h interrupt call -* Get Large Memory Size:: INT 15H, AX=E801h interrupt call -* Get Extended Memory Size:: INT 15H, AX=88h interrupt call -@end menu - - -@node Query System Address Map -@section INT 15H, AX=E820h interrupt call - -Real mode only. - -This call returns a memory map of all the installed @sc{ram}, and of -physical memory ranges reserved by the BIOS. The address map is returned -by making successive calls to this API, each returning one "run" of -physical address information. Each run has a type which dictates how -this run of physical address range should be treated by the operating -system. - -If the information returned from INT 15h, AX=E820h in some way differs -from INT 15h, AX=E801h (@pxref{Get Large Memory Size}) or INT 15h AH=88h -(@pxref{Get Extended Memory Size}), then the information returned from -E820h supersedes what is returned from these older interfaces. This -allows the BIOS to return whatever information it wishes to for -compatibility reasons. - -Input: - -@multitable @columnfractions .15 .25 .6 -@item @code{EAX} @tab Function Code @tab E820h - -@item @code{EBX} @tab Continuation @tab Contains the @dfn{continuation -value} to get the next run of physical memory. This is the value -returned by a previous call to this routine. If this is the first call, -@code{EBX} must contain zero. - -@item @code{ES:DI} @tab Buffer Pointer @tab Pointer to an Address Range -Descriptor structure which the BIOS is to fill in. - -@item @code{ECX} @tab Buffer Size @tab The length in bytes of the -structure passed to the BIOS. The BIOS will fill in at most @code{ECX} -bytes of the structure or however much of the structure the BIOS -implements. The minimum size which must be supported by both the BIOS -and the caller is 20 bytes. Future implementations may extend this -structure. - -@item @code{EDX} @tab Signature @tab @samp{SMAP} - Used by the BIOS to -verify the caller is requesting the system map information to be -returned in @code{ES:DI}. -@end multitable - -Output: - -@multitable @columnfractions 0.15 0.25 0.6 -@item @code{CF} @tab Carry Flag @tab Non-Carry - indicates no error - -@item @code{EAX} @tab Signature @tab @samp{SMAP} - Signature to verify -correct BIOS revision. - -@item @code{ES:DI} @tab Buffer Pointer @tab Returned Address Range -Descriptor pointer. Same value as on input. - -@item @code{ECX} @tab Buffer Size @tab Number of bytes returned by the -BIOS in the address range descriptor. The minimum size structure -returned by the BIOS is 20 bytes. - -@item @code{EBX} @tab Continuation @tab Contains the continuation value -to get the next address descriptor. The actual significance of the -continuation value is up to the discretion of the BIOS. The caller must -pass the continuation value unchanged as input to the next iteration of -the E820h call in order to get the next Address Range Descriptor. A -return value of zero means that this is the last descriptor. Note that -the BIOS indicates that the last valid descriptor has been returned by -either returning a zero as the continuation value, or by returning -carry. -@end multitable - -The Address Range Descriptor Structure is: - -@multitable @columnfractions 0.25 0.3 0.45 -@item Offset in Bytes @tab Name @tab Description - -@item 0 @tab @dfn{BaseAddrLow} @tab Low 32 Bits of Base Address - -@item 4 @tab @dfn{BaseAddrHigh} @tab High 32 Bits of Base Address - -@item 8 @tab @dfn{LengthLow} @tab Low 32 Bits of Length in Bytes - -@item 12 @tab @dfn{LengthHigh} @tab High 32 Bits of Length in Bytes - -@item 16 @tab @dfn{Type} @tab Address type of this range -@end multitable - -The @dfn{BaseAddrLow} and @dfn{BaseAddrHigh} together are the 64 bit -@dfn{BaseAddress} of this range. The @dfn{BaseAddress} is the physical -address of the start of the range being specified. - -The @dfn{LengthLow} and @dfn{LengthHigh} together are the 64 bit -@dfn{Length} of this range. The @dfn{Length} is the physical contiguous -length in bytes of a range being specified. - -The @dfn{Type} field describes the usage of the described address range -as defined in the table below: - -@multitable @columnfractions 0.1 0.35 0.55 -@item Value @tab Mnemonic @tab Description - -@item 1 @tab @dfn{AddressRangeMemory} @tab This run is available -@sc{ram} usable by the operating system. - -@item 2 @tab @dfn{AddressRangeReserved} @tab This run of addresses is in -use or reserved by the system, and must not be used by the operating -system. - -@item Other @tab @dfn{Undefined} @tab Undefined - Reserved for future -use. Any range of this type must be treated by the OS as if the type -returned was @dfn{AddressRangeReserved}. -@end multitable - -The BIOS can use the @dfn{AddressRangeReserved} address range type to -block out various addresses as @emph{not suitable} for use by a -programmable device. - -Some of the reasons a BIOS would do this are: - -@itemize @bullet -@item -The address range contains system @sc{rom}. - -@item -The address range contains @sc{ram} in use by the @sc{rom}. - -@item -The address range is in use by a memory mapped system device. - -@item -The address range is for whatever reason are unsuitable for a -standard device to use as a device memory space. -@end itemize - -Here is the list of assumptions and limitations: - -@enumerate -@item -The BIOS will return address ranges describing system memory and ISA -or PCI memory that is contiguous with that system memory. - -@item -The BIOS @emph{will not} return a range description for the memory -mapping of PCI devices. ISA Option @sc{rom}'s, and ISA plug & play -cards. This is because the OS has mechanisms available to detect them. - -@item -The BIOS will return chipset defined address holes that are not being -used by devices as reserved. - -@item -Address ranges defined for memory mapped I/O devices (for -example APICs) will be returned as reserved. - -@item -All occurrences of the system BIOS will be mapped as reserved. This -includes the area below 1 MB, at 16 MB (if present) and at end of the -address space (4 GB). - -@item -Standard I/O address ranges will not be reported. Example video memory at -A0000 to BFFFF physical will not be described by this function. The -range from E0000 to EFFFF is motherboard-specific and will be reported -differently on different computers. - -@item -All of lower memory is reported as normal memory. It is OS's -responsibility to handle standard @sc{ram} locations reserved for -specific uses, for example: the interrupt vector table (0:0) and the -BIOS data area (40:0). -@end enumerate - -Here we explain an example address map. This sample address map -describes a machine which has 128 MB @sc{ram}, 640K of base memory and -127 MB extended. The base memory has 639K available for the user and 1K -for an extended BIOS data area. There is a 4 MB Linear Frame Buffer -(LFB) based at 12 MB. The memory hole created by the chipset is from 8 -M to 16 M. There are memory mapped APIC devices in the system. The IO -Unit is at FEC00000 and the Local Unit is at FEE00000. The system BIOS -is remapped to 4G - 64K. - -Note that the 639K endpoint of the first memory range is also the base -memory size reported in the BIOS data segment at 40:13. - -Key to types: @dfn{ARM} is AddressRangeMemory, @dfn{ARR} is -AddressRangeReserved. - -@multitable @columnfractions 0.15 0.1 0.1 0.65 -@item Base (Hex) @tab Length @tab Type @tab Description - -@item 0000 0000 @tab 639K @tab ARM @tab Available Base memory - -typically the same value as is returned via the INT 12 function. - -@item 0009 FC00 @tab 1K @tab ARR @tab Memory reserved for use by the -BIOS(s). This area typically includes the Extended BIOS data area. - -@item 000F 0000 @tab 64K @tab ARR @tab System BIOS. - -@item 0010 0000 @tab 7M @tab ARM @tab Extended memory, this is not -limited to the 64MB address range. - -@item 0080 0000 @tab 8M @tab ARR @tab Chipset memory hole required to -support the LFB mapping at 12 MB. - -@item 0100 0000 @tab 120M @tab ARM @tab Base board @sc{ram} relocated -above a chipset memory hole. - -@item FEC0 0000 @tab 4K @tab ARR @tab IO APIC memory mapped I/O at -FEC00000. Note the range of addresses required for an APIC device may -vary from one motherboard manufacturer to another - -@item FEE0 0000 @tab 4K @tab ARR @tab Local APIC memory mapped I/O at -FEE00000. - -@item FFFF 0000 @tab 64K @tab ARR @tab Remapped System BIOS at end of -address space. -@end multitable - -The following code segment is intended to describe the algorithm needed -when calling the Query System Address Map function. It is an -implementation example and uses non standard mechanisms. - -@example -E820Present = FALSE; -Regs.ebx = 0; -do - @{ - Regs.eax = 0xE820; - Regs.es = SEGMENT (&Descriptor); - Regs.di = OFFSET (&Descriptor); - Regs.ecx = sizeof (Descriptor); - Regs.edx = 'SMAP'; - - _int (0x15, Regs); - - if ((Regs.eflags & EFLAGS_CARRY) || Regs.eax != 'SMAP') - @{ - break; - @} - - if (Regs.ecx < 20 || Regs.ecx > sizeof (Descriptor)) - @{ - /* bug in bios - all returned descriptors must be at - least 20 bytes long, and can not be larger than - the input buffer. */ - break; - @} - - E820Present = TRUE; - . - . - . - Add address range Descriptor.BaseAddress through - Descriptor.BaseAddress + Descriptor.Length - as type Descriptor.Type - . - . - . - @} -while (Regs.ebx != 0); - -if (! E820Present) - @{ - . - . - . - call INT 15H, AX E801h and/or INT 15H, AH=88h to obtain old style - memory information - . - . - . - @} -@end example - - -@node Get Large Memory Size -@section INT 15H, AX=E801h interrupt call - -Real mode only. - -Originally defined for EISA servers, this interface is capable of -reporting up to 4 GB of @sc{ram}. While not nearly as flexible as -E820h, it is present in many more systems. - -Input: - -@multitable @columnfractions 0.15 0.25 0.6 -@item @code{AX} @tab Function Code @tab E801h. -@end multitable - -Output: - -@multitable @columnfractions 0.15 0.25 0.6 -@item @code{CF} @tab Carry Flag @tab Non-Carry - indicates no error. - -@item @code{AX} @tab Extended 1 @tab Number of contiguous KB between 1 -and 16 MB, maximum 0x3C00 = 15 MB. - -@item @code{BX} @tab Extended 2 @tab Number of contiguous 64KB blocks -between 16 MB and 4GB. - -@item @code{CX} @tab Configured 1 @tab Number of contiguous KB between 1 -and 16 MB, maximum 0x3c00 = 15 MB. - -@item @code{DX} @tab Configured 2 @tab Number of contiguous 64KB blocks -between 16 MB and 4 GB. -@end multitable - -Not sure what this difference between the @dfn{Extended} and -@dfn{Configured} numbers are, but they appear to be identical, as -reported from the BIOS. - -It is possible for a machine using this interface to report a memory -hole just under 16 MB (Count 1 is less than 15 MB, but Count 2 is -non-zero). - - -@node Get Extended Memory Size -@section INT 15H, AX=88h interrupt call - -Real mode only. - -This interface is quite primitive. It returns a single value for -contiguous memory above 1 MB. The biggest limitation is that the value -returned is a 16-bit value, in KB, so it has a maximum saturation of -just under 64 MB even presuming it returns as much as it can. On some -systems, it won't return anything above the 16 MB boundary. - -The one useful point is that it works on every PC available. - -Input: - -@multitable @columnfractions 0.15 0.25 0.6 -@item @code{AH} @tab Function Code @tab 88h -@end multitable - -Output: - -@multitable @columnfractions 0.15 0.25 0.6 -@item @code{CF} @tab Carry Flag @tab Non-Carry - indicates no error. - -@item @code{AX} @tab Memory Count @tab Number of contiguous KB above 1 -MB. -@end multitable - - -@node Low-level disk I/O -@chapter INT 13H disk I/O interrupts - -In the PC world, living with the BIOS disk interface is definitely a -nightmare. This section documents how awful the chaos is and how GRUB -deals with the BIOS disks. - -@menu -* CHS Translation:: CHS addressing and LBA addressing -* CHS mode disk I/O:: INT 13H, AH=0xh interrupt call -* LBA mode disk I/O:: INT 13H, AH=4xh interrupt call -@end menu - - -@node CHS Translation -@section CHS addressing and LBA addressing - -CHS --- Cylinder/Head/Sector --- is the traditional way to address -sectors on a disk. There are at least two types of CHS addressing; the -CHS that is used at the INT 13H interface and the CHS that is used at -the ATA device interface. In the MFM/RLL/ESDI and early ATA days the CHS -used at the INT 13H interface was the same as the CHS used at the device -interface. - -Today we have CHS translating BIOS types that can use one CHS at the INT -13H interface and a different CHS at the device interface. These two -types of CHS will be called the logical CHS or @dfn{L-CHS} and the -physical CHS or @dfn{P-CHS} in this section. L-CHS is the CHS used at -the INT 13H interface and P-CHS is the CHS used at the device interface. - -The L-CHS used at the INT 13 interface allows up to 256 heads, up to -1024 cylinders and up to 63 sectors. This allows support of up to 8GB -drives. This scheme started with either ESDI or SCSI adapters many years -ago. - -The P-CHS used at the device interface allows up to 16 heads up to 65535 -cylinders, and up to 63 sectors. This allows access to about 2^26 sectors -(32GB) on an ATA device. When a P-CHS is used at the INT 13H interface -it is limited to 1024 cylinders, 16 heads and 63 sectors. This is where -the old 528MB limit originated. - -LBA --- Logical Block Address --- is another way of addressing sectors -that uses a simple numbering scheme starting with zero as the address of -the first sector on a device. The ATA standard requires that cylinder 0, -head 0, sector 1 address the same sector as addressed by LBA 0. LBA -addressing can be used at the ATA interface if the ATA device supports -it. LBA addressing is also used at the INT 13H interface by the AH=4xH -read/write calls. - -ATA devices may also support LBA at the device interface. LBA allows -access to approximately 2^28 sectors (137GB) on an ATA device. - -A SCSI host adapter can convert a L-CHS directly to an LBA used in the -SCSI read/write commands. On a PC today, SCSI is also limited to 8GB -when CHS addressing is used at the INT 13H interface. - -First, all OS's that want to be co-resident with another OS (and that is -all of the PC based OS's that we know of) @emph{must} use INT 13H to -determine the capacity of a hard disk. And that capacity information -@emph{must} be determined in L-CHS mode. Why is this? Because: - -@enumerate -@item -FDISK and the partition tables are really L-CHS based. - -@item -MS/PC DOS uses INT 13H AH=02H and AH=03H to read and write the disk and -these BIOS calls are L-CHS based. - -@item -The boot processing done by the BIOS is all L-CHS based. -@end enumerate - -During the boot processing, all of the disk read accesses are done in -L-CHS mode via INT 13H and this includes loading the first of the OS's -kernel code or boot manager's code. - -Second, because there can be multiple BIOS types in any one system, each -drive may be under the control of a different type of BIOS. For example, -drive 80H (the first hard drive) could be controlled by the original -system BIOS, drive 81H (the second drive) could be controlled by a -option @sc{rom} BIOS and drive 82H (the third drive) could be controlled -by a software driver. Also, be aware that each drive could be a -different type, for example, drive 80H could be an MFM drive, drive 81H -could be an ATA drive, drive 82H could be a SCSI drive. - -Third, not all OS's understand or use BIOS drive numbers greater than -81H. Even if there is INT 13H support for drives 82H or greater, the OS -may not use that support. - -Fourth, the BIOS INT 13H configuration calls are: - -@table @asis -@item AH=08H, Get Drive Parameters -This call is restricted to drives up to 528MB without CHS translation -and to drives up to 8GB with CHS translation. For older BIOS with no -support for >1024 cylinders or >528MB, this call returns the same CHS as -is used at the ATA interface (the P-CHS). For newer BIOS's that do -support >1024 cylinders or >528MB, this call returns a translated CHS -(the L-CHS). The CHS returned by this call is used by FDISK to build -partition records. - -@item AH=41H, Get BIOS Extensions Support -This call is used to determine if the IBM/Microsoft Extensions or if the -Phoenix Enhanced INT 13H calls are supported for the BIOS drive number. - -@item AH=48H, Extended Get Drive Parameters -This call is used to determine the CHS geometries, LBA information and -other data about the BIOS drive number. -@end table - -An ATA disk must implement both CHS and LBA addressing and must at any -given time support only one P-CHS at the device interface. And, the -drive must maintain a strict relationship between the sector addressing -in CHS mode and LBA mode. Quoting @cite{the ATA-2 document}: - -@example -@group -LBA = ( (cylinder * heads_per_cylinder + heads ) - * sectors_per_track ) + sector - 1 - -where heads_per_cylinder and sectors_per_track are the current -translation mode values. -@end group -@end example - -This algorithm can also be used by a BIOS or an OS to convert a L-CHS to -an LBA. - -This algorithm can be reversed such that an LBA can be converted to a -CHS: - -@example -@group -cylinder = LBA / (heads_per_cylinder * sectors_per_track) - temp = LBA % (heads_per_cylinder * sectors_per_track) - head = temp / sectors_per_track - sector = temp % sectors_per_track + 1 -@end group -@end example - -While most OS's compute disk addresses in an LBA scheme, an OS like DOS -must convert that LBA to a CHS in order to call INT 13H. - -The basic problem is that there is no requirement that a CHS translating -BIOS followed these rules. There are many other algorithms that can be -implemented to perform a similar function. Today, there are at least two -popular implementations: the Phoenix implementation (described above) and -the non-Phoenix implementations. Because a protected mode OS that does -not want to use INT 13H must implement the same CHS translation -algorithm. If it doesn't, your data gets scrambled. - -In the perfect world of tomorrow, maybe only LBA will be used. But today -we are faced with the following problems: - -@itemize @bullet -@item -Some drives >528MB don't implement LBA. - -@item -Some drives are optimized for CHS and may have lower performance when -given commands in LBA mode. Don't forget that LBA is something new for -the ATA disk designers who have worked very hard for many years to -optimize CHS address handling. And not all drive designs require the use -of LBA internally. - -@item -The L-CHS to LBA conversion is more complex and slower than the bit -shifting L-CHS to P-CHS conversion. - -@item -DOS, FDISK and the MBR are still CHS based --- they use the CHS returned -by INT 13H AH=08H. Any OS that can be installed on the same disk with -DOS must understand CHS addressing. - -@item -The BIOS boot processing and loading of the first OS kernel code is done -in CHS mode --- the CHS returned by INT 13H AH=08H is used. - -@item -Microsoft has said that their OS's will not use any disk capacity that -can not also be accessed by INT 13H AH=0xH. -@end itemize - -These are difficult problems to overcome in today's industry -environment. The result: chaos. - - -@node CHS mode disk I/O -@section INT 13H, AH=0xh interrupt call - -Real mode only. These functions are the traditional CHS mode disk -interface. GRUB calls them only if LBA mode is not available. - -INT 13H, AH=02h reads sectors into memory. - -Input: - -@multitable @columnfractions .15 .85 -@item @code{AH} @tab 02h - -@item @code{AL} @tab The number of sectors to read (must be non-zero). - -@item @code{CH} @tab Low 8 bits of cylinder number. - -@item @code{CL} @tab Sector number in bits 0-5, and high 2 bits of -cylinder number in bits 6-7. - -@item @code{DH} @tab Head number. - -@item @code{DL} @tab Drive number (bit 7 set for hard disk). - -@item @code{ES:BX} @tab Data buffer. -@end multitable - -Output: - -@multitable @columnfractions .15 .85 -@item @code{CF} @tab Set on error. - -@item @code{AH} @tab Status. - -@item @code{AL} @tab The number of sectors transferred (only valid if CF -set for some BIOSes). -@end multitable - -INT 13H, AH=03h writes disk sectors. - -Input: - -@multitable @columnfractions .15 .85 -@item @code{AH} @tab 03h - -@item @code{AL} @tab The number of sectors to write (must be non-zero). - -@item @code{CH} @tab Low 8 bits of cylinder number. - -@item @code{CL} @tab Sector number in bits 0-5, and high 2 bits of -cylinder number in bits 6-7. - -@item @code{DH} @tab Head number. - -@item @code{DL} @tab Drive number (bit 7 set for hard disk). - -@item @code{ES:BX} @tab Data buffer. -@end multitable - -Output: - -@multitable @columnfractions .15 .85 -@item @code{CF} @tab Set on error. - -@item @code{AH} @tab Status. - -@item @code{AL} @tab The number of sectors transferred (only valid if CF -set for some BIOSes). -@end multitable - -INT 13H, AH=08h returns drive parameters. For systems predating the IBM -PC/AT, this call is only valid for hard disks. - -Input: - -@multitable @columnfractions .15 .85 -@item @code{AH} @tab 08h - -@item @code{DL} @tab Drive number (bit 7 set for hard disk). -@end multitable - -Output: - -@multitable @columnfractions .15 .85 -@item @code{CF} @tab Set on error. - -@item @code{AH} @tab 0. - -@item @code{AL} @tab 0 on at least some BIOSes. - -@item @code{BL} @tab Drive type (AT/PS2 floppies only). - -@item @code{CH} @tab Low 8 bits of maximum cylinder number. - -@item @code{CL} @tab Maximum sector number in bits 0-5, and high 2 bits -of maximum cylinder number in bits 6-7. - -@item @code{DH} @tab Maximum head number. - -@item @code{DL} @tab The number of drives. - -@item @code{ES:DI} @tab Drive parameter table (floppies only). -@end multitable - - -@node LBA mode disk I/O -@section INT 13H, AH=4xh interrupt call - -Real mode only. These functions are IBM/MS INT 13 Extensions to support -LBA mode. GRUB uses them if available so that it can read/write over 8GB -area. - -INT 13, AH=41h checks if LBA is supported. - -Input: - -@multitable @columnfractions 0.15 0.85 -@item @code{AH} @tab 41h. - -@item @code{BX} @tab 55AAh. - -@item @code{DL} @tab Drive number. -@end multitable - -Output: - -@multitable @columnfractions 0.15 0.85 -@item @code{CF} @tab Set on error. - -@item @code{AH} @tab Major version of extensions (10h for 1.x, 20h for -2.0 / EDD-1.0, 21h for 2.1 / EDD-1.1 and 30h for EDD-3.0) if successful, -otherwise 01h (the error code of @dfn{invalid function}). - -@item @code{BX} @tab AA55h if installed. - -@item @code{AL} @tab Internal use. - -@item @code{CX} @tab API subset support bitmap (see below). - -@item @code{DH} @tab Extension version. -@end multitable - -The bitfields for the API subset support bitmap are@footnote{It is known -that (at least) the AMI BIOS in SuperMicro P6SBA motherboard -(AMIBIOSC0631) does @emph{not} return the bitfields correctly.}: - -@multitable @columnfractions 0.15 0.85 -@item Bit(s) @tab Description - -@item 0 @tab Extended disk access functions (AH=42h-44h, 47h, 48h) -supported. - -@item 1 @tab Removable drive controller functions (AH=45h, 46h, 48h, -49h, INT 15H, AH=52h) supported. - -@item 2 @tab Enhanced disk drive (EDD) functions (AH=48h, 4Eh) -supported. - -@item 3-15 @tab Reserved (0). -@end multitable - -INT 13, AH=42h reads sectors into memory. - -Input: - -@multitable @columnfractions .15 .85 -@item @code{AH} @tab 42h. - -@item @code{DL} @tab Drive number. - -@item @code{DS:SI} @tab Disk Address Packet (see below). -@end multitable - -Output: - -@multitable @columnfractions .15 .85 -@item @code{CF} @tab Set on error. - -@item @code{AH} @tab 0 if successful, otherwise error code. -@end multitable - -The format of @dfn{Disk Address Packet} is: - -@multitable @columnfractions 0.15 0.15 0.7 -@item Offset (hex) @tab Size (byte) @tab Description - -@item 00 @tab 1 @tab 10h (The size of packet). - -@item 01 @tab 1 @tab Reserved (0). - -@item 02 @tab 2 @tab The number of blocks to transfer (max 007F for -Phoenix EDD). - -@item 04 @tab 4 @tab Transfer buffer (SEGMENT:OFFSET). - -@item 08 @tab 8 @tab Starting absolute block number. -@end multitable - -INT 13, AH=43h writes disk sectors. - -Input: - -@multitable @columnfractions 0.15 0.85 -@item @code{AH} @tab 43h. - -@item @code{AL} @tab Write flags (In version 1.0 and 2.0, bit 0 is the -flag for @dfn{verify write} and other bits are reserved (0). In version -2.1, 00h and 01h indicates @dfn{write without verify}, and 02h indicates -@dfn{write with verify}. - -@item @code{DL} @tab Drive number. - -@item @code{DS:SI} @tab Disk Address Packet (see above). -@end multitable - -Output: - -@multitable @columnfractions 0.15 0.85 -@item @code{CF} @tab Set on error. - -@item @code{AH} @tab 0 if successful, otherwise error code. -@end multitable - -INT 13, AH=48h returns drive parameters. GRUB only makes use of the -total number of sectors, and ignore the CHS information, because only -L-CHS makes sense. @xref{CHS Translation}, for more information. - -Input: - -@multitable @columnfractions 0.15 0.85 -@item @code{AH} @tab 48h. - -@item @code{DL} @tab Drive number. - -@item @code{DS:SI} @tab Buffer for drive parameters (see below). -@end multitable - -Output: - -@multitable @columnfractions 0.15 0.85 -@item @code{CF} @tab Set on error. - -@item @code{AH} @tab 0 if successful, otherwise error code. -@end multitable - -The format of drive parameters is: - -@multitable @columnfractions 0.25 0.15 0.6 -@item Offset (hex) @tab Size (byte) @tab Description - -@item 00 @tab 2 @tab The size of buffer. Before calling this function, -set to the maximum buffer size, at least 1Ah. The size actually filled -is returned (1Ah for version 1.0, 1Eh for 2.x and 42h for 3.0). - -@item 02 @tab 2 @tab Information flags (see below). - -@item 04 @tab 4 @tab The number of physical cylinders. - -@item 08 @tab 4 @tab The number of physical heads. - -@item 0C @tab 4 @tab The number of physical sectors per track. - -@item 10 @tab 8 @tab The total number of sectors. - -@item 18 @tab 2 @tab The bytes per sector. - -@comment Add an empty row for readability... -@item @tab @tab - -@item @strong{v2.0 and later} @tab @tab - -@item 1A @tab 4 @tab EDD configuration parameters. - -@comment Add an empty row for readability... -@item @tab @tab - -@item @strong{v3.0} @tab @tab - -@item 1E @tab 2 @tab Signature BEDD to indicate presence of Device Path -information. - -@item 20 @tab 1 @tab The length of Device Path information, including -signature and this byte (24h for version 3.0). - -@item 21 @tab 3 @tab Reserved (0). - -@item 24 @tab 4 @tab ASCIZ name of host bus (@samp{ISA} or @samp{PCI}). - -@item 28 @tab 8 @tab ASCIZ name of interface type (@samp{ATA}, -@samp{ATAPI}, @samp{SCSI}, @samp{USB}, @samp{1394} or @samp{FIBRE}). - -@item 30 @tab 8 @tab Interface Path. - -@item 38 @tab 8 @tab Device Path. - -@item 40 @tab 1 @tab Reserved (0). - -@item 41 @tab 1 @tab Checksum of bytes 1Eh-40h (2's complement of sum, -which makes the 8 bit sum of bytes 1Eh-41h equal to 00h). -@end multitable - -The information flags are: - -@multitable @columnfractions 0.15 0.85 -@item Bit(s) @tab Description - -@item 0 @tab DMA boundary errors handles transparently. - -@item 1 @tab CHS information is valid. - -@item 2 @tab Removable drive. - -@item 3 @tab Write with verify supported. - -@item 4 @tab Drive has change-line support (required if drive is -removable). - -@item 5 @tab Drive can be locked (required if drive is removable). - -@item 6 @tab CHS information set to maximum supported values, not -current media. - -@item 7-15 @tab Reserved (0). -@end multitable - - -@node MBR -@chapter The structure of Master Boot Record - -A Master Boot Record (@dfn{MBR}) is the sector at cylinder 0, head 0, -sector 1 of a hard disk. A MBR-like structure must be created in each of -partitions by the FDISK program. - -At the completion of your system's Power On Self Test (@dfn{POST}), INT -19H is called. Usually INT 19 tries to read a boot sector from the first -floppy drive@footnote{Which drive is read first depends on your BIOS -settings.}. If a boot sector is found on the floppy disk, that boot -sector is read into memory at location 0000:7C00 and INT 19H jumps to -memory location 0000:7C00. However, if no boot sector is found on the -first floppy drive, INT 19H tries to read the MBR from the first hard -drive. If an MBR is found it is read into memory at location 0000:7C00 -and INT 19H jumps to memory location 0000:7C00. The small program in the -MBR will attempt to locate an active (bootable) partition in its -partition table@footnote{This behavior is DOS MBR's, and GRUB ignores -the active flag.}. The small program in the boot sector must locate the -first part of the operating system's kernel loader program (or perhaps -the kernel itself or perhaps a @dfn{boot manager program}) and read that -into memory. - -INT 19H is also called when the @key{CTRL}-@key{ALT}-@key{DEL} keys are -used. On most systems, @key{CTRL}-@key{ALT}-@key{DEL} causes an short -version of the POST to be executed before INT 19H is called. - -The stuff is: - -@table @asis -@item Offset 0000 -The address where the MBR code starts. - -@item Offset 01BE -The address where the partition table starts (@pxref{Partition table}). - -@item Offset 01FE -The signature, AA55. -@end table - -However, the first 62 bytes of a boot sector are known as the BIOS -Parameter Block (@dfn{BPB}), so GRUB cannot use these bytes for its own -purpose. - -If an active partition is found, that partition's boot record is read -into 0000:7C00 and the MBR code jumps to 0000:7C00 with @code{SI} -pointing to the partition table entry that describes the partition being -booted. The boot record program uses this data to determine the drive -being booted from and the location of the partition on the disk. - -The first byte of an active partition table entry is 80. This byte is -loaded into the @code{DL} register before INT 13H is called to read the -boot sector. When INT 13H is called, @code{DL} is the BIOS device -number. Because of this, the boot sector read by this MBR program can -only be read from BIOS device number 80 (the first hard disk). This is -one of the reasons why it is usually not possible to boot from any other -hard disk. - - -@node Partition table -@chapter The format of partition table - -@menu -* Partition basics:: Overview the partition table -* Partition types:: The list of the @dfn{type} code -* Partition entry format:: The format of the table entry -* Partition table rules:: Some basic rules for partition table -@end menu - - -@node Partition basics -@section Overview the partition table - -FDISK creates all partition records (sectors). The primary purpose of a -partition record is to hold a partition table. The rules for how FDISK -works are unwritten but so far most FDISK programs seem to follow the -same basic idea. - -First, all partition table records (sectors) have the same format. This -includes the partition table record at cylinder 0, head 0, sector 1 -- -what is known as the Master Boot Record (MBR). The last 66 bytes of a -partition table record contain a partition table and a 2 byte -signature. The first 446 bytes of these sectors usually contain a -program but only the program in the MBR is ever executed (so extended -partition table records could contain something other than a program in -the first 466 bytes). For more information, see @ref{MBR}. - -Second, extended partitions are @emph{nested} inside one another and -extended partition table records form a @dfn{linked list}. We will -attempt to show this in a diagram at @ref{Partition entry format}. - -Each partition table entry is 16 bytes and contains things like the -start and end location of a partition in CHS, the start in LBA, the size -in sectors, the partition @dfn{type} and the @dfn{active} flag. Older -versions of FDISK may compute incorrect LBA or size values. And when -your computer boots itself, only the CHS fields of the partition table -entries are used (another reason LBA doesn't solve the >528MB -problem). The CHS fields in the partition tables are in L-CHS format, -see @ref{CHS Translation}. - - -@node Partition types -@section The list of the @dfn{type} code - -There is no central clearing house to assign the codes used in the one -byte @dfn{type} field. But codes are assigned (or used) to define most -every type of file system that anyone has ever implemented on the x86 -PC: 12-bit FAT, 16-bit FAT, HPFS, NTFS, etc. Plus, an extended partition -also has a unique type code. - -In the FDISK program @samp{sfdisk}, the following list is assumed: - -@table @asis -@item 00 -Empty - -@item 01 -DOS 12-bit FAT - -@item 02 -XENIX / - -@item 03 -XENIX /usr - -@item 04 -DOS 16-bit FAT <32M - -@item 05 -DOS Extended - -@item 06 -DOS 16-bit FAT >=32M - -@item 07 -HPFS / NTFS - -@item 08 -AIX boot or SplitDrive - -@item 09 -AIX data or Coherent - -@item 0A -OS/2 Boot Manager - -@item 0B -Windows95 FAT32 - -@item 0C -Windows95 FAT32 (LBA) - -@item 0E -Windows95 FAT16 (LBA) - -@item 0F -Windows95 Extended (LBA) - -@item 10 -OPUS - -@item 11 -Hidden DOS FAT12 - -@item 12 -Compaq diagnostics - -@item 14 -Hidden DOS FAT16 - -@item 16 -Hidden DOS FAT16 (big) - -@item 17 -Hidden HPFS/NTFS - -@item 18 -AST Windows swapfile - -@item 24 -NEC DOS - -@item 3C -PartitionMagic recovery - -@item 40 -Venix 80286 - -@item 41 -Linux/MINIX (sharing disk with DRDOS) - -@item 42 -SFS or Linux swap (sharing disk with DRDOS) - -@item 43 -Linux native (sharing disk with DRDOS) - -@item 50 -DM (disk manager) - -@item 51 -DM6 Aux1 (or Novell) - -@item 52 -CP/M or Microsoft SysV/AT - -@item 53 -DM6 Aux3 - -@item 54 -DM6 - -@item 55 -EZ-Drive (disk manager) - -@item 56 -Golden Bow (disk manager) - -@item 5C -Priam Edisk (disk manager) - -@item 61 -SpeedStor - -@item 63 -GNU Hurd or Mach or Sys V/386 (such as ISC UNIX)@footnote{But the reason -why they decided that 63 means GNU Hurd is not known. Do not use 63 for -GNU Hurd, but use 83 for ext2fs, and A5 for FFS.} - -@item 64 -Novell Netware 286 - -@item 65 -Novell Netware 386 - -@item 70 -DiskSecure Multi-Boot - -@item 75 -PC/IX - -@item 77 -QNX4.x - -@item 78 -QNX4.x 2nd part - -@item 79 -QNX4.x 3rd part - -@item 80 -MINIX until 1.4a - -@item 81 -MINIX / old Linux - -@item 82 -Linux swap - -@item 83 -Linux native@footnote{This is not necessarily true. GNU Hurd uses 83 for -ext2fs partitions.} - -@item 84 -OS/2 hidden C: drive - -@item 85 -Linux extended - -@item 86 -NTFS volume set - -@item 87 -NTFS volume set - -@item 93 -Amoeba - -@item 94 -Amoeba BBT - -@item A0 -IBM Thinkpad hibernation - -@item A5 -BSD/386 - -@item A7 -NeXTSTEP 486 - -@item B7 -BSDI fs - -@item B8 -BSDI swap - -@item C1 -DRDOS/sec (FAT-12) - -@item C4 -DRDOS/sec (FAT-16, < 32M) - -@item C6 -DRDOS/sec (FAT-16, >= 32M) - -@item C7 -Syrinx - -@item DB -CP/M or Concurrent CP/M or Concurrent DOS or CTOS - -@item E1 -DOS access or SpeedStor 12-bit FAT extended partition - -@item E3 -DOS R/O or SpeedStor - -@item E4 -SpeedStor 16-bit FAT extended partition < 1024 cyl. - -@item F1 -SpeedStor - -@item F2 -DOS 3.3+ secondary - -@item F4 -SpeedStor large partition - -@item FE -SpeedStor >1024 cyl. or LANstep - -@item FF -Xenix Bad Block Table -@end table - -@node Partition entry format -@section The format of the table entry - -The 16 bytes of a partition table entry are used as follows: - -@example -@group - +--- Bit 7 is the active partition flag, bits 6-0 are zero. - | - | +--- Starting CHS in INT 13 call format. - | | - | | +--- Partition type byte. - | | | - | | | +--- Ending CHS in INT 13 call format. - | | | | - | | | | +-- Starting LBA. - | | | | | - | | | | | +-- Size in sectors. - | | | | | | - v <--+---> v <--+--> v v - - 0 1 2 3 4 5 6 7 8 9 A B C D E F - DH DL CH CL TB DL CH CL LBA..... SIZE.... - - 80 01 01 00 06 0e be 94 3e000000 0c610900 1st entry - - 00 00 81 95 05 0e fe 7d 4a610900 724e0300 2nd entry - - 00 00 00 00 00 00 00 00 00000000 00000000 3rd entry - - 00 00 00 00 00 00 00 00 00000000 00000000 4th entry -@end group -@end example - -Bytes 0-3 are used by the small program in the Master Boot Record to -read the first sector of an active partition into memory. The @dfn{DH}, -@dfn{DL}, @dfn{CH} and @dfn{CL} above show which x86 register is loaded -when the MBR program calls INT 13H AH=02h to read the active partition's -boot sector. For more information, see @ref{MBR}. - -These entries define the following partitions: - -@enumerate -@item -The first partition, a primary partition DOS FAT, starts at CHS 0H,1H,1H -(LBA 3EH) and ends at CHS 294H,EH,3EH with a size of 9610CH sectors. - -@item -The second partition, an extended partition, starts at CHS 295H,0H,1H -(LBA 9614AH) and ends at CHS 37DH,EH,3EH with a size of 34E72H sectors. - -@item -The third and fourth table entries are unused. -@end enumerate - - -@node Partition table rules -@section Some basic rules for partition table - -Keep in mind that there are @emph{no} written rules and @emph{no} -industry standards on how FDISK should work but here are some basic -rules that seem to be followed by most versions of FDISK: - -@enumerate -@item -In the MBR there can be 0-4 @dfn{primary} partitions, OR, 0-3 primary -partitions and 0-1 extended partition entry. - -@item -In an extended partition there can be 0-1 @dfn{secondary} partition -entries and 0-1 extended partition entries. - -@item -Only 1 primary partition in the MBR can be marked @dfn{active} at any -given time. - -@item -In most versions of FDISK, the first sector of a partition will be -aligned such that it is at head 0, sector 1 of a cylinder. This means -that there may be unused sectors on the track(s) prior to the first -sector of a partition and that there may be unused sectors following a -partition table sector. - -For example, most new versions of FDISK start the first partition -(primary or extended) at cylinder 0, head 1, sector 0. This leaves the -sectors at cylinder 0, head 0, sectors 2...n as unused sectors. This -same layout may be seen on the first track of an extended partition. -See example 2 below. - -Also note that software drivers like Ontrack's Disk Manager depend on -these unused sectors because these drivers will @dfn{hide} their code -there (in cylinder 0, head 0, sectors 2...n). This is also a good place -for boot sector virus programs to hang out. - -@item -The partition table entries (slots) can be used in any order. Some -versions of FDISK fill the table from the bottom up and some versions of -FDISK fill the table from the top down. Deleting a partition can leave -an unused entry (slot) in the middle of a table. - -@item -And then there is the @dfn{hack} that some newer OS's (OS/2 and Linux) -use in order to place a partition spanning or passed cylinder 1024 on a -system that does not have a CHS translating BIOS. These systems create a -partition table entry with the partition's starting and ending CHS -information set to all FFH. The starting and ending LBA information is -used to describe the location of the partition. The LBA can be converted -back to a CHS --- most likely a CHS with more than 1024 cylinders. Since -such a CHS can't be used by the system BIOS, these partitions can not be -booted or accessed until the OS's kernel and hard disk device drivers -are loaded. It is not known if the systems using this @dfn{hack} follow -the same rules for the creation of these type of partitions. -@end enumerate - -There are @emph{no} written rules as to how an OS scans the partition -table entries so each OS can have a different method. For DOS, this -means that different versions could assign different drive letters to -the same FAT file system partitions. diff --git a/docs/stamp-vti b/docs/stamp-vti index b8bcdfaff..3b7efa5d7 100644 --- a/docs/stamp-vti +++ b/docs/stamp-vti @@ -1,3 +1,3 @@ -@set UPDATED 22 October 2000 +@set UPDATED 8 February 2001 @set EDITION 0.5.97 @set VERSION 0.5.97 diff --git a/docs/tutorial.texi b/docs/tutorial.texi deleted file mode 100644 index 39e462153..000000000 --- a/docs/tutorial.texi +++ /dev/null @@ -1,1040 +0,0 @@ -@node Overview -@chapter 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 filename and the -drive (and the partition) where the kernel resides. To let GRUB know the -drive and the filename, you can either type in them manually via the -command-line interface (@pxref{Command line}), 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. - - -@c @node Fundamentals -@c @chapter Introduction to the technical basic knowledge -@c -@c I'm going to include Bill White's documentation here, once his -@c copyright problem will be solved. - - -@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}) 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 filenames, 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 -@file{/usr/share/grub/i386-pc} directory. You need to copy the files -@file{stage1}, @file{stage2}, and @file{*stage1_5} to the directory -@file{/boot/grub}. - -@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 @file{/boot/grub} directory, and write them to -the first and the second block of the floppy disk, respectively. - -@quotation -@strong{Caution:} This procedure will destroy any data currently stored -on the floppy. -@end quotation - -On a UNIX-like operating system, that is done with the following -commands: - -@example -@group -# @kbd{cd /boot/grub} -# @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 filename may be different. Consult the manual for your OS. - - -@node Installing GRUB natively -@section Installing GRUB natively - -@quotation -@strong{Caution:} Installing GRUB's stage1 in this manner will erase the -normal boot-sector used by an OS. -@end quotation - -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}). First, set the GRUB's @dfn{root device}@footnote{Note that -GRUB's root device doesn't necessarily mean your OS's root partition; if -you need to specify a root partition for your OS, add the argument into -the command @command{kernel}.} to the partition which has your GRUB -images, like this: - -@example -grub> @kbd{root (hd0,0)} -@end example - -If you are not sure which partition actually holds these files, use the -@command{find} command, like this: - -@example -grub> @kbd{find /boot/grub/stage1} -@end example - -This will search for the filename @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}: - -@example -grub> @kbd{setup (hd0)} -@end example - -This command will install GRUB on the MBR (@pxref{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 - -Unfortunately, if you do want to install GRUB under a UNIX-like OS (such -as @sc{gnu}), invoke the program @command{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 you may already know, 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 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:: -* OS-specific notes:: -@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 by 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}. - -@item -Load the kernel image by the command @command{kernel}. - -@item -If you need modules, load them with the command @command{module} or -@command{modulenounzip}. - -@item -Run the command @command{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 -filename 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. - -First, set GRUB's root device to the partition by the command -@command{rootnoverify}: - -@example -grub> @kbd{rootnoverify (hd0,0)} -@end example - -Second, 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.}: - -@example -grub> @kbd{makeactive} -@end example - -Third, load the boot loader by the command @command{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{Filesystem}. If this succeeds, run the command @command{boot}. - -However, DOS and Windows have a deficiency, so you might have to use -more complicated instructions. @xref{OS-specific notes}, 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. - -@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}. -@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. - -@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} after -@command{kernel}: - -@example -grub> @kbd{initrd /initrd} -@end example - -@item -Finally, run the command @command{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{Command-line and menu entry commands}, 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}. - -@item -Load the kernel with @command{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}. -@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{Commands}), 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, it ignores the -partition. If GRUB @dfn{unhide}s a DOS (or Windows) partition, 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}, 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{/boot/grub/menu.lst}. 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}). - -@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 -# Boot automatically after 30 secs. -timeout 30 -@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}, and the action is -described after it. Note that there is no command @command{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, 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. - -@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, 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 and the User -Reference Manual (@pxref{Introduction}). - - -@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 server that will assign an IP address to the machine on -which GRUB is running, and a file server. The former is either BOOTP, -DHCP or a RARP server (RARP is deprecated, since it cannot serve much -information). For the latter, only TFTP is supported at the moment. 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. - -Once you have set up the servers, run @command{bootp}, @command{dhcp} -or @command{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. - -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}. 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 details. The -topic is beyond the scope of this documentation. - -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{Commands}, -for more details. - -The command @command{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. - - -@node Security -@chapter Security - -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}. 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, 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}. 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 the -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}. 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. diff --git a/docs/user-ref.texi b/docs/user-ref.texi deleted file mode 100644 index 39314cbb5..000000000 --- a/docs/user-ref.texi +++ /dev/null @@ -1,1702 +0,0 @@ -@node Introduction -@chapter Introduction - -This part documents the user-visible aspect of GRUB. If you are looking -for the information on the internals, see the Programmer Reference -Manual (@pxref{Hacking}). - -@menu -* History:: From maggot to house fly. -* Features:: How GRUB is different. -* Role of a boot loader:: Judging a system by its boot loader. -@end menu - - -@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 Multiple Executable Formats -Supports many of the @dfn{a.out} variants plus @dfn{ELF}. Symbol -tables are also loaded. - -@item Support Non-Multiboot Kernels -Supports 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 -GRUB fully supports the Multiboot feature of loading multiple modules. - -@item Configuration File -Supports a human-readable text configuration file with preset boot -commands. 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 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 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 Multiple Filesystem Types -Supports 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 Decompression Support -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 file size and 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 -Supports reading data from any or all floppy or hard disk(s) recognized -by the BIOS, independent of the setting of the root device. - -@item Independent of Drive Geometry Translation -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 (@pxref{Memory detection}). 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 Network support -GRUB is 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 Remote terminal support -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 - -Future directions might include an internal programming language for -supporting richer sets of boot options with control statements (which -would make GRUB its own kind of kernel). Support for non-PC hardware -architectures is also planned.@footnote{There is already a port to the -NEC PC-98xx series. See -@url{http://www.kmc.kyoto-u.ac.jp/proj/linux98/arch/i386/boot/grub98/}, -for more information.} - - -@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 GRUB images -@chapter GRUB images - -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. See @ref{Hacking}, 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{Commands}). - -@menu -* Device syntax:: How to specify devices -* Filename syntax:: How to specify files -* Blocklist syntax:: How to specify blocklists -@end menu - - -@node Device syntax -@section How to specify devices - -The device syntax is like this: - -@example -@code{(@var{bios-device}[,@var{part-num}][,@var{bsd-subpart-letter}])} -@end example - -@samp{[]} means the parameter is optional. @var{bios-device} should be -either @samp{fd} or @samp{hd} followed by a digit, like @samp{fd0}. -But you can also set @var{bios-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{bios-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{bios-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 Filename syntax -@section How to specify files - -There are two ways to specify files, by @dfn{absolute filename} and by -@dfn{blocklist}. - -An absolute filename resembles a Unix absolute filename, 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 filename, 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}, then -@code{/boot/kernel} is the same as @code{(hd1,0)/boot/kernel}. - - -@node Blocklist syntax -@section How to specify blocklists - -A blocklist 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 filename syntax (@pxref{Filename 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:: The flexible command line interface. -* Menu interface:: The simple menu interface. -* Menu entry editor:: Editing a menu entry. -@end menu - - -@node Command line -@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{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 filenames depending on the -context. - -Note that you cannot use the completion functionality in the TFTP -filesystem. This is because TFTP doesn't support filename 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}. - - -@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 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: - -@deffn Command default num -Set the default entry to the entry number @var{num}. Numbering starts -from 0, and entry number 0 is the default if the command is not used. -@end deffn - -@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). This obviously won't help if the machine was rebooted by a -kernel that GRUB loaded. -@end deffn - -@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. -@end deffn - -@deffn Command timeout sec -Set a timeout, in @var{sec} seconds, before automatically booting the -default entry (normally the first entry defined). -@end deffn - -@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. - -@deffn Command bootp -Initialize a network device via the @dfn{BOOTP} protocol. This command -is only available if GRUB is compiled with netboot support. -@end deffn - -@deffn Command color normal [highlight] -Change the menu colors. The color @var{normal} is used for most -lines in the menu, 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 -# Set default colors. -color light-gray/blue black/light-gray - -# Change the colors. -title OS-BS like -color magenta/blue black/magenta -@end example -@end deffn - -@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 -grub> @kbd{device (fd0) /floppy-image} -grub> @kbd{device (hd0) /dev/sd0} -@end example - -This command can be used only in the grub shell (@pxref{Invoking the -grub shell}). -@end deffn - -@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. -@end deffn - -@deffn Command hide partition -Hide @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. -@end deffn - -@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 - -@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 - -@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 md5crypt. -@end deffn - -@deffn Command rarp -Initialize a network device via the @dfn{RARP} protocol. This command -is only available if GRUB is compiled with netboot support. -@end deffn - -@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. - -The serial port is not used as a communication channel unless the -@command{terminal} command is used. - -This command is only available if GRUB is compiled with serial support. -@end deffn - -@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 - -@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. Default is @option{console}. This command is only available if -GRUB is compiled with serial support. -@end deffn - -@deffn Command tftpserver ipaddr -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. -@end deffn - -@deffn Command unhide partition -Unhide @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. -@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}. - -@deffn Command blocklist file -Print the blocklist notation of the file @var{file} (@pxref{Blocklist -syntax}). -@end deffn - -@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 - -@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 - -@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. -@end deffn - -@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 - -@deffn Command configfile file -Load @var{file} as a configuration file. -@end deffn - -@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 - -@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 - -@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. -@end deffn - -@deffn Command find filename -Search for the filename @var{filename} in all of partitions and print -the list of the devices which contain the file. The filename -@var{filename} should be an absolute filename like -@code{/boot/grub/stage1}. -@end deffn - -@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} -or @command{testload} commands. -@end deffn - -@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 - -@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 - -@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 - -@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 - -@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. -@end deffn - -@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. 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 filename @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 - -@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{I/O ports -detection}. -@end deffn - -@deffn Command kernel [@option{--type=type}] 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. -@end deffn - -@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. - -This command is used in a menu, as shown in this this example: - -@example -title This entry is too dangerous to be executed by normal users -lock -root (hd0,a) -kernel /no-security-os -@end example -@end deffn - -@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 - -@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 -grub> @kbd{map (hd0) (hd1)} -grub> @kbd{map (hd1) (hd0)} -@end example - -The example exchanges the order between the first hard disk and the -second hard disk. -@end deffn - -@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. -@end deffn - -@deffn Command modulenounzip file @dots{} -The same as @command{module}, except that automatic decompression is -disabled. -@end deffn - -@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 - -@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 - -@deffn Command reboot -Reboot the computer. -@end deffn - -@deffn Command read addr -Read a 32-bit value from memory at address @var{addr} and display it in -hex format. -@end deffn - -@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}. -@end deffn - -@deffn Command rootnoverify device [hdbias] -Similar to @command{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 - -@deffn Command savedefault -Save the current menu entry as a default entry. -@end deffn - -@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} in the backend and installs GRUB -into the device @var{install_device}. If @var{image_device} is -specified, then find the GRUB 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. See the description on -@command{install}, for more information. -@end deffn - -@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 - -@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 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 filename 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 filename 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 filename -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 filename 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 -#!/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 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 filename @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 -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 filename, like this: - -@example -grub-install --grub-shell="grub --read-only" /dev/fd0 -@end example -@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 diff --git a/docs/version.texi b/docs/version.texi index b8bcdfaff..3b7efa5d7 100644 --- a/docs/version.texi +++ b/docs/version.texi @@ -1,3 +1,3 @@ -@set UPDATED 22 October 2000 +@set UPDATED 8 February 2001 @set EDITION 0.5.97 @set VERSION 0.5.97