1This is grub.info, produced by makeinfo version 4.0 from grub.texi. 2 3INFO-DIR-SECTION Kernel 4START-INFO-DIR-ENTRY 5* GRUB: (grub). The GRand Unified Bootloader 6* grub-install: (grub)Invoking grub-install. Install GRUB on your drive 7* grub-md5-crypt: (grub)Invoking grub-md5-crypt. Encrypt a password 8 in MD5 format 9* grub-terminfo: (grub)Invoking grub-terminfo. Generate a terminfo 10 command from a 11 terminfo name 12* grub-set-default: (grub)Invoking grub-set-default. Set a default boot 13 entry 14* mbchk: (grub)Invoking mbchk. Check for the format of a Multiboot kernel 15END-INFO-DIR-ENTRY 16 17 Copyright (C) 1999,2000,2001,2002,2004 Free Software Foundation, Inc. 18 19 Permission is granted to make and distribute verbatim copies of this 20manual provided the copyright notice and this permission notice are 21preserved on all copies. 22 23 Permission is granted to copy and distribute modified versions of 24this manual under the conditions for verbatim copying, provided also 25that the entire resulting derived work is distributed under the terms 26of a permission notice identical to this one. 27 28 Permission is granted to copy and distribute translations of this 29manual into another language, under the above conditions for modified 30versions. 31 32 33File: grub.info, Node: Top, Next: Introduction, Up: (dir) 34 35GRUB manual 36*********** 37 38 This is the documentation of GNU GRUB, the GRand Unified Bootloader, 39a flexible and powerful boot loader program for PCs. 40 41 This edition documents version 0.95. 42 43* Menu: 44 45* Introduction:: Capturing the spirit of GRUB 46* Naming convention:: Names of your drives in GRUB 47* Installation:: Installing GRUB on your drive 48* Booting:: How to boot different operating systems 49* Configuration:: Writing your own configuration file 50* Network:: Downloading OS images from a network 51* Serial terminal:: Using GRUB via a serial line 52* Preset Menu:: Embedding a configuration file into GRUB 53* Security:: Improving the security 54* Images:: GRUB image files 55* Filesystem:: Filesystem syntax and semantics 56* Interface:: The menu and the command-line 57* Commands:: The list of available builtin commands 58* Troubleshooting:: Error messages produced by GRUB 59* Invoking the grub shell:: How to use the grub shell 60* Invoking grub-install:: How to use the GRUB installer 61* Invoking grub-md5-crypt:: How to generate a cryptic password 62* Invoking grub-terminfo:: How to generate a terminfo command 63* Invoking grub-set-default:: How to set a default boot entry 64* Invoking mbchk:: How to use the Multiboot checker 65* Obtaining and Building GRUB:: How to obtain and build GRUB 66* Reporting bugs:: Where you should send a bug report 67* Future:: Some future plans on GRUB 68* Internals:: Hacking GRUB 69* Index:: 70 71 72File: grub.info, Node: Introduction, Next: Naming convention, Prev: Top, Up: Top 73 74Introduction to GRUB 75******************** 76 77* Menu: 78 79* Overview:: What exactly GRUB is and how to use it 80* History:: From maggot to house fly 81* Features:: GRUB features 82* Role of a boot loader:: The role of a boot loader 83 84 85File: grub.info, Node: Overview, Next: History, Up: Introduction 86 87Overview 88======== 89 90 Briefly, a "boot loader" is the first software program that runs when 91a computer starts. It is responsible for loading and transferring 92control to an operating system "kernel" software (such as Linux or GNU 93Mach). The kernel, in turn, initializes the rest of the operating 94system (e.g. a GNU system). 95 96 GNU GRUB is a very powerful boot loader, which can load a wide 97variety of free operating systems, as well as proprietary operating 98systems with chain-loading(1) (*note Overview-Footnote-1::). GRUB is 99designed to address the complexity of booting a personal computer; both 100the program and this manual are tightly bound to that computer platform, 101although porting to other platforms may be addressed in the future. 102 103 One of the important features in GRUB is flexibility; GRUB 104understands filesystems and kernel executable formats, so you can load 105an arbitrary operating system the way you like, without recording the 106physical position of your kernel on the disk. Thus you can load the 107kernel just by specifying its file name and the drive and partition 108where the kernel resides. 109 110 When booting with GRUB, you can use either a command-line interface 111(*note Command-line interface::), or a menu interface (*note Menu 112interface::). Using the command-line interface, you type the drive 113specification and file name of the kernel manually. In the menu 114interface, you just select an OS using the arrow keys. The menu is 115based on a configuration file which you prepare beforehand (*note 116Configuration::). While in the menu, you can switch to the command-line 117mode, and vice-versa. You can even edit menu entries before using them. 118 119 In the following chapters, you will learn how to specify a drive, a 120partition, and a file name (*note Naming convention::) to GRUB, how to 121install GRUB on your drive (*note Installation::), and how to boot your 122OSes (*note Booting::), step by step. 123 124 Besides the GRUB boot loader itself, there is a "grub shell" `grub' 125(*note Invoking the grub shell::) which can be run when you are in your 126operating system. It emulates the boot loader and can be used for 127installing the boot loader. 128 129 130File: grub.info, Node: Overview-Footnotes, Up: Overview 131 132 (1) "chain-load" is the mechanism for loading unsupported operating 133systems by loading another boot loader. It is typically used for 134loading DOS or Windows. 135 136 137File: grub.info, Node: History, Next: Features, Prev: Overview, Up: Introduction 138 139History of GRUB 140=============== 141 142 GRUB originated in 1995 when Erich Boleyn was trying to boot the GNU 143Hurd with the University of Utah's Mach 4 microkernel (now known as GNU 144Mach). Erich and Brian Ford designed the Multiboot Specification 145(*note Multiboot Specification: (multiboot)Top.), because they were 146determined not to add to the large number of mutually-incompatible PC 147boot methods. 148 149 Erich then began modifying the FreeBSD boot loader so that it would 150understand Multiboot. He soon realized that it would be a lot easier to 151write his own boot loader from scratch than to keep working on the 152FreeBSD boot loader, and so GRUB was born. 153 154 Erich added many features to GRUB, but other priorities prevented him 155from keeping up with the demands of its quickly-expanding user base. In 1561999, Gordon Matzigkeit and Yoshinori K. Okuji adopted GRUB as an 157official GNU package, and opened its development by making the latest 158sources available via anonymous CVS. *Note Obtaining and Building 159GRUB::, for more information. 160 161 162File: grub.info, Node: Features, Next: Role of a boot loader, Prev: History, Up: Introduction 163 164GRUB features 165============= 166 167 The primary requirement for GRUB is that it be compliant with the 168"Multiboot Specification", which is described in *Note Multiboot 169Specification: (multiboot)Top. 170 171 The other goals, listed in approximate order of importance, are: 172 173 * Basic functions must be straightforward for end-users. 174 175 * Rich functionality to support kernel experts and designers. 176 177 * Backward compatibility for booting FreeBSD, NetBSD, OpenBSD, and 178 Linux. Proprietary kernels (such as DOS, Windows NT, and OS/2) are 179 supported via a chain-loading function. 180 181 Except for specific compatibility modes (chain-loading and the Linux 182"piggyback" format), all kernels will be started in much the same state 183as in the Multiboot Specification. Only kernels loaded at 1 megabyte or 184above are presently supported. Any attempt to load below that boundary 185will simply result in immediate failure and an error message reporting 186the problem. 187 188 In addition to the requirements above, GRUB has the following 189features (note that the Multiboot Specification doesn't require all the 190features that GRUB supports): 191 192Recognize multiple executable formats 193 Support many of the "a.out" variants plus "ELF". Symbol tables are 194 also loaded. 195 196Support non-Multiboot kernels 197 Support many of the various free 32-bit kernels that lack Multiboot 198 compliance (primarily FreeBSD, NetBSD, OpenBSD, and Linux). 199 Chain-loading of other boot loaders is also supported. 200 201Load multiples modules 202 Fully support the Multiboot feature of loading multiple modules. 203 204Load a configuration file 205 Support a human-readable text configuration file with preset boot 206 commands. You can also load another configuration file dynamically 207 and embed a preset configuration file in a GRUB image file. The 208 list of commands (*note Commands::) are a superset of those 209 supported on the command-line. An example configuration file is 210 provided in *Note Configuration::. 211 212Provide a menu interface 213 A menu interface listing preset boot commands, with a programmable 214 timeout, is available. There is no fixed limit on the number of 215 boot entries, and the current implementation has space for several 216 hundred. 217 218Have a flexible command-line interface 219 A fairly flexible command-line interface, accessible from the menu, 220 is available to edit any preset commands, or write a new boot 221 command set from scratch. If no configuration file is present, 222 GRUB drops to the command-line. 223 224 The list of commands (*note Commands::) are a subset of those 225 supported for configuration files. Editing commands closely 226 resembles the Bash command-line (*note Bash: (features)Command 227 Line Editing.), with <TAB>-completion of commands, devices, 228 partitions, and files in a directory depending on context. 229 230Support multiple filesystem types 231 Support multiple filesystem types transparently, plus a useful 232 explicit blocklist notation. The currently supported filesystem 233 types are "BSD FFS", "DOS FAT16 and FAT32", "Minix fs", "Linux 234 ext2fs", "ReiserFS", "JFS", "XFS", and "VSTa fs". *Note 235 Filesystem::, for more information. 236 237Support automatic decompression 238 Can decompress files which were compressed by `gzip'. This 239 function is both automatic and transparent to the user (i.e. all 240 functions operate upon the uncompressed contents of the specified 241 files). This greatly reduces a file size and loading time, a 242 particularly great benefit for floppies.(1) (*note 243 Features-Footnote-1::) 244 245 It is conceivable that some kernel modules should be loaded in a 246 compressed state, so a different module-loading command can be 247 specified to avoid uncompressing the modules. 248 249Access data on any installed device 250 Support reading data from any or all floppies or hard disk(s) 251 recognized by the BIOS, independent of the setting of the root 252 device. 253 254Be independent of drive geometry translations 255 Unlike many other boot loaders, GRUB makes the particular drive 256 translation irrelevant. A drive installed and running with one 257 translation may be converted to another translation without any 258 adverse effects or changes in GRUB's configuration. 259 260Detect all installed RAM 261 GRUB can generally find all the installed RAM on a PC-compatible 262 machine. It uses an advanced BIOS query technique for finding all 263 memory regions. As described on the Multiboot Specification (*note 264 Multiboot Specification: (multiboot)Top.), not all kernels make 265 use of this information, but GRUB provides it for those who do. 266 267Support Logical Block Address mode 268 In traditional disk calls (called "CHS mode"), there is a geometry 269 translation problem, that is, the BIOS cannot access over 1024 270 cylinders, so the accessible space is limited to at least 508 MB 271 and to at most 8GB. GRUB can't universally solve this problem, as 272 there is no standard interface used in all machines. However, 273 several newer machines have the new interface, Logical Block 274 Address ("LBA") mode. GRUB automatically detects if LBA mode is 275 available and uses it if available. In LBA mode, GRUB can access 276 the entire disk. 277 278Support network booting 279 GRUB is basically a disk-based boot loader but also has network 280 support. You can load OS images from a network by using the "TFTP" 281 protocol. 282 283Support remote terminals 284 To support computers with no console, GRUB provides remote terminal 285 support, so that you can control GRUB from a remote host. Only 286 serial terminal support is implemented at the moment. 287 288 289File: grub.info, Node: Features-Footnotes, Up: Features 290 291 (1) There are a few pathological cases where loading a very badly 292organized ELF kernel might take longer, but in practice this never 293happen. 294 295 296File: grub.info, Node: Role of a boot loader, Prev: Features, Up: Introduction 297 298The role of a boot loader 299========================= 300 301 The following is a quotation from Gordon Matzigkeit, a GRUB fanatic: 302 303 Some people like to acknowledge both the operating system and 304 kernel when they talk about their computers, so they might say 305 they use "GNU/Linux" or "GNU/Hurd". Other people seem to think 306 that the kernel is the most important part of the system, so they 307 like to call their GNU operating systems "Linux systems." 308 309 I, personally, believe that this is a grave injustice, because the 310 _boot loader_ is the most important software of all. I used to 311 refer to the above systems as either "LILO"(1) (*note Role of a 312 boot loader-Footnote-1::) or "GRUB" systems. 313 314 Unfortunately, nobody ever understood what I was talking about; 315 now I just use the word "GNU" as a pseudonym for GRUB. 316 317 So, if you ever hear people talking about their alleged "GNU" 318 systems, remember that they are actually paying homage to the best 319 boot loader around... GRUB! 320 321 We, the GRUB maintainers, do not (usually) encourage Gordon's level 322of fanaticism, but it helps to remember that boot loaders deserve 323recognition. We hope that you enjoy using GNU GRUB as much as we did 324writing it. 325 326 327File: grub.info, Node: Role of a boot loader-Footnotes, Up: Role of a boot loader 328 329 (1) The LInux LOader, a boot loader that everybody uses, but nobody 330likes. 331 332 333File: grub.info, Node: Naming convention, Next: Installation, Prev: Introduction, Up: Top 334 335Naming convention 336***************** 337 338 The device syntax used in GRUB is a wee bit different from what you 339may have seen before in your operating system(s), and you need to know 340it so that you can specify a drive/partition. 341 342 Look at the following examples and explanations: 343 344 (fd0) 345 346 First of all, GRUB requires that the device name be enclosed with 347`(' and `)'. The `fd' part means that it is a floppy disk. The number 348`0' is the drive number, which is counted from _zero_. This expression 349means that GRUB will use the whole floppy disk. 350 351 (hd0,1) 352 353 Here, `hd' means it is a hard disk drive. The first integer `0' 354indicates the drive number, that is, the first hard disk, while the 355second integer, `1', indicates the partition number (or the PC slice 356number in the BSD terminology). Once again, please note that the 357partition numbers are counted from _zero_, not from one. This 358expression means the second partition of the first hard disk drive. In 359this case, GRUB uses one partition of the disk, instead of the whole 360disk. 361 362 (hd0,4) 363 364 This specifies the first "extended partition" of the first hard disk 365drive. Note that the partition numbers for extended partitions are 366counted from `4', regardless of the actual number of primary partitions 367on your hard disk. 368 369 (hd1,a) 370 371 This means the BSD `a' partition of the second hard disk. If you 372need to specify which PC slice number should be used, use something 373like this: `(hd1,0,a)'. If the PC slice number is omitted, GRUB 374searches for the first PC slice which has a BSD `a' partition. 375 376 Of course, to actually access the disks or partitions with GRUB, you 377need to use the device specification in a command, like `root (fd0)' or 378`unhide (hd0,2)'. To help you find out which number specifies a 379partition you want, the GRUB command-line (*note Command-line 380interface::) options have argument completion. This means that, for 381example, you only need to type 382 383 root ( 384 385 followed by a <TAB>, and GRUB will display the list of drives, 386partitions, or file names. So it should be quite easy to determine the 387name of your target partition, even with minimal knowledge of the 388syntax. 389 390 Note that GRUB does _not_ distinguish IDE from SCSI - it simply 391counts the drive numbers from zero, regardless of their type. Normally, 392any IDE drive number is less than any SCSI drive number, although that 393is not true if you change the boot sequence by swapping IDE and SCSI 394drives in your BIOS. 395 396 Now the question is, how to specify a file? Again, consider an 397example: 398 399 (hd0,0)/vmlinuz 400 401 This specifies the file named `vmlinuz', found on the first 402partition of the first hard disk drive. Note that the argument 403completion works with file names, too. 404 405 That was easy, admit it. Now read the next chapter, to find out how 406to actually install GRUB on your drive. 407 408 409File: grub.info, Node: Installation, Next: Booting, Prev: Naming convention, Up: Top 410 411Installation 412************ 413 414 In order to install GRUB as your boot loader, you need to first 415install the GRUB system and utilities under your UNIX-like operating 416system (*note Obtaining and Building GRUB::). You can do this either 417from the source tarball, or as a package for your OS. 418 419 After you have done that, you need to install the boot loader on a 420drive (floppy or hard disk). There are two ways of doing that - either 421using the utility `grub-install' (*note Invoking grub-install::) on a 422UNIX-like OS, or by running GRUB itself from a floppy. These are quite 423similar, however the utility might probe a wrong BIOS drive, so you 424should be careful. 425 426 Also, if you install GRUB on a UNIX-like OS, please make sure that 427you have an emergency boot disk ready, so that you can rescue your 428computer if, by any chance, your hard drive becomes unusable 429(unbootable). 430 431 GRUB comes with boot images, which are normally put in the directory 432`/usr/lib/grub/i386-pc'. If you do not use grub-install, then you need 433to copy the files `stage1', `stage2', and `*stage1_5' to the directory 434`/boot/grub', and run the `grub-set-default' (*note Invoking 435grub-set-default::) if you intend to use `default saved' (*note 436default::) in your configuration file. Hereafter, the directory where 437GRUB images are initially placed (normally `/usr/lib/grub/i386-pc') 438will be called the "image directory", and the directory where the boot 439loader needs to find them (usually `/boot/grub') will be called the 440"boot directory". 441 442* Menu: 443 444* Creating a GRUB boot floppy:: 445* Installing GRUB natively:: 446* Installing GRUB using grub-install:: 447* Making a GRUB bootable CD-ROM:: 448 449 450File: grub.info, Node: Creating a GRUB boot floppy, Next: Installing GRUB natively, Up: Installation 451 452Creating a GRUB boot floppy 453=========================== 454 455 To create a GRUB boot floppy, you need to take the files `stage1' 456and `stage2' from the image directory, and write them to the first and 457the second block of the floppy disk, respectively. 458 459 *Caution:* This procedure will destroy any data currently stored on 460the floppy. 461 462 On a UNIX-like operating system, that is done with the following 463commands: 464 465 # cd /usr/lib/grub/i386-pc 466 # dd if=stage1 of=/dev/fd0 bs=512 count=1 467 1+0 records in 468 1+0 records out 469 # dd if=stage2 of=/dev/fd0 bs=512 seek=1 470 153+1 records in 471 153+1 records out 472 # 473 474 The device file name may be different. Consult the manual for your 475OS. 476 477 478File: grub.info, Node: Installing GRUB natively, Next: Installing GRUB using grub-install, Prev: Creating a GRUB boot floppy, Up: Installation 479 480Installing GRUB natively 481======================== 482 483 *Caution:* Installing GRUB's stage1 in this manner will erase the 484normal boot-sector used by an OS. 485 486 GRUB can currently boot GNU Mach, Linux, FreeBSD, NetBSD, and OpenBSD 487directly, so using it on a boot sector (the first sector of a 488partition) should be okay. But generally, it would be a good idea to 489back up the first sector of the partition on which you are installing 490GRUB's stage1. This isn't as important if you are installing GRUB on 491the first sector of a hard disk, since it's easy to reinitialize it 492(e.g. by running `FDISK /MBR' from DOS). 493 494 If you decide to install GRUB in the native environment, which is 495definitely desirable, you'll need to create a GRUB boot disk, and 496reboot your computer with it. Otherwise, see *Note Installing GRUB 497using grub-install::. 498 499 Once started, GRUB will show the command-line interface (*note 500Command-line interface::). First, set the GRUB's "root device"(1) 501(*note Installing GRUB natively-Footnote-1::) to the partition 502containing the boot directory, like this: 503 504 grub> root (hd0,0) 505 506 If you are not sure which partition actually holds this directory, 507use the command `find' (*note find::), like this: 508 509 grub> find /boot/grub/stage1 510 511 This will search for the file name `/boot/grub/stage1' and show the 512devices which contain the file. 513 514 Once you've set the root device correctly, run the command `setup' 515(*note setup::): 516 517 grub> setup (hd0) 518 519 This command will install the GRUB boot loader on the Master Boot 520Record (MBR) of the first drive. If you want to put GRUB into the boot 521sector of a partition instead of putting it in the MBR, specify the 522partition into which you want to install GRUB: 523 524 grub> setup (hd0,0) 525 526 If you install GRUB into a partition or a drive other than the first 527one, you must chain-load GRUB from another boot loader. Refer to the 528manual for the boot loader to know how to chain-load GRUB. 529 530 After using the setup command, you will boot into GRUB without the 531GRUB floppy. See the chapter *Note Booting:: to find out how to boot 532your operating systems from GRUB. 533 534 535File: grub.info, Node: Installing GRUB natively-Footnotes, Up: Installing GRUB natively 536 537 (1) Note that GRUB's root device doesn't necessarily mean your OS's 538root partition; if you need to specify a root partition for your OS, 539add the argument into the command `kernel'. 540 541 542File: grub.info, Node: Installing GRUB using grub-install, Next: Making a GRUB bootable CD-ROM, Prev: Installing GRUB natively, Up: Installation 543 544Installing GRUB using grub-install 545================================== 546 547 *Caution:* This procedure is definitely less safe, because there are 548several ways in which your computer can become unbootable. For example, 549most operating systems don't tell GRUB how to map BIOS drives to OS 550devices correctly--GRUB merely "guesses" the mapping. This will succeed 551in most cases, but not always. Therefore, GRUB provides you with a map 552file called the "device map", which you must fix if it is wrong. *Note 553Device map::, for more details. 554 555 If you still do want to install GRUB under a UNIX-like OS (such as 556GNU), invoke the program `grub-install' (*note Invoking grub-install::) 557as the superuser ("root"). 558 559 The usage is basically very simple. You only need to specify one 560argument to the program, namely, where to install the boot loader. The 561argument can be either a device file (like `/dev/hda') or a partition 562specified in GRUB's notation. For example, under Linux the following 563will install GRUB into the MBR of the first IDE disk: 564 565 # grub-install /dev/hda 566 567 Likewise, under GNU/Hurd, this has the same effect: 568 569 # grub-install /dev/hd0 570 571 If it is the first BIOS drive, this is the same as well: 572 573 # grub-install '(hd0)' 574 575 Or you can omit the parentheses: 576 577 # grub-install hd0 578 579 But all the above examples assume that GRUB should use images under 580the root directory. If you want GRUB to use images under a directory 581other than the root directory, you need to specify the option 582`--root-directory'. The typical usage is that you create a GRUB boot 583floppy with a filesystem. Here is an example: 584 585 # mke2fs /dev/fd0 586 # mount -t ext2 /dev/fd0 /mnt 587 # grub-install --root-directory=/mnt fd0 588 # umount /mnt 589 590 Another example is when you have a separate boot partition which is 591mounted at `/boot'. Since GRUB is a boot loader, it doesn't know 592anything about mountpoints at all. Thus, you need to run `grub-install' 593like this: 594 595 # grub-install --root-directory=/boot /dev/hda 596 597 By the way, as noted above, it is quite difficult to guess BIOS 598drives correctly under a UNIX-like OS. Thus, `grub-install' will prompt 599you to check if it could really guess the correct mappings, after the 600installation. The format is defined in *Note Device map::. Please be 601quite careful. If the output is wrong, it is unlikely that your 602computer will be able to boot with no problem. 603 604 Note that `grub-install' is actually just a shell script and the 605real task is done by the grub shell `grub' (*note Invoking the grub 606shell::). Therefore, you may run `grub' directly to install GRUB, 607without using `grub-install'. Don't do that, however, unless you are 608very familiar with the internals of GRUB. Installing a boot loader on a 609running OS may be extremely dangerous. 610 611 612File: grub.info, Node: Making a GRUB bootable CD-ROM, Prev: Installing GRUB using grub-install, Up: Installation 613 614Making a GRUB bootable CD-ROM 615============================= 616 617 GRUB supports the "no emulation mode" in the El Torito 618specification(1) (*note Making a GRUB bootable CD-ROM-Footnote-1::). 619This means that you can use the whole CD-ROM from GRUB and you don't 620have to make a floppy or hard disk image file, which can cause 621compatibility problems. 622 623 For booting from a CD-ROM, GRUB uses a special Stage 2 called 624`stage2_eltorito'. The only GRUB files you need to have in your 625bootable CD-ROM are this `stage2_eltorito' and optionally a config file 626`menu.lst'. You don't need to use `stage1' or `stage2', because El 627Torito is quite different from the standard boot process. 628 629 Here is an example of procedures to make a bootable CD-ROM image. 630First, make a top directory for the bootable image, say, `iso': 631 632 $ mkdir iso 633 634 Make a directory for GRUB: 635 636 $ mkdir -p iso/boot/grub 637 638 Copy the file `stage2_eltorito': 639 640 $ cp /usr/lib/grub/i386-pc/stage2_eltorito iso/boot/grub 641 642 If desired, make the config file `menu.lst' under `iso/boot/grub' 643(*note Configuration::), and copy any files and directories for the 644disc to the directory `iso/'. 645 646 Finally, make a ISO9660 image file like this: 647 648 $ mkisofs -R -b boot/grub/stage2_eltorito -no-emul-boot \ 649 -boot-load-size 4 -boot-info-table -o grub.iso iso 650 651 This produces a file named `grub.iso', which then can be burned into 652a CD (or a DVD). `mkisofs' has already set up the disc to boot from 653the `boot/grub/stage2_eltorito' file, so there is no need to setup GRUB 654on the disc. (Note that the `-boot-load-size 4' bit is required for 655compatibility with the BIOS on many older machines.) 656 657 You can use the device `(cd)' to access a CD-ROM in your config 658file. This is not required; GRUB automatically sets the root device to 659`(cd)' when booted from a CD-ROM. It is only necessary to refer to 660`(cd)' if you want to access other drives as well. 661 662 663File: grub.info, Node: Making a GRUB bootable CD-ROM-Footnotes, Up: Making a GRUB bootable CD-ROM 664 665 (1) El Torito is a specification for bootable CD using BIOS 666functions. 667 668 669File: grub.info, Node: Booting, Next: Configuration, Prev: Installation, Up: Top 670 671Booting 672******* 673 674 GRUB can load Multiboot-compliant kernels in a consistent way, but 675for some free operating systems you need to use some OS-specific magic. 676 677* Menu: 678 679* General boot methods:: How to boot OSes with GRUB generally 680* OS-specific notes:: Notes on some operating systems 681* Making your system robust:: How to make your system robust 682 683 684File: grub.info, Node: General boot methods, Next: OS-specific notes, Up: Booting 685 686How to boot operating systems 687============================= 688 689 GRUB has two distinct boot methods. One of the two is to load an 690operating system directly, and the other is to chain-load another boot 691loader which then will load an operating system actually. Generally 692speaking, the former is more desirable, because you don't need to 693install or maintain other boot loaders and GRUB is flexible enough to 694load an operating system from an arbitrary disk/partition. However, the 695latter is sometimes required, since GRUB doesn't support all the 696existing operating systems natively. 697 698* Menu: 699 700* Loading an operating system directly:: 701* Chain-loading:: 702 703 704File: grub.info, Node: Loading an operating system directly, Next: Chain-loading, Up: General boot methods 705 706How to boot an OS directly with GRUB 707------------------------------------ 708 709 Multiboot (*note Multiboot Specification: (multiboot)Top.) is the 710native format supported by GRUB. For the sake of convenience, there is 711also support for Linux, FreeBSD, NetBSD and OpenBSD. If you want to 712boot other operating systems, you will have to chain-load them (*note 713Chain-loading::). 714 715 Generally, GRUB can boot any Multiboot-compliant OS in the following 716steps: 717 718 1. Set GRUB's root device to the drive where the OS images are stored 719 with the command `root' (*note root::). 720 721 2. Load the kernel image with the command `kernel' (*note kernel::). 722 723 3. If you need modules, load them with the command `module' (*note 724 module::) or `modulenounzip' (*note modulenounzip::). 725 726 4. Run the command `boot' (*note boot::). 727 728 Linux, FreeBSD, NetBSD and OpenBSD can be booted in a similar 729manner. You load a kernel image with the command `kernel' and then run 730the command `boot'. If the kernel requires some parameters, just append 731the parameters to `kernel', after the file name of the kernel. Also, 732please refer to *Note OS-specific notes::, for information on your 733OS-specific issues. 734 735 736File: grub.info, Node: Chain-loading, Prev: Loading an operating system directly, Up: General boot methods 737 738Load another boot loader to boot unsupported operating systems 739-------------------------------------------------------------- 740 741 If you want to boot an unsupported operating system (e.g. Windows 74295), chain-load a boot loader for the operating system. Normally, the 743boot loader is embedded in the "boot sector" of the partition on which 744the operating system is installed. 745 746 1. Set GRUB's root device to the partition by the command 747 `rootnoverify' (*note rootnoverify::): 748 749 grub> rootnoverify (hd0,0) 750 751 2. Set the "active" flag in the partition using the command 752 `makeactive'(1) (*note Chain-loading-Footnote-1::) (*note 753 makeactive::): 754 755 grub> makeactive 756 757 3. Load the boot loader with the command `chainloader' (*note 758 chainloader::): 759 760 grub> chainloader +1 761 762 `+1' indicates that GRUB should read one sector from the start of 763 the partition. The complete description about this syntax can be 764 found in *Note Block list syntax::. 765 766 4. Run the command `boot' (*note boot::). 767 768 However, DOS and Windows have some deficiencies, so you might have to 769use more complicated instructions. *Note DOS/Windows::, for more 770information. 771 772 773File: grub.info, Node: Chain-loading-Footnotes, Up: Chain-loading 774 775 (1) This is not necessary for most of the modern operating systems. 776 777 778File: grub.info, Node: OS-specific notes, Next: Making your system robust, Prev: General boot methods, Up: Booting 779 780Some caveats on OS-specific issues 781================================== 782 783 Here, we describe some caveats on several operating systems. 784 785* Menu: 786 787* GNU/Hurd:: 788* GNU/Linux:: 789* FreeBSD:: 790* NetBSD:: 791* OpenBSD:: 792* DOS/Windows:: 793* SCO UnixWare:: 794* QNX:: 795 796 797File: grub.info, Node: GNU/Hurd, Next: GNU/Linux, Up: OS-specific notes 798 799GNU/Hurd 800-------- 801 802 Since GNU/Hurd is Multiboot-compliant, it is easy to boot it; there 803is nothing special about it. But do not forget that you have to specify 804a root partition to the kernel. 805 806 1. Set GRUB's root device to the same drive as GNU/Hurd's. Probably 807 the command `find /boot/gnumach' or similar can help you (*note 808 find::). 809 810 2. Load the kernel and the module, like this: 811 812 grub> kernel /boot/gnumach root=hd0s1 813 grub> module /boot/serverboot 814 815 3. Run the command `boot' (*note boot::). 816 817 818File: grub.info, Node: GNU/Linux, Next: FreeBSD, Prev: GNU/Hurd, Up: OS-specific notes 819 820GNU/Linux 821--------- 822 823 It is relatively easy to boot GNU/Linux from GRUB, because it 824somewhat resembles to boot a Multiboot-compliant OS. 825 826 1. Set GRUB's root device to the same drive as GNU/Linux's. Probably 827 the command `find /vmlinuz' or similar can help you (*note find::). 828 829 2. Load the kernel: 830 831 grub> kernel /vmlinuz root=/dev/hda1 832 833 If you need to specify some kernel parameters, just append them to 834 the command. For example, to set `vga' to `ext', do this: 835 836 grub> kernel /vmlinuz root=/dev/hda1 vga=ext 837 838 See the documentation in the Linux source tree for complete 839 information on the available options. 840 841 3. If you use an initrd, execute the command `initrd' (*note 842 initrd::) after `kernel': 843 844 grub> initrd /initrd 845 846 4. Finally, run the command `boot' (*note boot::). 847 848 *Caution:* If you use an initrd and specify the `mem=' option to the 849kernel to let it use less than actual memory size, you will also have 850to specify the same memory size to GRUB. To let GRUB know the size, run 851the command `uppermem' _before_ loading the kernel. *Note uppermem::, 852for more information. 853 854 855File: grub.info, Node: FreeBSD, Next: NetBSD, Prev: GNU/Linux, Up: OS-specific notes 856 857FreeBSD 858------- 859 860 GRUB can load the kernel directly, either in ELF or a.out format. But 861this is not recommended, since FreeBSD's bootstrap interface sometimes 862changes heavily, so GRUB can't guarantee to pass kernel parameters 863correctly. 864 865 Thus, we'd recommend loading the very flexible loader `/boot/loader' 866instead. See this example: 867 868 grub> root (hd0,a) 869 grub> kernel /boot/loader 870 grub> boot 871 872 873File: grub.info, Node: NetBSD, Next: OpenBSD, Prev: FreeBSD, Up: OS-specific notes 874 875NetBSD 876------ 877 878 GRUB can load NetBSD a.out and ELF directly, follow these steps: 879 880 1. Set GRUB's root device with `root' (*note root::). 881 882 2. Load the kernel with `kernel' (*note kernel::). You should append 883 the ugly option `--type=netbsd', if you want to load an ELF 884 kernel, like this: 885 886 grub> kernel --type=netbsd /netbsd-elf 887 888 3. Run `boot' (*note boot::). 889 890 For now, however, GRUB doesn't allow you to pass kernel parameters, 891so it may be better to chain-load it instead. For more information, 892please see *Note Chain-loading::. 893 894 895File: grub.info, Node: OpenBSD, Next: DOS/Windows, Prev: NetBSD, Up: OS-specific notes 896 897OpenBSD 898------- 899 900 The booting instruction is exactly the same as for NetBSD (*note 901NetBSD::). 902 903 904File: grub.info, Node: DOS/Windows, Next: SCO UnixWare, Prev: OpenBSD, Up: OS-specific notes 905 906DOS/Windows 907----------- 908 909 GRUB cannot boot DOS or Windows directly, so you must chain-load them 910(*note Chain-loading::). However, their boot loaders have some critical 911deficiencies, so it may not work to just chain-load them. To overcome 912the problems, GRUB provides you with two helper functions. 913 914 If you have installed DOS (or Windows) on a non-first hard disk, you 915have to use the disk swapping technique, because that OS cannot boot 916from any disks but the first one. The workaround used in GRUB is the 917command `map' (*note map::), like this: 918 919 grub> map (hd0) (hd1) 920 grub> map (hd1) (hd0) 921 922 This performs a "virtual" swap between your first and second hard 923drive. 924 925 *Caution:* This is effective only if DOS (or Windows) uses BIOS to 926access the swapped disks. If that OS uses a special driver for the 927disks, this probably won't work. 928 929 Another problem arises if you installed more than one set of 930DOS/Windows onto one disk, because they could be confused if there are 931more than one primary partitions for DOS/Windows. Certainly you should 932avoid doing this, but there is a solution if you do want to do so. Use 933the partition hiding/unhiding technique. 934 935 If GRUB "hide"s a DOS (or Windows) partition (*note hide::), DOS (or 936Windows) will ignore the partition. If GRUB "unhide"s a DOS (or 937Windows) partition (*note unhide::), DOS (or Windows) will detect the 938partition. Thus, if you have installed DOS (or Windows) on the first 939and the second partition of the first hard disk, and you want to boot 940the copy on the first partition, do the following: 941 942 grub> unhide (hd0,0) 943 grub> hide (hd0,1) 944 grub> rootnoverify (hd0,0) 945 grub> chainloader +1 946 grub> makeactive 947 grub> boot 948 949 950File: grub.info, Node: SCO UnixWare, Next: QNX, Prev: DOS/Windows, Up: OS-specific notes 951 952SCO UnixWare 953------------ 954 955 It is known that the signature in the boot loader for SCO UnixWare is 956wrong, so you will have to specify the option `--force' to 957`chainloader' (*note chainloader::), like this: 958 959 grub> rootnoverify (hd1,0) 960 grub> chainloader --force +1 961 grub> makeactive 962 grub> boot 963 964 965File: grub.info, Node: QNX, Prev: SCO UnixWare, Up: OS-specific notes 966 967QNX 968--- 969 970 QNX seems to use a bigger boot loader, so you need to boot it up, 971like this: 972 973 grub> rootnoverify (hd1,1) 974 grub> chainloader +4 975 grub> boot 976 977 978File: grub.info, Node: Making your system robust, Prev: OS-specific notes, Up: Booting 979 980How to make your system robust 981============================== 982 983 When you test a new kernel or a new OS, it is important to make sure 984that your computer can boot even if the new system is unbootable. This 985is crucial especially if you maintain servers or remote systems. To 986accomplish this goal, you need to set up two things: 987 988 1. You must maintain a system which is always bootable. For instance, 989 if you test a new kernel, you need to keep a working kernel in a 990 different place. And, it would sometimes be very nice to even have 991 a complete copy of a working system in a different partition or 992 disk. 993 994 2. You must direct GRUB to boot a working system when the new system 995 fails. This is possible with the "fallback" system in GRUB. 996 997 The former requirement is very specific to each OS, so this 998documentation does not cover that topic. It is better to consult some 999backup tools. 1000 1001 So let's see the GRUB part. There are two possibilities: one of them 1002is quite simple but not very robust, and the other is a bit complex to 1003set up but probably the best solution to make sure that your system can 1004start as long as GRUB itself is bootable. 1005 1006* Menu: 1007 1008* Booting once-only:: 1009* Booting fallback systems:: 1010 1011 1012File: grub.info, Node: Booting once-only, Next: Booting fallback systems, Up: Making your system robust 1013 1014Booting once-only 1015----------------- 1016 1017 You can teach GRUB to boot an entry only at next boot time. Suppose 1018that your have an old kernel `old_kernel' and a new kernel 1019`new_kernel'. You know that `old_kernel' can boot your system 1020correctly, and you want to test `new_kernel'. 1021 1022 To ensure that your system will go back to the old kernel even if the 1023new kernel fails (e.g. it panics), you can specify that GRUB should try 1024the new kernel only once and boot the old kernel after that. 1025 1026 First, modify your configuration file. Here is an example: 1027 1028 default saved # This is important!!! 1029 timeout 10 1030 1031 title the old kernel 1032 root (hd0,0) 1033 kernel /old_kernel 1034 savedefault 1035 1036 title the new kernel 1037 root (hd0,0) 1038 kernel /new_kernel 1039 savedefault 0 # This is important!!! 1040 1041 Note that this configuration file uses `default saved' (*note 1042default::) at the head and `savedefault 0' (*note savedefault::) in the 1043entry for the new kernel. This means that GRUB boots a saved entry by 1044default, and booting the entry for the new kernel saves `0' as the 1045saved entry. 1046 1047 With this configuration file, after all, GRUB always tries to boot 1048the old kernel after it booted the new one, because `0' is the entry of 1049`the old kernel'. 1050 1051 The next step is to tell GRUB to boot the new kernel at next boot 1052time. For this, execute `grub-set-default' (*note Invoking 1053grub-set-default::): 1054 1055 # grub-set-default 1 1056 1057 This command sets the saved entry to `1', that is, to the new kernel. 1058 1059 This method is useful, but still not very robust, because GRUB stops 1060booting, if there is any error in the boot entry, such that the new 1061kernel has an invalid executable format. Thus, it it even better to use 1062the "fallback" mechanism of GRUB. Look at next subsection for this 1063feature. 1064 1065 1066File: grub.info, Node: Booting fallback systems, Prev: Booting once-only, Up: Making your system robust 1067 1068Booting fallback systems 1069------------------------ 1070 1071 GRUB supports a fallback mechanism of booting one or more other 1072entries if a default boot entry fails. You can specify multiple 1073fallback entries if you wish. 1074 1075 Suppose that you have three systems, `A', `B' and `C'. `A' is a 1076system which you want to boot by default. `B' is a backup system which 1077is supposed to boot safely. `C' is another backup system which is used 1078in case where `B' is broken. 1079 1080 Then you may want GRUB to boot the first system which is bootable 1081among `A', `B' and `C'. A configuration file can be written in this way: 1082 1083 default saved # This is important!!! 1084 timeout 10 1085 fallback 1 2 # This is important!!! 1086 1087 title A 1088 root (hd0,0) 1089 kernel /kernel 1090 savedefault fallback # This is important!!! 1091 1092 title B 1093 root (hd1,0) 1094 kernel /kernel 1095 savedefault fallback # This is important!!! 1096 1097 title C 1098 root (hd2,0) 1099 kernel /kernel 1100 savedefault 1101 1102 Note that `default saved' (*note default::), `fallback 1 2' and 1103`savedefault fallback' are used. GRUB will boot a saved entry by 1104default and save a fallback entry as next boot entry with this 1105configuration. 1106 1107 When GRUB tries to boot `A', GRUB saves `1' as next boot entry, 1108because the command `fallback' specifies that `1' is the first fallback 1109entry. The entry `1' is `B', so GRUB will try to boot `B' at next boot 1110time. 1111 1112 Likewise, when GRUB tries to boot `B', GRUB saves `2' as next boot 1113entry, because `fallback' specifies `2' as next fallback entry. This 1114makes sure that GRUB will boot `C' after booting `B'. 1115 1116 It is noteworthy that GRUB uses fallback entries both when GRUB 1117itself fails in booting an entry and when `A' or `B' fails in starting 1118up your system. So this solution ensures that your system is started 1119even if GRUB cannot find your kernel or if your kernel panics. 1120 1121 However, you need to run `grub-set-default' (*note Invoking 1122grub-set-default::) when `A' starts correctly or you fix `A' after it 1123crashes, since GRUB always sets next boot entry to a fallback entry. 1124You should run this command in a startup script such as `rc.local' to 1125boot `A' by default: 1126 1127 # grub-set-default 0 1128 1129 where `0' is the number of the boot entry for the system `A'. 1130 1131 If you want to see what is current default entry, you can look at the 1132file `/boot/grub/default' (or `/grub/default' in some systems). Because 1133this file is plain-text, you can just `cat' this file. But it is 1134strongly recommended *not to modify this file directly*, because GRUB 1135may fail in saving a default entry in this file, if you change this 1136file in an unintended manner. Therefore, you should use 1137`grub-set-default' when you need to change the default entry. 1138 1139 1140File: grub.info, Node: Configuration, Next: Network, Prev: Booting, Up: Top 1141 1142Configuration 1143************* 1144 1145 You've probably noticed that you need to type several commands to 1146boot your OS. There's a solution to that - GRUB provides a menu 1147interface (*note Menu interface::) from which you can select an item 1148(using arrow keys) that will do everything to boot an OS. 1149 1150 To enable the menu, you need a configuration file, `menu.lst' under 1151the boot directory. We'll analyze an example file. 1152 1153 The file first contains some general settings, the menu interface 1154related options. You can put these commands (*note Menu-specific 1155commands::) before any of the items (starting with `title' (*note 1156title::)). 1157 1158 # 1159 # Sample boot menu configuration file 1160 # 1161 1162 As you may have guessed, these lines are comments. Lines starting 1163with a hash character (`#'), and blank lines, are ignored by GRUB. 1164 1165 # By default, boot the first entry. 1166 default 0 1167 1168 The first entry (here, counting starts with number zero, not one!) 1169will be the default choice. 1170 1171 # Boot automatically after 30 secs. 1172 timeout 30 1173 1174 As the comment says, GRUB will boot automatically in 30 seconds, 1175unless interrupted with a keypress. 1176 1177 # Fallback to the second entry. 1178 fallback 1 1179 1180 If, for any reason, the default entry doesn't work, fall back to the 1181second one (this is rarely used, for obvious reasons). 1182 1183 Note that the complete descriptions of these commands, which are menu 1184interface specific, can be found in *Note Menu-specific commands::. 1185Other descriptions can be found in *Note Commands::. 1186 1187 Now, on to the actual OS definitions. You will see that each entry 1188begins with a special command, `title' (*note title::), and the action 1189is described after it. Note that there is no command `boot' (*note 1190boot::) at the end of each item. That is because GRUB automatically 1191executes `boot' if it loads other commands successfully. 1192 1193 The argument for the command `title' is used to display a short 1194title/description of the entry in the menu. Since `title' displays the 1195argument as is, you can write basically anything there. 1196 1197 # For booting GNU/Hurd 1198 title GNU/Hurd 1199 root (hd0,0) 1200 kernel /boot/gnumach.gz root=hd0s1 1201 module /boot/serverboot.gz 1202 1203 This boots GNU/Hurd from the first hard disk. 1204 1205 # For booting GNU/Linux 1206 title GNU/Linux 1207 kernel (hd1,0)/vmlinuz root=/dev/hdb1 1208 1209 This boots GNU/Linux, but from the second hard disk. 1210 1211 # For booting Mach (getting kernel from floppy) 1212 title Utah Mach4 multiboot 1213 root (hd0,2) 1214 pause Insert the diskette now^G!! 1215 kernel (fd0)/boot/kernel root=hd0s3 1216 module (fd0)/boot/bootstrap 1217 1218 This boots Mach with a kernel on a floppy, but the root filesystem at 1219hd0s3. It also contains a `pause' line (*note pause::), which will 1220cause GRUB to display a prompt and delay, before actually executing the 1221rest of the commands and booting. 1222 1223 # For booting FreeBSD 1224 title FreeBSD 1225 root (hd0,2,a) 1226 kernel /boot/loader 1227 1228 This item will boot FreeBSD kernel loaded from the `a' partition of 1229the third PC slice of the first hard disk. 1230 1231 # For booting OS/2 1232 title OS/2 1233 root (hd0,1) 1234 makeactive 1235 # chainload OS/2 bootloader from the first sector 1236 chainloader +1 1237 # This is similar to "chainload", but loads a specific file 1238 #chainloader /boot/chain.os2 1239 1240 This will boot OS/2, using a chain-loader (*note Chain-loading::). 1241 1242 # For booting Windows NT or Windows95 1243 title Windows NT / Windows 95 boot menu 1244 root (hd0,0) 1245 makeactive 1246 chainloader +1 1247 # For loading DOS if Windows NT is installed 1248 # chainload /bootsect.dos 1249 1250 The same as the above, but for Windows. 1251 1252 # For installing GRUB into the hard disk 1253 title Install GRUB into the hard disk 1254 root (hd0,0) 1255 setup (hd0) 1256 1257 This will just (re)install GRUB onto the hard disk. 1258 1259 # Change the colors. 1260 title Change the colors 1261 color light-green/brown blink-red/blue 1262 1263 In the last entry, the command `color' is used (*note color::), to 1264change the menu colors (try it!). This command is somewhat special, 1265because it can be used both in the command-line and in the menu. GRUB 1266has several such commands, see *Note General commands::. 1267 1268 We hope that you now understand how to use the basic features of 1269GRUB. To learn more about GRUB, see the following chapters. 1270 1271 1272File: grub.info, Node: Network, Next: Serial terminal, Prev: Configuration, Up: Top 1273 1274Downloading OS images from a network 1275************************************ 1276 1277 Although GRUB is a disk-based boot loader, it does provide network 1278support. To use the network support, you need to enable at least one 1279network driver in the GRUB build process. For more information please 1280see `netboot/README.netboot' in the source distribution. 1281 1282* Menu: 1283 1284* General usage of network support:: 1285* Diskless:: 1286 1287 1288File: grub.info, Node: General usage of network support, Next: Diskless, Up: Network 1289 1290How to set up your network 1291========================== 1292 1293 GRUB requires a file server and optionally a server that will assign 1294an IP address to the machine on which GRUB is running. For the former, 1295only TFTP is supported at the moment. The latter is either BOOTP, DHCP 1296or a RARP server(1) (*note General usage of network 1297support-Footnote-1::). It is not necessary to run both the servers on 1298one computer. How to configure these servers is beyond the scope of this 1299document, so please refer to the manuals specific to those 1300protocols/servers. 1301 1302 If you decided to use a server to assign an IP address, set up the 1303server and run `bootp' (*note bootp::), `dhcp' (*note dhcp::) or `rarp' 1304(*note rarp::) for BOOTP, DHCP or RARP, respectively. Each command will 1305show an assigned IP address, a netmask, an IP address for your TFTP 1306server and a gateway. If any of the addresses is wrong or it causes an 1307error, probably the configuration of your servers isn't set up properly. 1308 1309 Otherwise, run `ifconfig', like this: 1310 1311 grub> ifconfig --address=192.168.110.23 --server=192.168.110.14 1312 1313 You can also use `ifconfig' in conjuction with `bootp', `dhcp' or 1314`rarp' (e.g. to reassign the server address manually). *Note 1315ifconfig::, for more details. 1316 1317 Finally, download your OS images from your network. The network can 1318be accessed using the network drive `(nd)'. Everything else is very 1319similar to the normal instructions (*note Booting::). 1320 1321 Here is an example: 1322 1323 grub> bootp 1324 Probing... [NE*000] 1325 NE2000 base ... 1326 Address: 192.168.110.23 Netmask: 255.255.255.0 1327 Server: 192.168.110.14 Gateway: 192.168.110.1 1328 1329 grub> root (nd) 1330 grub> kernel /tftproot/gnumach.gz root=sd0s1 1331 grub> module /tftproot/serverboot.gz 1332 grub> boot 1333 1334 1335File: grub.info, Node: General usage of network support-Footnotes, Up: General usage of network support 1336 1337 (1) RARP is not advised, since it cannot serve much information 1338 1339