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 1550GRUB sends the string "GRUBClient" as its vendor class identifier to 1551the BOOTP/DHCP server. This can be used to generate answers specific 1552to GRUB clients on your network. 1553 1554See the manual of your BOOTP/DHCP server for more information. The 1555exact syntax should differ a little from the example. 1556 1557@node Serial terminal 1558@chapter Using GRUB via a serial line 1559 1560This chapter describes how to use the serial terminal support in GRUB. 1561 1562If you have many computers or computers with no display/keyboard, it 1563could be very useful to control the computers through serial 1564communications. To connect one computer with another via a serial line, 1565you need to prepare a null-modem (cross) serial cable, and you may need 1566to have multiport serial boards, if your computer doesn't have extra 1567serial ports. In addition, a terminal emulator is also required, such as 1568minicom. Refer to a manual of your operating system, for more 1569information. 1570 1571As for GRUB, the instruction to set up a serial terminal is quite 1572simple. First of all, make sure that you haven't specified the option 1573@option{--disable-serial} to the configure script when you built your 1574GRUB images. If you get them in binary form, probably they have serial 1575terminal support already. 1576 1577Then, initialize your serial terminal after GRUB starts up. Here is an 1578example: 1579 1580@example 1581@group 1582grub> @kbd{serial --unit=0 --speed=9600} 1583grub> @kbd{terminal serial} 1584@end group 1585@end example 1586 1587The command @command{serial} initializes the serial unit 0 with the 1588speed 9600bps. The serial unit 0 is usually called @samp{COM1}, so, if 1589you want to use COM2, you must specify @samp{--unit=1} instead. This 1590command accepts many other options, so please refer to @ref{serial}, 1591for more details. 1592 1593The command @command{terminal} (@pxref{terminal}) chooses which type of 1594terminal you want to use. In the case above, the terminal will be a 1595serial terminal, but you can also pass @code{console} to the command, 1596as @samp{terminal serial console}. In this case, a terminal in which 1597you press any key will be selected as a GRUB terminal. 1598 1599However, note that GRUB assumes that your terminal emulator is 1600compatible with VT100 by default. This is true for most terminal 1601emulators nowadays, but you should pass the option @option{--dumb} to 1602the command if your terminal emulator is not VT100-compatible or 1603implements few VT100 escape sequences. If you specify this option then 1604GRUB provides you with an alternative menu interface, because the normal 1605menu requires several fancy features of your terminal. 1606 1607 1608@node Preset Menu 1609@chapter Embedding a configuration file into GRUB 1610 1611GRUB supports a @dfn{preset menu} which is to be always loaded before 1612starting. The preset menu feature is useful, for example, when your 1613computer has no console but a serial cable. In this case, it is 1614critical to set up the serial terminal as soon as possible, since you 1615cannot see any message until the serial terminal begins to work. So it 1616is good to run the commands @command{serial} (@pxref{serial}) and 1617@command{terminal} (@pxref{terminal}) before anything else at the 1618start-up time. 1619 1620How the preset menu works is slightly complicated: 1621 1622@enumerate 1623@item 1624GRUB checks if the preset menu feature is used, and loads the preset 1625menu, if available. This includes running commands and reading boot 1626entries, like an ordinary configuration file. 1627 1628@item 1629GRUB checks if the configuration file is available. Note that this check 1630is performed @strong{regardless of the existence of the preset 1631menu}. The configuration file is loaded even if the preset menu was 1632loaded. 1633 1634@item 1635If the preset menu includes any boot entries, they are cleared when 1636the configuration file is loaded. It doesn't matter whether the 1637configuration file has any entries or no entry. The boot entries in the 1638preset menu are used only when GRUB fails in loading the configuration 1639file. 1640@end enumerate 1641 1642To enable the preset menu feature, you must rebuild GRUB specifying a 1643file to the configure script with the option 1644@option{--enable-preset-menu}. The file has the same semantics as 1645normal configuration files (@pxref{Configuration}). 1646 1647Another point you should take care is that the diskless support 1648(@pxref{Diskless}) diverts the preset menu. Diskless images embed a 1649preset menu to execute the command @command{bootp} (@pxref{bootp}) 1650automatically, unless you specify your own preset menu to the configure 1651script. This means that you must put commands to initialize a network in 1652the preset menu yourself, because diskless images don't set it up 1653implicitly, when you use the preset menu explicitly. 1654 1655Therefore, a typical preset menu used with diskless support would be 1656like this: 1657 1658@example 1659@group 1660# Set up the serial terminal, first of all. 1661serial --unit=0 --speed=19200 1662terminal --timeout=0 serial 1663 1664# Initialize the network. 1665dhcp 1666@end group 1667@end example 1668 1669 1670@node Security 1671@chapter Protecting your computer from cracking 1672 1673You may be interested in how to prevent ordinary users from doing 1674whatever they like, if you share your computer with other people. So 1675this chapter describes how to improve the security of GRUB. 1676 1677One thing which could be a security hole is that the user can do too 1678many things with GRUB, because GRUB allows one to modify its configuration 1679and run arbitrary commands at run-time. For example, the user can even 1680read @file{/etc/passwd} in the command-line interface by the command 1681@command{cat} (@pxref{cat}). So it is necessary to disable all the 1682interactive operations. 1683 1684Thus, GRUB provides a @dfn{password} feature, so that only administrators 1685can start the interactive operations (i.e. editing menu entries and 1686entering the command-line interface). To use this feature, you need to 1687run the command @command{password} in your configuration file 1688(@pxref{password}), like this: 1689 1690@example 1691password --md5 PASSWORD 1692@end example 1693 1694If this is specified, GRUB disallows any interactive control, until you 1695press the key @key{p} and enter a correct password. The option 1696@option{--md5} tells GRUB that @samp{PASSWORD} is in MD5 format. If it 1697is omitted, GRUB assumes the @samp{PASSWORD} is in clear text. 1698 1699You can encrypt your password with the command @command{md5crypt} 1700(@pxref{md5crypt}). For example, run the grub shell (@pxref{Invoking the 1701grub shell}), and enter your password: 1702 1703@example 1704@group 1705grub> md5crypt 1706Password: ********** 1707Encrypted: $1$U$JK7xFegdxWH6VuppCUSIb. 1708@end group 1709@end example 1710 1711Then, cut and paste the encrypted password to your configuration file. 1712 1713Also, you can specify an optional argument to @command{password}. See 1714this example: 1715 1716@example 1717password PASSWORD /boot/grub/menu-admin.lst 1718@end example 1719 1720In this case, GRUB will load @file{/boot/grub/menu-admin.lst} as a 1721configuration file when you enter the valid password. 1722 1723Another thing which may be dangerous is that any user can choose any 1724menu entry. Usually, this wouldn't be problematic, but you might want to 1725permit only administrators to run some of your menu entries, such as an 1726entry for booting an insecure OS like DOS. 1727 1728GRUB provides the command @command{lock} (@pxref{lock}). This command 1729always fails until you enter the valid password, so you can use it, like 1730this: 1731 1732@example 1733@group 1734title Boot DOS 1735lock 1736rootnoverify (hd0,1) 1737makeactive 1738chainload +1 1739@end group 1740@end example 1741 1742You should insert @command{lock} right after @command{title}, because 1743any user can execute commands in an entry until GRUB encounters 1744@command{lock}. 1745 1746You can also use the command @command{password} instead of 1747@command{lock}. In this case the boot process will ask for the password 1748and stop if it was entered incorrectly. Since the @command{password} 1749takes its own @var{PASSWORD} argument this is useful if you want 1750different passwords for different entries. 1751 1752 1753@node Images 1754@chapter GRUB image files 1755 1756GRUB consists of several images: two essential stages, optional stages 1757called @dfn{Stage 1.5}, one image for bootable CD-ROM, and two network 1758boot images. Here is a short overview of them. @xref{Internals}, for 1759more details. 1760 1761@table @file 1762@item stage1 1763This is an essential image used for booting up GRUB. Usually, this is 1764embedded in an MBR or the boot sector of a partition. Because a PC boot 1765sector is 512 bytes, the size of this image is exactly 512 bytes. 1766 1767All @file{stage1} must do is to load Stage 2 or Stage 1.5 from a local 1768disk. Because of the size restriction, @file{stage1} encodes the 1769location of Stage 2 (or Stage 1.5) in a block list format, so it never 1770understand any filesystem structure. 1771 1772@item stage2 1773This is the core image of GRUB. It does everything but booting up 1774itself. Usually, this is put in a filesystem, but that is not required. 1775 1776@item e2fs_stage1_5 1777@itemx fat_stage1_5 1778@itemx ffs_stage1_5 1779@itemx jfs_stage1_5 1780@itemx minix_stage1_5 1781@itemx reiserfs_stage1_5 1782@itemx vstafs_stage1_5 1783@itemx xfs_stage1_5 1784 1785These are called @dfn{Stage 1.5}, because they serve as a bridge 1786between @file{stage1} and @file{stage2}, that is to say, Stage 1.5 is 1787loaded by Stage 1 and Stage 1.5 loads Stage 2. The difference between 1788@file{stage1} and @file{*_stage1_5} is that the former doesn't 1789understand any filesystem while the latter understands one filesystem 1790(e.g. @file{e2fs_stage1_5} understands ext2fs). So you can move the 1791Stage 2 image to another location safely, even after GRUB has been 1792installed. 1793 1794While Stage 2 cannot generally be embedded in a fixed area as the size 1795is so large, Stage 1.5 can be installed into the area right after an MBR, 1796or the boot loader area of a ReiserFS or a FFS. 1797 1798@item stage2_eltorito 1799This is a boot image for CD-ROMs using the @dfn{no emulation mode} in 1800El Torito specification. This is identical to Stage 2, except that 1801this boots up without Stage 1 and sets up a special drive @samp{(cd)}. 1802 1803@item nbgrub 1804This is a network boot image for the Network Image Proposal used by some 1805network boot loaders, such as Etherboot. This is mostly the same as 1806Stage 2, but it also sets up a network and loads a configuration file 1807from the network. 1808 1809@item pxegrub 1810This is another network boot image for the Preboot Execution Environment 1811used by several Netboot ROMs. This is identical to @file{nbgrub}, except 1812for the format. 1813@end table 1814 1815 1816@node Filesystem 1817@chapter Filesystem syntax and semantics 1818 1819GRUB uses a special syntax for specifying disk drives which can be 1820accessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish 1821between IDE, ESDI, SCSI, or others. You must know yourself which BIOS 1822device is equivalent to which OS device. Normally, that will be clear if 1823you see the files in a device or use the command @command{find} 1824(@pxref{find}). 1825 1826@menu 1827* Device syntax:: How to specify devices 1828* File name syntax:: How to specify files 1829* Block list syntax:: How to specify block lists 1830@end menu 1831 1832 1833@node Device syntax 1834@section How to specify devices 1835 1836The device syntax is like this: 1837 1838@example 1839@code{(@var{device}[,@var{part-num}][,@var{bsd-subpart-letter}])} 1840@end example 1841 1842@samp{[]} means the parameter is optional. @var{device} should be 1843either @samp{fd} or @samp{hd} followed by a digit, like @samp{fd0}. 1844But you can also set @var{device} to a hexadecimal or a decimal number 1845which is a BIOS drive number, so the following are equivalent: 1846 1847@example 1848(hd0) 1849(0x80) 1850(128) 1851@end example 1852 1853@var{part-num} represents the partition number of @var{device}, starting 1854from zero for primary partitions and from four for extended partitions, 1855and @var{bsd-subpart-letter} represents the BSD disklabel subpartition, 1856such as @samp{a} or @samp{e}. 1857 1858A shortcut for specifying BSD subpartitions is 1859@code{(@var{device},@var{bsd-subpart-letter})}, in this case, GRUB 1860searches for the first PC partition containing a BSD disklabel, then 1861finds the subpartition @var{bsd-subpart-letter}. Here is an example: 1862 1863@example 1864(hd0,a) 1865@end example 1866 1867The syntax @samp{(hd0)} represents using the entire disk (or the 1868MBR when installing GRUB), while the syntax @samp{(hd0,0)} 1869represents using the first partition of the disk (or the boot sector 1870of the partition when installing GRUB). 1871 1872If you enabled the network support, the special drive, @samp{(nd)}, is 1873also available. Before using the network drive, you must initialize the 1874network. @xref{Network}, for more information. 1875 1876If you boot GRUB from a CD-ROM, @samp{(cd)} is available. @xref{Making 1877a GRUB bootable CD-ROM}, for details. 1878 1879 1880@node File name syntax 1881@section How to specify files 1882 1883There are two ways to specify files, by @dfn{absolute file name} and by 1884@dfn{block list}. 1885 1886An absolute file name resembles a Unix absolute file name, using 1887@samp{/} for the directory separator (not @samp{\} as in DOS). One 1888example is @samp{(hd0,0)/boot/grub/menu.lst}. This means the file 1889@file{/boot/grub/menu.lst} in the first partition of the first hard 1890disk. If you omit the device name in an absolute file name, GRUB uses 1891GRUB's @dfn{root device} implicitly. So if you set the root device to, 1892say, @samp{(hd1,0)} by the command @command{root} (@pxref{root}), then 1893@code{/boot/kernel} is the same as @code{(hd1,0)/boot/kernel}. 1894 1895 1896@node Block list syntax 1897@section How to specify block lists 1898 1899A block list is used for specifying a file that doesn't appear in the 1900filesystem, like a chainloader. The syntax is 1901@code{[@var{offset}]+@var{length}[,[@var{offset}]+@var{length}]@dots{}}. 1902Here is an example: 1903 1904@example 1905@code{0+100,200+1,300+300} 1906@end example 1907 1908This represents that GRUB should read blocks 0 through 99, block 200, 1909and blocks 300 through 599. If you omit an offset, then GRUB assumes 1910the offset is zero. 1911 1912Like the file name syntax (@pxref{File name syntax}), if a blocklist 1913does not contain a device name, then GRUB uses GRUB's @dfn{root 1914device}. So @code{(hd0,1)+1} is the same as @code{+1} when the root 1915device is @samp{(hd0,1)}. 1916 1917 1918@node Interface 1919@chapter GRUB's user interface 1920 1921GRUB has both a simple menu interface for choosing preset entries from a 1922configuration file, and a highly flexible command-line for performing 1923any desired combination of boot commands. 1924 1925GRUB looks for its configuration file as soon as it is loaded. If one 1926is found, then the full menu interface is activated using whatever 1927entries were found in the file. If you choose the @dfn{command-line} menu 1928option, or if the configuration file was not found, then GRUB drops to 1929the command-line interface. 1930 1931@menu 1932* Command-line interface:: The flexible command-line interface 1933* Menu interface:: The simple menu interface 1934* Menu entry editor:: Editing a menu entry 1935* Hidden menu interface:: The hidden menu interface 1936@end menu 1937 1938 1939@node Command-line interface 1940@section The flexible command-line interface 1941 1942The command-line interface provides a prompt and after it an editable 1943text area much like a command-line in Unix or DOS. Each command is 1944immediately executed after it is entered@footnote{However, this 1945behavior will be changed in the future version, in a user-invisible 1946way.}. The commands (@pxref{Command-line and menu entry commands}) are a 1947subset of those available in the configuration file, used with exactly 1948the same syntax. 1949 1950Cursor movement and editing of the text on the line can be done via a 1951subset of the functions available in the Bash shell: 1952 1953@table @key 1954@item C-f 1955@itemx PC right key 1956Move forward one character. 1957 1958@item C-b 1959@itemx PC left key 1960Move back one character. 1961 1962@item C-a 1963@itemx HOME 1964Move to the start of the line. 1965 1966@item C-e 1967@itemx END 1968Move the the end of the line. 1969 1970@item C-d 1971@itemx DEL 1972Delete the character underneath the cursor. 1973 1974@item C-h 1975@itemx BS 1976Delete the character to the left of the cursor. 1977 1978@item C-k 1979Kill the text from the current cursor position to the end of the line. 1980 1981@item C-u 1982Kill backward from the cursor to the beginning of the line. 1983 1984@item C-y 1985Yank the killed text back into the buffer at the cursor. 1986 1987@item C-p 1988@itemx PC up key 1989Move up through the history list. 1990 1991@item C-n 1992@itemx PC down key 1993Move down through the history list. 1994@end table 1995 1996When typing commands interactively, if the cursor is within or before 1997the first word in the command-line, pressing the @key{TAB} key (or 1998@key{C-i}) will display a listing of the available commands, and if the 1999cursor is after the first word, the @kbd{@key{TAB}} will provide a 2000completion listing of disks, partitions, and file names depending on the 2001context. Note that to obtain a list of drives, one must open a 2002parenthesis, as @command{root (}. 2003 2004Note that you cannot use the completion functionality in the TFTP 2005filesystem. This is because TFTP doesn't support file name listing for 2006the security. 2007 2008 2009@node Menu interface 2010@section The simple menu interface 2011 2012The menu interface is quite easy to use. Its commands are both 2013reasonably intuitive and described on screen. 2014 2015Basically, the menu interface provides a list of @dfn{boot entries} to 2016the user to choose from. Use the arrow keys to select the entry of 2017choice, then press @key{RET} to run it. An optional timeout is 2018available to boot the default entry (the first one if not set), which is 2019aborted by pressing any key. 2020 2021Commands are available to enter a bare command-line by pressing @key{c} 2022(which operates exactly like the non-config-file version of GRUB, but 2023allows one to return to the menu if desired by pressing @key{ESC}) or to 2024edit any of the @dfn{boot entries} by pressing @key{e}. 2025 2026If you protect the menu interface with a password (@pxref{Security}), 2027all you can do is choose an entry by pressing @key{RET}, or press 2028@key{p} to enter the password. 2029 2030 2031@node Menu entry editor 2032@section Editing a menu entry 2033 2034The menu entry editor looks much like the main menu interface, but the 2035lines in the menu are individual commands in the selected entry instead 2036of entry names. 2037 2038If an @key{ESC} is pressed in the editor, it aborts all the changes made 2039to the configuration entry and returns to the main menu interface. 2040 2041When a particular line is selected, the editor places the user in a 2042special version of the GRUB command-line to edit that line. When the 2043user hits @key{RET}, GRUB replaces the line in question in the boot 2044entry with the changes (unless it was aborted via @key{ESC}, 2045in which case the changes are thrown away). 2046 2047If you want to add a new line to the menu entry, press @key{o} if adding 2048a line after the current line or press @key{O} if before the current 2049line. 2050 2051To delete a line, hit the key @key{d}. Although GRUB unfortunately 2052does not support @dfn{undo}, you can do almost the same thing by just 2053returning to the main menu. 2054 2055 2056@node Hidden menu interface 2057@section The hidden menu interface 2058 2059When your terminal is dumb or you request GRUB to hide the menu 2060interface explicitly with the command @command{hiddenmenu} 2061(@pxref{hiddenmenu}), GRUB doesn't show the menu interface (@pxref{Menu 2062interface}) and automatically boots the default entry, unless 2063interrupted by pressing @key{ESC}. 2064 2065When you interrupt the timeout and your terminal is dumb, GRUB falls 2066back to the command-line interface (@pxref{Command-line interface}). 2067 2068 2069@node Commands 2070@chapter The list of available commands 2071 2072In this chapter, we list all commands that are available in GRUB. 2073 2074Commands belong to different groups. A few can only be used in 2075the global section of the configuration file (or ``menu''); most 2076of them can be entered on the command-line and can be used either 2077anywhere in the menu or specifically in the menu entries. 2078 2079@menu 2080* Menu-specific commands:: 2081* General commands:: 2082* Command-line and menu entry commands:: 2083@end menu 2084 2085 2086@node Menu-specific commands 2087@section The list of commands for the menu only 2088 2089The semantics used in parsing the configuration file are the following: 2090 2091@itemize @bullet 2092@item 2093The menu-specific commands have to be used before any others. 2094 2095@item 2096The files @emph{must} be in plain-text format. 2097 2098@item 2099@samp{#} at the beginning of a line in a configuration file means it is 2100only a comment. 2101 2102@item 2103Options are separated by spaces. 2104 2105@item 2106All numbers can be either decimal or hexadecimal. A hexadecimal number 2107must be preceded by @samp{0x}, and is case-insensitive. 2108 2109@item 2110Extra options or text at the end of the line are ignored unless otherwise 2111specified. 2112 2113@item 2114Unrecognized commands are added to the current entry, except before entries 2115start, where they are ignored. 2116@end itemize 2117 2118These commands can only be used in the menu: 2119 2120@menu 2121* default:: Set the default entry 2122* fallback:: Set the fallback entry 2123* hiddenmenu:: Hide the menu interface 2124* timeout:: Set the timeout 2125* title:: Start a menu entry 2126@end menu 2127 2128 2129@node default 2130@subsection default 2131 2132@deffn Command default num 2133Set the default entry to the entry number @var{num}. Numbering starts 2134from 0, and the entry number 0 is the default if the command is not 2135used. 2136 2137You can specify @samp{saved} instead of a number. In this case, the 2138default entry is the entry saved with the command 2139@command{savedefault}. @xref{savedefault}, for more information. 2140@end deffn 2141 2142 2143@node fallback 2144@subsection fallback 2145 2146@deffn Command fallback num... 2147Go into unattended boot mode: if the default boot entry has any errors, 2148instead of waiting for the user to do something, immediately start 2149over using the @var{num} entry (same numbering as the @code{default} 2150command (@pxref{default})). This obviously won't help if the machine was 2151rebooted by a kernel that GRUB loaded. You can specify multiple 2152fallback entry numbers. 2153@end deffn 2154 2155 2156@node hiddenmenu 2157@subsection hiddenmenu 2158 2159@deffn Command hiddenmenu 2160Don't display the menu. If the command is used, no menu will be 2161displayed on the control terminal, and the default entry will be 2162booted after the timeout expired. The user can still request the 2163menu to be displayed by pressing @key{ESC} before the timeout 2164expires. See also @ref{Hidden menu interface}. 2165@end deffn 2166 2167 2168@node timeout 2169@subsection timeout 2170 2171@deffn Command timeout sec 2172Set a timeout, in @var{sec} seconds, before automatically booting the 2173default entry (normally the first entry defined). 2174@end deffn 2175 2176 2177@node title 2178@subsection title 2179 2180@deffn Command title name @dots{} 2181Start a new boot entry, and set its name to the contents of the rest of 2182the line, starting with the first non-space character. 2183@end deffn 2184 2185 2186@node General commands 2187@section The list of general commands 2188 2189Commands usable anywhere in the menu and in the command-line. 2190 2191@menu 2192* bootp:: Initialize a network device via BOOTP 2193* color:: Color the menu interface 2194* device:: Specify a file as a drive 2195* dhcp:: Initialize a network device via DHCP 2196* hide:: Hide a partition 2197* ifconfig:: Configure a network device manually 2198* pager:: Change the state of the internal pager 2199* partnew:: Make a primary partition 2200* parttype:: Change the type of a partition 2201* password:: Set a password for the menu interface 2202* rarp:: Initialize a network device via RARP 2203* serial:: Set up a serial device 2204* setkey:: Configure the key map 2205* terminal:: Choose a terminal 2206* terminfo:: Define escape sequences for a terminal 2207* tftpserver:: Specify a TFTP server 2208* unhide:: Unhide a partition 2209@end menu 2210 2211 2212@node bootp 2213@subsection bootp 2214 2215@deffn Command bootp [@option{--with-configfile}] 2216Initialize a network device via the @dfn{BOOTP} protocol. This command 2217is only available if GRUB is compiled with netboot support. See also 2218@ref{Network}. 2219 2220If you specify @option{--with-configfile} to this command, GRUB will 2221fetch and load a configuration file specified by your BOOTP server 2222with the vendor tag @samp{150}. 2223@end deffn 2224 2225 2226@node color 2227@subsection color 2228 2229@deffn Command color normal [highlight] 2230Change the menu colors. The color @var{normal} is used for most 2231lines in the menu (@pxref{Menu interface}), and the color 2232@var{highlight} is used to highlight the line where the cursor 2233points. If you omit @var{highlight}, then the inverted color of 2234@var{normal} is used for the highlighted line. The format of a color is 2235@code{@var{foreground}/@var{background}}. @var{foreground} and 2236@var{background} are symbolic color names. A symbolic color name must be 2237one of these: 2238 2239@itemize @bullet 2240@item 2241black 2242 2243@item 2244blue 2245 2246@item 2247green 2248 2249@item 2250cyan 2251 2252@item 2253red 2254 2255@item 2256magenta 2257 2258@item 2259brown 2260 2261@item 2262light-gray 2263 2264@strong{These below can be specified only for the foreground.} 2265 2266@item 2267dark-gray 2268 2269@item 2270light-blue 2271 2272@item 2273light-green 2274 2275@item 2276light-cyan 2277 2278@item 2279light-red 2280 2281@item 2282light-magenta 2283 2284@item 2285yellow 2286 2287@item 2288white 2289@end itemize 2290 2291But only the first eight names can be used for @var{background}. You can 2292prefix @code{blink-} to @var{foreground} if you want a blinking 2293foreground color. 2294 2295This command can be used in the configuration file and on the command 2296line, so you may write something like this in your configuration file: 2297 2298@example 2299@group 2300# Set default colors. 2301color light-gray/blue black/light-gray 2302 2303# Change the colors. 2304title OS-BS like 2305color magenta/blue black/magenta 2306@end group 2307@end example 2308@end deffn 2309 2310 2311@node device 2312@subsection device 2313 2314@deffn Command device drive file 2315In the grub shell, specify the file @var{file} as the actual drive for a 2316@sc{bios} drive @var{drive}. You can use this command to create a disk 2317image, and/or to fix the drives guessed by GRUB when GRUB fails to 2318determine them correctly, like this: 2319 2320@example 2321@group 2322grub> @kbd{device (fd0) /floppy-image} 2323grub> @kbd{device (hd0) /dev/sd0} 2324@end group 2325@end example 2326 2327This command can be used only in the grub shell (@pxref{Invoking the 2328grub shell}). 2329@end deffn 2330 2331 2332@node dhcp 2333@subsection dhcp 2334 2335@deffn Command dhcp [--with-configfile] 2336Initialize a network device via the @dfn{DHCP} protocol. Currently, 2337this command is just an alias for @command{bootp}, since the two 2338protocols are very similar. This command is only available if GRUB is 2339compiled with netboot support. See also @ref{Network}. 2340 2341If you specify @option{--with-configfile} to this command, GRUB will 2342fetch and load a configuration file specified by your DHCP server 2343with the vendor tag @samp{150}. 2344@end deffn 2345 2346 2347@node hide 2348@subsection hide 2349 2350@deffn Command hide partition 2351Hide the partition @var{partition} by setting the @dfn{hidden} bit in 2352its partition type code. This is useful only when booting DOS or Windows 2353and multiple primary FAT partitions exist in one disk. See also 2354@ref{DOS/Windows}. 2355@end deffn 2356 2357 2358@node ifconfig 2359@subsection ifconfig 2360 2361@deffn Command ifconfig [@option{--server=server}] [@option{--gateway=gateway}] [@option{--mask=mask}] [@option{--address=address}] 2362Configure the IP address, the netmask, the gateway, and the server 2363address of a network device manually. The values must be in dotted 2364decimal format, like @samp{192.168.11.178}. The order of the options is 2365not important. This command shows current network configuration, if no 2366option is specified. See also @ref{Network}. 2367@end deffn 2368 2369 2370@node pager 2371@subsection pager 2372 2373@deffn Command pager [flag] 2374Toggle or set the state of the internal pager. If @var{flag} is 2375@samp{on}, the internal pager is enabled. If @var{flag} is @samp{off}, 2376it is disabled. If no argument is given, the state is toggled. 2377@end deffn 2378 2379 2380@node partnew 2381@subsection partnew 2382 2383@deffn Command partnew part type from len 2384Create a new primary partition. @var{part} is a partition specification 2385in GRUB syntax (@pxref{Naming convention}); @var{type} is the partition 2386type and must be a number in the range @code{0-0xff}; @var{from} is 2387the starting address and @var{len} is the length, both in sector units. 2388@end deffn 2389 2390 2391@node parttype 2392@subsection parttype 2393 2394@deffn Command parttype part type 2395Change the type of an existing partition. @var{part} is a partition 2396specification in GRUB syntax (@pxref{Naming convention}); @var{type} 2397is the new partition type and must be a number in the range 0-0xff. 2398@end deffn 2399 2400 2401@node password 2402@subsection password 2403 2404@deffn Command password [@option{--md5}] passwd [new-config-file] 2405If used in the first section of a menu file, disable all interactive 2406editing control (menu entry editor and command-line) and entries 2407protected by the command @command{lock}. If the password @var{passwd} is 2408entered, it loads the @var{new-config-file} as a new config file and 2409restarts the GRUB Stage 2, if @var{new-config-file} is 2410specified. Otherwise, GRUB will just unlock the privileged instructions. 2411You can also use this command in the script section, in which case it 2412will ask for the password, before continuing. The option 2413@option{--md5} tells GRUB that @var{passwd} is encrypted with 2414@command{md5crypt} (@pxref{md5crypt}). 2415@end deffn 2416 2417 2418@node rarp 2419@subsection rarp 2420 2421@deffn Command rarp 2422Initialize a network device via the @dfn{RARP} protocol. This command 2423is only available if GRUB is compiled with netboot support. See also 2424@ref{Network}. 2425@end deffn 2426 2427 2428@node serial 2429@subsection serial 2430 2431@deffn Command serial [@option{--unit=unit}] [@option{--port=port}] [@option{--speed=speed}] [@option{--word=word}] [@option{--parity=parity}] [@option{--stop=stop}] [@option{--device=dev}] 2432Initialize a serial device. @var{unit} is a number in the range 0-3 2433specifying which serial port to use; default is 0, which corresponds to 2434the port often called COM1. @var{port} is the I/O port where the UART 2435is to be found; if specified it takes precedence over @var{unit}. 2436@var{speed} is the transmission speed; default is 9600. @var{word} and 2437@var{stop} are the number of data bits and stop bits. Data bits must 2438be in the range 5-8 and stop bits must be 1 or 2. Default is 8 data 2439bits and one stop bit. @var{parity} is one of @samp{no}, @samp{odd}, 2440@samp{even} and defaults to @samp{no}. The option @option{--device} 2441can only be used in the grub shell and is used to specify the 2442tty device to be used in the host operating system (@pxref{Invoking the 2443grub shell}). 2444 2445The serial port is not used as a communication channel unless the 2446@command{terminal} command is used (@pxref{terminal}). 2447 2448This command is only available if GRUB is compiled with serial 2449support. See also @ref{Serial terminal}. 2450@end deffn 2451 2452 2453@node setkey 2454@subsection setkey 2455 2456@deffn Command setkey [to_key from_key] 2457Change the keyboard map. The key @var{from_key} is mapped to the key 2458@var{to_key}. If no argument is specified, reset key mappings. Note that 2459this command @emph{does not} exchange the keys. If you want to exchange 2460the keys, run this command again with the arguments exchanged, like this: 2461 2462@example 2463grub> @kbd{setkey capslock control} 2464grub> @kbd{setkey control capslock} 2465@end example 2466 2467A key must be an alphabet letter, a digit, or one of these symbols: 2468@samp{escape}, @samp{exclam}, @samp{at}, @samp{numbersign}, 2469@samp{dollar}, @samp{percent}, @samp{caret}, @samp{ampersand}, 2470@samp{asterisk}, @samp{parenleft}, @samp{parenright}, @samp{minus}, 2471@samp{underscore}, @samp{equal}, @samp{plus}, @samp{backspace}, 2472@samp{tab}, @samp{bracketleft}, @samp{braceleft}, @samp{bracketright}, 2473@samp{braceright}, @samp{enter}, @samp{control}, @samp{semicolon}, 2474@samp{colon}, @samp{quote}, @samp{doublequote}, @samp{backquote}, 2475@samp{tilde}, @samp{shift}, @samp{backslash}, @samp{bar}, @samp{comma}, 2476@samp{less}, @samp{period}, @samp{greater}, @samp{slash}, 2477@samp{question}, @samp{alt}, @samp{space}, @samp{capslock}, @samp{FX} 2478(@samp{X} is a digit), and @samp{delete}. This table describes to which 2479character each of the symbols corresponds: 2480 2481@table @samp 2482@item exclam 2483@samp{!} 2484 2485@item at 2486@samp{@@} 2487 2488@item numbersign 2489@samp{#} 2490 2491@item dollar 2492@samp{$} 2493 2494@item percent 2495@samp{%} 2496 2497@item caret 2498@samp{^} 2499 2500@item ampersand 2501@samp{&} 2502 2503@item asterisk 2504@samp{*} 2505 2506@item parenleft 2507@samp{(} 2508 2509@item parenright 2510@samp{)} 2511 2512@item minus 2513@samp{-} 2514 2515@item underscore 2516@samp{_} 2517 2518@item equal 2519@samp{=} 2520 2521@item plus 2522@samp{+} 2523 2524@item bracketleft 2525@samp{[} 2526 2527@item braceleft 2528@samp{@{} 2529 2530@item bracketright 2531@samp{]} 2532 2533@item braceright 2534@samp{@}} 2535 2536@item semicolon 2537@samp{;} 2538 2539@item colon 2540@samp{:} 2541 2542@item quote 2543@samp{'} 2544 2545@item doublequote 2546@samp{"} 2547 2548@item backquote 2549@samp{`} 2550 2551@item tilde 2552@samp{~} 2553 2554@item backslash 2555@samp{\} 2556 2557@item bar 2558@samp{|} 2559 2560@item comma 2561@samp{,} 2562 2563@item less 2564@samp{<} 2565 2566@item period 2567@samp{.} 2568 2569@item greater 2570@samp{>} 2571 2572@item slash 2573@samp{/} 2574 2575@item question 2576@samp{?} 2577 2578@item space 2579@samp{ } 2580@end table 2581@end deffn 2582 2583 2584@node terminal 2585@subsection terminal 2586 2587@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}] 2588Select a terminal for user interaction. The terminal is assumed to be 2589VT100-compatible unless @option{--dumb} is specified. If both 2590@option{console} and @option{serial} are specified, then GRUB will use 2591the one where a key is entered first or the first when the timeout 2592expires. If neither are specified, the current setting is 2593reported. This command is only available if GRUB is compiled with serial 2594support. See also @ref{Serial terminal}. 2595 2596This may not make sense for most users, but GRUB supports Hercules 2597console as well. Hercules console is usable like the ordinary console, 2598and the usage is quite similar to that for serial terminals: specify 2599@option{hercules} as the argument. 2600 2601The option @option{--lines} defines the number of lines in your 2602terminal, and it is used for the internal pager function. If you don't 2603specify this option, the number is assumed as 24. 2604 2605The option @option{--silent} suppresses the message to prompt you to 2606hit any key. This might be useful if your system has no terminal 2607device. 2608 2609The option @option{--no-echo} has GRUB not to echo back input 2610characters. This implies the option @option{--no-edit}. 2611 2612The option @option{--no-edit} disables the BASH-like editing feature. 2613@end deffn 2614 2615 2616@node terminfo 2617@subsection terminfo 2618 2619@deffn Command terminfo @option{--name=name} @option{--cursor-address=seq} [@option{--clear-screen=seq}] [@option{--enter-standout-mode=seq}] [@option{--exit-standout-mode=seq}] 2620Define the capabilities of your terminal. Use this command to define 2621escape sequences, if it is not vt100-compatible. You may use @samp{\e} 2622for @key{ESC} and @samp{^X} for a control character. 2623 2624You can use the utility @command{grub-terminfo} to generate 2625appropriate arguments to this command. @xref{Invoking grub-terminfo}. 2626 2627If no option is specified, the current settings are printed. 2628@end deffn 2629 2630 2631@node tftpserver 2632@subsection tftpserver 2633 2634@deffn Command tftpserver ipaddr 2635@strong{Caution:} This command exists only for backward 2636compatibility. Use @command{ifconfig} (@pxref{ifconfig}) instead. 2637 2638Override a TFTP server address returned by a BOOTP/DHCP/RARP server. The 2639argument @var{ipaddr} must be in dotted decimal format, like 2640@samp{192.168.0.15}. This command is only available if GRUB is compiled 2641with netboot support. See also @ref{Network}. 2642@end deffn 2643 2644 2645@node unhide 2646@subsection unhide 2647 2648@deffn Command unhide partition 2649Unhide the partition @var{partition} by clearing the @dfn{hidden} bit in 2650its partition type code. This is useful only when booting DOS or Windows 2651and multiple primary partitions exist on one disk. See also 2652@ref{DOS/Windows}. 2653@end deffn 2654 2655 2656@node Command-line and menu entry commands 2657@section The list of command-line and menu entry commands 2658 2659These commands are usable in the command-line and in menu entries. If 2660you forget a command, you can run the command @command{help} 2661(@pxref{help}). 2662 2663@menu 2664* blocklist:: Get the block list notation of a file 2665* boot:: Start up your operating system 2666* cat:: Show the contents of a file 2667* chainloader:: Chain-load another boot loader 2668* cmp:: Compare two files 2669* configfile:: Load a configuration file 2670* debug:: Toggle the debug flag 2671* displayapm:: Display APM information 2672* displaymem:: Display memory configuration 2673* embed:: Embed Stage 1.5 2674* find:: Find a file 2675* fstest:: Test a filesystem 2676* geometry:: Manipulate the geometry of a drive 2677* halt:: Shut down your computer 2678* help:: Show help messages 2679* impsprobe:: Probe SMP 2680* initrd:: Load an initrd 2681* install:: Install GRUB 2682* ioprobe:: Probe I/O ports used for a drive 2683* kernel:: Load a kernel 2684* lock:: Lock a menu entry 2685* makeactive:: Make a partition active 2686* map:: Map a drive to another 2687* md5crypt:: Encrypt a password in MD5 format 2688* module:: Load a module 2689* modulenounzip:: Load a module without decompression 2690* pause:: Wait for a key press 2691* quit:: Exit from the grub shell 2692* reboot:: Reboot your computer 2693* read:: Read data from memory 2694* root:: Set GRUB's root device 2695* rootnoverify:: Set GRUB's root device without mounting 2696* savedefault:: Save current entry as the default entry 2697* setup:: Set up GRUB's installation automatically 2698* testload:: Load a file for testing a filesystem 2699* testvbe:: Test VESA BIOS EXTENSION 2700* uppermem:: Set the upper memory size 2701* vbeprobe:: Probe VESA BIOS EXTENSION 2702@end menu 2703 2704 2705@node blocklist 2706@subsection blocklist 2707 2708@deffn Command blocklist file 2709Print the block list notation of the file @var{file}. @xref{Block list 2710syntax}. 2711@end deffn 2712 2713 2714@node boot 2715@subsection boot 2716 2717@deffn Command boot 2718Boot the OS or chain-loader which has been loaded. Only necessary if 2719running the fully interactive command-line (it is implicit at the end of 2720a menu entry). 2721@end deffn 2722 2723 2724@node cat 2725@subsection cat 2726 2727@deffn Command cat file 2728Display the contents of the file @var{file}. This command may be useful 2729to remind you of your OS's root partition: 2730 2731@example 2732grub> @kbd{cat /etc/fstab} 2733@end example 2734@end deffn 2735 2736 2737@node chainloader 2738@subsection chainloader 2739 2740@deffn Command chainloader [@option{--force}] file 2741Load @var{file} as a chain-loader. Like any other file loaded by the 2742filesystem code, it can use the blocklist notation to grab the first 2743sector of the current partition with @samp{+1}. If you specify the 2744option @option{--force}, then load @var{file} forcibly, whether it has a 2745correct signature or not. This is required when you want to load a 2746defective boot loader, such as SCO UnixWare 7.1 (@pxref{SCO UnixWare}). 2747@end deffn 2748 2749 2750@node cmp 2751@subsection cmp 2752 2753@deffn Command cmp file1 file2 2754Compare the file @var{file1} with the file @var{file2}. If they differ 2755in size, print the sizes like this: 2756 2757@example 2758Differ in size: 0x1234 [foo], 0x4321 [bar] 2759@end example 2760 2761If the sizes are equal but the bytes at an offset differ, then print the 2762bytes like this: 2763 2764@example 2765Differ at the offset 777: 0xbe [foo], 0xef [bar] 2766@end example 2767 2768If they are completely identical, nothing will be printed. 2769@end deffn 2770 2771 2772@node configfile 2773@subsection configfile 2774 2775@deffn Command configfile file 2776Load @var{file} as a configuration file. 2777@end deffn 2778 2779 2780@node debug 2781@subsection debug 2782 2783@deffn Command debug 2784Toggle debug mode (by default it is off). When debug mode is on, some 2785extra messages are printed to show disk activity. This global debug flag 2786is mainly useful for GRUB developers when testing new code. 2787@end deffn 2788 2789 2790@node displayapm 2791@subsection displayapm 2792 2793@deffn Command displayapm 2794Display APM BIOS information. 2795@end deffn 2796 2797 2798@node displaymem 2799@subsection displaymem 2800 2801@deffn Command displaymem 2802Display what GRUB thinks the system address space map of the machine is, 2803including all regions of physical @sc{ram} installed. GRUB's 2804@dfn{upper/lower memory} display uses the standard BIOS interface for 2805the available memory in the first megabyte, or @dfn{lower memory}, and a 2806synthesized number from various BIOS interfaces of the memory starting 2807at 1MB and going up to the first chipset hole for @dfn{upper memory} 2808(the standard PC @dfn{upper memory} interface is limited to reporting a 2809maximum of 64MB). 2810@end deffn 2811 2812 2813@node embed 2814@subsection embed 2815 2816@deffn Command embed stage1_5 device 2817Embed the Stage 1.5 @var{stage1_5} in the sectors after the MBR if 2818@var{device} is a drive, or in the @dfn{boot loader} area if @var{device} 2819is a FFS partition or a ReiserFS partition.@footnote{The latter feature 2820has not been implemented yet.} Print the number of sectors which 2821@var{stage1_5} occupies, if successful. 2822 2823Usually, you don't need to run this command directly. @xref{setup}. 2824@end deffn 2825 2826 2827@node find 2828@subsection find 2829 2830@deffn Command find filename 2831Search for the file name @var{filename} in all mountable partitions 2832and print the list of the devices which contain the file. The file 2833name @var{filename} should be an absolute file name like 2834@code{/boot/grub/stage1}. 2835@end deffn 2836 2837 2838@node fstest 2839@subsection fstest 2840 2841@deffn Command fstest 2842Toggle filesystem test mode. 2843Filesystem test mode, when turned on, prints out data corresponding to 2844all the device reads and what values are being sent to the low-level 2845routines. The format is @samp{<@var{partition-offset-sector}, 2846@var{byte-offset}, @var{byte-length}>} for high-level reads inside a 2847partition, and @samp{[@var{disk-offset-sector}]} for low-level sector 2848requests from the disk. 2849Filesystem test mode is turned off by any use of the @command{install} 2850(@pxref{install}) or @command{testload} (@pxref{testload}) commands. 2851@end deffn 2852 2853 2854@node geometry 2855@subsection geometry 2856 2857@deffn Command geometry drive [cylinder head sector [total_sector]] 2858Print the information for the drive @var{drive}. In the grub shell, you 2859can set the geometry of the drive arbitrarily. The number of 2860cylinders, the number of heads, the number of sectors and the number of 2861total sectors are set to CYLINDER, HEAD, SECTOR and TOTAL_SECTOR, 2862respectively. If you omit TOTAL_SECTOR, then it will be calculated 2863based on the C/H/S values automatically. 2864@end deffn 2865 2866 2867@node halt 2868@subsection halt 2869 2870@deffn Command halt @option{--no-apm} 2871The command halts the computer. If the @option{--no-apm} option 2872is specified, no APM BIOS call is performed. Otherwise, the computer 2873is shut down using APM. 2874@end deffn 2875 2876 2877@node help 2878@subsection help 2879 2880@deffn Command help @option{--all} [pattern @dots{}] 2881Display helpful information about builtin commands. If you do not 2882specify @var{pattern}, this command shows short descriptions of most of 2883available commands. If you specify the option @option{--all} to this 2884command, short descriptions of rarely used commands (such as 2885@ref{testload}) are displayed as well. 2886 2887If you specify any @var{patterns}, it displays longer information 2888about each of the commands which match those @var{patterns}. 2889@end deffn 2890 2891 2892@node impsprobe 2893@subsection impsprobe 2894 2895@deffn Command impsprobe 2896Probe the Intel Multiprocessor Specification 1.1 or 1.4 configuration 2897table and boot the various CPUs which are found into a tight loop. This 2898command can be used only in the Stage 2, but not in the grub shell. 2899@end deffn 2900 2901 2902@node initrd 2903@subsection initrd 2904 2905@deffn Command initrd file @dots{} 2906Load an initial ramdisk for a Linux format boot image and set the 2907appropriate parameters in the Linux setup area in memory. See also 2908@ref{GNU/Linux}. 2909@end deffn 2910 2911 2912@node install 2913@subsection install 2914 2915@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] 2916This command is fairly complex, and you should not use this command 2917unless you are familiar with GRUB. Use @command{setup} (@pxref{setup}) 2918instead. 2919 2920In short, it will perform a full install presuming the Stage 2 or Stage 29211.5@footnote{They're loaded the same way, so we will refer to the Stage 29221.5 as a Stage 2 from now on.} is in its final install location. 2923 2924In slightly more detail, it will load @var{stage1_file}, validate that 2925it is a GRUB Stage 1 of the right version number, install in it a 2926blocklist for loading @var{stage2_file} as a Stage 2. If the option 2927@option{d} is present, the Stage 1 will always look for the actual 2928disk @var{stage2_file} was installed on, rather than using the booting 2929drive. The Stage 2 will be loaded at address @var{addr}, which must be 2930@samp{0x8000} for a true Stage 2, and @samp{0x2000} for a Stage 1.5. If 2931@var{addr} is not present, GRUB will determine the address 2932automatically. It then writes the completed Stage 1 to the first block 2933of the device @var{dest_dev}. If the options @option{p} or 2934@var{config_file} are present, then it reads the first block of stage2, 2935modifies it with the values of the partition @var{stage2_file} was found 2936on (for @option{p}) or places the string @var{config_file} into the area 2937telling the stage2 where to look for a configuration file at boot 2938time. Likewise, if @var{real_config_file} is present and 2939@var{stage2_file} is a Stage 1.5, then the Stage 2 @var{config_file} is 2940patched with the configuration file name @var{real_config_file}. This 2941command preserves the DOS BPB (and for hard disks, the partition table) 2942of the sector the Stage 1 is to be installed into. 2943 2944@strong{Caution:} Several buggy BIOSes don't pass a booting drive 2945properly when booting from a hard disk drive. Therefore, you will 2946unfortunately have to specify the option @option{d}, whether your 2947Stage2 resides at the booting drive or not, if you have such a 2948BIOS. We know these are defective in this way: 2949 2950@table @asis 2951@item 2952Fujitsu LifeBook 400 BIOS version 31J0103A 2953 2954@item 2955HP Vectra XU 6/200 BIOS version GG.06.11 2956@end table 2957 2958@strong{Caution2:} A number of BIOSes don't return a correct LBA support 2959bitmap even if they do have the support. So GRUB provides a solution to 2960ignore the wrong bitmap, that is, the option @option{--force-lba}. Don't 2961use this option if you know that your BIOS doesn't have LBA support. 2962 2963@strong{Caution3:} You must specify the option @option{--stage2} in the 2964grub shell, if you cannot unmount the filesystem where your stage2 file 2965resides. The argument should be the file name in your operating system. 2966@end deffn 2967 2968 2969@node ioprobe 2970@subsection ioprobe 2971 2972@deffn Command ioprobe drive 2973Probe I/O ports used for the drive @var{drive}. This command will list 2974the I/O ports on the screen. For technical information, 2975@xref{Internals}. 2976@end deffn 2977 2978 2979@node kernel 2980@subsection kernel 2981 2982@deffn Command kernel [@option{--type=type}] [@option{--no-mem-option}] file @dots{} 2983Attempt to load the primary boot image (Multiboot a.out or @sc{elf}, 2984Linux zImage or bzImage, FreeBSD a.out, NetBSD a.out, etc.) from 2985@var{file}. The rest of the line is passed verbatim as the @dfn{kernel 2986command-line}. Any modules must be reloaded after using this command. 2987 2988This command also accepts the option @option{--type} so that you can 2989specify the kernel type of @var{file} explicitly. The argument 2990@var{type} must be one of these: @samp{netbsd}, @samp{freebsd}, 2991@samp{openbsd}, @samp{linux}, @samp{biglinux}, and 2992@samp{multiboot}. However, you need to specify it only if you want to 2993load a NetBSD @sc{elf} kernel, because GRUB can automatically determine 2994a kernel type in the other cases, quite safely. 2995 2996The option @option{--no-mem-option} is effective only for Linux. If the 2997option is specified, GRUB doesn't pass the option @option{mem=} to the 2998kernel. This option is implied for Linux kernels 2.4.18 and newer. 2999@end deffn 3000 3001 3002@node lock 3003@subsection lock 3004 3005@deffn Command lock 3006Prevent normal users from executing arbitrary menu entries. You must use 3007the command @command{password} if you really want this command to be 3008useful (@pxref{password}). 3009 3010This command is used in a menu, as shown in this example: 3011 3012@example 3013@group 3014title This entry is too dangerous to be executed by normal users 3015lock 3016root (hd0,a) 3017kernel /no-security-os 3018@end group 3019@end example 3020 3021See also @ref{Security}. 3022@end deffn 3023 3024 3025@node makeactive 3026@subsection makeactive 3027 3028@deffn Command makeactive 3029Set the active partition on the root disk to GRUB's root device. 3030This command is limited to @emph{primary} PC partitions on a hard disk. 3031@end deffn 3032 3033 3034@node map 3035@subsection map 3036 3037@deffn Command map to_drive from_drive 3038Map the drive @var{from_drive} to the drive @var{to_drive}. This is 3039necessary when you chain-load some operating systems, such as DOS, if 3040such an OS resides at a non-first drive. Here is an example: 3041 3042@example 3043@group 3044grub> @kbd{map (hd0) (hd1)} 3045grub> @kbd{map (hd1) (hd0)} 3046@end group 3047@end example 3048 3049The example exchanges the order between the first hard disk and the 3050second hard disk. See also @ref{DOS/Windows}. 3051@end deffn 3052 3053 3054@node md5crypt 3055@subsection md5crypt 3056 3057@deffn Command md5crypt 3058Prompt to enter a password, and encrypt it in MD5 format. The encrypted 3059password can be used with the command @command{password} 3060(@pxref{password}). See also @ref{Security}. 3061@end deffn 3062 3063 3064@node module 3065@subsection module 3066 3067@deffn Command module file @dots{} 3068Load a boot module @var{file} for a Multiboot format boot image (no 3069interpretation of the file contents are made, so the user of this 3070command must know what the kernel in question expects). The rest of the 3071line is passed as the @dfn{module command-line}, like the 3072@command{kernel} command. You must load a Multiboot kernel image before 3073loading any module. See also @ref{modulenounzip}. 3074@end deffn 3075 3076 3077@node modulenounzip 3078@subsection modulenounzip 3079 3080@deffn Command modulenounzip file @dots{} 3081The same as @command{module} (@pxref{module}), except that automatic 3082decompression is disabled. 3083@end deffn 3084 3085 3086@node pause 3087@subsection pause 3088 3089@deffn Command pause message @dots{} 3090Print the @var{message}, then wait until a key is pressed. Note that 3091placing @key{^G} (ASCII code 7) in the message will cause the speaker to 3092emit the standard beep sound, which is useful when prompting the user to 3093change floppies. 3094@end deffn 3095 3096 3097@node quit 3098@subsection quit 3099 3100@deffn Command quit 3101Exit from the grub shell @command{grub} (@pxref{Invoking the grub 3102shell}). This command can be used only in the grub shell. 3103@end deffn 3104 3105 3106@node reboot 3107@subsection reboot 3108 3109@deffn Command reboot 3110Reboot the computer. 3111@end deffn 3112 3113 3114@node read 3115@subsection read 3116 3117@deffn Command read addr 3118Read a 32-bit value from memory at address @var{addr} and display it in 3119hex format. 3120@end deffn 3121 3122 3123@node root 3124@subsection root 3125 3126@deffn Command root device [hdbias] 3127Set the current @dfn{root device} to the device @var{device}, then 3128attempt to mount it to get the partition size (for passing the partition 3129descriptor in @code{ES:ESI}, used by some chain-loaded boot loaders), the 3130BSD drive-type (for booting BSD kernels using their native boot format), 3131and correctly determine the PC partition where a BSD sub-partition is 3132located. The optional @var{hdbias} parameter is a number to tell a BSD 3133kernel how many BIOS drive numbers are on controllers before the current 3134one. For example, if there is an IDE disk and a SCSI disk, and your 3135FreeBSD root partition is on the SCSI disk, then use a @samp{1} for 3136@var{hdbias}. 3137 3138See also @ref{rootnoverify}. 3139@end deffn 3140 3141 3142@node rootnoverify 3143@subsection rootnoverify 3144 3145@deffn Command rootnoverify device [hdbias] 3146Similar to @command{root} (@pxref{root}), but don't attempt to mount the 3147partition. This is useful for when an OS is outside of the area of the 3148disk that GRUB can read, but setting the correct root device is still 3149desired. Note that the items mentioned in @command{root} above which 3150derived from attempting the mount will @emph{not} work correctly. 3151@end deffn 3152 3153 3154@node savedefault 3155@subsection savedefault 3156 3157@deffn Command savedefault num 3158Save the current menu entry or @var{num} if specified as a default 3159entry. Here is an example: 3160 3161@example 3162@group 3163default saved 3164timeout 10 3165 3166title GNU/Linux 3167root (hd0,0) 3168kernel /boot/vmlinuz root=/dev/sda1 vga=ext 3169initrd /boot/initrd 3170savedefault 3171 3172title FreeBSD 3173root (hd0,a) 3174kernel /boot/loader 3175savedefault 3176@end group 3177@end example 3178 3179With this configuration, GRUB will choose the entry booted previously as 3180the default entry. 3181 3182You can specify @samp{fallback} instead of a number. Then, next 3183fallback entry is saved. Next fallback entry is chosen from fallback 3184entries. Normally, this will be the first entry in fallback ones. 3185 3186See also @ref{default} and @ref{Invoking grub-set-default}. 3187@end deffn 3188 3189 3190@node setup 3191@subsection setup 3192 3193@deffn Command setup [@option{--force-lba}] [@option{--stage2=os_stage2_file}] [@option{--prefix=dir}] install_device [image_device] 3194Set up the installation of GRUB automatically. This command uses the 3195more flexible command @command{install} (@pxref{install}) in the backend 3196and installs GRUB into the device @var{install_device}. If 3197@var{image_device} is specified, then find the GRUB images 3198(@pxref{Images}) in the device @var{image_device}, otherwise use the 3199current @dfn{root device}, which can be set by the command 3200@command{root}. If @var{install_device} is a hard disk, then embed a 3201Stage 1.5 in the disk if possible. 3202 3203The option @option{--prefix} specifies the directory under which GRUB 3204images are put. If it is not specified, GRUB automatically searches them 3205in @file{/boot/grub} and @file{/grub}. 3206 3207The options @option{--force-lba} and @option{--stage2} are just passed 3208to @command{install} if specified. @xref{install}, for more 3209information. 3210@end deffn 3211 3212 3213@node testload 3214@subsection testload 3215 3216@deffn Command testload file 3217Read the entire contents of @var{file} in several different ways and 3218compare them, to test the filesystem code. The output is somewhat 3219cryptic, but if no errors are reported and the final @samp{i=@var{X}, 3220filepos=@var{Y}} reading has @var{X} and @var{Y} equal, then it is 3221definitely consistent, and very likely works correctly subject to a 3222consistent offset error. If this test succeeds, then a good next step is 3223to try loading a kernel. 3224@end deffn 3225 3226 3227@node testvbe 3228@subsection testvbe 3229 3230@deffn Command testvbe mode 3231Test the VESA BIOS EXTENSION mode @var{mode}. This command will switch 3232your video card to the graphics mode, and show an endless animation. Hit 3233any key to return. See also @ref{vbeprobe}. 3234@end deffn 3235 3236 3237@node uppermem 3238@subsection uppermem 3239 3240@deffn Command uppermem kbytes 3241Force GRUB to assume that only @var{kbytes} kilobytes of upper memory 3242are installed. Any system address range maps are discarded. 3243 3244@strong{Caution:} This should be used with great caution, and should 3245only be necessary on some old machines. GRUB's BIOS probe can pick up 3246all @sc{ram} on all new machines the author has ever heard of. It can 3247also be used for debugging purposes to lie to an OS. 3248@end deffn 3249 3250 3251@node vbeprobe 3252@subsection vbeprobe 3253 3254@deffn Command vbeprobe [mode] 3255Probe VESA BIOS EXTENSION information. If the mode @var{mode} is 3256specified, show only the information about @var{mode}. Otherwise, this 3257command lists up available VBE modes on the screen. See also 3258@ref{testvbe}. 3259@end deffn 3260 3261 3262@node Troubleshooting 3263@chapter Error messages reported by GRUB 3264 3265This chapter describes error messages reported by GRUB when you 3266encounter trouble. @xref{Invoking the grub shell}, if your problem is 3267specific to the grub shell. 3268 3269@menu 3270* Stage1 errors:: Errors reported by the Stage 1 3271* Stage1.5 errors:: Errors reported by the Stage 1.5 3272* Stage2 errors:: Errors reported by the Stage 2 3273@end menu 3274 3275 3276@node Stage1 errors 3277@section Errors reported by the Stage 1 3278 3279The general way that the Stage 1 handles errors is to print an error 3280string and then halt. Pressing @kbd{@key{CTRL}-@key{ALT}-@key{DEL}} will 3281reboot. 3282 3283The following is a comprehensive list of error messages for the Stage 1: 3284 3285@table @asis 3286@item Hard Disk Error 3287The stage2 or stage1.5 is being read from a hard disk, and the attempt 3288to determine the size and geometry of the hard disk failed. 3289 3290@item Floppy Error 3291The stage2 or stage1.5 is being read from a floppy disk, and the attempt 3292to determine the size and geometry of the floppy disk failed. It's listed 3293as a separate error since the probe sequence is different than for hard 3294disks. 3295 3296@item Read Error 3297A disk read error happened while trying to read the stage2 or stage1.5. 3298 3299@item Geom Error 3300The location of the stage2 or stage1.5 is not in the portion of the disk 3301supported directly by the BIOS read calls. This could occur because the 3302BIOS translated geometry has been changed by the user or the disk is 3303moved to another machine or controller after installation, or GRUB was 3304not installed using itself (if it was, the Stage 2 version of this error 3305would have been seen during that process and it would not have completed 3306the install). 3307@end table 3308 3309 3310@node Stage1.5 errors 3311@section Errors reported by the Stage 1.5 3312 3313The general way that the Stage 1.5 handles errors is to print an error 3314number in the form @code{Error @var{num}} and then halt. Pressing 3315@kbd{@key{CTRL}-@key{ALT}-@key{DEL}} will reboot. 3316 3317The error numbers correspond to the errors reported by Stage 33182. @xref{Stage2 errors}. 3319 3320 3321@node Stage2 errors 3322@section Errors reported by the Stage 2 3323 3324The general way that the Stage 2 handles errors is to abort the 3325operation in question, print an error string, then (if possible) either 3326continue based on the fact that an error occurred or wait for the user to 3327deal with the error. 3328 3329The following is a comprehensive list of error messages for the Stage 2 3330(error numbers for the Stage 1.5 are listed before the colon in each 3331description): 3332 3333@table @asis 3334@item 1 : Filename must be either an absolute filename or blocklist 3335This error is returned if a file name is requested which doesn't fit the 3336syntax/rules listed in the @ref{Filesystem}. 3337 3338@item 2 : Bad file or directory type 3339This error is returned if a file requested is not a regular file, but 3340something like a symbolic link, directory, or FIFO. 3341 3342@item 3 : Bad or corrupt data while decompressing file 3343This error is returned if the run-length decompression code gets an 3344internal error. This is usually from a corrupt file. 3345 3346@item 4 : Bad or incompatible header in compressed file 3347This error is returned if the file header for a supposedly compressed 3348file is bad. 3349 3350@item 5 : Partition table invalid or corrupt 3351This error is returned if the sanity checks on the integrity of the 3352partition table fail. This is a bad sign. 3353 3354@item 6 : Mismatched or corrupt version of stage1/stage2 3355This error is returned if the install command points to incompatible 3356or corrupt versions of the stage1 or stage2. It can't detect corruption 3357in general, but this is a sanity check on the version numbers, which 3358should be correct. 3359 3360@item 7 : Loading below 1MB is not supported 3361This error is returned if the lowest address in a kernel is below the 33621MB boundary. The Linux zImage format is a special case and can be 3363handled since it has a fixed loading address and maximum size. 3364 3365@item 8 : Kernel must be loaded before booting 3366This error is returned if GRUB is told to execute the boot sequence 3367without having a kernel to start. 3368 3369@item 9 : Unknown boot failure 3370This error is returned if the boot attempt did not succeed for reasons 3371which are unknown. 3372 3373@item 10 : Unsupported Multiboot features requested 3374This error is returned when the Multiboot features word in the Multiboot 3375header requires a feature that is not recognized. The point of this is 3376that the kernel requires special handling which GRUB is probably 3377unable to provide. 3378 3379@item 11 : Unrecognized device string 3380This error is returned if a device string was expected, and the string 3381encountered didn't fit the syntax/rules listed in the @ref{Filesystem}. 3382 3383@item 12 : Invalid device requested 3384This error is returned if a device string is recognizable but does not 3385fall under the other device errors. 3386 3387@item 13 : Invalid or unsupported executable format 3388This error is returned if the kernel image being loaded is not 3389recognized as Multiboot or one of the supported native formats (Linux 3390zImage or bzImage, FreeBSD, or NetBSD). 3391 3392@item 14 : Filesystem compatibility error, cannot read whole file 3393Some of the filesystem reading code in GRUB has limits on the length of 3394the files it can read. This error is returned when the user runs into 3395such a limit. 3396 3397@item 15 : File not found 3398This error is returned if the specified file name cannot be found, but 3399everything else (like the disk/partition info) is OK. 3400 3401@item 16 : Inconsistent filesystem structure 3402This error is returned by the filesystem code to denote an internal 3403error caused by the sanity checks of the filesystem structure on disk 3404not matching what it expects. This is usually caused by a corrupt 3405filesystem or bugs in the code handling it in GRUB. 3406 3407@item 17 : Cannot mount selected partition 3408This error is returned if the partition requested exists, but the 3409filesystem type cannot be recognized by GRUB. 3410 3411@item 18 : Selected cylinder exceeds maximum supported by BIOS 3412This error is returned when a read is attempted at a linear block 3413address beyond the end of the BIOS translated area. This generally 3414happens if your disk is larger than the BIOS can handle (512MB for 3415(E)IDE disks on older machines or larger than 8GB in general). 3416 3417@item 19 : Linux kernel must be loaded before initrd 3418This error is returned if the initrd command is used before loading a 3419Linux kernel. 3420 3421@item 20 : Multiboot kernel must be loaded before modules 3422This error is returned if the module load command is used before loading 3423a Multiboot kernel. It only makes sense in this case anyway, as GRUB has 3424no idea how to communicate the presence of such modules to a 3425non-Multiboot-aware kernel. 3426 3427@item 21 : Selected disk does not exist 3428This error is returned if the device part of a device- or full file name 3429refers to a disk or BIOS device that is not present or not recognized by 3430the BIOS in the system. 3431 3432@item 22 : No such partition 3433This error is returned if a partition is requested in the device part of 3434a device- or full file name which isn't on the selected disk. 3435 3436@item 23 : Error while parsing number 3437This error is returned if GRUB was expecting to read a number and 3438encountered bad data. 3439 3440@item 24 : Attempt to access block outside partition 3441This error is returned if a linear block address is outside of the disk 3442partition. This generally happens because of a corrupt filesystem on the 3443disk or a bug in the code handling it in GRUB (it's a great debugging 3444tool). 3445 3446@item 25 : Disk read error 3447This error is returned if there is a disk read error when trying to 3448probe or read data from a particular disk. 3449 3450@item 26 : Too many symbolic links 3451This error is returned if the link count is beyond the maximum 3452(currently 5), possibly the symbolic links are looped. 3453 3454@item 27 : Unrecognized command 3455This error is returned if an unrecognized command is entered on the 3456command-line or in a boot sequence section of a configuration file and 3457that entry is selected. 3458 3459@item 28 : Selected item cannot fit into memory 3460This error is returned if a kernel, module, or raw file load command is 3461either trying to load its data such that it won't fit into memory or it 3462is simply too big. 3463 3464@item 29 : Disk write error 3465This error is returned if there is a disk write error when trying to 3466write to a particular disk. This would generally only occur during an 3467install of set active partition command. 3468 3469@item 30 : Invalid argument 3470This error is returned if an argument specified to a command is invalid. 3471 3472@item 31 : File is not sector aligned 3473This error may occur only when you access a ReiserFS partition by 3474block-lists (e.g. the command @command{install}). In this case, you 3475should mount the partition with the @samp{-o notail} option. 3476 3477@item 32 : Must be authenticated 3478This error is returned if you try to run a locked entry. You should 3479enter a correct password before running such an entry. 3480 3481@item 33 : Serial device not configured 3482This error is returned if you try to change your terminal to a serial 3483one before initializing any serial device. 3484 3485@item 34 : No spare sectors on the disk 3486This error is returned if a disk doesn't have enough spare space. This 3487happens when you try to embed Stage 1.5 into the unused sectors after 3488the MBR, but the first partition starts right after the MBR or they are 3489used by EZ-BIOS. 3490@end table 3491 3492 3493@node Invoking the grub shell 3494@chapter Invoking the grub shell 3495 3496This chapter documents the grub shell @command{grub}. Note that the grub 3497shell is an emulator; it doesn't run under the native environment, so it 3498sometimes does something wrong. Therefore, you shouldn't trust it too 3499much. If there is anything wrong with it, don't hesitate to try the 3500native GRUB environment, especially when it guesses a wrong map between 3501BIOS drives and OS devices. 3502 3503@menu 3504* Basic usage:: How to use the grub shell 3505* Installation under UNIX:: How to install GRUB via @command{grub} 3506* Device map:: The map between BIOS drives and OS devices 3507@end menu 3508 3509 3510@node Basic usage 3511@section Introduction into the grub shell 3512 3513You can use the command @command{grub} for installing GRUB under your 3514operating systems and for a testbed when you add a new feature into GRUB 3515or when fixing a bug. @command{grub} is almost the same as the Stage 2, 3516and, in fact, it shares the source code with the Stage 2 and you can use 3517the same commands (@pxref{Commands}) in @command{grub}. It is emulated by 3518replacing BIOS calls with UNIX system calls and libc functions. 3519 3520The command @command{grub} accepts the following options: 3521 3522@table @option 3523@item --help 3524Print a summary of the command-line options and exit. 3525 3526@item --version 3527Print the version number of GRUB and exit. 3528 3529@item --verbose 3530Print some verbose messages for debugging purpose. 3531 3532@item --device-map=@var{file} 3533Use the device map file @var{file}. The format is described in 3534@ref{Device map}. 3535 3536@item --no-floppy 3537Do not probe any floppy drive. This option has no effect if the option 3538@option{--device-map} is specified (@pxref{Device map}). 3539 3540@item --probe-second-floppy 3541Probe the second floppy drive. If this option is not specified, the grub 3542shell does not probe it, as that sometimes takes a long time. If you 3543specify the device map file (@pxref{Device map}), the grub shell just 3544ignores this option. 3545 3546@item --config-file=@var{file} 3547Read the configuration file @var{file} instead of 3548@file{/boot/grub/menu.lst}. The format is the same as the normal GRUB 3549syntax. See @ref{Filesystem}, for more information. 3550 3551@item --boot-drive=@var{drive} 3552Set the stage2 @var{boot_drive} to @var{drive}. This argument should be 3553an integer (decimal, octal or hexadecimal). 3554 3555@item --install-partition=@var{par} 3556Set the stage2 @var{install_partition} to @var{par}. This argument 3557should be an integer (decimal, octal or hexadecimal). 3558 3559@item --no-config-file 3560Do not use the configuration file even if it can be read. 3561 3562@item --no-curses 3563Do not use the screen handling interface by the curses even if it is 3564available. 3565 3566@item --batch 3567This option has the same meaning as @samp{--no-config-file --no-curses}. 3568 3569@item --read-only 3570Disable writing to any disk. 3571 3572@item --hold 3573Wait until a debugger will attach. This option is useful when you want 3574to debug the startup code. 3575@end table 3576 3577 3578@node Installation under UNIX 3579@section How to install GRUB via @command{grub} 3580 3581The installation procedure is the same as under the @dfn{native} Stage 35822. @xref{Installation}, for more information. The command 3583@command{grub}-specific information is described here. 3584 3585What you should be careful about is @dfn{buffer cache}. @command{grub} 3586makes use of raw devices instead of filesystems that your operating 3587systems serve, so there exists a potential problem that some cache 3588inconsistency may corrupt your filesystems. What we recommend is: 3589 3590@itemize @bullet 3591@item 3592If you can unmount drives to which GRUB may write any amount of data, 3593unmount them before running @command{grub}. 3594 3595@item 3596If a drive cannot be unmounted but can be mounted with the read-only 3597flag, mount it in read-only mode. That should be secure. 3598 3599@item 3600If a drive must be mounted with the read-write flag, make sure that no 3601activity is being done on it while the command @command{grub} is 3602running. 3603 3604@item 3605Reboot your operating system as soon as possible. This is probably not 3606required if you follow the rules above, but reboot is the most secure 3607way. 3608@end itemize 3609 3610In addition, enter the command @command{quit} when you finish the 3611installation. That is @emph{very important} because @command{quit} makes 3612the buffer cache consistent. Do not push @key{C-c}. 3613 3614If you want to install GRUB non-interactively, specify @samp{--batch} 3615option in the command-line. This is a simple example: 3616 3617@example 3618@group 3619#!/bin/sh 3620 3621# Use /usr/sbin/grub if you are on an older system. 3622/sbin/grub --batch <<EOT 1>/dev/null 2>/dev/null 3623root (hd0,0) 3624setup (hd0) 3625quit 3626EOT 3627@end group 3628@end example 3629 3630 3631@node Device map 3632@section The map between BIOS drives and OS devices 3633 3634When you specify the option @option{--device-map} (@pxref{Basic usage}), 3635the grub shell creates the @dfn{device map file} automatically unless it 3636already exists. The file name @file{/boot/grub/device.map} is preferred. 3637 3638If the device map file exists, the grub shell reads it to map BIOS 3639drives to OS devices. This file consists of lines like this: 3640 3641@example 3642@var{device} @var{file} 3643@end example 3644 3645@var{device} is a drive specified in the GRUB syntax (@pxref{Device 3646syntax}), and @var{file} is an OS file, which is normally a device 3647file. 3648 3649The reason why the grub shell gives you the device map file is that it 3650cannot guess the map between BIOS drives and OS devices correctly in 3651some environments. For example, if you exchange the boot sequence 3652between IDE and SCSI in your BIOS, it gets the order wrong. 3653 3654Thus, edit the file if the grub shell makes a mistake. You can put any 3655comments in the file if needed, as the grub shell assumes that a line is 3656just a comment if the first character is @samp{#}. 3657 3658 3659@node Invoking grub-install 3660@chapter Invoking grub-install 3661 3662The program @command{grub-install} installs GRUB on your drive using the 3663grub shell (@pxref{Invoking the grub shell}). You must specify the 3664device name on which you want to install GRUB, like this: 3665 3666@example 3667grub-install @var{install_device} 3668@end example 3669 3670The device name @var{install_device} is an OS device name or a GRUB 3671device name. 3672 3673@command{grub-install} accepts the following options: 3674 3675@table @option 3676@item --help 3677Print a summary of the command-line options and exit. 3678 3679@item --version 3680Print the version number of GRUB and exit. 3681 3682@item --force-lba 3683Force GRUB to use LBA mode even for a buggy BIOS. Use this option only 3684if your BIOS doesn't work properly in LBA mode even though it supports 3685LBA mode. 3686 3687@item --root-directory=@var{dir} 3688Install GRUB images under the directory @var{dir} instead of the root 3689directory. This option is useful when you want to install GRUB into a 3690separate partition or a removable disk. Here is an example in which 3691you have a separate @dfn{boot} partition which is mounted on 3692@file{/boot}: 3693 3694@example 3695@kbd{grub-install --root-directory=/boot hd0} 3696@end example 3697 3698@item --grub-shell=@var{file} 3699Use @var{file} as the grub shell. You can append arbitrary options to 3700@var{file} after the file name, like this: 3701 3702@example 3703@kbd{grub-install --grub-shell="grub --read-only" /dev/fd0} 3704@end example 3705 3706@item --recheck 3707Recheck the device map, even if @file{/boot/grub/device.map} already 3708exists. You should use this option whenever you add/remove a disk 3709into/from your computer. 3710@end table 3711 3712 3713@node Invoking grub-md5-crypt 3714@chapter Invoking grub-md5-crypt 3715 3716The program @command{grub-md5-crypt} encrypts a password in MD5 format. 3717This is just a frontend of the grub shell (@pxref{Invoking the grub 3718shell}). Passwords encrypted by this program can be used with the 3719command @command{password} (@pxref{password}). 3720 3721@command{grub-md5-crypt} accepts the following options: 3722 3723@table @option 3724@item --help 3725Print a summary of the command-line options and exit. 3726 3727@item --version 3728Print the version information and exit. 3729 3730@item --grub-shell=@var{file} 3731Use @var{file} as the grub shell. 3732@end table 3733 3734 3735@node Invoking grub-terminfo 3736@chapter Invoking grub-terminfo 3737 3738The program @command{grub-terminfo} generates a terminfo command from 3739a terminfo name (@pxref{terminfo}). The result can be used in the 3740configuration file, to define escape sequences. Because GRUB assumes 3741that your terminal is vt100-compatible by default, this would be 3742useful only if your terminal is uncommon (such as vt52). 3743 3744@command{grub-terminfo} accepts the following options: 3745 3746@table @option 3747@item --help 3748Print a summary of the command-line options and exit. 3749 3750@item --version 3751Print the version information and exit. 3752@end table 3753 3754You must specify one argument to this command. For example: 3755 3756@example 3757@kbd{grub-terminfo vt52} 3758@end example 3759 3760 3761@node Invoking grub-set-default 3762@chapter Invoking grub-set-default 3763 3764The program @command{grub-set-default} sets the default boot entry for 3765GRUB. This automatically creates a file named @file{default} under 3766your GRUB directory (i.e. @file{/boot/grub}), if it is not 3767present. This file is used to determine the default boot entry when 3768GRUB boots up your system when you use @samp{default saved} in your 3769configuration file (@pxref{default}), and to save next default boot 3770entry when you use @samp{savedefault} in a boot entry 3771(@pxref{savedefault}). 3772 3773@command{grub-set-default} accepts the following options: 3774 3775@table @option 3776@item --help 3777Print a summary of the command-line options and exit. 3778 3779@item --version 3780Print the version information and exit. 3781 3782@item --root-directory=@var{dir} 3783Use the directory @var{dir} instead of the root directory 3784(i.e. @file{/}) to define the location of the default file. This 3785is useful when you mount a disk which is used for another system. 3786@end table 3787 3788You must specify a single argument to @command{grub-set-default}. This 3789argument is normally the number of a default boot entry. For example, 3790if you have this configuration file: 3791 3792@example 3793@group 3794default saved 3795timeout 10 3796 3797title GNU/Hurd 3798root (hd0,0) 3799... 3800 3801title GNU/Linux 3802root (hd0,1) 3803... 3804@end group 3805@end example 3806 3807and if you want to set the next default boot entry to GNU/Linux, you 3808may execute this command: 3809 3810@example 3811@kbd{grub-set-default 1} 3812@end example 3813 3814Because the entry for GNU/Linux is @samp{1}. Note that entries are 3815counted from zero. So, if you want to specify GNU/Hurd here, then you 3816should specify @samp{0}. 3817 3818This feature is very useful if you want to test a new kernel or to 3819make your system quite robust. @xref{Making your system robust}, for 3820more hints about how to set up a robust system. 3821 3822 3823@node Invoking mbchk 3824@chapter Invoking mbchk 3825 3826The program @command{mbchk} checks for the format of a Multiboot 3827kernel. We recommend using this program before booting your own kernel 3828by GRUB. 3829 3830@command{mbchk} accepts the following options: 3831 3832@table @option 3833@item --help 3834Print a summary of the command-line options and exit. 3835 3836@item --version 3837Print the version number of GRUB and exit. 3838 3839@item --quiet 3840Suppress all normal output. 3841@end table 3842 3843 3844@node Obtaining and Building GRUB 3845@appendix How to obtain and build GRUB 3846 3847@quotation 3848@strong{Caution:} GRUB requires binutils-2.9.1.0.23 or later because the 3849GNU assembler has been changed so that it can produce real 16bits 3850machine code between 2.9.1 and 2.9.1.0.x. See 3851@uref{http://sources.redhat.com/binutils/}, to obtain information on 3852how to get the latest version. 3853@end quotation 3854 3855GRUB is available from the GNU alpha archive site 3856@uref{ftp://alpha.gnu.org/gnu/grub} or any of its mirrors. The file 3857will be named grub-version.tar.gz. The current version is 3858@value{VERSION}, so the file you should grab is: 3859 3860@uref{ftp://alpha.gnu.org/gnu/grub/grub-@value{VERSION}.tar.gz} 3861 3862To unbundle GRUB use the instruction: 3863 3864@example 3865@kbd{zcat grub-@value{VERSION}.tar.gz | tar xvf -} 3866@end example 3867 3868which will create a directory called @file{grub-@value{VERSION}} with 3869all the sources. You can look at the file @file{INSTALL} for detailed 3870instructions on how to build and install GRUB, but you should be able to 3871just do: 3872 3873@example 3874@group 3875@kbd{cd grub-@value{VERSION}} 3876@kbd{./configure} 3877@kbd{make install} 3878@end group 3879@end example 3880 3881This will install the grub shell @file{grub} (@pxref{Invoking the grub 3882shell}), the Multiboot checker @file{mbchk} (@pxref{Invoking mbchk}), 3883and the GRUB images. This will also install the GRUB manual. 3884 3885Also, the latest version is available from the CVS. See 3886@uref{http://savannah.gnu.org/cvs/?group=grub} for more information. 3887 3888 3889@node Reporting bugs 3890@appendix Reporting bugs 3891 3892These are the guideline for how to report bugs. Take a look at this 3893list below before you submit bugs: 3894 3895@enumerate 3896@item 3897Before getting unsettled, read this manual through and through. Also, 3898see the @uref{http://www.gnu.org/software/grub/grub-faq.html, GNU GRUB FAQ}. 3899 3900@item 3901Always mention the information on your GRUB. The version number and the 3902configuration are quite important. If you build it yourself, write the 3903options specified to the configure script and your operating system, 3904including the versions of gcc and binutils. 3905 3906@item 3907If you have trouble with the installation, inform us of how you 3908installed GRUB. Don't omit error messages, if any. Just @samp{GRUB hangs 3909up when it boots} is not enough. 3910 3911The information on your hardware is also essential. These are especially 3912important: the geometries and the partition tables of your hard disk 3913drives and your BIOS. 3914 3915@item 3916If GRUB cannot boot your operating system, write down 3917@emph{everything} you see on the screen. Don't paraphrase them, like 3918@samp{The foo OS crashes with GRUB, even though it can boot with the 3919bar boot loader just fine}. Mention the commands you executed, the 3920messages printed by them, and information on your operating system 3921including the version number. 3922 3923@item 3924Explain what you wanted to do. It is very useful to know your purpose 3925and your wish, and how GRUB didn't satisfy you. 3926 3927@item 3928If you can investigate the problem yourself, please do. That will give 3929you and us much more information on the problem. Attaching a patch is 3930even better. 3931 3932When you attach a patch, make the patch in unified diff format, and 3933write ChangeLog entries. But, even when you make a patch, don't forget 3934to explain the problem, so that we can understand what your patch is 3935for. 3936 3937@item 3938Write down anything that you think might be related. Please understand 3939that we often need to reproduce the same problem you encounterred in our 3940environment. So your information should be sufficient for us to do the 3941same thing---Don't forget that we cannot see your computer directly. If 3942you are not sure whether to state a fact or leave it out, state it! 3943Reporting too many things is much better than omitting something 3944important. 3945@end enumerate 3946 3947If you follow the guideline above, submit a report to the 3948@uref{http://savannah.gnu.org/bugs/?group=grub, Bug Tracking System}. 3949Alternatively, you can submit a report via electronic mail to 3950@email{bug-grub@@gnu.org}, but we strongly recommend that you use the 3951Bug Tracking System, because e-mail can be passed over easily. 3952 3953Once we get your report, we will try to fix the bugs. 3954 3955 3956@node Future 3957@appendix Where GRUB will go 3958 3959We started the next generation of GRUB, GRUB 2. This will include 3960internationalization, dynamic module loading, real memory management, 3961multiple architecture support, a scripting language, and many other 3962nice feature. If you are interested in the development of GRUB 2, take 3963a look at @uref{http://www.gnu.org/software/grub/grub.html, the 3964homepage}. 3965 3966 3967@c Separate the programming guide. 3968@include internals.texi 3969 3970 3971@node Index 3972@unnumbered Index 3973 3974@c Currently, we use only the Concept Index. 3975@printindex cp 3976 3977 3978@bye 3979 3980Some notes: 3981 3982 This is the second attempt to rewrite the manual. The status is 3983mostly complete, but I need to check the spelling by ispell, and add 3984more indices. Perhaps I also have to let some English native speakers 3985proofread this manual through. My English is syntactically almost 3986perfect, but sometimes (often?) awful in the nuance. Hehe, I can't be an 3987English poet for now. 3988