1\input texinfo 2@c -*-texinfo-*- 3@c %**start of header 4@setfilename grub.info 5@settitle GRUB Manual 6@c %**end of header 7 8@include version.texi 9 10@c Unify all our little indices for now. 11@syncodeindex fn cp 12@syncodeindex vr cp 13@syncodeindex ky cp 14@syncodeindex pg cp 15@syncodeindex tp cp 16 17@footnotestyle separate 18@paragraphindent 3 19@finalout 20 21@dircategory Kernel 22@direntry 23* GRUB: (grub). The GRand Unified Bootloader 24* grub-install: (grub)Invoking grub-install. Install GRUB on your drive 25* grub-md5-crypt: (grub)Invoking grub-md5-crypt. Encrypt a password 26 in MD5 format 27* grub-terminfo: (grub)Invoking grub-terminfo. Generate a terminfo 28 command from a 29 terminfo name 30* grub-set-default: (grub)Invoking grub-set-default. Set a default boot 31 entry 32* mbchk: (grub)Invoking mbchk. Check for the format of a Multiboot kernel 33@end direntry 34 35@setchapternewpage odd 36 37@ifinfo 38Copyright @copyright{} 1999,2000,2001,2002,2004 Free Software Foundation, Inc. 39 40Permission is granted to make and distribute verbatim copies of 41this manual provided the copyright notice and this permission notice 42are preserved on all copies. 43 44@ignore 45Permission is granted to process this file through TeX and print the 46results, provided the printed document carries a copying permission 47notice identical to this one except for the removal of this paragraph 48(this paragraph not being relevant to the printed manual). 49 50@end ignore 51 52Permission is granted to copy and distribute modified versions of this 53manual under the conditions for verbatim copying, provided also that 54the entire resulting derived work is distributed under the terms of a 55permission notice identical to this one. 56 57Permission is granted to copy and distribute translations of this manual 58into another language, under the above conditions for modified versions. 59@end ifinfo 60 61@titlepage 62@sp 10 63@title the GRUB manual 64@subtitle The GRand Unified Bootloader, version @value{VERSION}, @value{UPDATED}. 65@author Gordon Matzigkeit 66@author Yoshinori K. Okuji 67@c The following two commands start the copyright page. 68@page 69@vskip 0pt plus 1filll 70Copyright @copyright{} 1999,2000,2001,2002,2004 Free Software Foundation, Inc. 71 72Permission is granted to make and distribute verbatim copies of 73this manual provided the copyright notice and this permission notice 74are preserved on all copies. 75Permission is granted to copy and distribute modified versions of this 76manual under the conditions for verbatim copying, provided that the entire 77resulting derived work is distributed under the terms of a permission 78notice identical to this one. 79 80Permission is granted to copy and distribute translations of this manual 81into another language, under the above conditions for modified versions, 82except that this permission notice may be stated in a translation approved 83by Free Software Foundation. 84@end titlepage 85 86@c Output the table of contents at the beginning. 87@contents 88 89@finalout 90@headings double 91 92@ifnottex 93@node Top 94@top GRUB manual 95 96This is the documentation of GNU GRUB, the GRand Unified Bootloader, 97a flexible and powerful boot loader program for @sc{pc}s. 98 99This edition documents version @value{VERSION}. 100@end ifnottex 101 102@menu 103* Introduction:: Capturing the spirit of GRUB 104* Naming convention:: Names of your drives in GRUB 105* Installation:: Installing GRUB on your drive 106* Booting:: How to boot different operating systems 107* Configuration:: Writing your own configuration file 108* Network:: Downloading OS images from a network 109* Serial terminal:: Using GRUB via a serial line 110* Preset Menu:: Embedding a configuration file into GRUB 111* Security:: Improving the security 112* Images:: GRUB image files 113* Filesystem:: Filesystem syntax and semantics 114* Interface:: The menu and the command-line 115* Commands:: The list of available builtin commands 116* Troubleshooting:: Error messages produced by GRUB 117* Invoking the grub shell:: How to use the grub shell 118* Invoking grub-install:: How to use the GRUB installer 119* Invoking grub-md5-crypt:: How to generate a cryptic password 120* Invoking grub-terminfo:: How to generate a terminfo command 121* Invoking grub-set-default:: How to set a default boot entry 122* Invoking mbchk:: How to use the Multiboot checker 123* Obtaining and Building GRUB:: How to obtain and build GRUB 124* Reporting bugs:: Where you should send a bug report 125* Future:: Some future plans on GRUB 126* Internals:: Hacking GRUB 127* Index:: 128@end menu 129 130 131@node Introduction 132@chapter Introduction to GRUB 133 134@menu 135* Overview:: What exactly GRUB is and how to use it 136* History:: From maggot to house fly 137* Features:: GRUB features 138* Role of a boot loader:: The role of a boot loader 139@end menu 140 141 142@node Overview 143@section Overview 144 145Briefly, a @dfn{boot loader} is the first software program that runs when 146a computer starts. It is responsible for loading and transferring 147control to an operating system @dfn{kernel} software (such as Linux or 148GNU Mach). The kernel, in turn, initializes the rest of the operating 149system (e.g. a GNU system). 150 151GNU GRUB is a very powerful boot loader, which can load a wide variety 152of free operating systems, as well as proprietary operating systems with 153chain-loading@footnote{@dfn{chain-load} is the mechanism for loading 154unsupported operating systems by loading another boot loader. It is 155typically used for loading DOS or Windows.}. GRUB is designed to 156address the complexity of booting a personal computer; both the 157program and this manual are tightly bound to that computer platform, 158although porting to other platforms may be addressed in the future. 159 160One of the important features in GRUB is flexibility; GRUB understands 161filesystems and kernel executable formats, so you can load an arbitrary 162operating system the way you like, without recording the physical 163position of your kernel on the disk. Thus you can load the kernel 164just by specifying its file name and the drive and partition where the 165kernel resides. 166 167When booting with GRUB, you can use either a command-line interface 168(@pxref{Command-line interface}), or a menu interface (@pxref{Menu 169interface}). Using the command-line interface, you type the drive 170specification and file name of the kernel manually. In the menu 171interface, you just select an OS using the arrow keys. The menu is 172based on a configuration file which you prepare beforehand 173(@pxref{Configuration}). While in the menu, you can switch to the 174command-line mode, and vice-versa. You can even edit menu entries 175before using them. 176 177In the following chapters, you will learn how to specify a drive, a 178partition, and a file name (@pxref{Naming convention}) to GRUB, how to 179install GRUB on your drive (@pxref{Installation}), and how to boot your 180OSes (@pxref{Booting}), step by step. 181 182Besides the GRUB boot loader itself, there is a @dfn{grub shell} 183@command{grub} (@pxref{Invoking the grub shell}) which can be run when 184you are in your operating system. It emulates the boot loader and can 185be used for installing the boot loader. 186 187 188@node History 189@section History of GRUB 190 191GRUB originated in 1995 when Erich Boleyn was trying to boot the GNU 192Hurd with the University of Utah's Mach 4 microkernel (now known as GNU 193Mach). Erich and Brian Ford designed the Multiboot Specification 194(@pxref{Top, Multiboot Specification, Motivation, multiboot, The Multiboot 195Specification}), because they were determined not to add to the large 196number of mutually-incompatible PC boot methods. 197 198Erich then began modifying the FreeBSD boot loader so that it would 199understand Multiboot. He soon realized that it would be a lot easier 200to write his own boot loader from scratch than to keep working on the 201FreeBSD boot loader, and so GRUB was born. 202 203Erich added many features to GRUB, but other priorities prevented him 204from keeping up with the demands of its quickly-expanding user base. In 2051999, Gordon Matzigkeit and Yoshinori K. Okuji adopted GRUB as an 206official GNU package, and opened its development by making the latest 207sources available via anonymous CVS. @xref{Obtaining and Building 208GRUB}, for more information. 209 210 211@node Features 212@section GRUB features 213 214The primary requirement for GRUB is that it be compliant with the 215@dfn{Multiboot Specification}, which is described in @ref{Top, Multiboot 216Specification, Motivation, multiboot, The Multiboot Specification}. 217 218The other goals, listed in approximate order of importance, are: 219 220@itemize @bullet{} 221@item 222Basic functions must be straightforward for end-users. 223 224@item 225Rich functionality to support kernel experts and designers. 226 227@item 228Backward compatibility for booting FreeBSD, NetBSD, OpenBSD, and 229Linux. Proprietary kernels (such as DOS, Windows NT, and OS/2) are 230supported via a chain-loading function. 231@end itemize 232 233Except for specific compatibility modes (chain-loading and the Linux 234@dfn{piggyback} format), all kernels will be started in much the same 235state as in the Multiboot Specification. Only kernels loaded at 1 megabyte 236or above are presently supported. Any attempt to load below that 237boundary will simply result in immediate failure and an error message 238reporting the problem. 239 240In addition to the requirements above, GRUB has the following features 241(note that the Multiboot Specification doesn't require all the features 242that GRUB supports): 243 244@table @asis 245@item Recognize multiple executable formats 246Support many of the @dfn{a.out} variants plus @dfn{ELF}. Symbol 247tables are also loaded. 248 249@item Support non-Multiboot kernels 250Support many of the various free 32-bit kernels that lack Multiboot 251compliance (primarily FreeBSD, NetBSD, OpenBSD, and 252Linux). Chain-loading of other boot loaders is also supported. 253 254@item Load multiples modules 255Fully support the Multiboot feature of loading multiple modules. 256 257@item Load a configuration file 258Support a human-readable text configuration file with preset boot 259commands. You can also load another configuration file dynamically and 260embed a preset configuration file in a GRUB image file. The list of 261commands (@pxref{Commands}) are a superset of those supported on the 262command-line. An example configuration file is provided in 263@ref{Configuration}. 264 265@item Provide a menu interface 266A menu interface listing preset boot commands, with a programmable 267timeout, is available. There is no fixed limit on the number of boot 268entries, and the current implementation has space for several hundred. 269 270@item Have a flexible command-line interface 271A fairly flexible command-line interface, accessible from the menu, 272is available to edit any preset commands, or write a new boot command 273set from scratch. If no configuration file is present, GRUB drops to 274the command-line. 275 276The list of commands (@pxref{Commands}) are a subset of those supported 277for configuration files. Editing commands closely resembles the Bash 278command-line (@pxref{Command Line Editing, Bash, Command Line Editing, 279features, Bash Features}), with @key{TAB}-completion of commands, 280devices, partitions, and files in a directory depending on context. 281 282@item Support multiple filesystem types 283Support multiple filesystem types transparently, plus a useful explicit 284blocklist notation. The currently supported filesystem types are 285@dfn{BSD FFS}, @dfn{DOS FAT16 and FAT32}, @dfn{Minix fs}, @dfn{Linux 286ext2fs}, @dfn{ReiserFS}, @dfn{JFS}, @dfn{XFS}, and @dfn{VSTa 287fs}. @xref{Filesystem}, for more information. 288 289@item Support automatic decompression 290Can decompress files which were compressed by @command{gzip}. This 291function is both automatic and transparent to the user (i.e. all 292functions operate upon the uncompressed contents of the specified 293files). This greatly reduces a file size and loading time, a 294particularly great benefit for floppies.@footnote{There are a few 295pathological cases where loading a very badly organized ELF kernel might 296take longer, but in practice this never happen.} 297 298It is conceivable that some kernel modules should be loaded in a 299compressed state, so a different module-loading command can be specified 300to avoid uncompressing the modules. 301 302@item Access data on any installed device 303Support reading data from any or all floppies or hard disk(s) recognized 304by the BIOS, independent of the setting of the root device. 305 306@item Be independent of drive geometry translations 307Unlike many other boot loaders, GRUB makes the particular drive 308translation irrelevant. A drive installed and running with one 309translation may be converted to another translation without any adverse 310effects or changes in GRUB's configuration. 311 312@item Detect all installed @sc{ram} 313GRUB can generally find all the installed @sc{ram} on a PC-compatible 314machine. It uses an advanced BIOS query technique for finding all 315memory regions. As described on the Multiboot Specification (@pxref{Top, 316Multiboot Specification, Motivation, multiboot, The Multiboot 317Specification}), not all kernels make use of this information, but GRUB 318provides it for those who do. 319 320@item Support Logical Block Address mode 321In traditional disk calls (called @dfn{CHS mode}), there is a geometry 322translation problem, that is, the BIOS cannot access over 1024 323cylinders, so the accessible space is limited to at least 508 MB and to 324at most 8GB. GRUB can't universally solve this problem, as there is no 325standard interface used in all machines. However, several newer machines 326have the new interface, Logical Block Address (@dfn{LBA}) mode. GRUB 327automatically detects if LBA mode is available and uses it if 328available. In LBA mode, GRUB can access the entire disk. 329 330@item Support network booting 331GRUB is basically a disk-based boot loader but also has network 332support. You can load OS images from a network by using the @dfn{TFTP} 333protocol. 334 335@item Support remote terminals 336To support computers with no console, GRUB provides remote terminal 337support, so that you can control GRUB from a remote host. Only serial 338terminal support is implemented at the moment. 339@end table 340 341 342@node Role of a boot loader 343@section The role of a boot loader 344 345The following is a quotation from Gordon Matzigkeit, a GRUB fanatic: 346 347@quotation 348Some people like to acknowledge both the operating system and kernel when 349they talk about their computers, so they might say they use 350``GNU/Linux'' or ``GNU/Hurd''. Other people seem to think that the 351kernel is the most important part of the system, so they like to call 352their GNU operating systems ``Linux systems.'' 353 354I, personally, believe that this is a grave injustice, because the 355@emph{boot loader} is the most important software of all. I used to 356refer to the above systems as either ``LILO''@footnote{The LInux LOader, 357a boot loader that everybody uses, but nobody likes.} or ``GRUB'' 358systems. 359 360Unfortunately, nobody ever understood what I was talking about; now I 361just use the word ``GNU'' as a pseudonym for GRUB. 362 363So, if you ever hear people talking about their alleged ``GNU'' systems, 364remember that they are actually paying homage to the best boot loader 365around@dots{} GRUB! 366@end quotation 367 368We, the GRUB maintainers, do not (usually) encourage Gordon's level of 369fanaticism, but it helps to remember that boot loaders deserve 370recognition. We hope that you enjoy using GNU GRUB as much as we did 371writing it. 372 373 374@node Naming convention 375@chapter Naming convention 376 377The device syntax used in GRUB is a wee bit different from what you may 378have seen before in your operating system(s), and you need to know it so 379that you can specify a drive/partition. 380 381Look at the following examples and explanations: 382 383@example 384(fd0) 385@end example 386 387First of all, GRUB requires that the device name be enclosed with 388@samp{(} and @samp{)}. The @samp{fd} part means that it is a floppy 389disk. The number @samp{0} is the drive number, which is counted from 390@emph{zero}. This expression means that GRUB will use the whole floppy 391disk. 392 393@example 394(hd0,1) 395@end example 396 397Here, @samp{hd} means it is a hard disk drive. The first integer 398@samp{0} indicates the drive number, that is, the first hard disk, while 399the second integer, @samp{1}, indicates the partition number (or the 400@sc{pc} slice number in the BSD terminology). Once again, please note 401that the partition numbers are counted from @emph{zero}, not from 402one. This expression means the second partition of the first hard disk 403drive. In this case, GRUB uses one partition of the disk, instead of the 404whole disk. 405 406@example 407(hd0,4) 408@end example 409 410This specifies the first @dfn{extended partition} of the first hard disk 411drive. Note that the partition numbers for extended partitions are 412counted from @samp{4}, regardless of the actual number of primary 413partitions on your hard disk. 414 415@example 416(hd1,a) 417@end example 418 419This means the BSD @samp{a} partition of the second hard disk. If you 420need to specify which @sc{pc} slice number should be used, use something 421like this: @samp{(hd1,0,a)}. If the @sc{pc} slice number is omitted, 422GRUB searches for the first @sc{pc} slice which has a BSD @samp{a} 423partition. 424 425Of course, to actually access the disks or partitions with GRUB, you 426need to use the device specification in a command, like @samp{root 427(fd0)} or @samp{unhide (hd0,2)}. To help you find out which number 428specifies a partition you want, the GRUB command-line 429(@pxref{Command-line interface}) options have argument 430completion. This means that, for example, you only need to type 431 432@example 433root ( 434@end example 435 436followed by a @key{TAB}, and GRUB will display the list of drives, 437partitions, or file names. So it should be quite easy to determine the 438name of your target partition, even with minimal knowledge of the 439syntax. 440 441Note that GRUB does @emph{not} distinguish IDE from SCSI - it simply 442counts the drive numbers from zero, regardless of their type. Normally, 443any IDE drive number is less than any SCSI drive number, although that 444is not true if you change the boot sequence by swapping IDE and SCSI 445drives in your BIOS. 446 447Now the question is, how to specify a file? Again, consider an 448example: 449 450@example 451(hd0,0)/vmlinuz 452@end example 453 454This specifies the file named @samp{vmlinuz}, found on the first 455partition of the first hard disk drive. Note that the argument 456completion works with file names, too. 457 458That was easy, admit it. Now read the next chapter, to find out how to 459actually install GRUB on your drive. 460 461 462@node Installation 463@chapter Installation 464 465In order to install GRUB as your boot loader, you need to first 466install the GRUB system and utilities under your UNIX-like operating 467system (@pxref{Obtaining and Building GRUB}). You can do this either 468from the source tarball, or as a package for your OS. 469 470After you have done that, you need to install the boot loader on a 471drive (floppy or hard disk). There are two ways of doing that - either 472using the utility @command{grub-install} (@pxref{Invoking 473grub-install}) on a UNIX-like OS, or by running GRUB itself from a 474floppy. These are quite similar, however the utility might probe a 475wrong BIOS drive, so you should be careful. 476 477Also, if you install GRUB on a UNIX-like OS, please make sure that you 478have an emergency boot disk ready, so that you can rescue your computer 479if, by any chance, your hard drive becomes unusable (unbootable). 480 481GRUB comes with boot images, which are normally put in the directory 482@file{/usr/lib/grub/i386-pc}. If you do not use grub-install, then 483you need to copy the files @file{stage1}, @file{stage2}, and 484@file{*stage1_5} to the directory @file{/boot/grub}, and run the 485@command{grub-set-default} (@pxref{Invoking grub-set-default}) if you 486intend to use @samp{default saved} (@pxref{default}) in your 487configuration file. Hereafter, the directory where GRUB images are 488initially placed (normally @file{/usr/lib/grub/i386-pc}) will be 489called the @dfn{image directory}, and the directory where the boot 490loader needs to find them (usually @file{/boot/grub}) will be called 491the @dfn{boot directory}. 492 493@menu 494* Creating a GRUB boot floppy:: 495* Installing GRUB natively:: 496* Installing GRUB using grub-install:: 497* Making a GRUB bootable CD-ROM:: 498@end menu 499 500 501@node Creating a GRUB boot floppy 502@section Creating a GRUB boot floppy 503 504To create a GRUB boot floppy, you need to take the files @file{stage1} 505and @file{stage2} from the image directory, and write them to the first 506and the second block of the floppy disk, respectively. 507 508@strong{Caution:} This procedure will destroy any data currently stored 509on the floppy. 510 511On a UNIX-like operating system, that is done with the following 512commands: 513 514@example 515@group 516# @kbd{cd /usr/lib/grub/i386-pc} 517# @kbd{dd if=stage1 of=/dev/fd0 bs=512 count=1} 5181+0 records in 5191+0 records out 520# @kbd{dd if=stage2 of=/dev/fd0 bs=512 seek=1} 521153+1 records in 522153+1 records out 523# 524@end group 525@end example 526 527The device file name may be different. Consult the manual for your OS. 528 529 530@node Installing GRUB natively 531@section Installing GRUB natively 532 533@strong{Caution:} Installing GRUB's stage1 in this manner will erase the 534normal boot-sector used by an OS. 535 536GRUB can currently boot GNU Mach, Linux, FreeBSD, NetBSD, and OpenBSD 537directly, so using it on a boot sector (the first sector of a 538partition) should be okay. But generally, it would be a good idea to 539back up the first sector of the partition on which you are installing 540GRUB's stage1. This isn't as important if you are installing GRUB on 541the first sector of a hard disk, since it's easy to reinitialize it 542(e.g. by running @samp{FDISK /MBR} from DOS). 543 544If you decide to install GRUB in the native environment, which is 545definitely desirable, you'll need to create a GRUB boot disk, and 546reboot your computer with it. Otherwise, see @ref{Installing GRUB using 547grub-install}. 548 549Once started, GRUB will show the command-line interface 550(@pxref{Command-line interface}). First, set the GRUB's @dfn{root 551device}@footnote{Note that GRUB's root device doesn't necessarily mean 552your OS's root partition; if you need to specify a root partition for 553your OS, add the argument into the command @command{kernel}.} to the 554partition containing the boot directory, like this: 555 556@example 557grub> @kbd{root (hd0,0)} 558@end example 559 560If you are not sure which partition actually holds this directory, use the 561command @command{find} (@pxref{find}), like this: 562 563@example 564grub> @kbd{find /boot/grub/stage1} 565@end example 566 567This will search for the file name @file{/boot/grub/stage1} and show the 568devices which contain the file. 569 570Once you've set the root device correctly, run the command 571@command{setup} (@pxref{setup}): 572 573@example 574grub> @kbd{setup (hd0)} 575@end example 576 577This command will install the GRUB boot loader on the Master Boot 578Record (MBR) of the first drive. If you want to put GRUB into the boot 579sector of a partition instead of putting it in the MBR, specify the 580partition into which you want to install GRUB: 581 582@example 583grub> @kbd{setup (hd0,0)} 584@end example 585 586If you install GRUB into a partition or a drive other than the first 587one, you must chain-load GRUB from another boot loader. Refer to the 588manual for the boot loader to know how to chain-load GRUB. 589 590After using the setup command, you will boot into GRUB without the 591GRUB floppy. See the chapter @ref{Booting} to find out how to boot 592your operating systems from GRUB. 593 594 595@node Installing GRUB using grub-install 596@section Installing GRUB using grub-install 597 598@strong{Caution:} This procedure is definitely less safe, because 599there are several ways in which your computer can become 600unbootable. For example, most operating systems don't tell GRUB how to 601map BIOS drives to OS devices correctly---GRUB merely @dfn{guesses} 602the mapping. This will succeed in most cases, but not 603always. Therefore, GRUB provides you with a map file called the 604@dfn{device map}, which you must fix if it is wrong. @xref{Device 605map}, for more details. 606 607If you still do want to install GRUB under a UNIX-like OS (such 608as @sc{gnu}), invoke the program @command{grub-install} (@pxref{Invoking 609grub-install}) as the superuser (@dfn{root}). 610 611The usage is basically very simple. You only need to specify one 612argument to the program, namely, where to install the boot loader. The 613argument can be either a device file (like @samp{/dev/hda}) or a 614partition specified in GRUB's notation. For example, under Linux the 615following will install GRUB into the MBR of the first IDE disk: 616 617@example 618# @kbd{grub-install /dev/hda} 619@end example 620 621Likewise, under GNU/Hurd, this has the same effect: 622 623@example 624# @kbd{grub-install /dev/hd0} 625@end example 626 627If it is the first BIOS drive, this is the same as well: 628 629@example 630# @kbd{grub-install '(hd0)'} 631@end example 632 633Or you can omit the parentheses: 634 635@example 636# @kbd{grub-install hd0} 637@end example 638 639But all the above examples assume that GRUB should use images under 640the root directory. If you want GRUB to use images under a directory 641other than the root directory, you need to specify the option 642@option{--root-directory}. The typical usage is that you create a GRUB 643boot floppy with a filesystem. Here is an example: 644 645@example 646@group 647# @kbd{mke2fs /dev/fd0} 648# @kbd{mount -t ext2 /dev/fd0 /mnt} 649# @kbd{grub-install --root-directory=/mnt fd0} 650# @kbd{umount /mnt} 651@end group 652@end example 653 654Another example is when you have a separate boot partition 655which is mounted at @file{/boot}. Since GRUB is a boot loader, it 656doesn't know anything about mountpoints at all. Thus, you need to run 657@command{grub-install} like this: 658 659@example 660# @kbd{grub-install --root-directory=/boot /dev/hda} 661@end example 662 663By the way, as noted above, it is quite difficult to guess BIOS drives 664correctly under a UNIX-like OS. Thus, @command{grub-install} will prompt 665you to check if it could really guess the correct mappings, after the 666installation. The format is defined in @ref{Device map}. Please be 667quite careful. If the output is wrong, it is unlikely that your 668computer will be able to boot with no problem. 669 670Note that @command{grub-install} is actually just a shell script and the 671real task is done by the grub shell @command{grub} (@pxref{Invoking the 672grub shell}). Therefore, you may run @command{grub} directly to install 673GRUB, without using @command{grub-install}. Don't do that, however, 674unless you are very familiar with the internals of GRUB. Installing a 675boot loader on a running OS may be extremely dangerous. 676 677 678@node Making a GRUB bootable CD-ROM 679@section Making a GRUB bootable CD-ROM 680 681GRUB supports the @dfn{no emulation mode} in the El Torito 682specification@footnote{El Torito is a specification for bootable CD 683using BIOS functions.}. This means that you can use the whole CD-ROM 684from GRUB and you don't have to make a floppy or hard disk image file, 685which can cause compatibility problems. 686 687For booting from a CD-ROM, GRUB uses a special Stage 2 called 688@file{stage2_eltorito}. The only GRUB files you need to have in your 689bootable CD-ROM are this @file{stage2_eltorito} and optionally a config file 690@file{menu.lst}. You don't need to use @file{stage1} or @file{stage2}, 691because El Torito is quite different from the standard boot process. 692 693Here is an example of procedures to make a bootable CD-ROM 694image. First, make a top directory for the bootable image, say, 695@samp{iso}: 696 697@example 698$ @kbd{mkdir iso} 699@end example 700 701Make a directory for GRUB: 702 703@example 704$ @kbd{mkdir -p iso/boot/grub} 705@end example 706 707Copy the file @file{stage2_eltorito}: 708 709@example 710$ @kbd{cp /usr/lib/grub/i386-pc/stage2_eltorito iso/boot/grub} 711@end example 712 713If desired, make the config file @file{menu.lst} under @file{iso/boot/grub} 714(@pxref{Configuration}), and copy any files and directories for the disc to the 715directory @file{iso/}. 716 717Finally, make a ISO9660 image file like this: 718 719@example 720$ @kbd{mkisofs -R -b boot/grub/stage2_eltorito -no-emul-boot \ 721 -boot-load-size 4 -boot-info-table -o grub.iso iso} 722@end example 723 724This produces a file named @file{grub.iso}, which then can be burned 725into a CD (or a DVD). @kbd{mkisofs} has already set up the disc to boot 726from the @kbd{boot/grub/stage2_eltorito} file, so there is no need to 727setup GRUB on the disc. (Note that the @kbd{-boot-load-size 4} bit is 728required for compatibility with the BIOS on many older machines.) 729 730You can use the device @samp{(cd)} to access a CD-ROM in your 731config file. This is not required; GRUB automatically sets the root device 732to @samp{(cd)} when booted from a CD-ROM. It is only necessary to refer to 733@samp{(cd)} if you want to access other drives as well. 734 735 736@node Booting 737@chapter Booting 738 739GRUB can load Multiboot-compliant kernels in a consistent way, 740but for some free operating systems you need to use some OS-specific 741magic. 742 743@menu 744* General boot methods:: How to boot OSes with GRUB generally 745* OS-specific notes:: Notes on some operating systems 746* Making your system robust:: How to make your system robust 747@end menu 748 749 750@node General boot methods 751@section How to boot operating systems 752 753GRUB has two distinct boot methods. One of the two is to load an 754operating system directly, and the other is to chain-load another boot 755loader which then will load an operating system actually. Generally 756speaking, the former is more desirable, because you don't need to 757install or maintain other boot loaders and GRUB is flexible enough to 758load an operating system from an arbitrary disk/partition. However, 759the latter is sometimes required, since GRUB doesn't support all the 760existing operating systems natively. 761 762@menu 763* Loading an operating system directly:: 764* Chain-loading:: 765@end menu 766 767 768@node Loading an operating system directly 769@subsection How to boot an OS directly with GRUB 770 771Multiboot (@pxref{Top, Multiboot Specification, Motivation, multiboot, 772The Multiboot Specification}) is the native format supported by GRUB. 773For the sake of convenience, there is also support for Linux, FreeBSD, 774NetBSD and OpenBSD. If you want to boot other operating systems, you 775will have to chain-load them (@pxref{Chain-loading}). 776 777Generally, GRUB can boot any Multiboot-compliant OS in the following 778steps: 779 780@enumerate 781@item 782Set GRUB's root device to the drive where the OS images are stored with 783the command @command{root} (@pxref{root}). 784 785@item 786Load the kernel image with the command @command{kernel} (@pxref{kernel}). 787 788@item 789If you need modules, load them with the command @command{module} 790(@pxref{module}) or @command{modulenounzip} (@pxref{modulenounzip}). 791 792@item 793Run the command @command{boot} (@pxref{boot}). 794@end enumerate 795 796Linux, FreeBSD, NetBSD and OpenBSD can be booted in a similar 797manner. You load a kernel image with the command @command{kernel} and 798then run the command @command{boot}. If the kernel requires some 799parameters, just append the parameters to @command{kernel}, after the 800file name of the kernel. Also, please refer to @ref{OS-specific notes}, 801for information on your OS-specific issues. 802 803 804@node Chain-loading 805@subsection Load another boot loader to boot unsupported operating systems 806 807If you want to boot an unsupported operating system (e.g. Windows 95), 808chain-load a boot loader for the operating system. Normally, the boot 809loader is embedded in the @dfn{boot sector} of the partition on which 810the operating system is installed. 811 812@enumerate 813@item 814Set GRUB's root device to the partition by the command 815@command{rootnoverify} (@pxref{rootnoverify}): 816 817@example 818grub> @kbd{rootnoverify (hd0,0)} 819@end example 820 821@item 822Set the @dfn{active} flag in the partition using the command 823@command{makeactive}@footnote{This is not necessary for most of the 824modern operating systems.} (@pxref{makeactive}): 825 826@example 827grub> @kbd{makeactive} 828@end example 829 830@item 831Load the boot loader with the command @command{chainloader} 832(@pxref{chainloader}): 833 834@example 835grub> @kbd{chainloader +1} 836@end example 837 838@samp{+1} indicates that GRUB should read one sector from the start of 839the partition. The complete description about this syntax can be found 840in @ref{Block list syntax}. 841 842@item 843Run the command @command{boot} (@pxref{boot}). 844@end enumerate 845 846However, DOS and Windows have some deficiencies, so you might have to 847use more complicated instructions. @xref{DOS/Windows}, for more 848information. 849 850 851@node OS-specific notes 852@section Some caveats on OS-specific issues 853 854Here, we describe some caveats on several operating systems. 855 856@menu 857* GNU/Hurd:: 858* GNU/Linux:: 859* FreeBSD:: 860* NetBSD:: 861* OpenBSD:: 862* DOS/Windows:: 863* SCO UnixWare:: 864* QNX:: 865@end menu 866 867 868@node GNU/Hurd 869@subsection GNU/Hurd 870 871Since GNU/Hurd is Multiboot-compliant, it is easy to boot it; there is 872nothing special about it. But do not forget that you have to specify a 873root partition to the kernel. 874 875@enumerate 876@item 877Set GRUB's root device to the same drive as GNU/Hurd's. Probably the 878command @code{find /boot/gnumach} or similar can help you 879(@pxref{find}). 880 881@item 882Load the kernel and the module, like this: 883 884@example 885@group 886grub> @kbd{kernel /boot/gnumach root=hd0s1} 887grub> @kbd{module /boot/serverboot} 888@end group 889@end example 890 891@item 892Run the command @command{boot} (@pxref{boot}). 893@end enumerate 894 895 896@node GNU/Linux 897@subsection GNU/Linux 898 899It is relatively easy to boot GNU/Linux from GRUB, because it somewhat 900resembles to boot a Multiboot-compliant OS. 901 902@enumerate 903@item 904Set GRUB's root device to the same drive as GNU/Linux's. Probably the 905command @code{find /vmlinuz} or similar can help you (@pxref{find}). 906 907@item 908Load the kernel: 909 910@example 911grub> @kbd{kernel /vmlinuz root=/dev/hda1} 912@end example 913 914If you need to specify some kernel parameters, just append them to the 915command. For example, to set @option{vga} to @samp{ext}, do this: 916 917@example 918grub> @kbd{kernel /vmlinuz root=/dev/hda1 vga=ext} 919@end example 920 921See the documentation in the Linux source tree for complete 922information on the available options. 923 924@item 925If you use an initrd, execute the command @command{initrd} 926(@pxref{initrd}) after @command{kernel}: 927 928@example 929grub> @kbd{initrd /initrd} 930@end example 931 932@item 933Finally, run the command @command{boot} (@pxref{boot}). 934@end enumerate 935 936@strong{Caution:} If you use an initrd and specify the @samp{mem=} 937option to the kernel to let it use less than actual memory size, you 938will also have to specify the same memory size to GRUB. To let GRUB know 939the size, run the command @command{uppermem} @emph{before} loading the 940kernel. @xref{uppermem}, for more information. 941 942 943@node FreeBSD 944@subsection FreeBSD 945 946GRUB can load the kernel directly, either in ELF or a.out format. But 947this is not recommended, since FreeBSD's bootstrap interface sometimes 948changes heavily, so GRUB can't guarantee to pass kernel parameters 949correctly. 950 951Thus, we'd recommend loading the very flexible loader 952@file{/boot/loader} instead. See this example: 953 954@example 955@group 956grub> @kbd{root (hd0,a)} 957grub> @kbd{kernel /boot/loader} 958grub> @kbd{boot} 959@end group 960@end example 961 962 963@node NetBSD 964@subsection NetBSD 965 966GRUB can load NetBSD a.out and ELF directly, follow these steps: 967 968@enumerate 969@item 970Set GRUB's root device with @command{root} (@pxref{root}). 971 972@item 973Load the kernel with @command{kernel} (@pxref{kernel}). You should 974append the ugly option @option{--type=netbsd}, if you want to load an 975ELF kernel, like this: 976 977@example 978grub> @kbd{kernel --type=netbsd /netbsd-elf} 979@end example 980 981@item 982Run @command{boot} (@pxref{boot}). 983@end enumerate 984 985For now, however, GRUB doesn't allow you to pass kernel parameters, so 986it may be better to chain-load it instead. For more information, please 987see @ref{Chain-loading}. 988 989 990@node OpenBSD 991@subsection OpenBSD 992 993The booting instruction is exactly the same as for NetBSD 994(@pxref{NetBSD}). 995 996 997@node DOS/Windows 998@subsection DOS/Windows 999 1000GRUB cannot boot DOS or Windows directly, so you must chain-load them 1001(@pxref{Chain-loading}). However, their boot loaders have some critical 1002deficiencies, so it may not work to just chain-load them. To overcome 1003the problems, GRUB provides you with two helper functions. 1004 1005If you have installed DOS (or Windows) on a non-first hard disk, you 1006have to use the disk swapping technique, because that OS cannot boot 1007from any disks but the first one. The workaround used in GRUB is the 1008command @command{map} (@pxref{map}), like this: 1009 1010@example 1011@group 1012grub> @kbd{map (hd0) (hd1)} 1013grub> @kbd{map (hd1) (hd0)} 1014@end group 1015@end example 1016 1017This performs a @dfn{virtual} swap between your first and second hard 1018drive. 1019 1020@strong{Caution:} This is effective only if DOS (or Windows) uses BIOS 1021to access the swapped disks. If that OS uses a special driver for the 1022disks, this probably won't work. 1023 1024Another problem arises if you installed more than one set of DOS/Windows 1025onto one disk, because they could be confused if there are more than one 1026primary partitions for DOS/Windows. Certainly you should avoid doing 1027this, but there is a solution if you do want to do so. Use the partition 1028hiding/unhiding technique. 1029 1030If GRUB @dfn{hide}s a DOS (or Windows) partition (@pxref{hide}), DOS (or 1031Windows) will ignore the partition. If GRUB @dfn{unhide}s a DOS (or 1032Windows) partition (@pxref{unhide}), DOS (or Windows) will detect the 1033partition. Thus, if you have installed DOS (or Windows) on the first 1034and the second partition of the first hard disk, and you want to boot 1035the copy on the first partition, do the following: 1036 1037@example 1038@group 1039grub> @kbd{unhide (hd0,0)} 1040grub> @kbd{hide (hd0,1)} 1041grub> @kbd{rootnoverify (hd0,0)} 1042grub> @kbd{chainloader +1} 1043grub> @kbd{makeactive} 1044grub> @kbd{boot} 1045@end group 1046@end example 1047 1048 1049@node SCO UnixWare 1050@subsection SCO UnixWare 1051 1052It is known that the signature in the boot loader for SCO UnixWare is 1053wrong, so you will have to specify the option @option{--force} to 1054@command{chainloader} (@pxref{chainloader}), like this: 1055 1056@example 1057@group 1058grub> @kbd{rootnoverify (hd1,0)} 1059grub> @kbd{chainloader --force +1} 1060grub> @kbd{makeactive} 1061grub> @kbd{boot} 1062@end group 1063@end example 1064 1065 1066@node QNX 1067@subsection QNX 1068 1069QNX seems to use a bigger boot loader, so you need to boot it up, like 1070this: 1071 1072@example 1073@group 1074grub> @kbd{rootnoverify (hd1,1)} 1075grub> @kbd{chainloader +4} 1076grub> @kbd{boot} 1077@end group 1078@end example 1079 1080 1081@node Making your system robust 1082@section How to make your system robust 1083 1084When you test a new kernel or a new OS, it is important to make sure 1085that your computer can boot even if the new system is unbootable. This 1086is crucial especially if you maintain servers or remote systems. To 1087accomplish this goal, you need to set up two things: 1088 1089@enumerate 1090@item 1091You must maintain a system which is always bootable. For instance, if 1092you test a new kernel, you need to keep a working kernel in a 1093different place. And, it would sometimes be very nice to even have a 1094complete copy of a working system in a different partition or disk. 1095 1096@item 1097You must direct GRUB to boot a working system when the new system 1098fails. This is possible with the @dfn{fallback} system in GRUB. 1099@end enumerate 1100 1101The former requirement is very specific to each OS, so this 1102documentation does not cover that topic. It is better to consult some 1103backup tools. 1104 1105So let's see the GRUB part. There are two possibilities: one of them 1106is quite simple but not very robust, and the other is a bit complex to 1107set up but probably the best solution to make sure that your system 1108can start as long as GRUB itself is bootable. 1109 1110@menu 1111* Booting once-only:: 1112* Booting fallback systems:: 1113@end menu 1114 1115 1116@node Booting once-only 1117@subsection Booting once-only 1118 1119You can teach GRUB to boot an entry only at next boot time. Suppose 1120that your have an old kernel @file{old_kernel} and a new kernel 1121@file{new_kernel}. You know that @file{old_kernel} can boot 1122your system correctly, and you want to test @file{new_kernel}. 1123 1124To ensure that your system will go back to the old kernel even if the 1125new kernel fails (e.g. it panics), you can specify that GRUB should 1126try the new kernel only once and boot the old kernel after that. 1127 1128First, modify your configuration file. Here is an example: 1129 1130@example 1131@group 1132default saved # This is important!!! 1133timeout 10 1134 1135title the old kernel 1136root (hd0,0) 1137kernel /old_kernel 1138savedefault 1139 1140title the new kernel 1141root (hd0,0) 1142kernel /new_kernel 1143savedefault 0 # This is important!!! 1144@end group 1145@end example 1146 1147Note that this configuration file uses @samp{default saved} 1148(@pxref{default}) at the head and @samp{savedefault 0} 1149(@pxref{savedefault}) in the entry for the new kernel. This means 1150that GRUB boots a saved entry by default, and booting the entry for the 1151new kernel saves @samp{0} as the saved entry. 1152 1153With this configuration file, after all, GRUB always tries to boot the 1154old kernel after it booted the new one, because @samp{0} is the entry 1155of @code{the old kernel}. 1156 1157The next step is to tell GRUB to boot the new kernel at next boot 1158time. For this, execute @command{grub-set-default} (@pxref{Invoking 1159grub-set-default}): 1160 1161@example 1162# @kbd{grub-set-default 1} 1163@end example 1164 1165This command sets the saved entry to @samp{1}, that is, to the new 1166kernel. 1167 1168This method is useful, but still not very robust, because GRUB stops 1169booting, if there is any error in the boot entry, such that the new 1170kernel has an invalid executable format. Thus, it it even better to 1171use the @dfn{fallback} mechanism of GRUB. Look at next subsection for 1172this feature. 1173 1174 1175@node Booting fallback systems 1176@subsection Booting fallback systems 1177 1178GRUB supports a fallback mechanism of booting one or more other 1179entries if a default boot entry fails. You can specify multiple 1180fallback entries if you wish. 1181 1182Suppose that you have three systems, @samp{A}, @samp{B} and 1183@samp{C}. @samp{A} is a system which you want to boot by 1184default. @samp{B} is a backup system which is supposed to boot 1185safely. @samp{C} is another backup system which is used in case where 1186@samp{B} is broken. 1187 1188Then you may want GRUB to boot the first system which is bootable 1189among @samp{A}, @samp{B} and @samp{C}. A configuration file can be 1190written in this way: 1191 1192@example 1193@group 1194default saved # This is important!!! 1195timeout 10 1196fallback 1 2 # This is important!!! 1197 1198title A 1199root (hd0,0) 1200kernel /kernel 1201savedefault fallback # This is important!!! 1202 1203title B 1204root (hd1,0) 1205kernel /kernel 1206savedefault fallback # This is important!!! 1207 1208title C 1209root (hd2,0) 1210kernel /kernel 1211savedefault 1212@end group 1213@end example 1214 1215Note that @samp{default saved} (@pxref{default}), @samp{fallback 1 2} 1216and @samp{savedefault fallback} are used. GRUB will boot a saved entry 1217by default and save a fallback entry as next boot entry with this 1218configuration. 1219 1220When GRUB tries to boot @samp{A}, GRUB saves @samp{1} as next boot 1221entry, because the command @command{fallback} specifies that @samp{1} 1222is the first fallback entry. The entry @samp{1} is @samp{B}, so GRUB 1223will try to boot @samp{B} at next boot time. 1224 1225Likewise, when GRUB tries to boot @samp{B}, GRUB saves @samp{2} as 1226next boot entry, because @command{fallback} specifies @samp{2} as next 1227fallback entry. This makes sure that GRUB will boot @samp{C} after 1228booting @samp{B}. 1229 1230It is noteworthy that GRUB uses fallback entries both when GRUB 1231itself fails in booting an entry and when @samp{A} or @samp{B} fails 1232in starting up your system. So this solution ensures that your system 1233is started even if GRUB cannot find your kernel or if your kernel 1234panics. 1235 1236However, you need to run @command{grub-set-default} (@pxref{Invoking 1237grub-set-default}) when @samp{A} starts correctly or you fix @samp{A} 1238after it crashes, since GRUB always sets next boot entry to a fallback 1239entry. You should run this command in a startup script such as 1240@file{rc.local} to boot @samp{A} by default: 1241 1242@example 1243# @kbd{grub-set-default 0} 1244@end example 1245 1246where @samp{0} is the number of the boot entry for the system 1247@samp{A}. 1248 1249If you want to see what is current default entry, you can look at the 1250file @file{/boot/grub/default} (or @file{/grub/default} in 1251some systems). Because this file is plain-text, you can just 1252@command{cat} this file. But it is strongly recommended @strong{not to 1253modify this file directly}, because GRUB may fail in saving a default 1254entry in this file, if you change this file in an unintended 1255manner. Therefore, you should use @command{grub-set-default} when you 1256need to change the default entry. 1257 1258 1259@node Configuration 1260@chapter Configuration 1261 1262You've probably noticed that you need to type several commands to boot your 1263OS. There's a solution to that - GRUB provides a menu interface 1264(@pxref{Menu interface}) from which you can select an item (using arrow 1265keys) that will do everything to boot an OS. 1266 1267To enable the menu, you need a configuration file, 1268@file{menu.lst} under the boot directory. We'll analyze an example 1269file. 1270 1271The file first contains some general settings, the menu interface 1272related options. You can put these commands (@pxref{Menu-specific 1273commands}) before any of the items (starting with @command{title} 1274(@pxref{title})). 1275 1276@example 1277@group 1278# 1279# Sample boot menu configuration file 1280# 1281@end group 1282@end example 1283 1284As you may have guessed, these lines are comments. Lines starting with a 1285hash character (@samp{#}), and blank lines, are ignored by GRUB. 1286 1287@example 1288@group 1289# By default, boot the first entry. 1290default 0 1291@end group 1292@end example 1293 1294The first entry (here, counting starts with number zero, not one!) will 1295be the default choice. 1296 1297@example 1298@group 1299# Boot automatically after 30 secs. 1300timeout 30 1301@end group 1302@end example 1303 1304As the comment says, GRUB will boot automatically in 30 seconds, unless 1305interrupted with a keypress. 1306 1307@example 1308@group 1309# Fallback to the second entry. 1310fallback 1 1311@end group 1312@end example 1313 1314If, for any reason, the default entry doesn't work, fall back to the 1315second one (this is rarely used, for obvious reasons). 1316 1317Note that the complete descriptions of these commands, which are menu 1318interface specific, can be found in @ref{Menu-specific 1319commands}. Other descriptions can be found in @ref{Commands}. 1320 1321Now, on to the actual OS definitions. You will see that each entry 1322begins with a special command, @command{title} (@pxref{title}), and the 1323action is described after it. Note that there is no command 1324@command{boot} (@pxref{boot}) at the end of each item. That is because 1325GRUB automatically executes @command{boot} if it loads other commands 1326successfully. 1327 1328The argument for the command @command{title} is used to display a short 1329title/description of the entry in the menu. Since @command{title} 1330displays the argument as is, you can write basically anything there. 1331 1332@example 1333@group 1334# For booting GNU/Hurd 1335title GNU/Hurd 1336root (hd0,0) 1337kernel /boot/gnumach.gz root=hd0s1 1338module /boot/serverboot.gz 1339@end group 1340@end example 1341 1342This boots GNU/Hurd from the first hard disk. 1343 1344@example 1345@group 1346# For booting GNU/Linux 1347title GNU/Linux 1348kernel (hd1,0)/vmlinuz root=/dev/hdb1 1349@end group 1350@end example 1351 1352This boots GNU/Linux, but from the second hard disk. 1353 1354@example 1355@group 1356# For booting Mach (getting kernel from floppy) 1357title Utah Mach4 multiboot 1358root (hd0,2) 1359pause Insert the diskette now^G!! 1360kernel (fd0)/boot/kernel root=hd0s3 1361module (fd0)/boot/bootstrap 1362@end group 1363@end example 1364 1365This boots Mach with a kernel on a floppy, but the root filesystem at 1366hd0s3. It also contains a @command{pause} line (@pxref{pause}), which 1367will cause GRUB to display a prompt and delay, before actually executing 1368the rest of the commands and booting. 1369 1370@example 1371@group 1372# For booting FreeBSD 1373title FreeBSD 1374root (hd0,2,a) 1375kernel /boot/loader 1376@end group 1377@end example 1378 1379This item will boot FreeBSD kernel loaded from the @samp{a} partition of 1380the third @sc{pc} slice of the first hard disk. 1381 1382@example 1383@group 1384# For booting OS/2 1385title OS/2 1386root (hd0,1) 1387makeactive 1388# chainload OS/2 bootloader from the first sector 1389chainloader +1 1390# This is similar to "chainload", but loads a specific file 1391#chainloader /boot/chain.os2 1392@end group 1393@end example 1394 1395This will boot OS/2, using a chain-loader (@pxref{Chain-loading}). 1396 1397@example 1398@group 1399# For booting Windows NT or Windows95 1400title Windows NT / Windows 95 boot menu 1401root (hd0,0) 1402makeactive 1403chainloader +1 1404# For loading DOS if Windows NT is installed 1405# chainload /bootsect.dos 1406@end group 1407@end example 1408 1409The same as the above, but for Windows. 1410 1411@example 1412@group 1413# For installing GRUB into the hard disk 1414title Install GRUB into the hard disk 1415root (hd0,0) 1416setup (hd0) 1417@end group 1418@end example 1419 1420This will just (re)install GRUB onto the hard disk. 1421 1422@example 1423# Change the colors. 1424title Change the colors 1425color light-green/brown blink-red/blue 1426@end example 1427 1428In the last entry, the command @command{color} is used (@pxref{color}), 1429to change the menu colors (try it!). This command is somewhat special, 1430because it can be used both in the command-line and in the menu. GRUB 1431has several such commands, see @ref{General commands}. 1432 1433We hope that you now understand how to use the basic features of 1434GRUB. To learn more about GRUB, see the following chapters. 1435 1436 1437@node Network 1438@chapter Downloading OS images from a network 1439 1440Although GRUB is a disk-based boot loader, it does provide network 1441support. To use the network support, you need to enable at least one 1442network driver in the GRUB build process. For more information please 1443see @file{netboot/README.netboot} in the source distribution. 1444 1445@menu 1446* General usage of network support:: 1447* Diskless:: 1448@end menu 1449 1450 1451@node General usage of network support 1452@section How to set up your network 1453 1454GRUB requires a file server and optionally a server that will assign an 1455IP address to the machine on which GRUB is running. For the former, only 1456TFTP is supported at the moment. The latter is either BOOTP, DHCP or a 1457RARP server@footnote{RARP is not advised, since it cannot serve much 1458information}. It is not necessary to run both the servers on one 1459computer. How to configure these servers is beyond the scope of this 1460document, so please refer to the manuals specific to those 1461protocols/servers. 1462 1463If you decided to use a server to assign an IP address, set up the 1464server and run @command{bootp} (@pxref{bootp}), @command{dhcp} 1465(@pxref{dhcp}) or @command{rarp} (@pxref{rarp}) for BOOTP, DHCP or RARP, 1466respectively. Each command will show an assigned IP address, a netmask, 1467an IP address for your TFTP server and a gateway. If any of the 1468addresses is wrong or it causes an error, probably the configuration of 1469your servers isn't set up properly. 1470 1471Otherwise, run @command{ifconfig}, like this: 1472 1473@example 1474grub> @kbd{ifconfig --address=192.168.110.23 --server=192.168.110.14} 1475@end example 1476 1477You can also use @command{ifconfig} in conjuction with @command{bootp}, 1478@command{dhcp} or @command{rarp} (e.g. to reassign the server address 1479manually). @xref{ifconfig}, for more details. 1480 1481Finally, download your OS images from your network. The network can be 1482accessed using the network drive @samp{(nd)}. Everything else is very 1483similar to the normal instructions (@pxref{Booting}). 1484 1485Here is an example: 1486 1487@example 1488@group 1489grub> @kbd{bootp} 1490Probing... [NE*000] 1491NE2000 base ... 1492Address: 192.168.110.23 Netmask: 255.255.255.0 1493Server: 192.168.110.14 Gateway: 192.168.110.1 1494 1495grub> @kbd{root (nd)} 1496grub> @kbd{kernel /tftproot/gnumach.gz root=sd0s1} 1497grub> @kbd{module /tftproot/serverboot.gz} 1498grub> @kbd{boot} 1499@end group 1500@end example 1501 1502 1503@node Diskless 1504@section Booting from a network 1505 1506It is sometimes very useful to boot from a network, especially when you 1507use a machine which has no local disk. In this case, you need to obtain 1508a kind of Net Boot @sc{rom}, such as a PXE @sc{rom} or a free software 1509package like Etherboot. Such a Boot @sc{rom} first boots the machine, 1510sets up the network card installed into the machine, and downloads a 1511second stage boot image from the network. Then, the second image will 1512try to boot an operating system actually from the network. 1513 1514GRUB provides two second stage images, @file{nbgrub} and 1515@file{pxegrub} (@pxref{Images}). These images are the same as the 1516normal Stage 2, except that they set up a network automatically, and try 1517to load a configuration file from the network, if specified. The usage 1518is very simple: If the machine has a PXE @sc{rom}, use 1519@file{pxegrub}. If the machine has an NBI loader such as Etherboot, use 1520@file{nbgrub}. There is no difference between them except their 1521formats. Since the way to load a second stage image you want to use 1522should be described in the manual on your Net Boot @sc{rom}, please 1523refer to the manual, for more information. 1524 1525However, there is one thing specific to GRUB. Namely, how to specify a 1526configuration file in a BOOTP/DHCP server. For now, GRUB uses the tag 1527@samp{150}, to get the name of a configuration file. The following is an 1528example with a BOOTP configuration: 1529 1530@example 1531@group 1532.allhost:hd=/tmp:bf=null:\ 1533 :ds=145.71.35.1 145.71.32.1:\ 1534 :sm=255.255.254.0:\ 1535 :gw=145.71.35.1:\ 1536 :sa=145.71.35.5: 1537 1538foo:ht=1:ha=63655d0334a7:ip=145.71.35.127:\ 1539 :bf=/nbgrub:\ 1540 :tc=.allhost:\ 1541 :T150="(nd)/tftpboot/menu.lst.foo": 1542@end group 1543@end example 1544 1545Note that you should specify the drive name @code{(nd)} in the name of 1546the configuration file. This is because you might change the root drive 1547before downloading the configuration from the TFTP server when the 1548preset menu feature is used (@pxref{Preset Menu}). 1549 1550See the manual of your BOOTP/DHCP server for more information. The 1551exact syntax should differ a little from the example. 1552 1553 1554@node Serial terminal 1555@chapter Using GRUB via a serial line 1556 1557This chapter describes how to use the serial terminal support in GRUB. 1558 1559If you have many computers or computers with no display/keyboard, it 1560could be very useful to control the computers through serial 1561communications. To connect one computer with another via a serial line, 1562you need to prepare a null-modem (cross) serial cable, and you may need 1563to have multiport serial boards, if your computer doesn't have extra 1564serial ports. In addition, a terminal emulator is also required, such as 1565minicom. Refer to a manual of your operating system, for more 1566information. 1567 1568As for GRUB, the instruction to set up a serial terminal is quite 1569simple. First of all, make sure that you haven't specified the option 1570@option{--disable-serial} to the configure script when you built your 1571GRUB images. If you get them in binary form, probably they have serial 1572terminal support already. 1573 1574Then, initialize your serial terminal after GRUB starts up. Here is an 1575example: 1576 1577@example 1578@group 1579grub> @kbd{serial --unit=0 --speed=9600} 1580grub> @kbd{terminal serial} 1581@end group 1582@end example 1583 1584The command @command{serial} initializes the serial unit 0 with the 1585speed 9600bps. The serial unit 0 is usually called @samp{COM1}, so, if 1586you want to use COM2, you must specify @samp{--unit=1} instead. This 1587command accepts many other options, so please refer to @ref{serial}, 1588for more details. 1589 1590The command @command{terminal} (@pxref{terminal}) chooses which type of 1591terminal you want to use. In the case above, the terminal will be a 1592serial terminal, but you can also pass @code{console} to the command, 1593as @samp{terminal serial console}. In this case, a terminal in which 1594you press any key will be selected as a GRUB terminal. 1595 1596However, note that GRUB assumes that your terminal emulator is 1597compatible with VT100 by default. This is true for most terminal 1598emulators nowadays, but you should pass the option @option{--dumb} to 1599the command if your terminal emulator is not VT100-compatible or 1600implements few VT100 escape sequences. If you specify this option then 1601GRUB provides you with an alternative menu interface, because the normal 1602menu requires several fancy features of your terminal. 1603 1604 1605@node Preset Menu 1606@chapter Embedding a configuration file into GRUB 1607 1608GRUB supports a @dfn{preset menu} which is to be always loaded before 1609starting. The preset menu feature is useful, for example, when your 1610computer has no console but a serial cable. In this case, it is 1611critical to set up the serial terminal as soon as possible, since you 1612cannot see any message until the serial terminal begins to work. So it 1613is good to run the commands @command{serial} (@pxref{serial}) and 1614@command{terminal} (@pxref{terminal}) before anything else at the 1615start-up time. 1616 1617How the preset menu works is slightly complicated: 1618 1619@enumerate 1620@item 1621GRUB checks if the preset menu feature is used, and loads the preset 1622menu, if available. This includes running commands and reading boot 1623entries, like an ordinary configuration file. 1624 1625@item 1626GRUB checks if the configuration file is available. Note that this check 1627is performed @strong{regardless of the existence of the preset 1628menu}. The configuration file is loaded even if the preset menu was 1629loaded. 1630 1631@item 1632If the preset menu includes any boot entries, they are cleared when 1633the configuration file is loaded. It doesn't matter whether the 1634configuration file has any entries or no entry. The boot entries in the 1635preset menu are used only when GRUB fails in loading the configuration 1636file. 1637@end enumerate 1638 1639To enable the preset menu feature, you must rebuild GRUB specifying a 1640file to the configure script with the option 1641@option{--enable-preset-menu}. The file has the same semantics as 1642normal configuration files (@pxref{Configuration}). 1643 1644Another point you should take care is that the diskless support 1645(@pxref{Diskless}) diverts the preset menu. Diskless images embed a 1646preset menu to execute the command @command{bootp} (@pxref{bootp}) 1647automatically, unless you specify your own preset menu to the configure 1648script. This means that you must put commands to initialize a network in 1649the preset menu yourself, because diskless images don't set it up 1650implicitly, when you use the preset menu explicitly. 1651 1652Therefore, a typical preset menu used with diskless support would be 1653like this: 1654 1655@example 1656@group 1657# Set up the serial terminal, first of all. 1658serial --unit=0 --speed=19200 1659terminal --timeout=0 serial 1660 1661# Initialize the network. 1662dhcp 1663@end group 1664@end example 1665 1666 1667@node Security 1668@chapter Protecting your computer from cracking 1669 1670You may be interested in how to prevent ordinary users from doing 1671whatever they like, if you share your computer with other people. So 1672this chapter describes how to improve the security of GRUB. 1673 1674One thing which could be a security hole is that the user can do too 1675many things with GRUB, because GRUB allows one to modify its configuration 1676and run arbitrary commands at run-time. For example, the user can even 1677read @file{/etc/passwd} in the command-line interface by the command 1678@command{cat} (@pxref{cat}). So it is necessary to disable all the 1679interactive operations. 1680 1681Thus, GRUB provides a @dfn{password} feature, so that only administrators 1682can start the interactive operations (i.e. editing menu entries and 1683entering the command-line interface). To use this feature, you need to 1684run the command @command{password} in your configuration file 1685(@pxref{password}), like this: 1686 1687@example 1688password --md5 PASSWORD 1689@end example 1690 1691If this is specified, GRUB disallows any interactive control, until you 1692press the key @key{p} and enter a correct password. The option 1693@option{--md5} tells GRUB that @samp{PASSWORD} is in MD5 format. If it 1694is omitted, GRUB assumes the @samp{PASSWORD} is in clear text. 1695 1696You can encrypt your password with the command @command{md5crypt} 1697(@pxref{md5crypt}). For example, run the grub shell (@pxref{Invoking the 1698grub shell}), and enter your password: 1699 1700@example 1701@group 1702grub> md5crypt 1703Password: ********** 1704Encrypted: $1$U$JK7xFegdxWH6VuppCUSIb. 1705@end group 1706@end example 1707 1708Then, cut and paste the encrypted password to your configuration file. 1709 1710Also, you can specify an optional argument to @command{password}. See 1711this example: 1712 1713@example 1714password PASSWORD /boot/grub/menu-admin.lst 1715@end example 1716 1717In this case, GRUB will load @file{/boot/grub/menu-admin.lst} as a 1718configuration file when you enter the valid password. 1719 1720Another thing which may be dangerous is that any user can choose any 1721menu entry. Usually, this wouldn't be problematic, but you might want to 1722permit only administrators to run some of your menu entries, such as an 1723entry for booting an insecure OS like DOS. 1724 1725GRUB provides the command @command{lock} (@pxref{lock}). This command 1726always fails until you enter the valid password, so you can use it, like 1727this: 1728 1729@example 1730@group 1731title Boot DOS 1732lock 1733rootnoverify (hd0,1) 1734makeactive 1735chainload +1 1736@end group 1737@end example 1738 1739You should insert @command{lock} right after @command{title}, because 1740any user can execute commands in an entry until GRUB encounters 1741@command{lock}. 1742 1743You can also use the command @command{password} instead of 1744@command{lock}. In this case the boot process will ask for the password 1745and stop if it was entered incorrectly. Since the @command{password} 1746takes its own @var{PASSWORD} argument this is useful if you want 1747different passwords for different entries. 1748 1749 1750@node Images 1751@chapter GRUB image files 1752 1753GRUB consists of several images: two essential stages, optional stages 1754called @dfn{Stage 1.5}, one image for bootable CD-ROM, and two network 1755boot images. Here is a short overview of them. @xref{Internals}, for 1756more details. 1757 1758@table @file 1759@item stage1 1760This is an essential image used for booting up GRUB. Usually, this is 1761embedded in an MBR or the boot sector of a partition. Because a PC boot 1762sector is 512 bytes, the size of this image is exactly 512 bytes. 1763 1764All @file{stage1} must do is to load Stage 2 or Stage 1.5 from a local 1765disk. Because of the size restriction, @file{stage1} encodes the 1766location of Stage 2 (or Stage 1.5) in a block list format, so it never 1767understand any filesystem structure. 1768 1769@item stage2 1770This is the core image of GRUB. It does everything but booting up 1771itself. Usually, this is put in a filesystem, but that is not required. 1772 1773@item e2fs_stage1_5 1774@itemx fat_stage1_5 1775@itemx ffs_stage1_5 1776@itemx jfs_stage1_5 1777@itemx minix_stage1_5 1778@itemx reiserfs_stage1_5 1779@itemx vstafs_stage1_5 1780@itemx xfs_stage1_5 1781 1782These are called @dfn{Stage 1.5}, because they serve as a bridge 1783between @file{stage1} and @file{stage2}, that is to say, Stage 1.5 is 1784loaded by Stage 1 and Stage 1.5 loads Stage 2. The difference between 1785@file{stage1} and @file{*_stage1_5} is that the former doesn't 1786understand any filesystem while the latter understands one filesystem 1787(e.g. @file{e2fs_stage1_5} understands ext2fs). So you can move the 1788Stage 2 image to another location safely, even after GRUB has been 1789installed. 1790 1791While Stage 2 cannot generally be embedded in a fixed area as the size 1792is so large, Stage 1.5 can be installed into the area right after an MBR, 1793or the boot loader area of a ReiserFS or a FFS. 1794 1795@item stage2_eltorito 1796This is a boot image for CD-ROMs using the @dfn{no emulation mode} in 1797El Torito specification. This is identical to Stage 2, except that 1798this boots up without Stage 1 and sets up a special drive @samp{(cd)}. 1799 1800@item nbgrub 1801This is a network boot image for the Network Image Proposal used by some 1802network boot loaders, such as Etherboot. This is mostly the same as 1803Stage 2, but it also sets up a network and loads a configuration file 1804from the network. 1805 1806@item pxegrub 1807This is another network boot image for the Preboot Execution Environment 1808used by several Netboot ROMs. This is identical to @file{nbgrub}, except 1809for the format. 1810@end table 1811 1812 1813@node Filesystem 1814@chapter Filesystem syntax and semantics 1815 1816GRUB uses a special syntax for specifying disk drives which can be 1817accessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish 1818between IDE, ESDI, SCSI, or others. You must know yourself which BIOS 1819device is equivalent to which OS device. Normally, that will be clear if 1820you see the files in a device or use the command @command{find} 1821(@pxref{find}). 1822 1823@menu 1824* Device syntax:: How to specify devices 1825* File name syntax:: How to specify files 1826* Block list syntax:: How to specify block lists 1827@end menu 1828 1829 1830@node Device syntax 1831@section How to specify devices 1832 1833The device syntax is like this: 1834 1835@example 1836@code{(@var{device}[,@var{part-num}][,@var{bsd-subpart-letter}])} 1837@end example 1838 1839@samp{[]} means the parameter is optional. @var{device} should be 1840either @samp{fd} or @samp{hd} followed by a digit, like @samp{fd0}. 1841But you can also set @var{device} to a hexadecimal or a decimal number 1842which is a BIOS drive number, so the following are equivalent: 1843 1844@example 1845(hd0) 1846(0x80) 1847(128) 1848@end example 1849 1850@var{part-num} represents the partition number of @var{device}, starting 1851from zero for primary partitions and from four for extended partitions, 1852and @var{bsd-subpart-letter} represents the BSD disklabel subpartition, 1853such as @samp{a} or @samp{e}. 1854 1855A shortcut for specifying BSD subpartitions is 1856@code{(@var{device},@var{bsd-subpart-letter})}, in this case, GRUB 1857searches for the first PC partition containing a BSD disklabel, then 1858finds the subpartition @var{bsd-subpart-letter}. Here is an example: 1859 1860@example 1861(hd0,a) 1862@end example 1863 1864The syntax @samp{(hd0)} represents using the entire disk (or the 1865MBR when installing GRUB), while the syntax @samp{(hd0,0)} 1866represents using the first partition of the disk (or the boot sector 1867of the partition when installing GRUB). 1868 1869If you enabled the network support, the special drive, @samp{(nd)}, is 1870also available. Before using the network drive, you must initialize the 1871network. @xref{Network}, for more information. 1872 1873If you boot GRUB from a CD-ROM, @samp{(cd)} is available. @xref{Making 1874a GRUB bootable CD-ROM}, for details. 1875 1876 1877@node File name syntax 1878@section How to specify files 1879 1880There are two ways to specify files, by @dfn{absolute file name} and by 1881@dfn{block list}. 1882 1883An absolute file name resembles a Unix absolute file name, using 1884@samp{/} for the directory separator (not @samp{\} as in DOS). One 1885example is @samp{(hd0,0)/boot/grub/menu.lst}. This means the file 1886@file{/boot/grub/menu.lst} in the first partition of the first hard 1887disk. If you omit the device name in an absolute file name, GRUB uses 1888GRUB's @dfn{root device} implicitly. So if you set the root device to, 1889say, @samp{(hd1,0)} by the command @command{root} (@pxref{root}), then 1890@code{/boot/kernel} is the same as @code{(hd1,0)/boot/kernel}. 1891 1892 1893@node Block list syntax 1894@section How to specify block lists 1895 1896A block list is used for specifying a file that doesn't appear in the 1897filesystem, like a chainloader. The syntax is 1898@code{[@var{offset}]+@var{length}[,[@var{offset}]+@var{length}]@dots{}}. 1899Here is an example: 1900 1901@example 1902@code{0+100,200+1,300+300} 1903@end example 1904 1905This represents that GRUB should read blocks 0 through 99, block 200, 1906and blocks 300 through 599. If you omit an offset, then GRUB assumes 1907the offset is zero. 1908 1909Like the file name syntax (@pxref{File name syntax}), if a blocklist 1910does not contain a device name, then GRUB uses GRUB's @dfn{root 1911device}. So @code{(hd0,1)+1} is the same as @code{+1} when the root 1912device is @samp{(hd0,1)}. 1913 1914 1915@node Interface 1916@chapter GRUB's user interface 1917 1918GRUB has both a simple menu interface for choosing preset entries from a 1919configuration file, and a highly flexible command-line for performing 1920any desired combination of boot commands. 1921 1922GRUB looks for its configuration file as soon as it is loaded. If one 1923is found, then the full menu interface is activated using whatever 1924entries were found in the file. If you choose the @dfn{command-line} menu 1925option, or if the configuration file was not found, then GRUB drops to 1926the command-line interface. 1927 1928@menu 1929* Command-line interface:: The flexible command-line interface 1930* Menu interface:: The simple menu interface 1931* Menu entry editor:: Editing a menu entry 1932* Hidden menu interface:: The hidden menu interface 1933@end menu 1934 1935 1936@node Command-line interface 1937@section The flexible command-line interface 1938 1939The command-line interface provides a prompt and after it an editable 1940text area much like a command-line in Unix or DOS. Each command is 1941immediately executed after it is entered@footnote{However, this 1942behavior will be changed in the future version, in a user-invisible 1943way.}. The commands (@pxref{Command-line and menu entry commands}) are a 1944subset of those available in the configuration file, used with exactly 1945the same syntax. 1946 1947Cursor movement and editing of the text on the line can be done via a 1948subset of the functions available in the Bash shell: 1949 1950@table @key 1951@item C-f 1952@itemx PC right key 1953Move forward one character. 1954 1955@item C-b 1956@itemx PC left key 1957Move back one character. 1958 1959@item C-a 1960@itemx HOME 1961Move to the start of the line. 1962 1963@item C-e 1964@itemx END 1965Move the the end of the line. 1966 1967@item C-d 1968@itemx DEL 1969Delete the character underneath the cursor. 1970 1971@item C-h 1972@itemx BS 1973Delete the character to the left of the cursor. 1974 1975@item C-k 1976Kill the text from the current cursor position to the end of the line. 1977 1978@item C-u 1979Kill backward from the cursor to the beginning of the line. 1980 1981@item C-y 1982Yank the killed text back into the buffer at the cursor. 1983 1984@item C-p 1985@itemx PC up key 1986Move up through the history list. 1987 1988@item C-n 1989@itemx PC down key 1990Move down through the history list. 1991@end table 1992 1993When typing commands interactively, if the cursor is within or before 1994the first word in the command-line, pressing the @key{TAB} key (or 1995@key{C-i}) will display a listing of the available commands, and if the 1996cursor is after the first word, the @kbd{@key{TAB}} will provide a 1997completion listing of disks, partitions, and file names depending on the 1998context. Note that to obtain a list of drives, one must open a 1999parenthesis, as @command{root (}. 2000 2001Note that you cannot use the completion functionality in the TFTP 2002filesystem. This is because TFTP doesn't support file name listing for 2003the security. 2004 2005 2006@node Menu interface 2007@section The simple menu interface 2008 2009The menu interface is quite easy to use. Its commands are both 2010reasonably intuitive and described on screen. 2011 2012Basically, the menu interface provides a list of @dfn{boot entries} to 2013the user to choose from. Use the arrow keys to select the entry of 2014choice, then press @key{RET} to run it. An optional timeout is 2015available to boot the default entry (the first one if not set), which is 2016aborted by pressing any key. 2017 2018Commands are available to enter a bare command-line by pressing @key{c} 2019(which operates exactly like the non-config-file version of GRUB, but 2020allows one to return to the menu if desired by pressing @key{ESC}) or to 2021edit any of the @dfn{boot entries} by pressing @key{e}. 2022 2023If you protect the menu interface with a password (@pxref{Security}), 2024all you can do is choose an entry by pressing @key{RET}, or press 2025@key{p} to enter the password. 2026 2027 2028@node Menu entry editor 2029@section Editing a menu entry 2030 2031The menu entry editor looks much like the main menu interface, but the 2032lines in the menu are individual commands in the selected entry instead 2033of entry names. 2034 2035If an @key{ESC} is pressed in the editor, it aborts all the changes made 2036to the configuration entry and returns to the main menu interface. 2037 2038When a particular line is selected, the editor places the user in a 2039special version of the GRUB command-line to edit that line. When the 2040user hits @key{RET}, GRUB replaces the line in question in the boot 2041entry with the changes (unless it was aborted via @key{ESC}, 2042in which case the changes are thrown away). 2043 2044If you want to add a new line to the menu entry, press @key{o} if adding 2045a line after the current line or press @key{O} if before the current 2046line. 2047 2048To delete a line, hit the key @key{d}. Although GRUB unfortunately 2049does not support @dfn{undo}, you can do almost the same thing by just 2050returning to the main menu. 2051 2052 2053@node Hidden menu interface 2054@section The hidden menu interface 2055 2056When your terminal is dumb or you request GRUB to hide the menu 2057interface explicitly with the command @command{hiddenmenu} 2058(@pxref{hiddenmenu}), GRUB doesn't show the menu interface (@pxref{Menu 2059interface}) and automatically boots the default entry, unless 2060interrupted by pressing @key{ESC}. 2061 2062When you interrupt the timeout and your terminal is dumb, GRUB falls 2063back to the command-line interface (@pxref{Command-line interface}). 2064 2065 2066@node Commands 2067@chapter The list of available commands 2068 2069In this chapter, we list all commands that are available in GRUB. 2070 2071Commands belong to different groups. A few can only be used in 2072the global section of the configuration file (or ``menu''); most 2073of them can be entered on the command-line and can be used either 2074anywhere in the menu or specifically in the menu entries. 2075 2076@menu 2077* Menu-specific commands:: 2078* General commands:: 2079* Command-line and menu entry commands:: 2080@end menu 2081 2082 2083@node Menu-specific commands 2084@section The list of commands for the menu only 2085 2086The semantics used in parsing the configuration file are the following: 2087 2088@itemize @bullet 2089@item 2090The menu-specific commands have to be used before any others. 2091 2092@item 2093The files @emph{must} be in plain-text format. 2094 2095@item 2096@samp{#} at the beginning of a line in a configuration file means it is 2097only a comment. 2098 2099@item 2100Options are separated by spaces. 2101 2102@item 2103All numbers can be either decimal or hexadecimal. A hexadecimal number 2104must be preceded by @samp{0x}, and is case-insensitive. 2105 2106@item 2107Extra options or text at the end of the line are ignored unless otherwise 2108specified. 2109 2110@item 2111Unrecognized commands are added to the current entry, except before entries 2112start, where they are ignored. 2113@end itemize 2114 2115These commands can only be used in the menu: 2116 2117@menu 2118* default:: Set the default entry 2119* fallback:: Set the fallback entry 2120* hiddenmenu:: Hide the menu interface 2121* timeout:: Set the timeout 2122* title:: Start a menu entry 2123@end menu 2124 2125 2126@node default 2127@subsection default 2128 2129@deffn Command default num 2130Set the default entry to the entry number @var{num}. Numbering starts 2131from 0, and the entry number 0 is the default if the command is not 2132used. 2133 2134You can specify @samp{saved} instead of a number. In this case, the 2135default entry is the entry saved with the command 2136@command{savedefault}. @xref{savedefault}, for more information. 2137@end deffn 2138 2139 2140@node fallback 2141@subsection fallback 2142 2143@deffn Command fallback num... 2144Go into unattended boot mode: if the default boot entry has any errors, 2145instead of waiting for the user to do something, immediately start 2146over using the @var{num} entry (same numbering as the @code{default} 2147command (@pxref{default})). This obviously won't help if the machine was 2148rebooted by a kernel that GRUB loaded. You can specify multiple 2149fallback entry numbers. 2150@end deffn 2151 2152 2153@node hiddenmenu 2154@subsection hiddenmenu 2155 2156@deffn Command hiddenmenu 2157Don't display the menu. If the command is used, no menu will be 2158displayed on the control terminal, and the default entry will be 2159booted after the timeout expired. The user can still request the 2160menu to be displayed by pressing @key{ESC} before the timeout 2161expires. See also @ref{Hidden menu interface}. 2162@end deffn 2163 2164 2165@node timeout 2166@subsection timeout 2167 2168@deffn Command timeout sec 2169Set a timeout, in @var{sec} seconds, before automatically booting the 2170default entry (normally the first entry defined). 2171@end deffn 2172 2173 2174@node title 2175@subsection title 2176 2177@deffn Command title name @dots{} 2178Start a new boot entry, and set its name to the contents of the rest of 2179the line, starting with the first non-space character. 2180@end deffn 2181 2182 2183@node General commands 2184@section The list of general commands 2185 2186Commands usable anywhere in the menu and in the command-line. 2187 2188@menu 2189* bootp:: Initialize a network device via BOOTP 2190* color:: Color the menu interface 2191* device:: Specify a file as a drive 2192* dhcp:: Initialize a network device via DHCP 2193* hide:: Hide a partition 2194* ifconfig:: Configure a network device manually 2195* pager:: Change the state of the internal pager 2196* partnew:: Make a primary partition 2197* parttype:: Change the type of a partition 2198* password:: Set a password for the menu interface 2199* rarp:: Initialize a network device via RARP 2200* serial:: Set up a serial device 2201* setkey:: Configure the key map 2202* terminal:: Choose a terminal 2203* terminfo:: Define escape sequences for a terminal 2204* tftpserver:: Specify a TFTP server 2205* unhide:: Unhide a partition 2206@end menu 2207 2208 2209@node bootp 2210@subsection bootp 2211 2212@deffn Command bootp [@option{--with-configfile}] 2213Initialize a network device via the @dfn{BOOTP} protocol. This command 2214is only available if GRUB is compiled with netboot support. See also 2215@ref{Network}. 2216 2217If you specify @option{--with-configfile} to this command, GRUB will 2218fetch and load a configuration file specified by your BOOTP server 2219with the vendor tag @samp{150}. 2220@end deffn 2221 2222 2223@node color 2224@subsection color 2225 2226@deffn Command color normal [highlight] 2227Change the menu colors. The color @var{normal} is used for most 2228lines in the menu (@pxref{Menu interface}), and the color 2229@var{highlight} is used to highlight the line where the cursor 2230points. If you omit @var{highlight}, then the inverted color of 2231@var{normal} is used for the highlighted line. The format of a color is 2232@code{@var{foreground}/@var{background}}. @var{foreground} and 2233@var{background} are symbolic color names. A symbolic color name must be 2234one of these: 2235 2236@itemize @bullet 2237@item 2238black 2239 2240@item 2241blue 2242 2243@item 2244green 2245 2246@item 2247cyan 2248 2249@item 2250red 2251 2252@item 2253magenta 2254 2255@item 2256brown 2257 2258@item 2259light-gray 2260 2261@strong{These below can be specified only for the foreground.} 2262 2263@item 2264dark-gray 2265 2266@item 2267light-blue 2268 2269@item 2270light-green 2271 2272@item 2273light-cyan 2274 2275@item 2276light-red 2277 2278@item 2279light-magenta 2280 2281@item 2282yellow 2283 2284@item 2285white 2286@end itemize 2287 2288But only the first eight names can be used for @var{background}. You can 2289prefix @code{blink-} to @var{foreground} if you want a blinking 2290foreground color. 2291 2292This command can be used in the configuration file and on the command 2293line, so you may write something like this in your configuration file: 2294 2295@example 2296@group 2297# Set default colors. 2298color light-gray/blue black/light-gray 2299 2300# Change the colors. 2301title OS-BS like 2302color magenta/blue black/magenta 2303@end group 2304@end example 2305@end deffn 2306 2307 2308@node device 2309@subsection device 2310 2311@deffn Command device drive file 2312In the grub shell, specify the file @var{file} as the actual drive for a 2313@sc{bios} drive @var{drive}. You can use this command to create a disk 2314image, and/or to fix the drives guessed by GRUB when GRUB fails to 2315determine them correctly, like this: 2316 2317@example 2318@group 2319grub> @kbd{device (fd0) /floppy-image} 2320grub> @kbd{device (hd0) /dev/sd0} 2321@end group 2322@end example 2323 2324This command can be used only in the grub shell (@pxref{Invoking the 2325grub shell}). 2326@end deffn 2327 2328 2329@node dhcp 2330@subsection dhcp 2331 2332@deffn Command dhcp [--with-configfile] 2333Initialize a network device via the @dfn{DHCP} protocol. Currently, 2334this command is just an alias for @command{bootp}, since the two 2335protocols are very similar. This command is only available if GRUB is 2336compiled with netboot support. See also @ref{Network}. 2337 2338If you specify @option{--with-configfile} to this command, GRUB will 2339fetch and load a configuration file specified by your DHCP server 2340with the vendor tag @samp{150}. 2341@end deffn 2342 2343 2344@node hide 2345@subsection hide 2346 2347@deffn Command hide partition 2348Hide the partition @var{partition} by setting the @dfn{hidden} bit in 2349its partition type code. This is useful only when booting DOS or Windows 2350and multiple primary FAT partitions exist in one disk. See also 2351@ref{DOS/Windows}. 2352@end deffn 2353 2354 2355@node ifconfig 2356@subsection ifconfig 2357 2358@deffn Command ifconfig [@option{--server=server}] [@option{--gateway=gateway}] [@option{--mask=mask}] [@option{--address=address}] 2359Configure the IP address, the netmask, the gateway, and the server 2360address of a network device manually. The values must be in dotted 2361decimal format, like @samp{192.168.11.178}. The order of the options is 2362not important. This command shows current network configuration, if no 2363option is specified. See also @ref{Network}. 2364@end deffn 2365 2366 2367@node pager 2368@subsection pager 2369 2370@deffn Command pager [flag] 2371Toggle or set the state of the internal pager. If @var{flag} is 2372@samp{on}, the internal pager is enabled. If @var{flag} is @samp{off}, 2373it is disabled. If no argument is given, the state is toggled. 2374@end deffn 2375 2376 2377@node partnew 2378@subsection partnew 2379 2380@deffn Command partnew part type from len 2381Create a new primary partition. @var{part} is a partition specification 2382in GRUB syntax (@pxref{Naming convention}); @var{type} is the partition 2383type and must be a number in the range @code{0-0xff}; @var{from} is 2384the starting address and @var{len} is the length, both in sector units. 2385@end deffn 2386 2387 2388@node parttype 2389@subsection parttype 2390 2391@deffn Command parttype part type 2392Change the type of an existing partition. @var{part} is a partition 2393specification in GRUB syntax (@pxref{Naming convention}); @var{type} 2394is the new partition type and must be a number in the range 0-0xff. 2395@end deffn 2396 2397 2398@node password 2399@subsection password 2400 2401@deffn Command password [@option{--md5}] passwd [new-config-file] 2402If used in the first section of a menu file, disable all interactive 2403editing control (menu entry editor and command-line) and entries 2404protected by the command @command{lock}. If the password @var{passwd} is 2405entered, it loads the @var{new-config-file} as a new config file and 2406restarts the GRUB Stage 2, if @var{new-config-file} is 2407specified. Otherwise, GRUB will just unlock the privileged instructions. 2408You can also use this command in the script section, in which case it 2409will ask for the password, before continuing. The option 2410@option{--md5} tells GRUB that @var{passwd} is encrypted with 2411@command{md5crypt} (@pxref{md5crypt}). 2412@end deffn 2413 2414 2415@node rarp 2416@subsection rarp 2417 2418@deffn Command rarp 2419Initialize a network device via the @dfn{RARP} protocol. This command 2420is only available if GRUB is compiled with netboot support. See also 2421@ref{Network}. 2422@end deffn 2423 2424 2425@node serial 2426@subsection serial 2427 2428@deffn Command serial [@option{--unit=unit}] [@option{--port=port}] [@option{--speed=speed}] [@option{--word=word}] [@option{--parity=parity}] [@option{--stop=stop}] [@option{--device=dev}] 2429Initialize a serial device. @var{unit} is a number in the range 0-3 2430specifying which serial port to use; default is 0, which corresponds to 2431the port often called COM1. @var{port} is the I/O port where the UART 2432is to be found; if specified it takes precedence over @var{unit}. 2433@var{speed} is the transmission speed; default is 9600. @var{word} and 2434@var{stop} are the number of data bits and stop bits. Data bits must 2435be in the range 5-8 and stop bits must be 1 or 2. Default is 8 data 2436bits and one stop bit. @var{parity} is one of @samp{no}, @samp{odd}, 2437@samp{even} and defaults to @samp{no}. The option @option{--device} 2438can only be used in the grub shell and is used to specify the 2439tty device to be used in the host operating system (@pxref{Invoking the 2440grub shell}). 2441 2442The serial port is not used as a communication channel unless the 2443@command{terminal} command is used (@pxref{terminal}). 2444 2445This command is only available if GRUB is compiled with serial 2446support. See also @ref{Serial terminal}. 2447@end deffn 2448 2449 2450@node setkey 2451@subsection setkey 2452 2453@deffn Command setkey [to_key from_key] 2454Change the keyboard map. The key @var{from_key} is mapped to the key 2455@var{to_key}. If no argument is specified, reset key mappings. Note that 2456this command @emph{does not} exchange the keys. If you want to exchange 2457the keys, run this command again with the arguments exchanged, like this: 2458 2459@example 2460grub> @kbd{setkey capslock control} 2461grub> @kbd{setkey control capslock} 2462@end example 2463 2464A key must be an alphabet letter, a digit, or one of these symbols: 2465@samp{escape}, @samp{exclam}, @samp{at}, @samp{numbersign}, 2466@samp{dollar}, @samp{percent}, @samp{caret}, @samp{ampersand}, 2467@samp{asterisk}, @samp{parenleft}, @samp{parenright}, @samp{minus}, 2468@samp{underscore}, @samp{equal}, @samp{plus}, @samp{backspace}, 2469@samp{tab}, @samp{bracketleft}, @samp{braceleft}, @samp{bracketright}, 2470@samp{braceright}, @samp{enter}, @samp{control}, @samp{semicolon}, 2471@samp{colon}, @samp{quote}, @samp{doublequote}, @samp{backquote}, 2472@samp{tilde}, @samp{shift}, @samp{backslash}, @samp{bar}, @samp{comma}, 2473@samp{less}, @samp{period}, @samp{greater}, @samp{slash}, 2474@samp{question}, @samp{alt}, @samp{space}, @samp{capslock}, @samp{FX} 2475(@samp{X} is a digit), and @samp{delete}. This table describes to which 2476character each of the symbols corresponds: 2477 2478@table @samp 2479@item exclam 2480@samp{!} 2481 2482@item at 2483@samp{@@} 2484 2485@item numbersign 2486@samp{#} 2487 2488@item dollar 2489@samp{$} 2490 2491@item percent 2492@samp{%} 2493 2494@item caret 2495@samp{^} 2496 2497@item ampersand 2498@samp{&} 2499 2500@item asterisk 2501@samp{*} 2502 2503@item parenleft 2504@samp{(} 2505 2506@item parenright 2507@samp{)} 2508 2509@item minus 2510@samp{-} 2511 2512@item underscore 2513@samp{_} 2514 2515@item equal 2516@samp{=} 2517 2518@item plus 2519@samp{+} 2520 2521@item bracketleft 2522@samp{[} 2523 2524@item braceleft 2525@samp{@{} 2526 2527@item bracketright 2528@samp{]} 2529 2530@item braceright 2531@samp{@}} 2532 2533@item semicolon 2534@samp{;} 2535 2536@item colon 2537@samp{:} 2538 2539@item quote 2540@samp{'} 2541 2542@item doublequote 2543@samp{"} 2544 2545@item backquote 2546@samp{`} 2547 2548@item tilde 2549@samp{~} 2550 2551@item backslash 2552@samp{\} 2553 2554@item bar 2555@samp{|} 2556 2557@item comma 2558@samp{,} 2559 2560@item less 2561@samp{<} 2562 2563@item period 2564@samp{.} 2565 2566@item greater 2567@samp{>} 2568 2569@item slash 2570@samp{/} 2571 2572@item question 2573@samp{?} 2574 2575@item space 2576@samp{ } 2577@end table 2578@end deffn 2579 2580 2581@node terminal 2582@subsection terminal 2583 2584@deffn Command terminal [@option{--dumb}] [@option{--no-echo}] [@option{--no-edit}] [@option{--timeout=secs}] [@option{--lines=lines}] [@option{--silent}] [@option{console}] [@option{serial}] [@option{hercules}] 2585Select a terminal for user interaction. The terminal is assumed to be 2586VT100-compatible unless @option{--dumb} is specified. If both 2587@option{console} and @option{serial} are specified, then GRUB will use 2588the one where a key is entered first or the first when the timeout 2589expires. If neither are specified, the current setting is 2590reported. This command is only available if GRUB is compiled with serial 2591support. See also @ref{Serial terminal}. 2592 2593This may not make sense for most users, but GRUB supports Hercules 2594console as well. Hercules console is usable like the ordinary console, 2595and the usage is quite similar to that for serial terminals: specify 2596@option{hercules} as the argument. 2597 2598The option @option{--lines} defines the number of lines in your 2599terminal, and it is used for the internal pager function. If you don't 2600specify this option, the number is assumed as 24. 2601 2602The option @option{--silent} suppresses the message to prompt you to 2603hit any key. This might be useful if your system has no terminal 2604device. 2605 2606The option @option{--no-echo} has GRUB not to echo back input 2607characters. This implies the option @option{--no-edit}. 2608 2609The option @option{--no-edit} disables the BASH-like editing feature. 2610@end deffn 2611 2612 2613@node terminfo 2614@subsection terminfo 2615 2616@deffn Command terminfo @option{--name=name} @option{--cursor-address=seq} [@option{--clear-screen=seq}] [@option{--enter-standout-mode=seq}] [@option{--exit-standout-mode=seq}] 2617Define the capabilities of your terminal. Use this command to define 2618escape sequences, if it is not vt100-compatible. You may use @samp{\e} 2619for @key{ESC} and @samp{^X} for a control character. 2620 2621You can use the utility @command{grub-terminfo} to generate 2622appropriate arguments to this command. @xref{Invoking grub-terminfo}. 2623 2624If no option is specified, the current settings are printed. 2625@end deffn 2626 2627 2628@node tftpserver 2629@subsection tftpserver 2630 2631@deffn Command tftpserver ipaddr 2632@strong{Caution:} This command exists only for backward 2633compatibility. Use @command{ifconfig} (@pxref{ifconfig}) instead. 2634 2635Override a TFTP server address returned by a BOOTP/DHCP/RARP server. The 2636argument @var{ipaddr} must be in dotted decimal format, like 2637@samp{192.168.0.15}. This command is only available if GRUB is compiled 2638with netboot support. See also @ref{Network}. 2639@end deffn 2640 2641 2642@node unhide 2643@subsection unhide 2644 2645@deffn Command unhide partition 2646Unhide the partition @var{partition} by clearing the @dfn{hidden} bit in 2647its partition type code. This is useful only when booting DOS or Windows 2648and multiple primary partitions exist on one disk. See also 2649@ref{DOS/Windows}. 2650@end deffn 2651 2652 2653@node Command-line and menu entry commands 2654@section The list of command-line and menu entry commands 2655 2656These commands are usable in the command-line and in menu entries. If 2657you forget a command, you can run the command @command{help} 2658(@pxref{help}). 2659 2660@menu 2661* blocklist:: Get the block list notation of a file 2662* boot:: Start up your operating system 2663* cat:: Show the contents of a file 2664* chainloader:: Chain-load another boot loader 2665* cmp:: Compare two files 2666* configfile:: Load a configuration file 2667* debug:: Toggle the debug flag 2668* displayapm:: Display APM information 2669* displaymem:: Display memory configuration 2670* embed:: Embed Stage 1.5 2671* find:: Find a file 2672* fstest:: Test a filesystem 2673* geometry:: Manipulate the geometry of a drive 2674* halt:: Shut down your computer 2675* help:: Show help messages 2676* impsprobe:: Probe SMP 2677* initrd:: Load an initrd 2678* install:: Install GRUB 2679* ioprobe:: Probe I/O ports used for a drive 2680* kernel:: Load a kernel 2681* lock:: Lock a menu entry 2682* makeactive:: Make a partition active 2683* map:: Map a drive to another 2684* md5crypt:: Encrypt a password in MD5 format 2685* module:: Load a module 2686* modulenounzip:: Load a module without decompression 2687* pause:: Wait for a key press 2688* quit:: Exit from the grub shell 2689* reboot:: Reboot your computer 2690* read:: Read data from memory 2691* root:: Set GRUB's root device 2692* rootnoverify:: Set GRUB's root device without mounting 2693* savedefault:: Save current entry as the default entry 2694* setup:: Set up GRUB's installation automatically 2695* testload:: Load a file for testing a filesystem 2696* testvbe:: Test VESA BIOS EXTENSION 2697* uppermem:: Set the upper memory size 2698* vbeprobe:: Probe VESA BIOS EXTENSION 2699@end menu 2700 2701 2702@node blocklist 2703@subsection blocklist 2704 2705@deffn Command blocklist file 2706Print the block list notation of the file @var{file}. @xref{Block list 2707syntax}. 2708@end deffn 2709 2710 2711@node boot 2712@subsection boot 2713 2714@deffn Command boot 2715Boot the OS or chain-loader which has been loaded. Only necessary if 2716running the fully interactive command-line (it is implicit at the end of 2717a menu entry). 2718@end deffn 2719 2720 2721@node cat 2722@subsection cat 2723 2724@deffn Command cat file 2725Display the contents of the file @var{file}. This command may be useful 2726to remind you of your OS's root partition: 2727 2728@example 2729grub> @kbd{cat /etc/fstab} 2730@end example 2731@end deffn 2732 2733 2734@node chainloader 2735@subsection chainloader 2736 2737@deffn Command chainloader [@option{--force}] file 2738Load @var{file} as a chain-loader. Like any other file loaded by the 2739filesystem code, it can use the blocklist notation to grab the first 2740sector of the current partition with @samp{+1}. If you specify the 2741option @option{--force}, then load @var{file} forcibly, whether it has a 2742correct signature or not. This is required when you want to load a 2743defective boot loader, such as SCO UnixWare 7.1 (@pxref{SCO UnixWare}). 2744@end deffn 2745 2746 2747@node cmp 2748@subsection cmp 2749 2750@deffn Command cmp file1 file2 2751Compare the file @var{file1} with the file @var{file2}. If they differ 2752in size, print the sizes like this: 2753 2754@example 2755Differ in size: 0x1234 [foo], 0x4321 [bar] 2756@end example 2757 2758If the sizes are equal but the bytes at an offset differ, then print the 2759bytes like this: 2760 2761@example 2762Differ at the offset 777: 0xbe [foo], 0xef [bar] 2763@end example 2764 2765If they are completely identical, nothing will be printed. 2766@end deffn 2767 2768 2769@node configfile 2770@subsection configfile 2771 2772@deffn Command configfile file 2773Load @var{file} as a configuration file. 2774@end deffn 2775 2776 2777@node debug 2778@subsection debug 2779 2780@deffn Command debug 2781Toggle debug mode (by default it is off). When debug mode is on, some 2782extra messages are printed to show disk activity. This global debug flag 2783is mainly useful for GRUB developers when testing new code. 2784@end deffn 2785 2786 2787@node displayapm 2788@subsection displayapm 2789 2790@deffn Command displayapm 2791Display APM BIOS information. 2792@end deffn 2793 2794 2795@node displaymem 2796@subsection displaymem 2797 2798@deffn Command displaymem 2799Display what GRUB thinks the system address space map of the machine is, 2800including all regions of physical @sc{ram} installed. GRUB's 2801@dfn{upper/lower memory} display uses the standard BIOS interface for 2802the available memory in the first megabyte, or @dfn{lower memory}, and a 2803synthesized number from various BIOS interfaces of the memory starting 2804at 1MB and going up to the first chipset hole for @dfn{upper memory} 2805(the standard PC @dfn{upper memory} interface is limited to reporting a 2806maximum of 64MB). 2807@end deffn 2808 2809 2810@node embed 2811@subsection embed 2812 2813@deffn Command embed stage1_5 device 2814Embed the Stage 1.5 @var{stage1_5} in the sectors after the MBR if 2815@var{device} is a drive, or in the @dfn{boot loader} area if @var{device} 2816is a FFS partition or a ReiserFS partition.@footnote{The latter feature 2817has not been implemented yet.} Print the number of sectors which 2818@var{stage1_5} occupies, if successful. 2819 2820Usually, you don't need to run this command directly. @xref{setup}. 2821@end deffn 2822 2823 2824@node find 2825@subsection find 2826 2827@deffn Command find filename 2828Search for the file name @var{filename} in all mountable partitions 2829and print the list of the devices which contain the file. The file 2830name @var{filename} should be an absolute file name like 2831@code{/boot/grub/stage1}. 2832@end deffn 2833 2834 2835@node fstest 2836@subsection fstest 2837 2838@deffn Command fstest 2839Toggle filesystem test mode. 2840Filesystem test mode, when turned on, prints out data corresponding to 2841all the device reads and what values are being sent to the low-level 2842routines. The format is @samp{<@var{partition-offset-sector}, 2843@var{byte-offset}, @var{byte-length}>} for high-level reads inside a 2844partition, and @samp{[@var{disk-offset-sector}]} for low-level sector 2845requests from the disk. 2846Filesystem test mode is turned off by any use of the @command{install} 2847(@pxref{install}) or @command{testload} (@pxref{testload}) commands. 2848@end deffn 2849 2850 2851@node geometry 2852@subsection geometry 2853 2854@deffn Command geometry drive [cylinder head sector [total_sector]] 2855Print the information for the drive @var{drive}. In the grub shell, you 2856can set the geometry of the drive arbitrarily. The number of 2857cylinders, the number of heads, the number of sectors and the number of 2858total sectors are set to CYLINDER, HEAD, SECTOR and TOTAL_SECTOR, 2859respectively. If you omit TOTAL_SECTOR, then it will be calculated 2860based on the C/H/S values automatically. 2861@end deffn 2862 2863 2864@node halt 2865@subsection halt 2866 2867@deffn Command halt @option{--no-apm} 2868The command halts the computer. If the @option{--no-apm} option 2869is specified, no APM BIOS call is performed. Otherwise, the computer 2870is shut down using APM. 2871@end deffn 2872 2873 2874@node help 2875@subsection help 2876 2877@deffn Command help @option{--all} [pattern @dots{}] 2878Display helpful information about builtin commands. If you do not 2879specify @var{pattern}, this command shows short descriptions of most of 2880available commands. If you specify the option @option{--all} to this 2881command, short descriptions of rarely used commands (such as 2882@ref{testload}) are displayed as well. 2883 2884If you specify any @var{patterns}, it displays longer information 2885about each of the commands which match those @var{patterns}. 2886@end deffn 2887 2888 2889@node impsprobe 2890@subsection impsprobe 2891 2892@deffn Command impsprobe 2893Probe the Intel Multiprocessor Specification 1.1 or 1.4 configuration 2894table and boot the various CPUs which are found into a tight loop. This 2895command can be used only in the Stage 2, but not in the grub shell. 2896@end deffn 2897 2898 2899@node initrd 2900@subsection initrd 2901 2902@deffn Command initrd file @dots{} 2903Load an initial ramdisk for a Linux format boot image and set the 2904appropriate parameters in the Linux setup area in memory. See also 2905@ref{GNU/Linux}. 2906@end deffn 2907 2908 2909@node install 2910@subsection install 2911 2912@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] 2913This command is fairly complex, and you should not use this command 2914unless you are familiar with GRUB. Use @command{setup} (@pxref{setup}) 2915instead. 2916 2917In short, it will perform a full install presuming the Stage 2 or Stage 29181.5@footnote{They're loaded the same way, so we will refer to the Stage 29191.5 as a Stage 2 from now on.} is in its final install location. 2920 2921In slightly more detail, it will load @var{stage1_file}, validate that 2922it is a GRUB Stage 1 of the right version number, install in it a 2923blocklist for loading @var{stage2_file} as a Stage 2. If the option 2924@option{d} is present, the Stage 1 will always look for the actual 2925disk @var{stage2_file} was installed on, rather than using the booting 2926drive. The Stage 2 will be loaded at address @var{addr}, which must be 2927@samp{0x8000} for a true Stage 2, and @samp{0x2000} for a Stage 1.5. If 2928@var{addr} is not present, GRUB will determine the address 2929automatically. It then writes the completed Stage 1 to the first block 2930of the device @var{dest_dev}. If the options @option{p} or 2931@var{config_file} are present, then it reads the first block of stage2, 2932modifies it with the values of the partition @var{stage2_file} was found 2933on (for @option{p}) or places the string @var{config_file} into the area 2934telling the stage2 where to look for a configuration file at boot 2935time. Likewise, if @var{real_config_file} is present and 2936@var{stage2_file} is a Stage 1.5, then the Stage 2 @var{config_file} is 2937patched with the configuration file name @var{real_config_file}. This 2938command preserves the DOS BPB (and for hard disks, the partition table) 2939of the sector the Stage 1 is to be installed into. 2940 2941@strong{Caution:} Several buggy BIOSes don't pass a booting drive 2942properly when booting from a hard disk drive. Therefore, you will 2943unfortunately have to specify the option @option{d}, whether your 2944Stage2 resides at the booting drive or not, if you have such a 2945BIOS. We know these are defective in this way: 2946 2947@table @asis 2948@item 2949Fujitsu LifeBook 400 BIOS version 31J0103A 2950 2951@item 2952HP Vectra XU 6/200 BIOS version GG.06.11 2953@end table 2954 2955@strong{Caution2:} A number of BIOSes don't return a correct LBA support 2956bitmap even if they do have the support. So GRUB provides a solution to 2957ignore the wrong bitmap, that is, the option @option{--force-lba}. Don't 2958use this option if you know that your BIOS doesn't have LBA support. 2959 2960@strong{Caution3:} You must specify the option @option{--stage2} in the 2961grub shell, if you cannot unmount the filesystem where your stage2 file 2962resides. The argument should be the file name in your operating system. 2963@end deffn 2964 2965 2966@node ioprobe 2967@subsection ioprobe 2968 2969@deffn Command ioprobe drive 2970Probe I/O ports used for the drive @var{drive}. This command will list 2971the I/O ports on the screen. For technical information, 2972@xref{Internals}. 2973@end deffn 2974 2975 2976@node kernel 2977@subsection kernel 2978 2979@deffn Command kernel [@option{--type=type}] [@option{--no-mem-option}] file @dots{} 2980Attempt to load the primary boot image (Multiboot a.out or @sc{elf}, 2981Linux zImage or bzImage, FreeBSD a.out, NetBSD a.out, etc.) from 2982@var{file}. The rest of the line is passed verbatim as the @dfn{kernel 2983command-line}. Any modules must be reloaded after using this command. 2984 2985This command also accepts the option @option{--type} so that you can 2986specify the kernel type of @var{file} explicitly. The argument 2987@var{type} must be one of these: @samp{netbsd}, @samp{freebsd}, 2988@samp{openbsd}, @samp{linux}, @samp{biglinux}, and 2989@samp{multiboot}. However, you need to specify it only if you want to 2990load a NetBSD @sc{elf} kernel, because GRUB can automatically determine 2991a kernel type in the other cases, quite safely. 2992 2993The option @option{--no-mem-option} is effective only for Linux. If the 2994option is specified, GRUB doesn't pass the option @option{mem=} to the 2995kernel. This option is implied for Linux kernels 2.4.18 and newer. 2996@end deffn 2997 2998 2999@node lock 3000@subsection lock 3001 3002@deffn Command lock 3003Prevent normal users from executing arbitrary menu entries. You must use 3004the command @command{password} if you really want this command to be 3005useful (@pxref{password}). 3006 3007This command is used in a menu, as shown in this example: 3008 3009@example 3010@group 3011title This entry is too dangerous to be executed by normal users 3012lock 3013root (hd0,a) 3014kernel /no-security-os 3015@end group 3016@end example 3017 3018See also @ref{Security}. 3019@end deffn 3020 3021 3022@node makeactive 3023@subsection makeactive 3024 3025@deffn Command makeactive 3026Set the active partition on the root disk to GRUB's root device. 3027This command is limited to @emph{primary} PC partitions on a hard disk. 3028@end deffn 3029 3030 3031@node map 3032@subsection map 3033 3034@deffn Command map to_drive from_drive 3035Map the drive @var{from_drive} to the drive @var{to_drive}. This is 3036necessary when you chain-load some operating systems, such as DOS, if 3037such an OS resides at a non-first drive. Here is an example: 3038 3039@example 3040@group 3041grub> @kbd{map (hd0) (hd1)} 3042grub> @kbd{map (hd1) (hd0)} 3043@end group 3044@end example 3045 3046The example exchanges the order between the first hard disk and the 3047second hard disk. See also @ref{DOS/Windows}. 3048@end deffn 3049 3050 3051@node md5crypt 3052@subsection md5crypt 3053 3054@deffn Command md5crypt 3055Prompt to enter a password, and encrypt it in MD5 format. The encrypted 3056password can be used with the command @command{password} 3057(@pxref{password}). See also @ref{Security}. 3058@end deffn 3059 3060 3061@node module 3062@subsection module 3063 3064@deffn Command module file @dots{} 3065Load a boot module @var{file} for a Multiboot format boot image (no 3066interpretation of the file contents are made, so the user of this 3067command must know what the kernel in question expects). The rest of the 3068line is passed as the @dfn{module command-line}, like the 3069@command{kernel} command. You must load a Multiboot kernel image before 3070loading any module. See also @ref{modulenounzip}. 3071@end deffn 3072 3073 3074@node modulenounzip 3075@subsection modulenounzip 3076 3077@deffn Command modulenounzip file @dots{} 3078The same as @command{module} (@pxref{module}), except that automatic 3079decompression is disabled. 3080@end deffn 3081 3082 3083@node pause 3084@subsection pause 3085 3086@deffn Command pause message @dots{} 3087Print the @var{message}, then wait until a key is pressed. Note that 3088placing @key{^G} (ASCII code 7) in the message will cause the speaker to 3089emit the standard beep sound, which is useful when prompting the user to 3090change floppies. 3091@end deffn 3092 3093 3094@node quit 3095@subsection quit 3096 3097@deffn Command quit 3098Exit from the grub shell @command{grub} (@pxref{Invoking the grub 3099shell}). This command can be used only in the grub shell. 3100@end deffn 3101 3102 3103@node reboot 3104@subsection reboot 3105 3106@deffn Command reboot 3107Reboot the computer. 3108@end deffn 3109 3110 3111@node read 3112@subsection read 3113 3114@deffn Command read addr 3115Read a 32-bit value from memory at address @var{addr} and display it in 3116hex format. 3117@end deffn 3118 3119 3120@node root 3121@subsection root 3122 3123@deffn Command root device [hdbias] 3124Set the current @dfn{root device} to the device @var{device}, then 3125attempt to mount it to get the partition size (for passing the partition 3126descriptor in @code{ES:ESI}, used by some chain-loaded boot loaders), the 3127BSD drive-type (for booting BSD kernels using their native boot format), 3128and correctly determine the PC partition where a BSD sub-partition is 3129located. The optional @var{hdbias} parameter is a number to tell a BSD 3130kernel how many BIOS drive numbers are on controllers before the current 3131one. For example, if there is an IDE disk and a SCSI disk, and your 3132FreeBSD root partition is on the SCSI disk, then use a @samp{1} for 3133@var{hdbias}. 3134 3135See also @ref{rootnoverify}. 3136@end deffn 3137 3138 3139@node rootnoverify 3140@subsection rootnoverify 3141 3142@deffn Command rootnoverify device [hdbias] 3143Similar to @command{root} (@pxref{root}), but don't attempt to mount the 3144partition. This is useful for when an OS is outside of the area of the 3145disk that GRUB can read, but setting the correct root device is still 3146desired. Note that the items mentioned in @command{root} above which 3147derived from attempting the mount will @emph{not} work correctly. 3148@end deffn 3149 3150 3151@node savedefault 3152@subsection savedefault 3153 3154@deffn Command savedefault num 3155Save the current menu entry or @var{num} if specified as a default 3156entry. Here is an example: 3157 3158@example 3159@group 3160default saved 3161timeout 10 3162 3163title GNU/Linux 3164root (hd0,0) 3165kernel /boot/vmlinuz root=/dev/sda1 vga=ext 3166initrd /boot/initrd 3167savedefault 3168 3169title FreeBSD 3170root (hd0,a) 3171kernel /boot/loader 3172savedefault 3173@end group 3174@end example 3175 3176With this configuration, GRUB will choose the entry booted previously as 3177the default entry. 3178 3179You can specify @samp{fallback} instead of a number. Then, next 3180fallback entry is saved. Next fallback entry is chosen from fallback 3181entries. Normally, this will be the first entry in fallback ones. 3182 3183See also @ref{default} and @ref{Invoking grub-set-default}. 3184@end deffn 3185 3186 3187@node setup 3188@subsection setup 3189 3190@deffn Command setup [@option{--force-lba}] [@option{--stage2=os_stage2_file}] [@option{--prefix=dir}] install_device [image_device] 3191Set up the installation of GRUB automatically. This command uses the 3192more flexible command @command{install} (@pxref{install}) in the backend 3193and installs GRUB into the device @var{install_device}. If 3194@var{image_device} is specified, then find the GRUB images 3195(@pxref{Images}) in the device @var{image_device}, otherwise use the 3196current @dfn{root device}, which can be set by the command 3197@command{root}. If @var{install_device} is a hard disk, then embed a 3198Stage 1.5 in the disk if possible. 3199 3200The option @option{--prefix} specifies the directory under which GRUB 3201images are put. If it is not specified, GRUB automatically searches them 3202in @file{/boot/grub} and @file{/grub}. 3203 3204The options @option{--force-lba} and @option{--stage2} are just passed 3205to @command{install} if specified. @xref{install}, for more 3206information. 3207@end deffn 3208 3209 3210@node testload 3211@subsection testload 3212 3213@deffn Command testload file 3214Read the entire contents of @var{file} in several different ways and 3215compare them, to test the filesystem code. The output is somewhat 3216cryptic, but if no errors are reported and the final @samp{i=@var{X}, 3217filepos=@var{Y}} reading has @var{X} and @var{Y} equal, then it is 3218definitely consistent, and very likely works correctly subject to a 3219consistent offset error. If this test succeeds, then a good next step is 3220to try loading a kernel. 3221@end deffn 3222 3223 3224@node testvbe 3225@subsection testvbe 3226 3227@deffn Command testvbe mode 3228Test the VESA BIOS EXTENSION mode @var{mode}. This command will switch 3229your video card to the graphics mode, and show an endless animation. Hit 3230any key to return. See also @ref{vbeprobe}. 3231@end deffn 3232 3233 3234@node uppermem 3235@subsection uppermem 3236 3237@deffn Command uppermem kbytes 3238Force GRUB to assume that only @var{kbytes} kilobytes of upper memory 3239are installed. Any system address range maps are discarded. 3240 3241@strong{Caution:} This should be used with great caution, and should 3242only be necessary on some old machines. GRUB's BIOS probe can pick up 3243all @sc{ram} on all new machines the author has ever heard of. It can 3244also be used for debugging purposes to lie to an OS. 3245@end deffn 3246 3247 3248@node vbeprobe 3249@subsection vbeprobe 3250 3251@deffn Command vbeprobe [mode] 3252Probe VESA BIOS EXTENSION information. If the mode @var{mode} is 3253specified, show only the information about @var{mode}. Otherwise, this 3254command lists up available VBE modes on the screen. See also 3255@ref{testvbe}. 3256@end deffn 3257 3258 3259@node Troubleshooting 3260@chapter Error messages reported by GRUB 3261 3262This chapter describes error messages reported by GRUB when you 3263encounter trouble. @xref{Invoking the grub shell}, if your problem is 3264specific to the grub shell. 3265 3266@menu 3267* Stage1 errors:: Errors reported by the Stage 1 3268* Stage1.5 errors:: Errors reported by the Stage 1.5 3269* Stage2 errors:: Errors reported by the Stage 2 3270@end menu 3271 3272 3273@node Stage1 errors 3274@section Errors reported by the Stage 1 3275 3276The general way that the Stage 1 handles errors is to print an error 3277string and then halt. Pressing @kbd{@key{CTRL}-@key{ALT}-@key{DEL}} will 3278reboot. 3279 3280The following is a comprehensive list of error messages for the Stage 1: 3281 3282@table @asis 3283@item Hard Disk Error 3284The stage2 or stage1.5 is being read from a hard disk, and the attempt 3285to determine the size and geometry of the hard disk failed. 3286 3287@item Floppy Error 3288The stage2 or stage1.5 is being read from a floppy disk, and the attempt 3289to determine the size and geometry of the floppy disk failed. It's listed 3290as a separate error since the probe sequence is different than for hard 3291disks. 3292 3293@item Read Error 3294A disk read error happened while trying to read the stage2 or stage1.5. 3295 3296@item Geom Error 3297The location of the stage2 or stage1.5 is not in the portion of the disk 3298supported directly by the BIOS read calls. This could occur because the 3299BIOS translated geometry has been changed by the user or the disk is 3300moved to another machine or controller after installation, or GRUB was 3301not installed using itself (if it was, the Stage 2 version of this error 3302would have been seen during that process and it would not have completed 3303the install). 3304@end table 3305 3306 3307@node Stage1.5 errors 3308@section Errors reported by the Stage 1.5 3309 3310The general way that the Stage 1.5 handles errors is to print an error 3311number in the form @code{Error @var{num}} and then halt. Pressing 3312@kbd{@key{CTRL}-@key{ALT}-@key{DEL}} will reboot. 3313 3314The error numbers correspond to the errors reported by Stage 33152. @xref{Stage2 errors}. 3316 3317 3318@node Stage2 errors 3319@section Errors reported by the Stage 2 3320 3321The general way that the Stage 2 handles errors is to abort the 3322operation in question, print an error string, then (if possible) either 3323continue based on the fact that an error occurred or wait for the user to 3324deal with the error. 3325 3326The following is a comprehensive list of error messages for the Stage 2 3327(error numbers for the Stage 1.5 are listed before the colon in each 3328description): 3329 3330@table @asis 3331@item 1 : Filename must be either an absolute filename or blocklist 3332This error is returned if a file name is requested which doesn't fit the 3333syntax/rules listed in the @ref{Filesystem}. 3334 3335@item 2 : Bad file or directory type 3336This error is returned if a file requested is not a regular file, but 3337something like a symbolic link, directory, or FIFO. 3338 3339@item 3 : Bad or corrupt data while decompressing file 3340This error is returned if the run-length decompression code gets an 3341internal error. This is usually from a corrupt file. 3342 3343@item 4 : Bad or incompatible header in compressed file 3344This error is returned if the file header for a supposedly compressed 3345file is bad. 3346 3347@item 5 : Partition table invalid or corrupt 3348This error is returned if the sanity checks on the integrity of the 3349partition table fail. This is a bad sign. 3350 3351@item 6 : Mismatched or corrupt version of stage1/stage2 3352This error is returned if the install command points to incompatible 3353or corrupt versions of the stage1 or stage2. It can't detect corruption 3354in general, but this is a sanity check on the version numbers, which 3355should be correct. 3356 3357@item 7 : Loading below 1MB is not supported 3358This error is returned if the lowest address in a kernel is below the 33591MB boundary. The Linux zImage format is a special case and can be 3360handled since it has a fixed loading address and maximum size. 3361 3362@item 8 : Kernel must be loaded before booting 3363This error is returned if GRUB is told to execute the boot sequence 3364without having a kernel to start. 3365 3366@item 9 : Unknown boot failure 3367This error is returned if the boot attempt did not succeed for reasons 3368which are unknown. 3369 3370@item 10 : Unsupported Multiboot features requested 3371This error is returned when the Multiboot features word in the Multiboot 3372header requires a feature that is not recognized. The point of this is 3373that the kernel requires special handling which GRUB is probably 3374unable to provide. 3375 3376@item 11 : Unrecognized device string 3377This error is returned if a device string was expected, and the string 3378encountered didn't fit the syntax/rules listed in the @ref{Filesystem}. 3379 3380@item 12 : Invalid device requested 3381This error is returned if a device string is recognizable but does not 3382fall under the other device errors. 3383 3384@item 13 : Invalid or unsupported executable format 3385This error is returned if the kernel image being loaded is not 3386recognized as Multiboot or one of the supported native formats (Linux 3387zImage or bzImage, FreeBSD, or NetBSD). 3388 3389@item 14 : Filesystem compatibility error, cannot read whole file 3390Some of the filesystem reading code in GRUB has limits on the length of 3391the files it can read. This error is returned when the user runs into 3392such a limit. 3393 3394@item 15 : File not found 3395This error is returned if the specified file name cannot be found, but 3396everything else (like the disk/partition info) is OK. 3397 3398@item 16 : Inconsistent filesystem structure 3399This error is returned by the filesystem code to denote an internal 3400error caused by the sanity checks of the filesystem structure on disk 3401not matching what it expects. This is usually caused by a corrupt 3402filesystem or bugs in the code handling it in GRUB. 3403 3404@item 17 : Cannot mount selected partition 3405This error is returned if the partition requested exists, but the 3406filesystem type cannot be recognized by GRUB. 3407 3408@item 18 : Selected cylinder exceeds maximum supported by BIOS 3409This error is returned when a read is attempted at a linear block 3410address beyond the end of the BIOS translated area. This generally 3411happens if your disk is larger than the BIOS can handle (512MB for 3412(E)IDE disks on older machines or larger than 8GB in general). 3413 3414@item 19 : Linux kernel must be loaded before initrd 3415This error is returned if the initrd command is used before loading a 3416Linux kernel. 3417 3418@item 20 : Multiboot kernel must be loaded before modules 3419This error is returned if the module load command is used before loading 3420a Multiboot kernel. It only makes sense in this case anyway, as GRUB has 3421no idea how to communicate the presence of such modules to a 3422non-Multiboot-aware kernel. 3423 3424@item 21 : Selected disk does not exist 3425This error is returned if the device part of a device- or full file name 3426refers to a disk or BIOS device that is not present or not recognized by 3427the BIOS in the system. 3428 3429@item 22 : No such partition 3430This error is returned if a partition is requested in the device part of 3431a device- or full file name which isn't on the selected disk. 3432 3433@item 23 : Error while parsing number 3434This error is returned if GRUB was expecting to read a number and 3435encountered bad data. 3436 3437@item 24 : Attempt to access block outside partition 3438This error is returned if a linear block address is outside of the disk 3439partition. This generally happens because of a corrupt filesystem on the 3440disk or a bug in the code handling it in GRUB (it's a great debugging 3441tool). 3442 3443@item 25 : Disk read error 3444This error is returned if there is a disk read error when trying to 3445probe or read data from a particular disk. 3446 3447@item 26 : Too many symbolic links 3448This error is returned if the link count is beyond the maximum 3449(currently 5), possibly the symbolic links are looped. 3450 3451@item 27 : Unrecognized command 3452This error is returned if an unrecognized command is entered on the 3453command-line or in a boot sequence section of a configuration file and 3454that entry is selected. 3455 3456@item 28 : Selected item cannot fit into memory 3457This error is returned if a kernel, module, or raw file load command is 3458either trying to load its data such that it won't fit into memory or it 3459is simply too big. 3460 3461@item 29 : Disk write error 3462This error is returned if there is a disk write error when trying to 3463write to a particular disk. This would generally only occur during an 3464install of set active partition command. 3465 3466@item 30 : Invalid argument 3467This error is returned if an argument specified to a command is invalid. 3468 3469@item 31 : File is not sector aligned 3470This error may occur only when you access a ReiserFS partition by 3471block-lists (e.g. the command @command{install}). In this case, you 3472should mount the partition with the @samp{-o notail} option. 3473 3474@item 32 : Must be authenticated 3475This error is returned if you try to run a locked entry. You should 3476enter a correct password before running such an entry. 3477 3478@item 33 : Serial device not configured 3479This error is returned if you try to change your terminal to a serial 3480one before initializing any serial device. 3481 3482@item 34 : No spare sectors on the disk 3483This error is returned if a disk doesn't have enough spare space. This 3484happens when you try to embed Stage 1.5 into the unused sectors after 3485the MBR, but the first partition starts right after the MBR or they are 3486used by EZ-BIOS. 3487@end table 3488 3489 3490@node Invoking the grub shell 3491@chapter Invoking the grub shell 3492 3493This chapter documents the grub shell @command{grub}. Note that the grub 3494shell is an emulator; it doesn't run under the native environment, so it 3495sometimes does something wrong. Therefore, you shouldn't trust it too 3496much. If there is anything wrong with it, don't hesitate to try the 3497native GRUB environment, especially when it guesses a wrong map between 3498BIOS drives and OS devices. 3499 3500@menu 3501* Basic usage:: How to use the grub shell 3502* Installation under UNIX:: How to install GRUB via @command{grub} 3503* Device map:: The map between BIOS drives and OS devices 3504@end menu 3505 3506 3507@node Basic usage 3508@section Introduction into the grub shell 3509 3510You can use the command @command{grub} for installing GRUB under your 3511operating systems and for a testbed when you add a new feature into GRUB 3512or when fixing a bug. @command{grub} is almost the same as the Stage 2, 3513and, in fact, it shares the source code with the Stage 2 and you can use 3514the same commands (@pxref{Commands}) in @command{grub}. It is emulated by 3515replacing BIOS calls with UNIX system calls and libc functions. 3516 3517The command @command{grub} accepts the following options: 3518 3519@table @option 3520@item --help 3521Print a summary of the command-line options and exit. 3522 3523@item --version 3524Print the version number of GRUB and exit. 3525 3526@item --verbose 3527Print some verbose messages for debugging purpose. 3528 3529@item --device-map=@var{file} 3530Use the device map file @var{file}. The format is described in 3531@ref{Device map}. 3532 3533@item --no-floppy 3534Do not probe any floppy drive. This option has no effect if the option 3535@option{--device-map} is specified (@pxref{Device map}). 3536 3537@item --probe-second-floppy 3538Probe the second floppy drive. If this option is not specified, the grub 3539shell does not probe it, as that sometimes takes a long time. If you 3540specify the device map file (@pxref{Device map}), the grub shell just 3541ignores this option. 3542 3543@item --config-file=@var{file} 3544Read the configuration file @var{file} instead of 3545@file{/boot/grub/menu.lst}. The format is the same as the normal GRUB 3546syntax. See @ref{Filesystem}, for more information. 3547 3548@item --boot-drive=@var{drive} 3549Set the stage2 @var{boot_drive} to @var{drive}. This argument should be 3550an integer (decimal, octal or hexadecimal). 3551 3552@item --install-partition=@var{par} 3553Set the stage2 @var{install_partition} to @var{par}. This argument 3554should be an integer (decimal, octal or hexadecimal). 3555 3556@item --no-config-file 3557Do not use the configuration file even if it can be read. 3558 3559@item --no-curses 3560Do not use the screen handling interface by the curses even if it is 3561available. 3562 3563@item --batch 3564This option has the same meaning as @samp{--no-config-file --no-curses}. 3565 3566@item --read-only 3567Disable writing to any disk. 3568 3569@item --hold 3570Wait until a debugger will attach. This option is useful when you want 3571to debug the startup code. 3572@end table 3573 3574 3575@node Installation under UNIX 3576@section How to install GRUB via @command{grub} 3577 3578The installation procedure is the same as under the @dfn{native} Stage 35792. @xref{Installation}, for more information. The command 3580@command{grub}-specific information is described here. 3581 3582What you should be careful about is @dfn{buffer cache}. @command{grub} 3583makes use of raw devices instead of filesystems that your operating 3584systems serve, so there exists a potential problem that some cache 3585inconsistency may corrupt your filesystems. What we recommend is: 3586 3587@itemize @bullet 3588@item 3589If you can unmount drives to which GRUB may write any amount of data, 3590unmount them before running @command{grub}. 3591 3592@item 3593If a drive cannot be unmounted but can be mounted with the read-only 3594flag, mount it in read-only mode. That should be secure. 3595 3596@item 3597If a drive must be mounted with the read-write flag, make sure that no 3598activity is being done on it while the command @command{grub} is 3599running. 3600 3601@item 3602Reboot your operating system as soon as possible. This is probably not 3603required if you follow the rules above, but reboot is the most secure 3604way. 3605@end itemize 3606 3607In addition, enter the command @command{quit} when you finish the 3608installation. That is @emph{very important} because @command{quit} makes 3609the buffer cache consistent. Do not push @key{C-c}. 3610 3611If you want to install GRUB non-interactively, specify @samp{--batch} 3612option in the command-line. This is a simple example: 3613 3614@example 3615@group 3616#!/bin/sh 3617 3618# Use /usr/sbin/grub if you are on an older system. 3619/sbin/grub --batch <<EOT 1>/dev/null 2>/dev/null 3620root (hd0,0) 3621setup (hd0) 3622quit 3623EOT 3624@end group 3625@end example 3626 3627 3628@node Device map 3629@section The map between BIOS drives and OS devices 3630 3631When you specify the option @option{--device-map} (@pxref{Basic usage}), 3632the grub shell creates the @dfn{device map file} automatically unless it 3633already exists. The file name @file{/boot/grub/device.map} is preferred. 3634 3635If the device map file exists, the grub shell reads it to map BIOS 3636drives to OS devices. This file consists of lines like this: 3637 3638@example 3639@var{device} @var{file} 3640@end example 3641 3642@var{device} is a drive specified in the GRUB syntax (@pxref{Device 3643syntax}), and @var{file} is an OS file, which is normally a device 3644file. 3645 3646The reason why the grub shell gives you the device map file is that it 3647cannot guess the map between BIOS drives and OS devices correctly in 3648some environments. For example, if you exchange the boot sequence 3649between IDE and SCSI in your BIOS, it gets the order wrong. 3650 3651Thus, edit the file if the grub shell makes a mistake. You can put any 3652comments in the file if needed, as the grub shell assumes that a line is 3653just a comment if the first character is @samp{#}. 3654 3655 3656@node Invoking grub-install 3657@chapter Invoking grub-install 3658 3659The program @command{grub-install} installs GRUB on your drive using the 3660grub shell (@pxref{Invoking the grub shell}). You must specify the 3661device name on which you want to install GRUB, like this: 3662 3663@example 3664grub-install @var{install_device} 3665@end example 3666 3667The device name @var{install_device} is an OS device name or a GRUB 3668device name. 3669 3670@command{grub-install} accepts the following options: 3671 3672@table @option 3673@item --help 3674Print a summary of the command-line options and exit. 3675 3676@item --version 3677Print the version number of GRUB and exit. 3678 3679@item --force-lba 3680Force GRUB to use LBA mode even for a buggy BIOS. Use this option only 3681if your BIOS doesn't work properly in LBA mode even though it supports 3682LBA mode. 3683 3684@item --root-directory=@var{dir} 3685Install GRUB images under the directory @var{dir} instead of the root 3686directory. This option is useful when you want to install GRUB into a 3687separate partition or a removable disk. Here is an example in which 3688you have a separate @dfn{boot} partition which is mounted on 3689@file{/boot}: 3690 3691@example 3692@kbd{grub-install --root-directory=/boot hd0} 3693@end example 3694 3695@item --grub-shell=@var{file} 3696Use @var{file} as the grub shell. You can append arbitrary options to 3697@var{file} after the file name, like this: 3698 3699@example 3700@kbd{grub-install --grub-shell="grub --read-only" /dev/fd0} 3701@end example 3702 3703@item --recheck 3704Recheck the device map, even if @file{/boot/grub/device.map} already 3705exists. You should use this option whenever you add/remove a disk 3706into/from your computer. 3707@end table 3708 3709 3710@node Invoking grub-md5-crypt 3711@chapter Invoking grub-md5-crypt 3712 3713The program @command{grub-md5-crypt} encrypts a password in MD5 format. 3714This is just a frontend of the grub shell (@pxref{Invoking the grub 3715shell}). Passwords encrypted by this program can be used with the 3716command @command{password} (@pxref{password}). 3717 3718@command{grub-md5-crypt} accepts the following options: 3719 3720@table @option 3721@item --help 3722Print a summary of the command-line options and exit. 3723 3724@item --version 3725Print the version information and exit. 3726 3727@item --grub-shell=@var{file} 3728Use @var{file} as the grub shell. 3729@end table 3730 3731 3732@node Invoking grub-terminfo 3733@chapter Invoking grub-terminfo 3734 3735The program @command{grub-terminfo} generates a terminfo command from 3736a terminfo name (@pxref{terminfo}). The result can be used in the 3737configuration file, to define escape sequences. Because GRUB assumes 3738that your terminal is vt100-compatible by default, this would be 3739useful only if your terminal is uncommon (such as vt52). 3740 3741@command{grub-terminfo} accepts the following options: 3742 3743@table @option 3744@item --help 3745Print a summary of the command-line options and exit. 3746 3747@item --version 3748Print the version information and exit. 3749@end table 3750 3751You must specify one argument to this command. For example: 3752 3753@example 3754@kbd{grub-terminfo vt52} 3755@end example 3756 3757 3758@node Invoking grub-set-default 3759@chapter Invoking grub-set-default 3760 3761The program @command{grub-set-default} sets the default boot entry for 3762GRUB. This automatically creates a file named @file{default} under 3763your GRUB directory (i.e. @file{/boot/grub}), if it is not 3764present. This file is used to determine the default boot entry when 3765GRUB boots up your system when you use @samp{default saved} in your 3766configuration file (@pxref{default}), and to save next default boot 3767entry when you use @samp{savedefault} in a boot entry 3768(@pxref{savedefault}). 3769 3770@command{grub-set-default} accepts the following options: 3771 3772@table @option 3773@item --help 3774Print a summary of the command-line options and exit. 3775 3776@item --version 3777Print the version information and exit. 3778 3779@item --root-directory=@var{dir} 3780Use the directory @var{dir} instead of the root directory 3781(i.e. @file{/}) to define the location of the default file. This 3782is useful when you mount a disk which is used for another system. 3783@end table 3784 3785You must specify a single argument to @command{grub-set-default}. This 3786argument is normally the number of a default boot entry. For example, 3787if you have this configuration file: 3788 3789@example 3790@group 3791default saved 3792timeout 10 3793 3794title GNU/Hurd 3795root (hd0,0) 3796... 3797 3798title GNU/Linux 3799root (hd0,1) 3800... 3801@end group 3802@end example 3803 3804and if you want to set the next default boot entry to GNU/Linux, you 3805may execute this command: 3806 3807@example 3808@kbd{grub-set-default 1} 3809@end example 3810 3811Because the entry for GNU/Linux is @samp{1}. Note that entries are 3812counted from zero. So, if you want to specify GNU/Hurd here, then you 3813should specify @samp{0}. 3814 3815This feature is very useful if you want to test a new kernel or to 3816make your system quite robust. @xref{Making your system robust}, for 3817more hints about how to set up a robust system. 3818 3819 3820@node Invoking mbchk 3821@chapter Invoking mbchk 3822 3823The program @command{mbchk} checks for the format of a Multiboot 3824kernel. We recommend using this program before booting your own kernel 3825by GRUB. 3826 3827@command{mbchk} accepts the following options: 3828 3829@table @option 3830@item --help 3831Print a summary of the command-line options and exit. 3832 3833@item --version 3834Print the version number of GRUB and exit. 3835 3836@item --quiet 3837Suppress all normal output. 3838@end table 3839 3840 3841@node Obtaining and Building GRUB 3842@appendix How to obtain and build GRUB 3843 3844@quotation 3845@strong{Caution:} GRUB requires binutils-2.9.1.0.23 or later because the 3846GNU assembler has been changed so that it can produce real 16bits 3847machine code between 2.9.1 and 2.9.1.0.x. See 3848@uref{http://sources.redhat.com/binutils/}, to obtain information on 3849how to get the latest version. 3850@end quotation 3851 3852GRUB is available from the GNU alpha archive site 3853@uref{ftp://alpha.gnu.org/gnu/grub} or any of its mirrors. The file 3854will be named grub-version.tar.gz. The current version is 3855@value{VERSION}, so the file you should grab is: 3856 3857@uref{ftp://alpha.gnu.org/gnu/grub/grub-@value{VERSION}.tar.gz} 3858 3859To unbundle GRUB use the instruction: 3860 3861@example 3862@kbd{zcat grub-@value{VERSION}.tar.gz | tar xvf -} 3863@end example 3864 3865which will create a directory called @file{grub-@value{VERSION}} with 3866all the sources. You can look at the file @file{INSTALL} for detailed 3867instructions on how to build and install GRUB, but you should be able to 3868just do: 3869 3870@example 3871@group 3872@kbd{cd grub-@value{VERSION}} 3873@kbd{./configure} 3874@kbd{make install} 3875@end group 3876@end example 3877 3878This will install the grub shell @file{grub} (@pxref{Invoking the grub 3879shell}), the Multiboot checker @file{mbchk} (@pxref{Invoking mbchk}), 3880and the GRUB images. This will also install the GRUB manual. 3881 3882Also, the latest version is available from the CVS. See 3883@uref{http://savannah.gnu.org/cvs/?group=grub} for more information. 3884 3885 3886@node Reporting bugs 3887@appendix Reporting bugs 3888 3889These are the guideline for how to report bugs. Take a look at this 3890list below before you submit bugs: 3891 3892@enumerate 3893@item 3894Before getting unsettled, read this manual through and through. Also, 3895see the @uref{http://www.gnu.org/software/grub/grub-faq.html, GNU GRUB FAQ}. 3896 3897@item 3898Always mention the information on your GRUB. The version number and the 3899configuration are quite important. If you build it yourself, write the 3900options specified to the configure script and your operating system, 3901including the versions of gcc and binutils. 3902 3903@item 3904If you have trouble with the installation, inform us of how you 3905installed GRUB. Don't omit error messages, if any. Just @samp{GRUB hangs 3906up when it boots} is not enough. 3907 3908The information on your hardware is also essential. These are especially 3909important: the geometries and the partition tables of your hard disk 3910drives and your BIOS. 3911 3912@item 3913If GRUB cannot boot your operating system, write down 3914@emph{everything} you see on the screen. Don't paraphrase them, like 3915@samp{The foo OS crashes with GRUB, even though it can boot with the 3916bar boot loader just fine}. Mention the commands you executed, the 3917messages printed by them, and information on your operating system 3918including the version number. 3919 3920@item 3921Explain what you wanted to do. It is very useful to know your purpose 3922and your wish, and how GRUB didn't satisfy you. 3923 3924@item 3925If you can investigate the problem yourself, please do. That will give 3926you and us much more information on the problem. Attaching a patch is 3927even better. 3928 3929When you attach a patch, make the patch in unified diff format, and 3930write ChangeLog entries. But, even when you make a patch, don't forget 3931to explain the problem, so that we can understand what your patch is 3932for. 3933 3934@item 3935Write down anything that you think might be related. Please understand 3936that we often need to reproduce the same problem you encounterred in our 3937environment. So your information should be sufficient for us to do the 3938same thing---Don't forget that we cannot see your computer directly. If 3939you are not sure whether to state a fact or leave it out, state it! 3940Reporting too many things is much better than omitting something 3941important. 3942@end enumerate 3943 3944If you follow the guideline above, submit a report to the 3945@uref{http://savannah.gnu.org/bugs/?group=grub, Bug Tracking System}. 3946Alternatively, you can submit a report via electronic mail to 3947@email{bug-grub@@gnu.org}, but we strongly recommend that you use the 3948Bug Tracking System, because e-mail can be passed over easily. 3949 3950Once we get your report, we will try to fix the bugs. 3951 3952 3953@node Future 3954@appendix Where GRUB will go 3955 3956We started the next generation of GRUB, GRUB 2. This will include 3957internationalization, dynamic module loading, real memory management, 3958multiple architecture support, a scripting language, and many other 3959nice feature. If you are interested in the development of GRUB 2, take 3960a look at @uref{http://www.gnu.org/software/grub/grub.html, the 3961homepage}. 3962 3963 3964@c Separate the programming guide. 3965@include internals.texi 3966 3967 3968@node Index 3969@unnumbered Index 3970 3971@c Currently, we use only the Concept Index. 3972@printindex cp 3973 3974 3975@bye 3976 3977Some notes: 3978 3979 This is the second attempt to rewrite the manual. The status is 3980mostly complete, but I need to check the spelling by ispell, and add 3981more indices. Perhaps I also have to let some English native speakers 3982proofread this manual through. My English is syntactically almost 3983perfect, but sometimes (often?) awful in the nuance. Hehe, I can't be an 3984English poet for now. 3985