1This is ../../docs/grub.info, produced by makeinfo version 4.8 from 2../../docs/grub.texi. 3 4INFO-DIR-SECTION Kernel 5START-INFO-DIR-ENTRY 6* GRUB: (grub). The GRand Unified Bootloader 7* grub-install: (grub)Invoking grub-install. Install GRUB on your drive 8* grub-md5-crypt: (grub)Invoking grub-md5-crypt. Encrypt a password 9 in MD5 format 10* grub-terminfo: (grub)Invoking grub-terminfo. Generate a terminfo 11 command from a 12 terminfo name 13* grub-set-default: (grub)Invoking grub-set-default. Set a default boot 14 entry 15* mbchk: (grub)Invoking mbchk. Check for the format of a Multiboot kernel 16END-INFO-DIR-ENTRY 17 18 Copyright (C) 1999,2000,2001,2002,2004 Free Software Foundation, Inc. 19 20 Permission is granted to make and distribute verbatim copies of this 21manual provided the copyright notice and this permission notice are 22preserved on all copies. 23 24 Permission is granted to copy and distribute modified versions of 25this manual under the conditions for verbatim copying, provided also 26that the entire resulting derived work is distributed under the terms 27of a permission notice identical to this one. 28 29 Permission is granted to copy and distribute translations of this 30manual into another language, under the above conditions for modified 31versions. 32 33 34File: grub.info, Node: Top, Next: Introduction, Up: (dir) 35 36GRUB manual 37*********** 38 39This is the documentation of GNU GRUB, the GRand Unified Bootloader, a 40flexible and powerful boot loader program for PCs. 41 42 This edition documents version 0.97. 43 44* Menu: 45 46* Introduction:: Capturing the spirit of GRUB 47* Naming convention:: Names of your drives in GRUB 48* Installation:: Installing GRUB on your drive 49* Booting:: How to boot different operating systems 50* Configuration:: Writing your own configuration file 51* Network:: Downloading OS images from a network 52* Serial terminal:: Using GRUB via a serial line 53* Preset Menu:: Embedding a configuration file into GRUB 54* Security:: Improving the security 55* Images:: GRUB image files 56* Filesystem:: Filesystem syntax and semantics 57* Interface:: The menu and the command-line 58* Commands:: The list of available builtin commands 59* Troubleshooting:: Error messages produced by GRUB 60* Invoking the grub shell:: How to use the grub shell 61* Invoking grub-install:: How to use the GRUB installer 62* Invoking grub-md5-crypt:: How to generate a cryptic password 63* Invoking grub-terminfo:: How to generate a terminfo command 64* Invoking grub-set-default:: How to set a default boot entry 65* Invoking mbchk:: How to use the Multiboot checker 66* Obtaining and Building GRUB:: How to obtain and build GRUB 67* Reporting bugs:: Where you should send a bug report 68* Future:: Some future plans on GRUB 69* Internals:: Hacking GRUB 70* Index:: 71 72 73File: grub.info, Node: Introduction, Next: Naming convention, Prev: Top, Up: Top 74 751 Introduction to GRUB 76********************** 77 78* Menu: 79 80* Overview:: What exactly GRUB is and how to use it 81* History:: From maggot to house fly 82* Features:: GRUB features 83* Role of a boot loader:: The role of a boot loader 84 85 86File: grub.info, Node: Overview, Next: History, Up: Introduction 87 881.1 Overview 89============ 90 91Briefly, a "boot loader" is the first software program that runs when a 92computer starts. It is responsible for loading and transferring 93control to an operating system "kernel" software (such as Linux or GNU 94Mach). The kernel, in turn, initializes the rest of the operating 95system (e.g. a GNU system). 96 97 GNU GRUB is a very powerful boot loader, which can load a wide 98variety of free operating systems, as well as proprietary operating 99systems with chain-loading(1) (*note Overview-Footnote-1::). GRUB is 100designed to address the complexity of booting a personal computer; both 101the program and this manual are tightly bound to that computer platform, 102although porting to other platforms may be addressed in the future. 103 104 One of the important features in GRUB is flexibility; GRUB 105understands filesystems and kernel executable formats, so you can load 106an arbitrary operating system the way you like, without recording the 107physical position of your kernel on the disk. Thus you can load the 108kernel just by specifying its file name and the drive and partition 109where the kernel resides. 110 111 When booting with GRUB, you can use either a command-line interface 112(*note Command-line interface::), or a menu interface (*note Menu 113interface::). Using the command-line interface, you type the drive 114specification and file name of the kernel manually. In the menu 115interface, you just select an OS using the arrow keys. The menu is 116based on a configuration file which you prepare beforehand (*note 117Configuration::). While in the menu, you can switch to the command-line 118mode, and vice-versa. You can even edit menu entries before using them. 119 120 In the following chapters, you will learn how to specify a drive, a 121partition, and a file name (*note Naming convention::) to GRUB, how to 122install GRUB on your drive (*note Installation::), and how to boot your 123OSes (*note Booting::), step by step. 124 125 Besides the GRUB boot loader itself, there is a "grub shell" `grub' 126(*note Invoking the grub shell::) which can be run when you are in your 127operating system. It emulates the boot loader and can be used for 128installing the boot loader. 129 130 131File: grub.info, Node: Overview-Footnotes, Up: Overview 132 133 (1) "chain-load" is the mechanism for loading unsupported operating 134systems by loading another boot loader. It is typically used for 135loading DOS or Windows. 136 137 138File: grub.info, Node: History, Next: Features, Prev: Overview, Up: Introduction 139 1401.2 History of GRUB 141=================== 142 143GRUB originated in 1995 when Erich Boleyn was trying to boot the GNU 144Hurd with the University of Utah's Mach 4 microkernel (now known as GNU 145Mach). Erich and Brian Ford designed the Multiboot Specification 146(*note Multiboot Specification: (multiboot)Top.), because they were 147determined not to add to the large number of mutually-incompatible PC 148boot methods. 149 150 Erich then began modifying the FreeBSD boot loader so that it would 151understand Multiboot. He soon realized that it would be a lot easier to 152write his own boot loader from scratch than to keep working on the 153FreeBSD boot loader, and so GRUB was born. 154 155 Erich added many features to GRUB, but other priorities prevented him 156from keeping up with the demands of its quickly-expanding user base. In 1571999, Gordon Matzigkeit and Yoshinori K. Okuji adopted GRUB as an 158official GNU package, and opened its development by making the latest 159sources available via anonymous CVS. *Note Obtaining and Building 160GRUB::, for more information. 161 162 163File: grub.info, Node: Features, Next: Role of a boot loader, Prev: History, Up: Introduction 164 1651.3 GRUB features 166================= 167 168The primary requirement for GRUB is that it be compliant with the 169"Multiboot Specification", which is described in *Note Multiboot 170Specification: (multiboot)Top. 171 172 The other goals, listed in approximate order of importance, are: 173 174 * Basic functions must be straightforward for end-users. 175 176 * Rich functionality to support kernel experts and designers. 177 178 * Backward compatibility for booting FreeBSD, NetBSD, OpenBSD, and 179 Linux. Proprietary kernels (such as DOS, Windows NT, and OS/2) are 180 supported via a chain-loading function. 181 182 Except for specific compatibility modes (chain-loading and the Linux 183"piggyback" format), all kernels will be started in much the same state 184as in the Multiboot Specification. Only kernels loaded at 1 megabyte or 185above are presently supported. Any attempt to load below that boundary 186will simply result in immediate failure and an error message reporting 187the problem. 188 189 In addition to the requirements above, GRUB has the following 190features (note that the Multiboot Specification doesn't require all the 191features that GRUB supports): 192 193Recognize multiple executable formats 194 Support many of the "a.out" variants plus "ELF". Symbol tables are 195 also loaded. 196 197Support non-Multiboot kernels 198 Support many of the various free 32-bit kernels that lack Multiboot 199 compliance (primarily FreeBSD, NetBSD, OpenBSD, and Linux). 200 Chain-loading of other boot loaders is also supported. 201 202Load multiples modules 203 Fully support the Multiboot feature of loading multiple modules. 204 205Load a configuration file 206 Support a human-readable text configuration file with preset boot 207 commands. You can also load another configuration file dynamically 208 and embed a preset configuration file in a GRUB image file. The 209 list of commands (*note Commands::) are a superset of those 210 supported on the command-line. An example configuration file is 211 provided in *Note Configuration::. 212 213Provide a menu interface 214 A menu interface listing preset boot commands, with a programmable 215 timeout, is available. There is no fixed limit on the number of 216 boot entries, and the current implementation has space for several 217 hundred. 218 219Have a flexible command-line interface 220 A fairly flexible command-line interface, accessible from the menu, 221 is available to edit any preset commands, or write a new boot 222 command set from scratch. If no configuration file is present, 223 GRUB drops to the command-line. 224 225 The list of commands (*note Commands::) are a subset of those 226 supported for configuration files. Editing commands closely 227 resembles the Bash command-line (*note Bash: (features)Command 228 Line Editing.), with <TAB>-completion of commands, devices, 229 partitions, and files in a directory depending on context. 230 231Support multiple filesystem types 232 Support multiple filesystem types transparently, plus a useful 233 explicit blocklist notation. The currently supported filesystem 234 types are "BSD FFS", "DOS FAT16 and FAT32", "Minix fs", "Linux 235 ext2fs", "ReiserFS", "JFS", "XFS", and "VSTa fs". *Note 236 Filesystem::, for more information. 237 238Support automatic decompression 239 Can decompress files which were compressed by `gzip'. This 240 function is both automatic and transparent to the user (i.e. all 241 functions operate upon the uncompressed contents of the specified 242 files). This greatly reduces a file size and loading time, a 243 particularly great benefit for floppies.(1) (*note 244 Features-Footnote-1::) 245 246 It is conceivable that some kernel modules should be loaded in a 247 compressed state, so a different module-loading command can be 248 specified to avoid uncompressing the modules. 249 250Access data on any installed device 251 Support reading data from any or all floppies or hard disk(s) 252 recognized by the BIOS, independent of the setting of the root 253 device. 254 255Be independent of drive geometry translations 256 Unlike many other boot loaders, GRUB makes the particular drive 257 translation irrelevant. A drive installed and running with one 258 translation may be converted to another translation without any 259 adverse effects or changes in GRUB's configuration. 260 261Detect all installed RAM 262 GRUB can generally find all the installed RAM on a PC-compatible 263 machine. It uses an advanced BIOS query technique for finding all 264 memory regions. As described on the Multiboot Specification (*note 265 Multiboot Specification: (multiboot)Top.), not all kernels make 266 use of this information, but GRUB provides it for those who do. 267 268Support Logical Block Address mode 269 In traditional disk calls (called "CHS mode"), there is a geometry 270 translation problem, that is, the BIOS cannot access over 1024 271 cylinders, so the accessible space is limited to at least 508 MB 272 and to at most 8GB. GRUB can't universally solve this problem, as 273 there is no standard interface used in all machines. However, 274 several newer machines have the new interface, Logical Block 275 Address ("LBA") mode. GRUB automatically detects if LBA mode is 276 available and uses it if available. In LBA mode, GRUB can access 277 the entire disk. 278 279Support network booting 280 GRUB is basically a disk-based boot loader but also has network 281 support. You can load OS images from a network by using the "TFTP" 282 protocol. 283 284Support remote terminals 285 To support computers with no console, GRUB provides remote terminal 286 support, so that you can control GRUB from a remote host. Only 287 serial terminal support is implemented at the moment. 288 289 290File: grub.info, Node: Features-Footnotes, Up: Features 291 292 (1) There are a few pathological cases where loading a very badly 293organized ELF kernel might take longer, but in practice this never 294happen. 295 296 297File: grub.info, Node: Role of a boot loader, Prev: Features, Up: Introduction 298 2991.4 The role of a boot loader 300============================= 301 302The following is a quotation from Gordon Matzigkeit, a GRUB fanatic: 303 304 Some people like to acknowledge both the operating system and 305 kernel when they talk about their computers, so they might say 306 they use "GNU/Linux" or "GNU/Hurd". Other people seem to think 307 that the kernel is the most important part of the system, so they 308 like to call their GNU operating systems "Linux systems." 309 310 I, personally, believe that this is a grave injustice, because the 311 _boot loader_ is the most important software of all. I used to 312 refer to the above systems as either "LILO"(1) (*note Role of a 313 boot loader-Footnote-1::) or "GRUB" systems. 314 315 Unfortunately, nobody ever understood what I was talking about; 316 now I just use the word "GNU" as a pseudonym for GRUB. 317 318 So, if you ever hear people talking about their alleged "GNU" 319 systems, remember that they are actually paying homage to the best 320 boot loader around... GRUB! 321 322 We, the GRUB maintainers, do not (usually) encourage Gordon's level 323of fanaticism, but it helps to remember that boot loaders deserve 324recognition. We hope that you enjoy using GNU GRUB as much as we did 325writing it. 326 327 328File: grub.info, Node: Role of a boot loader-Footnotes, Up: Role of a boot loader 329 330 (1) The LInux LOader, a boot loader that everybody uses, but nobody 331likes. 332 333 334File: grub.info, Node: Naming convention, Next: Installation, Prev: Introduction, Up: Top 335 3362 Naming convention 337******************* 338 339The device syntax used in GRUB is a wee bit different from what you may 340have seen before in your operating system(s), and you need to know it so 341that you can specify a drive/partition. 342 343 Look at the following examples and explanations: 344 345 (fd0) 346 347 First of all, GRUB requires that the device name be enclosed with 348`(' and `)'. The `fd' part means that it is a floppy disk. The number 349`0' is the drive number, which is counted from _zero_. This expression 350means that GRUB will use the whole floppy disk. 351 352 (hd0,1) 353 354 Here, `hd' means it is a hard disk drive. The first integer `0' 355indicates the drive number, that is, the first hard disk, while the 356second integer, `1', indicates the partition number (or the PC slice 357number in the BSD terminology). Once again, please note that the 358partition numbers are counted from _zero_, not from one. This 359expression means the second partition of the first hard disk drive. In 360this case, GRUB uses one partition of the disk, instead of the whole 361disk. 362 363 (hd0,4) 364 365 This specifies the first "extended partition" of the first hard disk 366drive. Note that the partition numbers for extended partitions are 367counted from `4', regardless of the actual number of primary partitions 368on your hard disk. 369 370 (hd1,a) 371 372 This means the BSD `a' partition of the second hard disk. If you 373need to specify which PC slice number should be used, use something 374like this: `(hd1,0,a)'. If the PC slice number is omitted, GRUB 375searches for the first PC slice which has a BSD `a' partition. 376 377 Of course, to actually access the disks or partitions with GRUB, you 378need to use the device specification in a command, like `root (fd0)' or 379`unhide (hd0,2)'. To help you find out which number specifies a 380partition you want, the GRUB command-line (*note Command-line 381interface::) options have argument completion. This means that, for 382example, you only need to type 383 384 root ( 385 386 followed by a <TAB>, and GRUB will display the list of drives, 387partitions, or file names. So it should be quite easy to determine the 388name of your target partition, even with minimal knowledge of the 389syntax. 390 391 Note that GRUB does _not_ distinguish IDE from SCSI - it simply 392counts the drive numbers from zero, regardless of their type. Normally, 393any IDE drive number is less than any SCSI drive number, although that 394is not true if you change the boot sequence by swapping IDE and SCSI 395drives in your BIOS. 396 397 Now the question is, how to specify a file? Again, consider an 398example: 399 400 (hd0,0)/vmlinuz 401 402 This specifies the file named `vmlinuz', found on the first 403partition of the first hard disk drive. Note that the argument 404completion works with file names, too. 405 406 That was easy, admit it. Now read the next chapter, to find out how 407to actually install GRUB on your drive. 408 409 410File: grub.info, Node: Installation, Next: Booting, Prev: Naming convention, Up: Top 411 4123 Installation 413************** 414 415In order to install GRUB as your boot loader, you need to first install 416the GRUB system and utilities under your UNIX-like operating system 417(*note Obtaining and Building GRUB::). You can do this either from the 418source tarball, or as a package for your OS. 419 420 After you have done that, you need to install the boot loader on a 421drive (floppy or hard disk). There are two ways of doing that - either 422using the utility `grub-install' (*note Invoking grub-install::) on a 423UNIX-like OS, or by running GRUB itself from a floppy. These are quite 424similar, however the utility might probe a wrong BIOS drive, so you 425should be careful. 426 427 Also, if you install GRUB on a UNIX-like OS, please make sure that 428you have an emergency boot disk ready, so that you can rescue your 429computer if, by any chance, your hard drive becomes unusable 430(unbootable). 431 432 GRUB comes with boot images, which are normally put in the directory 433`/usr/lib/grub/i386-pc'. If you do not use grub-install, then you need 434to copy the files `stage1', `stage2', and `*stage1_5' to the directory 435`/boot/grub', and run the `grub-set-default' (*note Invoking 436grub-set-default::) if you intend to use `default saved' (*note 437default::) in your configuration file. Hereafter, the directory where 438GRUB images are initially placed (normally `/usr/lib/grub/i386-pc') 439will be called the "image directory", and the directory where the boot 440loader needs to find them (usually `/boot/grub') will be called the 441"boot directory". 442 443* Menu: 444 445* Creating a GRUB boot floppy:: 446* Installing GRUB natively:: 447* Installing GRUB using grub-install:: 448* Making a GRUB bootable CD-ROM:: 449 450 451File: grub.info, Node: Creating a GRUB boot floppy, Next: Installing GRUB natively, Up: Installation 452 4533.1 Creating a GRUB boot floppy 454=============================== 455 456To create a GRUB boot floppy, you need to take the files `stage1' and 457`stage2' from the image directory, and write them to the first and the 458second block of the floppy disk, respectively. 459 460 *Caution:* This procedure will destroy any data currently stored on 461the floppy. 462 463 On a UNIX-like operating system, that is done with the following 464commands: 465 466 # cd /usr/lib/grub/i386-pc 467 # dd if=stage1 of=/dev/fd0 bs=512 count=1 468 1+0 records in 469 1+0 records out 470 # dd if=stage2 of=/dev/fd0 bs=512 seek=1 471 153+1 records in 472 153+1 records out 473 # 474 475 The device file name may be different. Consult the manual for your 476OS. 477 478 479File: grub.info, Node: Installing GRUB natively, Next: Installing GRUB using grub-install, Prev: Creating a GRUB boot floppy, Up: Installation 480 4813.2 Installing GRUB natively 482============================ 483 484*Caution:* Installing GRUB's stage1 in this manner will erase the 485normal boot-sector used by an OS. 486 487 GRUB can currently boot GNU Mach, Linux, FreeBSD, NetBSD, and OpenBSD 488directly, so using it on a boot sector (the first sector of a 489partition) should be okay. But generally, it would be a good idea to 490back up the first sector of the partition on which you are installing 491GRUB's stage1. This isn't as important if you are installing GRUB on 492the first sector of a hard disk, since it's easy to reinitialize it 493(e.g. by running `FDISK /MBR' from DOS). 494 495 If you decide to install GRUB in the native environment, which is 496definitely desirable, you'll need to create a GRUB boot disk, and 497reboot your computer with it. Otherwise, see *Note Installing GRUB 498using grub-install::. 499 500 Once started, GRUB will show the command-line interface (*note 501Command-line interface::). First, set the GRUB's "root device"(1) 502(*note Installing GRUB natively-Footnote-1::) to the partition 503containing the boot directory, like this: 504 505 grub> root (hd0,0) 506 507 If you are not sure which partition actually holds this directory, 508use the command `find' (*note find::), like this: 509 510 grub> find /boot/grub/stage1 511 512 This will search for the file name `/boot/grub/stage1' and show the 513devices which contain the file. 514 515 Once you've set the root device correctly, run the command `setup' 516(*note setup::): 517 518 grub> setup (hd0) 519 520 This command will install the GRUB boot loader on the Master Boot 521Record (MBR) of the first drive. If you want to put GRUB into the boot 522sector of a partition instead of putting it in the MBR, specify the 523partition into which you want to install GRUB: 524 525 grub> setup (hd0,0) 526 527 If you install GRUB into a partition or a drive other than the first 528one, you must chain-load GRUB from another boot loader. Refer to the 529manual for the boot loader to know how to chain-load GRUB. 530 531 After using the setup command, you will boot into GRUB without the 532GRUB floppy. See the chapter *Note Booting:: to find out how to boot 533your operating systems from GRUB. 534 535 536File: grub.info, Node: Installing GRUB natively-Footnotes, Up: Installing GRUB natively 537 538 (1) Note that GRUB's root device doesn't necessarily mean your OS's 539root partition; if you need to specify a root partition for your OS, 540add the argument into the command `kernel'. 541 542 543File: grub.info, Node: Installing GRUB using grub-install, Next: Making a GRUB bootable CD-ROM, Prev: Installing GRUB natively, Up: Installation 544 5453.3 Installing GRUB using grub-install 546====================================== 547 548*Caution:* This procedure is definitely less safe, because there are 549several ways in which your computer can become unbootable. For example, 550most operating systems don't tell GRUB how to map BIOS drives to OS 551devices correctly--GRUB merely "guesses" the mapping. This will succeed 552in most cases, but not always. Therefore, GRUB provides you with a map 553file called the "device map", which you must fix if it is wrong. *Note 554Device map::, for more details. 555 556 If you still do want to install GRUB under a UNIX-like OS (such as 557GNU), invoke the program `grub-install' (*note Invoking grub-install::) 558as the superuser ("root"). 559 560 The usage is basically very simple. You only need to specify one 561argument to the program, namely, where to install the boot loader. The 562argument can be either a device file (like `/dev/hda') or a partition 563specified in GRUB's notation. For example, under Linux the following 564will install GRUB into the MBR of the first IDE disk: 565 566 # grub-install /dev/hda 567 568 Likewise, under GNU/Hurd, this has the same effect: 569 570 # grub-install /dev/hd0 571 572 If it is the first BIOS drive, this is the same as well: 573 574 # grub-install '(hd0)' 575 576 Or you can omit the parentheses: 577 578 # grub-install hd0 579 580 But all the above examples assume that GRUB should use images under 581the root directory. If you want GRUB to use images under a directory 582other than the root directory, you need to specify the option 583`--root-directory'. The typical usage is that you create a GRUB boot 584floppy with a filesystem. Here is an example: 585 586 # mke2fs /dev/fd0 587 # mount -t ext2 /dev/fd0 /mnt 588 # grub-install --root-directory=/mnt fd0 589 # umount /mnt 590 591 Another example is when you have a separate boot partition which is 592mounted at `/boot'. Since GRUB is a boot loader, it doesn't know 593anything about mountpoints at all. Thus, you need to run `grub-install' 594like this: 595 596 # grub-install --root-directory=/boot /dev/hda 597 598 By the way, as noted above, it is quite difficult to guess BIOS 599drives correctly under a UNIX-like OS. Thus, `grub-install' will prompt 600you to check if it could really guess the correct mappings, after the 601installation. The format is defined in *Note Device map::. Please be 602quite careful. If the output is wrong, it is unlikely that your 603computer will be able to boot with no problem. 604 605 Note that `grub-install' is actually just a shell script and the 606real task is done by the grub shell `grub' (*note Invoking the grub 607shell::). Therefore, you may run `grub' directly to install GRUB, 608without using `grub-install'. Don't do that, however, unless you are 609very familiar with the internals of GRUB. Installing a boot loader on a 610running OS may be extremely dangerous. 611 612 613File: grub.info, Node: Making a GRUB bootable CD-ROM, Prev: Installing GRUB using grub-install, Up: Installation 614 6153.4 Making a GRUB bootable CD-ROM 616================================= 617 618GRUB supports the "no emulation mode" in the El Torito specification(1) 619(*note Making a GRUB bootable CD-ROM-Footnote-1::). This means that you 620can use the whole CD-ROM from GRUB and you don't have to make a floppy 621or hard disk image file, which can cause compatibility 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 6714 Booting 672********* 673 674GRUB can load Multiboot-compliant kernels in a consistent way, but for 675some 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 6864.1 How to boot operating systems 687================================= 688 689GRUB 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 7064.1.1 How to boot an OS directly with GRUB 707------------------------------------------ 708 709Multiboot (*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 7384.1.2 Load another boot loader to boot unsupported operating systems 739-------------------------------------------------------------------- 740 741If you want to boot an unsupported operating system (e.g. Windows 95), 742chain-load a boot loader for the operating system. Normally, the boot 743loader is embedded in the "boot sector" of the partition on which the 744operating 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 7804.2 Some caveats on OS-specific issues 781====================================== 782 783Here, 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 7994.2.1 GNU/Hurd 800-------------- 801 802Since GNU/Hurd is Multiboot-compliant, it is easy to boot it; there is 803nothing special about it. But do not forget that you have to specify a 804root 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 8204.2.2 GNU/Linux 821--------------- 822 823It is relatively easy to boot GNU/Linux from GRUB, because it somewhat 824resembles 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 8574.2.3 FreeBSD 858------------- 859 860GRUB 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 8754.2.4 NetBSD 876------------ 877 878GRUB 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 8974.2.5 OpenBSD 898------------- 899 900The 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 9064.2.6 DOS/Windows 907----------------- 908 909GRUB 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 9524.2.7 SCO UnixWare 953------------------ 954 955It 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 9674.2.8 QNX 968--------- 969 970QNX seems to use a bigger boot loader, so you need to boot it up, like 971this: 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 9804.3 How to make your system robust 981================================== 982 983When 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 10144.3.1 Booting once-only 1015----------------------- 1016 1017You 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 10684.3.2 Booting fallback systems 1069------------------------------ 1070 1071GRUB supports a fallback mechanism of booting one or more other entries 1072if a default boot entry fails. You can specify multiple fallback 1073entries 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 11425 Configuration 1143*************** 1144 1145You've probably noticed that you need to type several commands to boot 1146your OS. There's a solution to that - GRUB provides a menu interface 1147(*note Menu interface::) from which you can select an item (using arrow 1148keys) 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 12746 Downloading OS images from a network 1275************************************** 1276 1277Although 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 12906.1 How to set up your network 1291============================== 1292 1293GRUB requires a file server and optionally a server that will assign an 1294IP address to the machine on which GRUB is running. For the former, only 1295TFTP is supported at the moment. The latter is either BOOTP, DHCP or a 1296RARP server(1) (*note General usage of network support-Footnote-1::). 1297It is not necessary to run both the servers on one computer. How to 1298configure these servers is beyond the scope of this document, so please 1299refer to the manuals specific to those protocols/servers. 1300 1301 If you decided to use a server to assign an IP address, set up the 1302server and run `bootp' (*note bootp::), `dhcp' (*note dhcp::) or `rarp' 1303(*note rarp::) for BOOTP, DHCP or RARP, respectively. Each command will 1304show an assigned IP address, a netmask, an IP address for your TFTP 1305server and a gateway. If any of the addresses is wrong or it causes an 1306error, probably the configuration of your servers isn't set up properly. 1307 1308 Otherwise, run `ifconfig', like this: 1309 1310 grub> ifconfig --address=192.168.110.23 --server=192.168.110.14 1311 1312 You can also use `ifconfig' in conjuction with `bootp', `dhcp' or 1313`rarp' (e.g. to reassign the server address manually). *Note 1314ifconfig::, for more details. 1315 1316 Finally, download your OS images from your network. The network can 1317be accessed using the network drive `(nd)'. Everything else is very 1318similar to the normal instructions (*note Booting::). 1319 1320 Here is an example: 1321 1322 grub> bootp 1323 Probing... [NE*000] 1324 NE2000 base ... 1325 Address: 192.168.110.23 Netmask: 255.255.255.0 1326 Server: 192.168.110.14 Gateway: 192.168.110.1 1327 1328 grub> root (nd) 1329 grub> kernel /tftproot/gnumach.gz root=sd0s1 1330 grub> module /tftproot/serverboot.gz 1331 grub> boot 1332 1333 1334File: grub.info, Node: General usage of network support-Footnotes, Up: General usage of network support 1335 1336 (1) RARP is not advised, since it cannot serve much information 1337 1338 1339File: grub.info, Node: Diskless, Prev: General usage of network support, Up: Network 1340 13416.2 Booting from a network 1342========================== 1343 1344It is sometimes very useful to boot from a network, especially when you 1345use a machine which has no local disk. In this case, you need to obtain 1346a kind of Net Boot ROM, such as a PXE ROM or a free software package 1347like Etherboot. Such a Boot ROM first boots the machine, sets up the 1348network card installed into the machine, and downloads a second stage 1349boot image from the network. Then, the second image will try to boot an 1350operating system actually from the network. 1351 1352 GRUB provides two second stage images, `nbgrub' and `pxegrub' (*note 1353Images::). These images are the same as the normal Stage 2, except that 1354they set up a network automatically, and try to load a configuration 1355file from the network, if specified. The usage is very simple: If the 1356machine has a PXE ROM, use `pxegrub'. If the machine has an NBI loader 1357such as Etherboot, use `nbgrub'. There is no difference between them 1358except their formats. Since the way to load a second stage image you 1359want to use should be described in the manual on your Net Boot ROM, 1360please refer to the manual, for more information. 1361 1362 However, there is one thing specific to GRUB. Namely, how to specify 1363a configuration file in a BOOTP/DHCP server. For now, GRUB uses the tag 1364`150', to get the name of a configuration file. The following is an 1365example with a BOOTP configuration: 1366 1367 .allhost:hd=/tmp:bf=null:\ 1368 :ds=145.71.35.1 145.71.32.1:\ 1369 :sm=255.255.254.0:\ 1370 :gw=145.71.35.1:\ 1371 :sa=145.71.35.5: 1372 1373 foo:ht=1:ha=63655d0334a7:ip=145.71.35.127:\ 1374 :bf=/nbgrub:\ 1375 :tc=.allhost:\ 1376 :T150="(nd)/tftpboot/menu.lst.foo": 1377 1378 Note that you should specify the drive name `(nd)' in the name of 1379the configuration file. This is because you might change the root drive 1380before downloading the configuration from the TFTP server when the 1381preset menu feature is used (*note Preset Menu::). 1382 1383 See the manual of your BOOTP/DHCP server for more information. The 1384exact syntax should differ a little from the example. 1385 1386 1387File: grub.info, Node: Serial terminal, Next: Preset Menu, Prev: Network, Up: Top 1388 13897 Using GRUB via a serial line 1390****************************** 1391 1392This chapter describes how to use the serial terminal support in GRUB. 1393 1394 If you have many computers or computers with no display/keyboard, it 1395could be very useful to control the computers through serial 1396communications. To connect one computer with another via a serial line, 1397you need to prepare a null-modem (cross) serial cable, and you may need 1398to have multiport serial boards, if your computer doesn't have extra 1399serial ports. In addition, a terminal emulator is also required, such as 1400minicom. Refer to a manual of your operating system, for more 1401information. 1402 1403 As for GRUB, the instruction to set up a serial terminal is quite 1404simple. First of all, make sure that you haven't specified the option 1405`--disable-serial' to the configure script when you built your GRUB 1406images. If you get them in binary form, probably they have serial 1407terminal support already. 1408 1409 Then, initialize your serial terminal after GRUB starts up. Here is 1410an example: 1411 1412 grub> serial --unit=0 --speed=9600 1413 grub> terminal serial 1414 1415 The command `serial' initializes the serial unit 0 with the speed 14169600bps. The serial unit 0 is usually called `COM1', so, if you want to 1417use COM2, you must specify `--unit=1' instead. This command accepts 1418many other options, so please refer to *Note serial::, for more details. 1419 1420 The command `terminal' (*note terminal::) chooses which type of 1421terminal you want to use. In the case above, the terminal will be a 1422serial terminal, but you can also pass `console' to the command, as 1423`terminal serial console'. In this case, a terminal in which you press 1424any key will be selected as a GRUB terminal. 1425 1426 However, note that GRUB assumes that your terminal emulator is 1427compatible with VT100 by default. This is true for most terminal 1428emulators nowadays, but you should pass the option `--dumb' to the 1429command if your terminal emulator is not VT100-compatible or implements 1430few VT100 escape sequences. If you specify this option then GRUB 1431provides you with an alternative menu interface, because the normal 1432menu requires several fancy features of your terminal. 1433 1434 1435File: grub.info, Node: Preset Menu, Next: Security, Prev: Serial terminal, Up: Top 1436 14378 Embedding a configuration file into GRUB 1438****************************************** 1439 1440GRUB supports a "preset menu" which is to be always loaded before 1441starting. The preset menu feature is useful, for example, when your 1442computer has no console but a serial cable. In this case, it is 1443critical to set up the serial terminal as soon as possible, since you 1444cannot see any message until the serial terminal begins to work. So it 1445is good to run the commands `serial' (*note serial::) and `terminal' 1446(*note terminal::) before anything else at the start-up time. 1447 1448 How the preset menu works is slightly complicated: 1449 1450 1. GRUB checks if the preset menu feature is used, and loads the 1451 preset menu, if available. This includes running commands and 1452 reading boot entries, like an ordinary configuration file. 1453 1454 2. GRUB checks if the configuration file is available. Note that this 1455 check is performed *regardless of the existence of the preset 1456 menu*. The configuration file is loaded even if the preset menu was 1457 loaded. 1458 1459 3. If the preset menu includes any boot entries, they are cleared when 1460 the configuration file is loaded. It doesn't matter whether the 1461 configuration file has any entries or no entry. The boot entries 1462 in the preset menu are used only when GRUB fails in loading the 1463 configuration file. 1464 1465 To enable the preset menu feature, you must rebuild GRUB specifying a 1466file to the configure script with the option `--enable-preset-menu'. 1467The file has the same semantics as normal configuration files (*note 1468Configuration::). 1469 1470 Another point you should take care is that the diskless support 1471(*note Diskless::) diverts the preset menu. Diskless images embed a 1472preset menu to execute the command `bootp' (*note bootp::) 1473automatically, unless you specify your own preset menu to the configure 1474script. This means that you must put commands to initialize a network in 1475the preset menu yourself, because diskless images don't set it up 1476implicitly, when you use the preset menu explicitly. 1477 1478 Therefore, a typical preset menu used with diskless support would be 1479like this: 1480 1481 # Set up the serial terminal, first of all. 1482 serial --unit=0 --speed=19200 1483 terminal --timeout=0 serial 1484 1485 # Initialize the network. 1486 dhcp 1487 1488 1489File: grub.info, Node: Security, Next: Images, Prev: Preset Menu, Up: Top 1490 14919 Protecting your computer from cracking 1492**************************************** 1493 1494You may be interested in how to prevent ordinary users from doing 1495whatever they like, if you share your computer with other people. So 1496this chapter describes how to improve the security of GRUB. 1497 1498 One thing which could be a security hole is that the user can do too 1499many things with GRUB, because GRUB allows one to modify its 1500configuration and run arbitrary commands at run-time. For example, the 1501user can even read `/etc/passwd' in the command-line interface by the 1502command `cat' (*note cat::). So it is necessary to disable all the 1503interactive operations. 1504 1505 Thus, GRUB provides a "password" feature, so that only administrators 1506can start the interactive operations (i.e. editing menu entries and 1507entering the command-line interface). To use this feature, you need to 1508run the command `password' in your configuration file (*note 1509password::), like this: 1510 1511 password --md5 PASSWORD 1512 1513 If this is specified, GRUB disallows any interactive control, until 1514you press the key <p> and enter a correct password. The option `--md5' 1515tells GRUB that `PASSWORD' is in MD5 format. If it is omitted, GRUB 1516assumes the `PASSWORD' is in clear text. 1517 1518 You can encrypt your password with the command `md5crypt' (*note 1519md5crypt::). For example, run the grub shell (*note Invoking the grub 1520shell::), and enter your password: 1521 1522 grub> md5crypt 1523 Password: ********** 1524 Encrypted: $1$U$JK7xFegdxWH6VuppCUSIb. 1525 1526 Then, cut and paste the encrypted password to your configuration 1527file. 1528 1529 Also, you can specify an optional argument to `password'. See this 1530example: 1531 1532 password PASSWORD /boot/grub/menu-admin.lst 1533 1534 In this case, GRUB will load `/boot/grub/menu-admin.lst' as a 1535configuration file when you enter the valid password. 1536 1537 Another thing which may be dangerous is that any user can choose any 1538menu entry. Usually, this wouldn't be problematic, but you might want to 1539permit only administrators to run some of your menu entries, such as an 1540entry for booting an insecure OS like DOS. 1541 1542 GRUB provides the command `lock' (*note lock::). This command always 1543fails until you enter the valid password, so you can use it, like this: 1544 1545 title Boot DOS 1546 lock 1547 rootnoverify (hd0,1) 1548 makeactive 1549 chainload +1 1550 1551 You should insert `lock' right after `title', because any user can 1552execute commands in an entry until GRUB encounters `lock'. 1553 1554 You can also use the command `password' instead of `lock'. In this 1555case the boot process will ask for the password and stop if it was 1556entered incorrectly. Since the `password' takes its own PASSWORD 1557argument this is useful if you want different passwords for different 1558entries. 1559 1560 1561File: grub.info, Node: Images, Next: Filesystem, Prev: Security, Up: Top 1562 156310 GRUB image files 1564******************* 1565 1566GRUB consists of several images: two essential stages, optional stages 1567called "Stage 1.5", one image for bootable CD-ROM, and two network boot 1568images. Here is a short overview of them. *Note Internals::, for more 1569details. 1570 1571`stage1' 1572 This is an essential image used for booting up GRUB. Usually, this 1573 is embedded in an MBR or the boot sector of a partition. Because a 1574 PC boot sector is 512 bytes, the size of this image is exactly 512 1575 bytes. 1576 1577 All `stage1' must do is to load Stage 2 or Stage 1.5 from a local 1578 disk. Because of the size restriction, `stage1' encodes the 1579 location of Stage 2 (or Stage 1.5) in a block list format, so it 1580 never understand any filesystem structure. 1581 1582`stage2' 1583 This is the core image of GRUB. It does everything but booting up 1584 itself. Usually, this is put in a filesystem, but that is not 1585 required. 1586 1587`e2fs_stage1_5' 1588`fat_stage1_5' 1589`ffs_stage1_5' 1590`jfs_stage1_5' 1591`minix_stage1_5' 1592`reiserfs_stage1_5' 1593`vstafs_stage1_5' 1594`xfs_stage1_5' 1595 These are called "Stage 1.5", because they serve as a bridge 1596 between `stage1' and `stage2', that is to say, Stage 1.5 is loaded 1597 by Stage 1 and Stage 1.5 loads Stage 2. The difference between 1598 `stage1' and `*_stage1_5' is that the former doesn't understand 1599 any filesystem while the latter understands one filesystem (e.g. 1600 `e2fs_stage1_5' understands ext2fs). So you can move the Stage 2 1601 image to another location safely, even after GRUB has been 1602 installed. 1603 1604 While Stage 2 cannot generally be embedded in a fixed area as the 1605 size is so large, Stage 1.5 can be installed into the area right 1606 after an MBR, or the boot loader area of a ReiserFS or a FFS. 1607 1608`stage2_eltorito' 1609 This is a boot image for CD-ROMs using the "no emulation mode" in 1610 El Torito specification. This is identical to Stage 2, except that 1611 this boots up without Stage 1 and sets up a special drive `(cd)'. 1612 1613`nbgrub' 1614 This is a network boot image for the Network Image Proposal used 1615 by some network boot loaders, such as Etherboot. This is mostly 1616 the same as Stage 2, but it also sets up a network and loads a 1617 configuration file from the network. 1618 1619`pxegrub' 1620 This is another network boot image for the Preboot Execution 1621 Environment used by several Netboot ROMs. This is identical to 1622 `nbgrub', except for the format. 1623 1624 1625File: grub.info, Node: Filesystem, Next: Interface, Prev: Images, Up: Top 1626 162711 Filesystem syntax and semantics 1628********************************** 1629 1630GRUB uses a special syntax for specifying disk drives which can be 1631accessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish 1632between IDE, ESDI, SCSI, or others. You must know yourself which BIOS 1633device is equivalent to which OS device. Normally, that will be clear if 1634you see the files in a device or use the command `find' (*note find::). 1635 1636* Menu: 1637 1638* Device syntax:: How to specify devices 1639* File name syntax:: How to specify files 1640* Block list syntax:: How to specify block lists 1641 1642 1643File: grub.info, Node: Device syntax, Next: File name syntax, Up: Filesystem 1644 164511.1 How to specify devices 1646=========================== 1647 1648The device syntax is like this: 1649 1650 `(DEVICE[,PART-NUM][,BSD-SUBPART-LETTER])' 1651 1652 `[]' means the parameter is optional. DEVICE should be either `fd' 1653or `hd' followed by a digit, like `fd0'. But you can also set DEVICE 1654to a hexadecimal or a decimal number which is a BIOS drive number, so 1655the following are equivalent: 1656 1657 (hd0) 1658 (0x80) 1659 (128) 1660 1661 PART-NUM represents the partition number of DEVICE, starting from 1662zero for primary partitions and from four for extended partitions, and 1663BSD-SUBPART-LETTER represents the BSD disklabel subpartition, such as 1664`a' or `e'. 1665 1666 A shortcut for specifying BSD subpartitions is 1667`(DEVICE,BSD-SUBPART-LETTER)', in this case, GRUB searches for the 1668first PC partition containing a BSD disklabel, then finds the 1669subpartition BSD-SUBPART-LETTER. Here is an example: 1670 1671 (hd0,a) 1672 1673 The syntax `(hd0)' represents using the entire disk (or the MBR when 1674installing GRUB), while the syntax `(hd0,0)' represents using the first 1675partition of the disk (or the boot sector of the partition when 1676installing GRUB). 1677 1678 If you enabled the network support, the special drive, `(nd)', is 1679also available. Before using the network drive, you must initialize the 1680network. *Note Network::, for more information. 1681 1682 If you boot GRUB from a CD-ROM, `(cd)' is available. *Note Making a 1683GRUB bootable CD-ROM::, for details. 1684 1685 1686File: grub.info, Node: File name syntax, Next: Block list syntax, Prev: Device syntax, Up: Filesystem 1687 168811.2 How to specify files 1689========================= 1690 1691There are two ways to specify files, by "absolute file name" and by 1692"block list". 1693 1694 An absolute file name resembles a Unix absolute file name, using `/' 1695for the directory separator (not `\' as in DOS). One example is 1696`(hd0,0)/boot/grub/menu.lst'. This means the file `/boot/grub/menu.lst' 1697in the first partition of the first hard disk. If you omit the device 1698name in an absolute file name, GRUB uses GRUB's "root device" 1699implicitly. So if you set the root device to, say, `(hd1,0)' by the 1700command `root' (*note root::), then `/boot/kernel' is the same as 1701`(hd1,0)/boot/kernel'. 1702 1703 1704File: grub.info, Node: Block list syntax, Prev: File name syntax, Up: Filesystem 1705 170611.3 How to specify block lists 1707=============================== 1708 1709A block list is used for specifying a file that doesn't appear in the 1710filesystem, like a chainloader. The syntax is 1711`[OFFSET]+LENGTH[,[OFFSET]+LENGTH]...'. Here is an example: 1712 1713 `0+100,200+1,300+300' 1714 1715 This represents that GRUB should read blocks 0 through 99, block 200, 1716and blocks 300 through 599. If you omit an offset, then GRUB assumes 1717the offset is zero. 1718 1719 Like the file name syntax (*note File name syntax::), if a blocklist 1720does not contain a device name, then GRUB uses GRUB's "root device". So 1721`(hd0,1)+1' is the same as `+1' when the root device is `(hd0,1)'. 1722 1723 1724File: grub.info, Node: Interface, Next: Commands, Prev: Filesystem, Up: Top 1725 172612 GRUB's user interface 1727************************ 1728 1729GRUB has both a simple menu interface for choosing preset entries from a 1730configuration file, and a highly flexible command-line for performing 1731any desired combination of boot commands. 1732 1733 GRUB looks for its configuration file as soon as it is loaded. If one 1734is found, then the full menu interface is activated using whatever 1735entries were found in the file. If you choose the "command-line" menu 1736option, or if the configuration file was not found, then GRUB drops to 1737the command-line interface. 1738 1739* Menu: 1740 1741* Command-line interface:: The flexible command-line interface 1742* Menu interface:: The simple menu interface 1743* Menu entry editor:: Editing a menu entry 1744* Hidden menu interface:: The hidden menu interface 1745 1746 1747File: grub.info, Node: Command-line interface, Next: Menu interface, Up: Interface 1748 174912.1 The flexible command-line interface 1750======================================== 1751 1752The command-line interface provides a prompt and after it an editable 1753text area much like a command-line in Unix or DOS. Each command is 1754immediately executed after it is entered(1) (*note Command-line 1755interface-Footnote-1::). The commands (*note Command-line and menu 1756entry commands::) are a subset of those available in the configuration 1757file, used with exactly the same syntax. 1758 1759 Cursor movement and editing of the text on the line can be done via a 1760subset of the functions available in the Bash shell: 1761 1762<C-f> 1763<PC right key> 1764 Move forward one character. 1765 1766<C-b> 1767<PC left key> 1768 Move back one character. 1769 1770<C-a> 1771<HOME> 1772 Move to the start of the line. 1773 1774<C-e> 1775<END> 1776 Move the the end of the line. 1777 1778<C-d> 1779<DEL> 1780 Delete the character underneath the cursor. 1781 1782<C-h> 1783<BS> 1784 Delete the character to the left of the cursor. 1785 1786<C-k> 1787 Kill the text from the current cursor position to the end of the 1788 line. 1789 1790<C-u> 1791 Kill backward from the cursor to the beginning of the line. 1792 1793<C-y> 1794 Yank the killed text back into the buffer at the cursor. 1795 1796<C-p> 1797<PC up key> 1798 Move up through the history list. 1799 1800<C-n> 1801<PC down key> 1802 Move down through the history list. 1803 1804 When typing commands interactively, if the cursor is within or before 1805the first word in the command-line, pressing the <TAB> key (or <C-i>) 1806will display a listing of the available commands, and if the cursor is 1807after the first word, the `<TAB>' will provide a completion listing of 1808disks, partitions, and file names depending on the context. Note that 1809to obtain a list of drives, one must open a parenthesis, as `root ('. 1810 1811 Note that you cannot use the completion functionality in the TFTP 1812filesystem. This is because TFTP doesn't support file name listing for 1813the security. 1814 1815 1816File: grub.info, Node: Command-line interface-Footnotes, Up: Command-line interface 1817 1818 (1) However, this behavior will be changed in the future version, in 1819a user-invisible way. 1820 1821 1822File: grub.info, Node: Menu interface, Next: Menu entry editor, Prev: Command-line interface, Up: Interface 1823 182412.2 The simple menu interface 1825============================== 1826 1827The menu interface is quite easy to use. Its commands are both 1828reasonably intuitive and described on screen. 1829 1830 Basically, the menu interface provides a list of "boot entries" to 1831the user to choose from. Use the arrow keys to select the entry of 1832choice, then press <RET> to run it. An optional timeout is available 1833to boot the default entry (the first one if not set), which is aborted 1834by pressing any key. 1835 1836 Commands are available to enter a bare command-line by pressing <c> 1837(which operates exactly like the non-config-file version of GRUB, but 1838allows one to return to the menu if desired by pressing <ESC>) or to 1839edit any of the "boot entries" by pressing <e>. 1840 1841 If you protect the menu interface with a password (*note Security::), 1842all you can do is choose an entry by pressing <RET>, or press <p> to 1843enter the password. 1844 1845 1846File: grub.info, Node: Menu entry editor, Next: Hidden menu interface, Prev: Menu interface, Up: Interface 1847 184812.3 Editing a menu entry 1849========================= 1850 1851The menu entry editor looks much like the main menu interface, but the 1852lines in the menu are individual commands in the selected entry instead 1853of entry names. 1854 1855 If an <ESC> is pressed in the editor, it aborts all the changes made 1856to the configuration entry and returns to the main menu interface. 1857 1858 When a particular line is selected, the editor places the user in a 1859special version of the GRUB command-line to edit that line. When the 1860user hits <RET>, GRUB replaces the line in question in the boot entry 1861with the changes (unless it was aborted via <ESC>, in which case the 1862changes are thrown away). 1863 1864 If you want to add a new line to the menu entry, press <o> if adding 1865a line after the current line or press <O> if before the current line. 1866 1867 To delete a line, hit the key <d>. Although GRUB unfortunately does 1868not support "undo", you can do almost the same thing by just returning 1869to the main menu. 1870 1871 1872File: grub.info, Node: Hidden menu interface, Prev: Menu entry editor, Up: Interface 1873 187412.4 The hidden menu interface 1875============================== 1876 1877When your terminal is dumb or you request GRUB to hide the menu 1878interface explicitly with the command `hiddenmenu' (*note 1879hiddenmenu::), GRUB doesn't show the menu interface (*note Menu 1880interface::) and automatically boots the default entry, unless 1881interrupted by pressing <ESC>. 1882 1883 When you interrupt the timeout and your terminal is dumb, GRUB falls 1884back to the command-line interface (*note Command-line interface::). 1885 1886 1887File: grub.info, Node: Commands, Next: Troubleshooting, Prev: Interface, Up: Top 1888 188913 The list of available commands 1890********************************* 1891 1892In this chapter, we list all commands that are available in GRUB. 1893 1894 Commands belong to different groups. A few can only be used in the 1895global section of the configuration file (or "menu"); most of them can 1896be entered on the command-line and can be used either anywhere in the 1897menu or specifically in the menu entries. 1898 1899* Menu: 1900 1901* Menu-specific commands:: 1902* General commands:: 1903* Command-line and menu entry commands:: 1904 1905 1906File: grub.info, Node: Menu-specific commands, Next: General commands, Up: Commands 1907 190813.1 The list of commands for the menu only 1909=========================================== 1910 1911The semantics used in parsing the configuration file are the following: 1912 1913 * The menu-specific commands have to be used before any others. 1914 1915 * The files _must_ be in plain-text format. 1916 1917 * `#' at the beginning of a line in a configuration file means it is 1918 only a comment. 1919 1920 * Options are separated by spaces. 1921 1922 * All numbers can be either decimal or hexadecimal. A hexadecimal 1923 number must be preceded by `0x', and is case-insensitive. 1924 1925 * Extra options or text at the end of the line are ignored unless 1926 otherwise specified. 1927 1928 * Unrecognized commands are added to the current entry, except 1929 before entries start, where they are ignored. 1930 1931 These commands can only be used in the menu: 1932 1933* Menu: 1934 1935* default:: Set the default entry 1936* fallback:: Set the fallback entry 1937* hiddenmenu:: Hide the menu interface 1938* timeout:: Set the timeout 1939* title:: Start a menu entry 1940 1941 1942File: grub.info, Node: default, Next: fallback, Up: Menu-specific commands 1943 194413.1.1 default 1945-------------- 1946 1947 -- Command: default num 1948 Set the default entry to the entry number NUM. Numbering starts 1949 from 0, and the entry number 0 is the default if the command is not 1950 used. 1951 1952 You can specify `saved' instead of a number. In this case, the 1953 default entry is the entry saved with the command `savedefault'. 1954 *Note savedefault::, for more information. 1955 1956 1957File: grub.info, Node: fallback, Next: hiddenmenu, Prev: default, Up: Menu-specific commands 1958 195913.1.2 fallback 1960--------------- 1961 1962 -- Command: fallback num... 1963 Go into unattended boot mode: if the default boot entry has any 1964 errors, instead of waiting for the user to do something, 1965 immediately start over using the NUM entry (same numbering as the 1966 `default' command (*note default::)). This obviously won't help if 1967 the machine was rebooted by a kernel that GRUB loaded. You can 1968 specify multiple fallback entry numbers. 1969 1970 1971File: grub.info, Node: hiddenmenu, Next: timeout, Prev: fallback, Up: Menu-specific commands 1972 197313.1.3 hiddenmenu 1974----------------- 1975 1976 -- Command: hiddenmenu 1977 Don't display the menu. If the command is used, no menu will be 1978 displayed on the control terminal, and the default entry will be 1979 booted after the timeout expired. The user can still request the 1980 menu to be displayed by pressing <ESC> before the timeout expires. 1981 See also *Note Hidden menu interface::. 1982 1983 1984File: grub.info, Node: timeout, Next: title, Prev: hiddenmenu, Up: Menu-specific commands 1985 198613.1.4 timeout 1987-------------- 1988 1989 -- Command: timeout sec 1990 Set a timeout, in SEC seconds, before automatically booting the 1991 default entry (normally the first entry defined). 1992 1993 1994File: grub.info, Node: title, Prev: timeout, Up: Menu-specific commands 1995 199613.1.5 title 1997------------ 1998 1999 -- Command: title name ... 2000 Start a new boot entry, and set its name to the contents of the 2001 rest of the line, starting with the first non-space character. 2002 2003 2004File: grub.info, Node: General commands, Next: Command-line and menu entry commands, Prev: Menu-specific commands, Up: Commands 2005 200613.2 The list of general commands 2007================================= 2008 2009Commands usable anywhere in the menu and in the command-line. 2010 2011* Menu: 2012 2013* bootp:: Initialize a network device via BOOTP 2014* color:: Color the menu interface 2015* device:: Specify a file as a drive 2016* dhcp:: Initialize a network device via DHCP 2017* hide:: Hide a partition 2018* ifconfig:: Configure a network device manually 2019* pager:: Change the state of the internal pager 2020* partnew:: Make a primary partition 2021* parttype:: Change the type of a partition 2022* password:: Set a password for the menu interface 2023* rarp:: Initialize a network device via RARP 2024* serial:: Set up a serial device 2025* setkey:: Configure the key map 2026* terminal:: Choose a terminal 2027* terminfo:: Define escape sequences for a terminal 2028* tftpserver:: Specify a TFTP server 2029* unhide:: Unhide a partition 2030 2031 2032File: grub.info, Node: bootp, Next: color, Up: General commands 2033 203413.2.1 bootp 2035------------ 2036 2037 -- Command: bootp [`--with-configfile'] 2038 Initialize a network device via the "BOOTP" protocol. This command 2039 is only available if GRUB is compiled with netboot support. See 2040 also *Note Network::. 2041 2042 If you specify `--with-configfile' to this command, GRUB will 2043 fetch and load a configuration file specified by your BOOTP server 2044 with the vendor tag `150'. 2045 2046 2047File: grub.info, Node: color, Next: device, Prev: bootp, Up: General commands 2048 204913.2.2 color 2050------------ 2051 2052 -- Command: color normal [highlight] 2053 Change the menu colors. The color NORMAL is used for most lines in 2054 the menu (*note Menu interface::), and the color HIGHLIGHT is used 2055 to highlight the line where the cursor points. If you omit 2056 HIGHLIGHT, then the inverted color of NORMAL is used for the 2057 highlighted line. The format of a color is 2058 `FOREGROUND/BACKGROUND'. FOREGROUND and BACKGROUND are symbolic 2059 color names. A symbolic color name must be one of these: 2060 2061 * black 2062 2063 * blue 2064 2065 * green 2066 2067 * cyan 2068 2069 * red 2070 2071 * magenta 2072 2073 * brown 2074 2075 * light-gray 2076 2077 *These below can be specified only for the foreground.* 2078 2079 * dark-gray 2080 2081 * light-blue 2082 2083 * light-green 2084 2085 * light-cyan 2086 2087 * light-red 2088 2089 * light-magenta 2090 2091 * yellow 2092 2093 * white 2094 2095 But only the first eight names can be used for BACKGROUND. You can 2096 prefix `blink-' to FOREGROUND if you want a blinking foreground 2097 color. 2098 2099 This command can be used in the configuration file and on the 2100 command line, so you may write something like this in your 2101 configuration file: 2102 2103 # Set default colors. 2104 color light-gray/blue black/light-gray 2105 2106 # Change the colors. 2107 title OS-BS like 2108 color magenta/blue black/magenta 2109 2110 2111File: grub.info, Node: device, Next: dhcp, Prev: color, Up: General commands 2112 211313.2.3 device 2114------------- 2115 2116 -- Command: device drive file 2117 In the grub shell, specify the file FILE as the actual drive for a 2118 BIOS drive DRIVE. You can use this command to create a disk image, 2119 and/or to fix the drives guessed by GRUB when GRUB fails to 2120 determine them correctly, like this: 2121 2122 grub> device (fd0) /floppy-image 2123 grub> device (hd0) /dev/sd0 2124 2125 This command can be used only in the grub shell (*note Invoking 2126 the grub shell::). 2127 2128 2129File: grub.info, Node: dhcp, Next: hide, Prev: device, Up: General commands 2130 213113.2.4 dhcp 2132----------- 2133 2134 -- Command: dhcp [-with-configfile] 2135 Initialize a network device via the "DHCP" protocol. Currently, 2136 this command is just an alias for `bootp', since the two protocols 2137 are very similar. This command is only available if GRUB is 2138 compiled with netboot support. See also *Note Network::. 2139 2140 If you specify `--with-configfile' to this command, GRUB will 2141 fetch and load a configuration file specified by your DHCP server 2142 with the vendor tag `150'. 2143 2144 2145File: grub.info, Node: hide, Next: ifconfig, Prev: dhcp, Up: General commands 2146 214713.2.5 hide 2148----------- 2149 2150 -- Command: hide partition 2151 Hide the partition PARTITION by setting the "hidden" bit in its 2152 partition type code. This is useful only when booting DOS or 2153 Windows and multiple primary FAT partitions exist in one disk. See 2154 also *Note DOS/Windows::. 2155 2156 2157File: grub.info, Node: ifconfig, Next: pager, Prev: hide, Up: General commands 2158 215913.2.6 ifconfig 2160--------------- 2161 2162 -- Command: ifconfig [`--server=server'] [`--gateway=gateway'] 2163 [`--mask=mask'] [`--address=address'] 2164 Configure the IP address, the netmask, the gateway, and the server 2165 address of a network device manually. The values must be in dotted 2166 decimal format, like `192.168.11.178'. The order of the options is 2167 not important. This command shows current network configuration, 2168 if no option is specified. See also *Note Network::. 2169 2170 2171File: grub.info, Node: pager, Next: partnew, Prev: ifconfig, Up: General commands 2172 217313.2.7 pager 2174------------ 2175 2176 -- Command: pager [flag] 2177 Toggle or set the state of the internal pager. If FLAG is `on', 2178 the internal pager is enabled. If FLAG is `off', it is disabled. 2179 If no argument is given, the state is toggled. 2180 2181 2182File: grub.info, Node: partnew, Next: parttype, Prev: pager, Up: General commands 2183 218413.2.8 partnew 2185-------------- 2186 2187 -- Command: partnew part type from len 2188 Create a new primary partition. PART is a partition specification 2189 in GRUB syntax (*note Naming convention::); TYPE is the partition 2190 type and must be a number in the range `0-0xff'; FROM is the 2191 starting address and LEN is the length, both in sector units. 2192 2193 2194File: grub.info, Node: parttype, Next: password, Prev: partnew, Up: General commands 2195 219613.2.9 parttype 2197--------------- 2198 2199 -- Command: parttype part type 2200 Change the type of an existing partition. PART is a partition 2201 specification in GRUB syntax (*note Naming convention::); TYPE is 2202 the new partition type and must be a number in the range 0-0xff. 2203 2204 2205File: grub.info, Node: password, Next: rarp, Prev: parttype, Up: General commands 2206 220713.2.10 password 2208---------------- 2209 2210 -- Command: password [`--md5'] passwd [new-config-file] 2211 If used in the first section of a menu file, disable all 2212 interactive editing control (menu entry editor and command-line) 2213 and entries protected by the command `lock'. If the password 2214 PASSWD is entered, it loads the NEW-CONFIG-FILE as a new config 2215 file and restarts the GRUB Stage 2, if NEW-CONFIG-FILE is 2216 specified. Otherwise, GRUB will just unlock the privileged 2217 instructions. You can also use this command in the script 2218 section, in which case it will ask for the password, before 2219 continuing. The option `--md5' tells GRUB that PASSWD is 2220 encrypted with `md5crypt' (*note md5crypt::). 2221 2222 2223File: grub.info, Node: rarp, Next: serial, Prev: password, Up: General commands 2224 222513.2.11 rarp 2226------------ 2227 2228 -- Command: rarp 2229 Initialize a network device via the "RARP" protocol. This command 2230 is only available if GRUB is compiled with netboot support. See 2231 also *Note Network::. 2232 2233 2234File: grub.info, Node: serial, Next: setkey, Prev: rarp, Up: General commands 2235 223613.2.12 serial 2237-------------- 2238 2239 -- Command: serial [`--unit=unit'] [`--port=port'] [`--speed=speed'] 2240 [`--word=word'] [`--parity=parity'] [`--stop=stop'] 2241 [`--device=dev'] 2242 Initialize a serial device. UNIT is a number in the range 0-3 2243 specifying which serial port to use; default is 0, which 2244 corresponds to the port often called COM1. PORT is the I/O port 2245 where the UART is to be found; if specified it takes precedence 2246 over UNIT. SPEED is the transmission speed; default is 9600. WORD 2247 and STOP are the number of data bits and stop bits. Data bits must 2248 be in the range 5-8 and stop bits must be 1 or 2. Default is 8 data 2249 bits and one stop bit. PARITY is one of `no', `odd', `even' and 2250 defaults to `no'. The option `--device' can only be used in the 2251 grub shell and is used to specify the tty device to be used in the 2252 host operating system (*note Invoking the grub shell::). 2253 2254 The serial port is not used as a communication channel unless the 2255 `terminal' command is used (*note terminal::). 2256 2257 This command is only available if GRUB is compiled with serial 2258 support. See also *Note Serial terminal::. 2259 2260 2261File: grub.info, Node: setkey, Next: terminal, Prev: serial, Up: General commands 2262 226313.2.13 setkey 2264-------------- 2265 2266 -- Command: setkey [to_key from_key] 2267 Change the keyboard map. The key FROM_KEY is mapped to the key 2268 TO_KEY. If no argument is specified, reset key mappings. Note that 2269 this command _does not_ exchange the keys. If you want to exchange 2270 the keys, run this command again with the arguments exchanged, 2271 like this: 2272 2273 grub> setkey capslock control 2274 grub> setkey control capslock 2275 2276 A key must be an alphabet letter, a digit, or one of these symbols: 2277 `escape', `exclam', `at', `numbersign', `dollar', `percent', 2278 `caret', `ampersand', `asterisk', `parenleft', `parenright', 2279 `minus', `underscore', `equal', `plus', `backspace', `tab', 2280 `bracketleft', `braceleft', `bracketright', `braceright', `enter', 2281 `control', `semicolon', `colon', `quote', `doublequote', 2282 `backquote', `tilde', `shift', `backslash', `bar', `comma', 2283 `less', `period', `greater', `slash', `question', `alt', `space', 2284 `capslock', `FX' (`X' is a digit), and `delete'. This table 2285 describes to which character each of the symbols corresponds: 2286 2287 `exclam' 2288 `!' 2289 2290 `at' 2291 `@' 2292 2293 `numbersign' 2294 `#' 2295 2296 `dollar' 2297 `$' 2298 2299 `percent' 2300 `%' 2301 2302 `caret' 2303 `^' 2304 2305 `ampersand' 2306 `&' 2307 2308 `asterisk' 2309 `*' 2310 2311 `parenleft' 2312 `(' 2313 2314 `parenright' 2315 `)' 2316 2317 `minus' 2318 `-' 2319 2320 `underscore' 2321 `_' 2322 2323 `equal' 2324 `=' 2325 2326 `plus' 2327 `+' 2328 2329 `bracketleft' 2330 `[' 2331 2332 `braceleft' 2333 `{' 2334 2335 `bracketright' 2336 `]' 2337 2338 `braceright' 2339 `}' 2340 2341 `semicolon' 2342 `;' 2343 2344 `colon' 2345 `:' 2346 2347 `quote' 2348 `'' 2349 2350 `doublequote' 2351 `"' 2352 2353 `backquote' 2354 ``' 2355 2356 `tilde' 2357 `~' 2358 2359 `backslash' 2360 `\' 2361 2362 `bar' 2363 `|' 2364 2365 `comma' 2366 `,' 2367 2368 `less' 2369 `<' 2370 2371 `period' 2372 `.' 2373 2374 `greater' 2375 `>' 2376 2377 `slash' 2378 `/' 2379 2380 `question' 2381 `?' 2382 2383 `space' 2384 ` ' 2385 2386 2387File: grub.info, Node: terminal, Next: terminfo, Prev: setkey, Up: General commands 2388 238913.2.14 terminal 2390---------------- 2391 2392 -- Command: terminal [`--dumb'] [`--no-echo'] [`--no-edit'] 2393 [`--timeout=secs'] [`--lines=lines'] [`--silent'] [`console'] 2394 [`serial'] [`hercules'] 2395 Select a terminal for user interaction. The terminal is assumed to 2396 be VT100-compatible unless `--dumb' is specified. If both 2397 `console' and `serial' are specified, then GRUB will use the one 2398 where a key is entered first or the first when the timeout 2399 expires. If neither are specified, the current setting is 2400 reported. This command is only available if GRUB is compiled with 2401 serial support. See also *Note Serial terminal::. 2402 2403 This may not make sense for most users, but GRUB supports Hercules 2404 console as well. Hercules console is usable like the ordinary 2405 console, and the usage is quite similar to that for serial 2406 terminals: specify `hercules' as the argument. 2407 2408 The option `--lines' defines the number of lines in your terminal, 2409 and it is used for the internal pager function. If you don't 2410 specify this option, the number is assumed as 24. 2411 2412 The option `--silent' suppresses the message to prompt you to hit 2413 any key. This might be useful if your system has no terminal 2414 device. 2415 2416 The option `--no-echo' has GRUB not to echo back input characters. 2417 This implies the option `--no-edit'. 2418 2419 The option `--no-edit' disables the BASH-like editing feature. 2420 2421 2422File: grub.info, Node: terminfo, Next: tftpserver, Prev: terminal, Up: General commands 2423 242413.2.15 terminfo 2425---------------- 2426 2427 -- Command: terminfo `--name=name' `--cursor-address=seq' 2428 [`--clear-screen=seq'] [`--enter-standout-mode=seq'] 2429 [`--exit-standout-mode=seq'] 2430 Define the capabilities of your terminal. Use this command to 2431 define escape sequences, if it is not vt100-compatible. You may 2432 use `\e' for <ESC> and `^X' for a control character. 2433 2434 You can use the utility `grub-terminfo' to generate appropriate 2435 arguments to this command. *Note Invoking grub-terminfo::. 2436 2437 If no option is specified, the current settings are printed. 2438 2439 2440File: grub.info, Node: tftpserver, Next: unhide, Prev: terminfo, Up: General commands 2441 244213.2.16 tftpserver 2443------------------ 2444 2445 -- Command: tftpserver ipaddr 2446 *Caution:* This command exists only for backward compatibility. 2447 Use `ifconfig' (*note ifconfig::) instead. 2448 2449 Override a TFTP server address returned by a BOOTP/DHCP/RARP 2450 server. The argument IPADDR must be in dotted decimal format, like 2451 `192.168.0.15'. This command is only available if GRUB is compiled 2452 with netboot support. See also *Note Network::. 2453 2454 2455File: grub.info, Node: unhide, Prev: tftpserver, Up: General commands 2456 245713.2.17 unhide 2458-------------- 2459 2460 -- Command: unhide partition 2461 Unhide the partition PARTITION by clearing the "hidden" bit in its 2462 partition type code. This is useful only when booting DOS or 2463 Windows and multiple primary partitions exist on one disk. See also 2464 *Note DOS/Windows::. 2465 2466 2467File: grub.info, Node: Command-line and menu entry commands, Prev: General commands, Up: Commands 2468 246913.3 The list of command-line and menu entry commands 2470===================================================== 2471 2472These commands are usable in the command-line and in menu entries. If 2473you forget a command, you can run the command `help' (*note help::). 2474 2475* Menu: 2476 2477* blocklist:: Get the block list notation of a file 2478* boot:: Start up your operating system 2479* cat:: Show the contents of a file 2480* chainloader:: Chain-load another boot loader 2481* cmp:: Compare two files 2482* configfile:: Load a configuration file 2483* debug:: Toggle the debug flag 2484* displayapm:: Display APM information 2485* displaymem:: Display memory configuration 2486* embed:: Embed Stage 1.5 2487* find:: Find a file 2488* fstest:: Test a filesystem 2489* geometry:: Manipulate the geometry of a drive 2490* halt:: Shut down your computer 2491* help:: Show help messages 2492* impsprobe:: Probe SMP 2493* initrd:: Load an initrd 2494* install:: Install GRUB 2495* ioprobe:: Probe I/O ports used for a drive 2496* kernel:: Load a kernel 2497* lock:: Lock a menu entry 2498* makeactive:: Make a partition active 2499* map:: Map a drive to another 2500* md5crypt:: Encrypt a password in MD5 format 2501* module:: Load a module 2502* modulenounzip:: Load a module without decompression 2503* pause:: Wait for a key press 2504* quit:: Exit from the grub shell 2505* reboot:: Reboot your computer 2506* read:: Read data from memory 2507* root:: Set GRUB's root device 2508* rootnoverify:: Set GRUB's root device without mounting 2509* savedefault:: Save current entry as the default entry 2510* setup:: Set up GRUB's installation automatically 2511* testload:: Load a file for testing a filesystem 2512* testvbe:: Test VESA BIOS EXTENSION 2513* uppermem:: Set the upper memory size 2514* vbeprobe:: Probe VESA BIOS EXTENSION 2515 2516 2517File: grub.info, Node: blocklist, Next: boot, Up: Command-line and menu entry commands 2518 251913.3.1 blocklist 2520---------------- 2521 2522 -- Command: blocklist file 2523 Print the block list notation of the file FILE. *Note Block list 2524 syntax::. 2525 2526 2527File: grub.info, Node: boot, Next: cat, Prev: blocklist, Up: Command-line and menu entry commands 2528 252913.3.2 boot 2530----------- 2531 2532 -- Command: boot 2533 Boot the OS or chain-loader which has been loaded. Only necessary 2534 if running the fully interactive command-line (it is implicit at 2535 the end of a menu entry). 2536 2537 2538File: grub.info, Node: cat, Next: chainloader, Prev: boot, Up: Command-line and menu entry commands 2539 254013.3.3 cat 2541---------- 2542 2543 -- Command: cat file 2544 Display the contents of the file FILE. This command may be useful 2545 to remind you of your OS's root partition: 2546 2547 grub> cat /etc/fstab 2548 2549 2550File: grub.info, Node: chainloader, Next: cmp, Prev: cat, Up: Command-line and menu entry commands 2551 255213.3.4 chainloader 2553------------------ 2554 2555 -- Command: chainloader [`--force'] file 2556 Load FILE as a chain-loader. Like any other file loaded by the 2557 filesystem code, it can use the blocklist notation to grab the 2558 first sector of the current partition with `+1'. If you specify the 2559 option `--force', then load FILE forcibly, whether it has a 2560 correct signature or not. This is required when you want to load a 2561 defective boot loader, such as SCO UnixWare 7.1 (*note SCO 2562 UnixWare::). 2563 2564 2565File: grub.info, Node: cmp, Next: configfile, Prev: chainloader, Up: Command-line and menu entry commands 2566 256713.3.5 cmp 2568---------- 2569 2570 -- Command: cmp file1 file2 2571 Compare the file FILE1 with the file FILE2. If they differ in 2572 size, print the sizes like this: 2573 2574 Differ in size: 0x1234 [foo], 0x4321 [bar] 2575 2576 If the sizes are equal but the bytes at an offset differ, then 2577 print the bytes like this: 2578 2579 Differ at the offset 777: 0xbe [foo], 0xef [bar] 2580 2581 If they are completely identical, nothing will be printed. 2582 2583 2584File: grub.info, Node: configfile, Next: debug, Prev: cmp, Up: Command-line and menu entry commands 2585 258613.3.6 configfile 2587----------------- 2588 2589 -- Command: configfile file 2590 Load FILE as a configuration file. 2591 2592 2593File: grub.info, Node: debug, Next: displayapm, Prev: configfile, Up: Command-line and menu entry commands 2594 259513.3.7 debug 2596------------ 2597 2598 -- Command: debug 2599 Toggle debug mode (by default it is off). When debug mode is on, 2600 some extra messages are printed to show disk activity. This global 2601 debug flag is mainly useful for GRUB developers when testing new 2602 code. 2603 2604 2605File: grub.info, Node: displayapm, Next: displaymem, Prev: debug, Up: Command-line and menu entry commands 2606 260713.3.8 displayapm 2608----------------- 2609 2610 -- Command: displayapm 2611 Display APM BIOS information. 2612 2613 2614File: grub.info, Node: displaymem, Next: embed, Prev: displayapm, Up: Command-line and menu entry commands 2615 261613.3.9 displaymem 2617----------------- 2618 2619 -- Command: displaymem 2620 Display what GRUB thinks the system address space map of the 2621 machine is, including all regions of physical RAM installed. GRUB's 2622 "upper/lower memory" display uses the standard BIOS interface for 2623 the available memory in the first megabyte, or "lower memory", and 2624 a synthesized number from various BIOS interfaces of the memory 2625 starting at 1MB and going up to the first chipset hole for "upper 2626 memory" (the standard PC "upper memory" interface is limited to 2627 reporting a maximum of 64MB). 2628 2629 2630File: grub.info, Node: embed, Next: find, Prev: displaymem, Up: Command-line and menu entry commands 2631 263213.3.10 embed 2633------------- 2634 2635 -- Command: embed stage1_5 device 2636 Embed the Stage 1.5 STAGE1_5 in the sectors after the MBR if 2637 DEVICE is a drive, or in the "boot loader" area if DEVICE is a FFS 2638 partition or a ReiserFS partition.(1) (*note embed-Footnote-1::) 2639 Print the number of sectors which STAGE1_5 occupies, if successful. 2640 2641 Usually, you don't need to run this command directly. *Note 2642 setup::. 2643 2644 2645File: grub.info, Node: embed-Footnotes, Up: embed 2646 2647 (1) The latter feature has not been implemented yet. 2648 2649 2650File: grub.info, Node: find, Next: fstest, Prev: embed, Up: Command-line and menu entry commands 2651 265213.3.11 find 2653------------ 2654 2655 -- Command: find filename 2656 Search for the file name FILENAME in all mountable partitions and 2657 print the list of the devices which contain the file. The file 2658 name FILENAME should be an absolute file name like 2659 `/boot/grub/stage1'. 2660 2661 2662File: grub.info, Node: fstest, Next: geometry, Prev: find, Up: Command-line and menu entry commands 2663 266413.3.12 fstest 2665-------------- 2666 2667 -- Command: fstest 2668 Toggle filesystem test mode. Filesystem test mode, when turned 2669 on, prints out data corresponding to all the device reads and what 2670 values are being sent to the low-level routines. The format is 2671 `<PARTITION-OFFSET-SECTOR, BYTE-OFFSET, BYTE-LENGTH>' for 2672 high-level reads inside a partition, and `[DISK-OFFSET-SECTOR]' 2673 for low-level sector requests from the disk. Filesystem test mode 2674 is turned off by any use of the `install' (*note install::) or 2675 `testload' (*note testload::) commands. 2676 2677 2678File: grub.info, Node: geometry, Next: halt, Prev: fstest, Up: Command-line and menu entry commands 2679 268013.3.13 geometry 2681---------------- 2682 2683 -- Command: geometry drive [cylinder head sector [total_sector]] 2684 Print the information for the drive DRIVE. In the grub shell, you 2685 can set the geometry of the drive arbitrarily. The number of 2686 cylinders, the number of heads, the number of sectors and the 2687 number of total sectors are set to CYLINDER, HEAD, SECTOR and 2688 TOTAL_SECTOR, respectively. If you omit TOTAL_SECTOR, then it will 2689 be calculated based on the C/H/S values automatically. 2690 2691 2692File: grub.info, Node: halt, Next: help, Prev: geometry, Up: Command-line and menu entry commands 2693 269413.3.14 halt 2695------------ 2696 2697 -- Command: halt `--no-apm' 2698 The command halts the computer. If the `--no-apm' option is 2699 specified, no APM BIOS call is performed. Otherwise, the computer 2700 is shut down using APM. 2701 2702 2703File: grub.info, Node: help, Next: impsprobe, Prev: halt, Up: Command-line and menu entry commands 2704 270513.3.15 help 2706------------ 2707 2708 -- Command: help `--all' [pattern ...] 2709 Display helpful information about builtin commands. If you do not 2710 specify PATTERN, this command shows short descriptions of most of 2711 available commands. If you specify the option `--all' to this 2712 command, short descriptions of rarely used commands (such as *Note 2713 testload::) are displayed as well. 2714 2715 If you specify any PATTERNS, it displays longer information about 2716 each of the commands which match those PATTERNS. 2717 2718 2719File: grub.info, Node: impsprobe, Next: initrd, Prev: help, Up: Command-line and menu entry commands 2720 272113.3.16 impsprobe 2722----------------- 2723 2724 -- Command: impsprobe 2725 Probe the Intel Multiprocessor Specification 1.1 or 1.4 2726 configuration table and boot the various CPUs which are found into 2727 a tight loop. This command can be used only in the Stage 2, but 2728 not in the grub shell. 2729 2730 2731File: grub.info, Node: initrd, Next: install, Prev: impsprobe, Up: Command-line and menu entry commands 2732 273313.3.17 initrd 2734-------------- 2735 2736 -- Command: initrd file ... 2737 Load an initial ramdisk for a Linux format boot image and set the 2738 appropriate parameters in the Linux setup area in memory. See also 2739 *Note GNU/Linux::. 2740 2741 2742File: grub.info, Node: install, Next: ioprobe, Prev: initrd, Up: Command-line and menu entry commands 2743 274413.3.18 install 2745--------------- 2746 2747 -- Command: install [`--force-lba'] [`--stage2=os_stage2_file'] 2748 stage1_file [`d'] dest_dev stage2_file [addr] [`p'] 2749 [config_file] [real_config_file] 2750 This command is fairly complex, and you should not use this command 2751 unless you are familiar with GRUB. Use `setup' (*note setup::) 2752 instead. 2753 2754 In short, it will perform a full install presuming the Stage 2 or 2755 Stage 1.5(1) (*note install-Footnote-1::) is in its final install 2756 location. 2757 2758 In slightly more detail, it will load STAGE1_FILE, validate that 2759 it is a GRUB Stage 1 of the right version number, install in it a 2760 blocklist for loading STAGE2_FILE as a Stage 2. If the option `d' 2761 is present, the Stage 1 will always look for the actual disk 2762 STAGE2_FILE was installed on, rather than using the booting drive. 2763 The Stage 2 will be loaded at address ADDR, which must be `0x8000' 2764 for a true Stage 2, and `0x2000' for a Stage 1.5. If ADDR is not 2765 present, GRUB will determine the address automatically. It then 2766 writes the completed Stage 1 to the first block of the device 2767 DEST_DEV. If the options `p' or CONFIG_FILE are present, then it 2768 reads the first block of stage2, modifies it with the values of 2769 the partition STAGE2_FILE was found on (for `p') or places the 2770 string CONFIG_FILE into the area telling the stage2 where to look 2771 for a configuration file at boot time. Likewise, if 2772 REAL_CONFIG_FILE is present and STAGE2_FILE is a Stage 1.5, then 2773 the Stage 2 CONFIG_FILE is patched with the configuration file 2774 name REAL_CONFIG_FILE. This command preserves the DOS BPB (and for 2775 hard disks, the partition table) of the sector the Stage 1 is to 2776 be installed into. 2777 2778 *Caution:* Several buggy BIOSes don't pass a booting drive 2779 properly when booting from a hard disk drive. Therefore, you will 2780 unfortunately have to specify the option `d', whether your Stage2 2781 resides at the booting drive or not, if you have such a BIOS. We 2782 know these are defective in this way: 2783 2784 2785 Fujitsu LifeBook 400 BIOS version 31J0103A 2786 2787 2788 HP Vectra XU 6/200 BIOS version GG.06.11 2789 2790 *Caution2:* A number of BIOSes don't return a correct LBA support 2791 bitmap even if they do have the support. So GRUB provides a 2792 solution to ignore the wrong bitmap, that is, the option 2793 `--force-lba'. Don't use this option if you know that your BIOS 2794 doesn't have LBA support. 2795 2796 *Caution3:* You must specify the option `--stage2' in the grub 2797 shell, if you cannot unmount the filesystem where your stage2 file 2798 resides. The argument should be the file name in your operating 2799 system. 2800 2801 2802File: grub.info, Node: install-Footnotes, Up: install 2803 2804 (1) They're loaded the same way, so we will refer to the Stage 1.5 2805as a Stage 2 from now on. 2806 2807 2808File: grub.info, Node: ioprobe, Next: kernel, Prev: install, Up: Command-line and menu entry commands 2809 281013.3.19 ioprobe 2811--------------- 2812 2813 -- Command: ioprobe drive 2814 Probe I/O ports used for the drive DRIVE. This command will list 2815 the I/O ports on the screen. For technical information, *Note 2816 Internals::. 2817 2818 2819File: grub.info, Node: kernel, Next: lock, Prev: ioprobe, Up: Command-line and menu entry commands 2820 282113.3.20 kernel 2822-------------- 2823 2824 -- Command: kernel [`--type=type'] [`--no-mem-option'] file ... 2825 Attempt to load the primary boot image (Multiboot a.out or ELF, 2826 Linux zImage or bzImage, FreeBSD a.out, NetBSD a.out, etc.) from 2827 FILE. The rest of the line is passed verbatim as the "kernel 2828 command-line". Any modules must be reloaded after using this 2829 command. 2830 2831 This command also accepts the option `--type' so that you can 2832 specify the kernel type of FILE explicitly. The argument TYPE must 2833 be one of these: `netbsd', `freebsd', `openbsd', `linux', 2834 `biglinux', and `multiboot'. However, you need to specify it only 2835 if you want to load a NetBSD ELF kernel, because GRUB can 2836 automatically determine a kernel type in the other cases, quite 2837 safely. 2838 2839 The option `--no-mem-option' is effective only for Linux. If the 2840 option is specified, GRUB doesn't pass the option `mem=' to the 2841 kernel. This option is implied for Linux kernels 2.4.18 and newer. 2842 2843 2844File: grub.info, Node: lock, Next: makeactive, Prev: kernel, Up: Command-line and menu entry commands 2845 284613.3.21 lock 2847------------ 2848 2849 -- Command: lock 2850 Prevent normal users from executing arbitrary menu entries. You 2851 must use the command `password' if you really want this command to 2852 be useful (*note password::). 2853 2854 This command is used in a menu, as shown in this example: 2855 2856 title This entry is too dangerous to be executed by normal users 2857 lock 2858 root (hd0,a) 2859 kernel /no-security-os 2860 2861 See also *Note Security::. 2862 2863 2864File: grub.info, Node: makeactive, Next: map, Prev: lock, Up: Command-line and menu entry commands 2865 286613.3.22 makeactive 2867------------------ 2868 2869 -- Command: makeactive 2870 Set the active partition on the root disk to GRUB's root device. 2871 This command is limited to _primary_ PC partitions on a hard disk. 2872 2873 2874File: grub.info, Node: map, Next: md5crypt, Prev: makeactive, Up: Command-line and menu entry commands 2875 287613.3.23 map 2877----------- 2878 2879 -- Command: map to_drive from_drive 2880 Map the drive FROM_DRIVE to the drive TO_DRIVE. This is necessary 2881 when you chain-load some operating systems, such as DOS, if such 2882 an OS resides at a non-first drive. Here is an example: 2883 2884 grub> map (hd0) (hd1) 2885 grub> map (hd1) (hd0) 2886 2887 The example exchanges the order between the first hard disk and the 2888 second hard disk. See also *Note DOS/Windows::. 2889 2890 2891File: grub.info, Node: md5crypt, Next: module, Prev: map, Up: Command-line and menu entry commands 2892 289313.3.24 md5crypt 2894---------------- 2895 2896 -- Command: md5crypt 2897 Prompt to enter a password, and encrypt it in MD5 format. The 2898 encrypted password can be used with the command `password' (*note 2899 password::). See also *Note Security::. 2900 2901 2902File: grub.info, Node: module, Next: modulenounzip, Prev: md5crypt, Up: Command-line and menu entry commands 2903 290413.3.25 module 2905-------------- 2906 2907 -- Command: module file ... 2908 Load a boot module FILE for a Multiboot format boot image (no 2909 interpretation of the file contents are made, so the user of this 2910 command must know what the kernel in question expects). The rest 2911 of the line is passed as the "module command-line", like the 2912 `kernel' command. You must load a Multiboot kernel image before 2913 loading any module. See also *Note modulenounzip::. 2914 2915 2916File: grub.info, Node: modulenounzip, Next: pause, Prev: module, Up: Command-line and menu entry commands 2917 291813.3.26 modulenounzip 2919--------------------- 2920 2921 -- Command: modulenounzip file ... 2922 The same as `module' (*note module::), except that automatic 2923 decompression is disabled. 2924 2925 2926File: grub.info, Node: pause, Next: quit, Prev: modulenounzip, Up: Command-line and menu entry commands 2927 292813.3.27 pause 2929------------- 2930 2931 -- Command: pause message ... 2932 Print the MESSAGE, then wait until a key is pressed. Note that 2933 placing <^G> (ASCII code 7) in the message will cause the speaker 2934 to emit the standard beep sound, which is useful when prompting 2935 the user to change floppies. 2936 2937 2938File: grub.info, Node: quit, Next: reboot, Prev: pause, Up: Command-line and menu entry commands 2939 294013.3.28 quit 2941------------ 2942 2943 -- Command: quit 2944 Exit from the grub shell `grub' (*note Invoking the grub shell::). 2945 This command can be used only in the grub shell. 2946 2947 2948File: grub.info, Node: reboot, Next: read, Prev: quit, Up: Command-line and menu entry commands 2949 295013.3.29 reboot 2951-------------- 2952 2953 -- Command: reboot 2954 Reboot the computer. 2955 2956 2957File: grub.info, Node: read, Next: root, Prev: reboot, Up: Command-line and menu entry commands 2958 295913.3.30 read 2960------------ 2961 2962 -- Command: read addr 2963 Read a 32-bit value from memory at address ADDR and display it in 2964 hex format. 2965 2966 2967File: grub.info, Node: root, Next: rootnoverify, Prev: read, Up: Command-line and menu entry commands 2968 296913.3.31 root 2970------------ 2971 2972 -- Command: root device [hdbias] 2973 Set the current "root device" to the device DEVICE, then attempt 2974 to mount it to get the partition size (for passing the partition 2975 descriptor in `ES:ESI', used by some chain-loaded boot loaders), 2976 the BSD drive-type (for booting BSD kernels using their native 2977 boot format), and correctly determine the PC partition where a BSD 2978 sub-partition is located. The optional HDBIAS parameter is a 2979 number to tell a BSD kernel how many BIOS drive numbers are on 2980 controllers before the current one. For example, if there is an 2981 IDE disk and a SCSI disk, and your FreeBSD root partition is on 2982 the SCSI disk, then use a `1' for HDBIAS. 2983 2984 See also *Note rootnoverify::. 2985 2986 2987File: grub.info, Node: rootnoverify, Next: savedefault, Prev: root, Up: Command-line and menu entry commands 2988 298913.3.32 rootnoverify 2990-------------------- 2991 2992 -- Command: rootnoverify device [hdbias] 2993 Similar to `root' (*note root::), but don't attempt to mount the 2994 partition. This is useful for when an OS is outside of the area of 2995 the disk that GRUB can read, but setting the correct root device 2996 is still desired. Note that the items mentioned in `root' above 2997 which derived from attempting the mount will _not_ work correctly. 2998 2999 3000File: grub.info, Node: savedefault, Next: setup, Prev: rootnoverify, Up: Command-line and menu entry commands 3001 300213.3.33 savedefault 3003------------------- 3004 3005 -- Command: savedefault num 3006 Save the current menu entry or NUM if specified as a default 3007 entry. Here is an example: 3008 3009 default saved 3010 timeout 10 3011 3012 title GNU/Linux 3013 root (hd0,0) 3014 kernel /boot/vmlinuz root=/dev/sda1 vga=ext 3015 initrd /boot/initrd 3016 savedefault 3017 3018 title FreeBSD 3019 root (hd0,a) 3020 kernel /boot/loader 3021 savedefault 3022 3023 With this configuration, GRUB will choose the entry booted 3024 previously as the default entry. 3025 3026 You can specify `fallback' instead of a number. Then, next 3027 fallback entry is saved. Next fallback entry is chosen from 3028 fallback entries. Normally, this will be the first entry in 3029 fallback ones. 3030 3031 See also *Note default:: and *Note Invoking grub-set-default::. 3032 3033 3034File: grub.info, Node: setup, Next: testload, Prev: savedefault, Up: Command-line and menu entry commands 3035 303613.3.34 setup 3037------------- 3038 3039 -- Command: setup [`--force-lba'] [`--stage2=os_stage2_file'] 3040 [`--prefix=dir'] install_device [image_device] 3041 Set up the installation of GRUB automatically. This command uses 3042 the more flexible command `install' (*note install::) in the 3043 backend and installs GRUB into the device INSTALL_DEVICE. If 3044 IMAGE_DEVICE is specified, then find the GRUB images (*note 3045 Images::) in the device IMAGE_DEVICE, otherwise use the current 3046 "root device", which can be set by the command `root'. If 3047 INSTALL_DEVICE is a hard disk, then embed a Stage 1.5 in the disk 3048 if possible. 3049 3050 The option `--prefix' specifies the directory under which GRUB 3051 images are put. If it is not specified, GRUB automatically 3052 searches them in `/boot/grub' and `/grub'. 3053 3054 The options `--force-lba' and `--stage2' are just passed to 3055 `install' if specified. *Note install::, for more information. 3056 3057 3058File: grub.info, Node: testload, Next: testvbe, Prev: setup, Up: Command-line and menu entry commands 3059 306013.3.35 testload 3061---------------- 3062 3063 -- Command: testload file 3064 Read the entire contents of FILE in several different ways and 3065 compare them, to test the filesystem code. The output is somewhat 3066 cryptic, but if no errors are reported and the final `i=X, 3067 filepos=Y' reading has X and Y equal, then it is definitely 3068 consistent, and very likely works correctly subject to a 3069 consistent offset error. If this test succeeds, then a good next 3070 step is to try loading a kernel. 3071 3072 3073File: grub.info, Node: testvbe, Next: uppermem, Prev: testload, Up: Command-line and menu entry commands 3074 307513.3.36 testvbe 3076--------------- 3077 3078 -- Command: testvbe mode 3079 Test the VESA BIOS EXTENSION mode MODE. This command will switch 3080 your video card to the graphics mode, and show an endless 3081 animation. Hit any key to return. See also *Note vbeprobe::. 3082 3083 3084File: grub.info, Node: uppermem, Next: vbeprobe, Prev: testvbe, Up: Command-line and menu entry commands 3085 308613.3.37 uppermem 3087---------------- 3088 3089 -- Command: uppermem kbytes 3090 Force GRUB to assume that only KBYTES kilobytes of upper memory 3091 are installed. Any system address range maps are discarded. 3092 3093 *Caution:* This should be used with great caution, and should only 3094 be necessary on some old machines. GRUB's BIOS probe can pick up 3095 all RAM on all new machines the author has ever heard of. It can 3096 also be used for debugging purposes to lie to an OS. 3097 3098 3099File: grub.info, Node: vbeprobe, Prev: uppermem, Up: Command-line and menu entry commands 3100 310113.3.38 vbeprobe 3102---------------- 3103 3104 -- Command: vbeprobe [mode] 3105 Probe VESA BIOS EXTENSION information. If the mode MODE is 3106 specified, show only the information about MODE. Otherwise, this 3107 command lists up available VBE modes on the screen. See also *Note 3108 testvbe::. 3109 3110 3111File: grub.info, Node: Troubleshooting, Next: Invoking the grub shell, Prev: Commands, Up: Top 3112 311314 Error messages reported by GRUB 3114********************************** 3115 3116This chapter describes error messages reported by GRUB when you 3117encounter trouble. *Note Invoking the grub shell::, if your problem is 3118specific to the grub shell. 3119 3120* Menu: 3121 3122* Stage1 errors:: Errors reported by the Stage 1 3123* Stage1.5 errors:: Errors reported by the Stage 1.5 3124* Stage2 errors:: Errors reported by the Stage 2 3125 3126 3127File: grub.info, Node: Stage1 errors, Next: Stage1.5 errors, Up: Troubleshooting 3128 312914.1 Errors reported by the Stage 1 3130=================================== 3131 3132The general way that the Stage 1 handles errors is to print an error 3133string and then halt. Pressing `<CTRL>-<ALT>-<DEL>' will reboot. 3134 3135 The following is a comprehensive list of error messages for the 3136Stage 1: 3137 3138Hard Disk Error 3139 The stage2 or stage1.5 is being read from a hard disk, and the 3140 attempt to determine the size and geometry of the hard disk failed. 3141 3142Floppy Error 3143 The stage2 or stage1.5 is being read from a floppy disk, and the 3144 attempt to determine the size and geometry of the floppy disk 3145 failed. It's listed as a separate error since the probe sequence 3146 is different than for hard disks. 3147 3148Read Error 3149 A disk read error happened while trying to read the stage2 or 3150 stage1.5. 3151 3152Geom Error 3153 The location of the stage2 or stage1.5 is not in the portion of 3154 the disk supported directly by the BIOS read calls. This could 3155 occur because the BIOS translated geometry has been changed by the 3156 user or the disk is moved to another machine or controller after 3157 installation, or GRUB was not installed using itself (if it was, 3158 the Stage 2 version of this error would have been seen during that 3159 process and it would not have completed the install). 3160 3161 3162File: grub.info, Node: Stage1.5 errors, Next: Stage2 errors, Prev: Stage1 errors, Up: Troubleshooting 3163 316414.2 Errors reported by the Stage 1.5 3165===================================== 3166 3167The general way that the Stage 1.5 handles errors is to print an error 3168number in the form `Error NUM' and then halt. Pressing 3169`<CTRL>-<ALT>-<DEL>' will reboot. 3170 3171 The error numbers correspond to the errors reported by Stage 2. 3172*Note Stage2 errors::. 3173 3174 3175File: grub.info, Node: Stage2 errors, Prev: Stage1.5 errors, Up: Troubleshooting 3176 317714.3 Errors reported by the Stage 2 3178=================================== 3179 3180The general way that the Stage 2 handles errors is to abort the 3181operation in question, print an error string, then (if possible) either 3182continue based on the fact that an error occurred or wait for the user 3183to deal with the error. 3184 3185 The following is a comprehensive list of error messages for the 3186Stage 2 (error numbers for the Stage 1.5 are listed before the colon in 3187each description): 3188 31891 : Filename must be either an absolute filename or blocklist 3190 This error is returned if a file name is requested which doesn't 3191 fit the syntax/rules listed in the *Note Filesystem::. 3192 31932 : Bad file or directory type 3194 This error is returned if a file requested is not a regular file, 3195 but something like a symbolic link, directory, or FIFO. 3196 31973 : Bad or corrupt data while decompressing file 3198 This error is returned if the run-length decompression code gets an 3199 internal error. This is usually from a corrupt file. 3200 32014 : Bad or incompatible header in compressed file 3202 This error is returned if the file header for a supposedly 3203 compressed file is bad. 3204 32055 : Partition table invalid or corrupt 3206 This error is returned if the sanity checks on the integrity of the 3207 partition table fail. This is a bad sign. 3208 32096 : Mismatched or corrupt version of stage1/stage2 3210 This error is returned if the install command points to 3211 incompatible or corrupt versions of the stage1 or stage2. It can't 3212 detect corruption in general, but this is a sanity check on the 3213 version numbers, which should be correct. 3214 32157 : Loading below 1MB is not supported 3216 This error is returned if the lowest address in a kernel is below 3217 the 1MB boundary. The Linux zImage format is a special case and 3218 can be handled since it has a fixed loading address and maximum 3219 size. 3220 32218 : Kernel must be loaded before booting 3222 This error is returned if GRUB is told to execute the boot sequence 3223 without having a kernel to start. 3224 32259 : Unknown boot failure 3226 This error is returned if the boot attempt did not succeed for 3227 reasons which are unknown. 3228 322910 : Unsupported Multiboot features requested 3230 This error is returned when the Multiboot features word in the 3231 Multiboot header requires a feature that is not recognized. The 3232 point of this is that the kernel requires special handling which 3233 GRUB is probably unable to provide. 3234 323511 : Unrecognized device string 3236 This error is returned if a device string was expected, and the 3237 string encountered didn't fit the syntax/rules listed in the *Note 3238 Filesystem::. 3239 324012 : Invalid device requested 3241 This error is returned if a device string is recognizable but does 3242 not fall under the other device errors. 3243 324413 : Invalid or unsupported executable format 3245 This error is returned if the kernel image being loaded is not 3246 recognized as Multiboot or one of the supported native formats 3247 (Linux zImage or bzImage, FreeBSD, or NetBSD). 3248 324914 : Filesystem compatibility error, cannot read whole file 3250 Some of the filesystem reading code in GRUB has limits on the 3251 length of the files it can read. This error is returned when the 3252 user runs into such a limit. 3253 325415 : File not found 3255 This error is returned if the specified file name cannot be found, 3256 but everything else (like the disk/partition info) is OK. 3257 325816 : Inconsistent filesystem structure 3259 This error is returned by the filesystem code to denote an internal 3260 error caused by the sanity checks of the filesystem structure on 3261 disk not matching what it expects. This is usually caused by a 3262 corrupt filesystem or bugs in the code handling it in GRUB. 3263 326417 : Cannot mount selected partition 3265 This error is returned if the partition requested exists, but the 3266 filesystem type cannot be recognized by GRUB. 3267 326818 : Selected cylinder exceeds maximum supported by BIOS 3269 This error is returned when a read is attempted at a linear block 3270 address beyond the end of the BIOS translated area. This generally 3271 happens if your disk is larger than the BIOS can handle (512MB for 3272 (E)IDE disks on older machines or larger than 8GB in general). 3273 327419 : Linux kernel must be loaded before initrd 3275 This error is returned if the initrd command is used before 3276 loading a Linux kernel. 3277 327820 : Multiboot kernel must be loaded before modules 3279 This error is returned if the module load command is used before 3280 loading a Multiboot kernel. It only makes sense in this case 3281 anyway, as GRUB has no idea how to communicate the presence of 3282 such modules to a non-Multiboot-aware kernel. 3283 328421 : Selected disk does not exist 3285 This error is returned if the device part of a device- or full 3286 file name refers to a disk or BIOS device that is not present or 3287 not recognized by the BIOS in the system. 3288 328922 : No such partition 3290 This error is returned if a partition is requested in the device 3291 part of a device- or full file name which isn't on the selected 3292 disk. 3293 329423 : Error while parsing number 3295 This error is returned if GRUB was expecting to read a number and 3296 encountered bad data. 3297 329824 : Attempt to access block outside partition 3299 This error is returned if a linear block address is outside of the 3300 disk partition. This generally happens because of a corrupt 3301 filesystem on the disk or a bug in the code handling it in GRUB 3302 (it's a great debugging tool). 3303 330425 : Disk read error 3305 This error is returned if there is a disk read error when trying to 3306 probe or read data from a particular disk. 3307 330826 : Too many symbolic links 3309 This error is returned if the link count is beyond the maximum 3310 (currently 5), possibly the symbolic links are looped. 3311 331227 : Unrecognized command 3313 This error is returned if an unrecognized command is entered on the 3314 command-line or in a boot sequence section of a configuration file 3315 and that entry is selected. 3316 331728 : Selected item cannot fit into memory 3318 This error is returned if a kernel, module, or raw file load 3319 command is either trying to load its data such that it won't fit 3320 into memory or it is simply too big. 3321 332229 : Disk write error 3323 This error is returned if there is a disk write error when trying 3324 to write to a particular disk. This would generally only occur 3325 during an install of set active partition command. 3326 332730 : Invalid argument 3328 This error is returned if an argument specified to a command is 3329 invalid. 3330 333131 : File is not sector aligned 3332 This error may occur only when you access a ReiserFS partition by 3333 block-lists (e.g. the command `install'). In this case, you should 3334 mount the partition with the `-o notail' option. 3335 333632 : Must be authenticated 3337 This error is returned if you try to run a locked entry. You should 3338 enter a correct password before running such an entry. 3339 334033 : Serial device not configured 3341 This error is returned if you try to change your terminal to a 3342 serial one before initializing any serial device. 3343 334434 : No spare sectors on the disk 3345 This error is returned if a disk doesn't have enough spare space. 3346 This happens when you try to embed Stage 1.5 into the unused 3347 sectors after the MBR, but the first partition starts right after 3348 the MBR or they are used by EZ-BIOS. 3349 3350 3351File: grub.info, Node: Invoking the grub shell, Next: Invoking grub-install, Prev: Troubleshooting, Up: Top 3352 335315 Invoking the grub shell 3354************************** 3355 3356This chapter documents the grub shell `grub'. Note that the grub shell 3357is an emulator; it doesn't run under the native environment, so it 3358sometimes does something wrong. Therefore, you shouldn't trust it too 3359much. If there is anything wrong with it, don't hesitate to try the 3360native GRUB environment, especially when it guesses a wrong map between 3361BIOS drives and OS devices. 3362 3363* Menu: 3364 3365* Basic usage:: How to use the grub shell 3366* Installation under UNIX:: How to install GRUB via `grub' 3367* Device map:: The map between BIOS drives and OS devices 3368 3369 3370File: grub.info, Node: Basic usage, Next: Installation under UNIX, Up: Invoking the grub shell 3371 337215.1 Introduction into the grub shell 3373===================================== 3374 3375You can use the command `grub' for installing GRUB under your operating 3376systems and for a testbed when you add a new feature into GRUB or when 3377fixing a bug. `grub' is almost the same as the Stage 2, and, in fact, 3378it shares the source code with the Stage 2 and you can use the same 3379commands (*note Commands::) in `grub'. It is emulated by replacing BIOS 3380calls with UNIX system calls and libc functions. 3381 3382 The command `grub' accepts the following options: 3383 3384`--help' 3385 Print a summary of the command-line options and exit. 3386 3387`--version' 3388 Print the version number of GRUB and exit. 3389 3390`--verbose' 3391 Print some verbose messages for debugging purpose. 3392 3393`--device-map=FILE' 3394 Use the device map file FILE. The format is described in *Note 3395 Device map::. 3396 3397`--no-floppy' 3398 Do not probe any floppy drive. This option has no effect if the 3399 option `--device-map' is specified (*note Device map::). 3400 3401`--probe-second-floppy' 3402 Probe the second floppy drive. If this option is not specified, 3403 the grub shell does not probe it, as that sometimes takes a long 3404 time. If you specify the device map file (*note Device map::), the 3405 grub shell just ignores this option. 3406 3407`--config-file=FILE' 3408 Read the configuration file FILE instead of `/boot/grub/menu.lst'. 3409 The format is the same as the normal GRUB syntax. See *Note 3410 Filesystem::, for more information. 3411 3412`--boot-drive=DRIVE' 3413 Set the stage2 BOOT_DRIVE to DRIVE. This argument should be an 3414 integer (decimal, octal or hexadecimal). 3415 3416`--install-partition=PAR' 3417 Set the stage2 INSTALL_PARTITION to PAR. This argument should be 3418 an integer (decimal, octal or hexadecimal). 3419 3420`--no-config-file' 3421 Do not use the configuration file even if it can be read. 3422 3423`--no-curses' 3424 Do not use the screen handling interface by the curses even if it 3425 is available. 3426 3427`--batch' 3428 This option has the same meaning as `--no-config-file --no-curses'. 3429 3430`--read-only' 3431 Disable writing to any disk. 3432 3433`--hold' 3434 Wait until a debugger will attach. This option is useful when you 3435 want to debug the startup code. 3436 3437 3438File: grub.info, Node: Installation under UNIX, Next: Device map, Prev: Basic usage, Up: Invoking the grub shell 3439 344015.2 How to install GRUB via `grub' 3441=================================== 3442 3443The installation procedure is the same as under the "native" Stage 2. 3444*Note Installation::, for more information. The command `grub'-specific 3445information is described here. 3446 3447 What you should be careful about is "buffer cache". `grub' makes use 3448of raw devices instead of filesystems that your operating systems 3449serve, so there exists a potential problem that some cache 3450inconsistency may corrupt your filesystems. What we recommend is: 3451 3452 * If you can unmount drives to which GRUB may write any amount of 3453 data, unmount them before running `grub'. 3454 3455 * If a drive cannot be unmounted but can be mounted with the 3456 read-only flag, mount it in read-only mode. That should be secure. 3457 3458 * If a drive must be mounted with the read-write flag, make sure 3459 that no activity is being done on it while the command `grub' is 3460 running. 3461 3462 * Reboot your operating system as soon as possible. This is probably 3463 not required if you follow the rules above, but reboot is the most 3464 secure way. 3465 3466 In addition, enter the command `quit' when you finish the 3467installation. That is _very important_ because `quit' makes the buffer 3468cache consistent. Do not push <C-c>. 3469 3470 If you want to install GRUB non-interactively, specify `--batch' 3471option in the command-line. This is a simple example: 3472 3473 #!/bin/sh 3474 3475 # Use /usr/sbin/grub if you are on an older system. 3476 /sbin/grub --batch <<EOT 1>/dev/null 2>/dev/null 3477 root (hd0,0) 3478 setup (hd0) 3479 quit 3480 EOT 3481 3482 3483File: grub.info, Node: Device map, Prev: Installation under UNIX, Up: Invoking the grub shell 3484 348515.3 The map between BIOS drives and OS devices 3486=============================================== 3487 3488When you specify the option `--device-map' (*note Basic usage::), the 3489grub shell creates the "device map file" automatically unless it 3490already exists. The file name `/boot/grub/device.map' is preferred. 3491 3492 If the device map file exists, the grub shell reads it to map BIOS 3493drives to OS devices. This file consists of lines like this: 3494 3495 DEVICE FILE 3496 3497 DEVICE is a drive specified in the GRUB syntax (*note Device 3498syntax::), and FILE is an OS file, which is normally a device file. 3499 3500 The reason why the grub shell gives you the device map file is that 3501it cannot guess the map between BIOS drives and OS devices correctly in 3502some environments. For example, if you exchange the boot sequence 3503between IDE and SCSI in your BIOS, it gets the order wrong. 3504 3505 Thus, edit the file if the grub shell makes a mistake. You can put 3506any comments in the file if needed, as the grub shell assumes that a 3507line is just a comment if the first character is `#'. 3508 3509 3510File: grub.info, Node: Invoking grub-install, Next: Invoking grub-md5-crypt, Prev: Invoking the grub shell, Up: Top 3511 351216 Invoking grub-install 3513************************ 3514 3515The program `grub-install' installs GRUB on your drive using the grub 3516shell (*note Invoking the grub shell::). You must specify the device 3517name on which you want to install GRUB, like this: 3518 3519 grub-install INSTALL_DEVICE 3520 3521 The device name INSTALL_DEVICE is an OS device name or a GRUB device 3522name. 3523 3524 `grub-install' accepts the following options: 3525 3526`--help' 3527 Print a summary of the command-line options and exit. 3528 3529`--version' 3530 Print the version number of GRUB and exit. 3531 3532`--force-lba' 3533 Force GRUB to use LBA mode even for a buggy BIOS. Use this option 3534 only if your BIOS doesn't work properly in LBA mode even though it 3535 supports LBA mode. 3536 3537`--root-directory=DIR' 3538 Install GRUB images under the directory DIR instead of the root 3539 directory. This option is useful when you want to install GRUB 3540 into a separate partition or a removable disk. Here is an example 3541 in which you have a separate "boot" partition which is mounted on 3542 `/boot': 3543 3544 grub-install --root-directory=/boot hd0 3545 3546`--grub-shell=FILE' 3547 Use FILE as the grub shell. You can append arbitrary options to 3548 FILE after the file name, like this: 3549 3550 grub-install --grub-shell="grub --read-only" /dev/fd0 3551 3552`--recheck' 3553 Recheck the device map, even if `/boot/grub/device.map' already 3554 exists. You should use this option whenever you add/remove a disk 3555 into/from your computer. 3556 3557 3558File: grub.info, Node: Invoking grub-md5-crypt, Next: Invoking grub-terminfo, Prev: Invoking grub-install, Up: Top 3559 356017 Invoking grub-md5-crypt 3561************************** 3562 3563The program `grub-md5-crypt' encrypts a password in MD5 format. This 3564is just a frontend of the grub shell (*note Invoking the grub shell::). 3565Passwords encrypted by this program can be used with the command 3566`password' (*note password::). 3567 3568 `grub-md5-crypt' accepts the following options: 3569 3570`--help' 3571 Print a summary of the command-line options and exit. 3572 3573`--version' 3574 Print the version information and exit. 3575 3576`--grub-shell=FILE' 3577 Use FILE as the grub shell. 3578 3579 3580File: grub.info, Node: Invoking grub-terminfo, Next: Invoking grub-set-default, Prev: Invoking grub-md5-crypt, Up: Top 3581 358218 Invoking grub-terminfo 3583************************* 3584 3585The program `grub-terminfo' generates a terminfo command from a 3586terminfo name (*note terminfo::). The result can be used in the 3587configuration file, to define escape sequences. Because GRUB assumes 3588that your terminal is vt100-compatible by default, this would be useful 3589only if your terminal is uncommon (such as vt52). 3590 3591 `grub-terminfo' accepts the following options: 3592 3593`--help' 3594 Print a summary of the command-line options and exit. 3595 3596`--version' 3597 Print the version information and exit. 3598 3599 You must specify one argument to this command. For example: 3600 3601 grub-terminfo vt52 3602 3603 3604File: grub.info, Node: Invoking grub-set-default, Next: Invoking mbchk, Prev: Invoking grub-terminfo, Up: Top 3605 360619 Invoking grub-set-default 3607**************************** 3608 3609The program `grub-set-default' sets the default boot entry for GRUB. 3610This automatically creates a file named `default' under your GRUB 3611directory (i.e. `/boot/grub'), if it is not present. This file is used 3612to determine the default boot entry when GRUB boots up your system when 3613you use `default saved' in your configuration file (*note default::), 3614and to save next default boot entry when you use `savedefault' in a 3615boot entry (*note savedefault::). 3616 3617 `grub-set-default' accepts the following options: 3618 3619`--help' 3620 Print a summary of the command-line options and exit. 3621 3622`--version' 3623 Print the version information and exit. 3624 3625`--root-directory=DIR' 3626 Use the directory DIR instead of the root directory (i.e. `/') to 3627 define the location of the default file. This is useful when you 3628 mount a disk which is used for another system. 3629 3630 You must specify a single argument to `grub-set-default'. This 3631argument is normally the number of a default boot entry. For example, 3632if you have this configuration file: 3633 3634 default saved 3635 timeout 10 3636 3637 title GNU/Hurd 3638 root (hd0,0) 3639 ... 3640 3641 title GNU/Linux 3642 root (hd0,1) 3643 ... 3644 3645 and if you want to set the next default boot entry to GNU/Linux, you 3646may execute this command: 3647 3648 grub-set-default 1 3649 3650 Because the entry for GNU/Linux is `1'. Note that entries are 3651counted from zero. So, if you want to specify GNU/Hurd here, then you 3652should specify `0'. 3653 3654 This feature is very useful if you want to test a new kernel or to 3655make your system quite robust. *Note Making your system robust::, for 3656more hints about how to set up a robust system. 3657 3658 3659File: grub.info, Node: Invoking mbchk, Next: Obtaining and Building GRUB, Prev: Invoking grub-set-default, Up: Top 3660 366120 Invoking mbchk 3662***************** 3663 3664The program `mbchk' checks for the format of a Multiboot kernel. We 3665recommend using this program before booting your own kernel by GRUB. 3666 3667 `mbchk' accepts the following options: 3668 3669`--help' 3670 Print a summary of the command-line options and exit. 3671 3672`--version' 3673 Print the version number of GRUB and exit. 3674 3675`--quiet' 3676 Suppress all normal output. 3677 3678 3679File: grub.info, Node: Obtaining and Building GRUB, Next: Reporting bugs, Prev: Invoking mbchk, Up: Top 3680 3681Appendix A How to obtain and build GRUB 3682*************************************** 3683 3684 *Caution:* GRUB requires binutils-2.9.1.0.23 or later because the 3685 GNU assembler has been changed so that it can produce real 16bits 3686 machine code between 2.9.1 and 2.9.1.0.x. See 3687 `http://sources.redhat.com/binutils/', to obtain information on 3688 how to get the latest version. 3689 3690 GRUB is available from the GNU alpha archive site 3691`ftp://alpha.gnu.org/gnu/grub' or any of its mirrors. The file will be 3692named grub-version.tar.gz. The current version is 0.97, so the file you 3693should grab is: 3694 3695 `ftp://alpha.gnu.org/gnu/grub/grub-0.97.tar.gz' 3696 3697 To unbundle GRUB use the instruction: 3698 3699 zcat grub-0.97.tar.gz | tar xvf - 3700 3701 which will create a directory called `grub-0.97' with all the 3702sources. You can look at the file `INSTALL' for detailed instructions 3703on how to build and install GRUB, but you should be able to just do: 3704 3705 cd grub-0.97 3706 ./configure 3707 make install 3708 3709 This will install the grub shell `grub' (*note Invoking the grub 3710shell::), the Multiboot checker `mbchk' (*note Invoking mbchk::), and 3711the GRUB images. This will also install the GRUB manual. 3712 3713 Also, the latest version is available from the CVS. See 3714`http://savannah.gnu.org/cvs/?group=grub' for more information. 3715 3716 3717File: grub.info, Node: Reporting bugs, Next: Future, Prev: Obtaining and Building GRUB, Up: Top 3718 3719Appendix B Reporting bugs 3720************************* 3721 3722These are the guideline for how to report bugs. Take a look at this 3723list below before you submit bugs: 3724 3725 1. Before getting unsettled, read this manual through and through. 3726 Also, see the GNU GRUB FAQ 3727 (http://www.gnu.org/software/grub/grub-faq.html). 3728 3729 2. Always mention the information on your GRUB. The version number 3730 and the configuration are quite important. If you build it 3731 yourself, write the options specified to the configure script and 3732 your operating system, including the versions of gcc and binutils. 3733 3734 3. If you have trouble with the installation, inform us of how you 3735 installed GRUB. Don't omit error messages, if any. Just `GRUB hangs 3736 up when it boots' is not enough. 3737 3738 The information on your hardware is also essential. These are 3739 especially important: the geometries and the partition tables of 3740 your hard disk drives and your BIOS. 3741 3742 4. If GRUB cannot boot your operating system, write down _everything_ 3743 you see on the screen. Don't paraphrase them, like `The foo OS 3744 crashes with GRUB, even though it can boot with the bar boot 3745 loader just fine'. Mention the commands you executed, the messages 3746 printed by them, and information on your operating system 3747 including the version number. 3748 3749 5. Explain what you wanted to do. It is very useful to know your 3750 purpose and your wish, and how GRUB didn't satisfy you. 3751 3752 6. If you can investigate the problem yourself, please do. That will 3753 give you and us much more information on the problem. Attaching a 3754 patch is even better. 3755 3756 When you attach a patch, make the patch in unified diff format, and 3757 write ChangeLog entries. But, even when you make a patch, don't 3758 forget to explain the problem, so that we can understand what your 3759 patch is for. 3760 3761 7. Write down anything that you think might be related. Please 3762 understand that we often need to reproduce the same problem you 3763 encounterred in our environment. So your information should be 3764 sufficient for us to do the same thing--Don't forget that we 3765 cannot see your computer directly. If you are not sure whether to 3766 state a fact or leave it out, state it! Reporting too many things 3767 is much better than omitting something important. 3768 3769 If you follow the guideline above, submit a report to the Bug 3770Tracking System (http://savannah.gnu.org/bugs/?group=grub). 3771Alternatively, you can submit a report via electronic mail to 3772<bug-grub@gnu.org>, but we strongly recommend that you use the Bug 3773Tracking System, because e-mail can be passed over easily. 3774 3775 Once we get your report, we will try to fix the bugs. 3776 3777 3778File: grub.info, Node: Future, Next: Internals, Prev: Reporting bugs, Up: Top 3779 3780Appendix C Where GRUB will go 3781***************************** 3782 3783We started the next generation of GRUB, GRUB 2. This will include 3784internationalization, dynamic module loading, real memory management, 3785multiple architecture support, a scripting language, and many other 3786nice feature. If you are interested in the development of GRUB 2, take 3787a look at the homepage (http://www.gnu.org/software/grub/grub.html). 3788 3789 3790File: grub.info, Node: Internals, Next: Index, Prev: Future, Up: Top 3791 3792Appendix D Hacking GRUB 3793*********************** 3794 3795This chapter documents the user-invisible aspect of GRUB. 3796 3797 As a general rule of software development, it is impossible to keep 3798the descriptions of the internals up-to-date, and it is quite hard to 3799document everything. So refer to the source code, whenever you are not 3800satisfied with this documentation. Please assume that this gives just 3801hints to you. 3802 3803* Menu: 3804 3805* Memory map:: The memory map of various components 3806* Embedded data:: Embedded variables in GRUB 3807* Filesystem interface:: The generic interface for filesystems 3808* Command interface:: The generic interface for built-ins 3809* Bootstrap tricks:: The bootstrap mechanism used in GRUB 3810* I/O ports detection:: How to probe I/O ports used by INT 13H 3811* Memory detection:: How to detect all installed RAM 3812* Low-level disk I/O:: INT 13H disk I/O interrupts 3813* MBR:: The structure of Master Boot Record 3814* Partition table:: The format of partition tables 3815* Submitting patches:: Where and how you should send patches 3816 3817 3818File: grub.info, Node: Memory map, Next: Embedded data, Up: Internals 3819 3820D.1 The memory map of various components 3821======================================== 3822 3823GRUB consists of two distinct components, called "stages", which are 3824loaded at different times in the boot process. Because they run 3825mutual-exclusively, sometimes a memory area overlaps with another 3826memory area. And, even in one stage, a single memory area can be used 3827for various purposes, because their usages are mutually exclusive. 3828 3829 Here is the memory map of the various components: 3830 38310 to 4K-1 3832 BIOS and real mode interrupts 3833 38340x07BE to 0x07FF 3835 Partition table passed to another boot loader 3836 3837down from 8K-1 3838 Real mode stack 3839 38400x2000 to ? 3841 The optional Stage 1.5 is loaded here 3842 38430x2000 to 0x7FFF 3844 Command-line buffer for Multiboot kernels and modules 3845 38460x7C00 to 0x7DFF 3847 Stage 1 is loaded here by BIOS or another boot loader 3848 38490x7F00 to 0x7F42 3850 LBA drive parameters 3851 38520x8000 to ? 3853 Stage2 is loaded here 3854 3855The end of Stage 2 to 416K-1 3856 Heap, in particular used for the menu 3857 3858down from 416K-1 3859 Protected mode stack 3860 3861416K to 448K-1 3862 Filesystem buffer 3863 3864448K to 479.5K-1 3865 Raw device buffer 3866 3867479.5K to 480K-1 3868 512-byte scratch area 3869 3870480K to 512K-1 3871 Buffers for various functions, such as password, command-line, cut 3872 and paste, and completion. 3873 3874The last 1K of lower memory 3875 Disk swapping code and data 3876 3877 See the file `stage2/shared.h', for more information. 3878 3879 3880File: grub.info, Node: Embedded data, Next: Filesystem interface, Prev: Memory map, Up: Internals 3881 3882D.2 Embedded variables in GRUB 3883============================== 3884 3885Stage 1 and Stage 2 have embedded variables whose locations are 3886well-defined, so that the installation can patch the binary file 3887directly without recompilation of the stages. 3888 3889 In Stage 1, these are defined: 3890 3891`0x3E' 3892 The version number (not GRUB's, but the installation mechanism's). 3893 3894`0x40' 3895 The boot drive. If it is 0xFF, use a drive passed by BIOS. 3896 3897`0x41' 3898 The flag for if forcing LBA. 3899 3900`0x42' 3901 The starting address of Stage 2. 3902 3903`0x44' 3904 The first sector of Stage 2. 3905 3906`0x48' 3907 The starting segment of Stage 2. 3908 3909`0x1FE' 3910 The signature (`0xAA55'). 3911 3912 See the file `stage1/stage1.S', for more information. 3913 3914 In the first sector of Stage 1.5 and Stage 2, the block lists are 3915recorded between `firstlist' and `lastlist'. The address of `lastlist' 3916is determined when assembling the file `stage2/start.S'. 3917 3918 The trick here is that it is actually read backward, and the first 39198-byte block list is not read here, but after the pointer is decremented 39208 bytes, then after reading it, it decrements again, reads, and so on, 3921until it is finished. The terminating condition is when the number of 3922sectors to be read in the next block list is zero. 3923 3924 The format of a block list can be seen from the example in the code 3925just before the `firstlist' label. Note that it is always from the 3926beginning of the disk, but _not_ relative to the partition boundaries. 3927 3928 In the second sector of Stage 1.5 and Stage 2, these are defined: 3929 3930`0x6' 3931 The version number (likewise, the installation mechanism's). 3932 3933`0x8' 3934 The installed partition. 3935 3936`0xC' 3937 The saved entry number. 3938 3939`0x10' 3940 The identifier. 3941 3942`0x11' 3943 The flag for if forcing LBA. 3944 3945`0x12' 3946 The version string (GRUB's). 3947 3948`0x12' + "the length of the version string" 3949 The name of a configuration file. 3950 3951 See the file `stage2/asm.S', for more information. 3952 3953 3954File: grub.info, Node: Filesystem interface, Next: Command interface, Prev: Embedded data, Up: Internals 3955 3956D.3 The generic interface for filesystems 3957========================================= 3958 3959For any particular partition, it is presumed that only one of the 3960"normal" filesystems such as FAT, FFS, or ext2fs can be used, so there 3961is a switch table managed by the functions in `disk_io.c'. The notation 3962is that you can only "mount" one at a time. 3963 3964 The block list filesystem has a special place in the system. In 3965addition to the "normal" filesystem (or even without one mounted), you 3966can access disk blocks directly (in the indicated partition) via the 3967block list notation. Using the block list filesystem doesn't effect any 3968other filesystem mounts. 3969 3970 The variables which can be read by the filesystem backend are: 3971 3972`current_drive' 3973 The current BIOS drive number (numbered from 0, if a floppy, and 3974 numbered from 0x80, if a hard disk). 3975 3976`current_partition' 3977 The current partition number. 3978 3979`current_slice' 3980 The current partition type. 3981 3982`saved_drive' 3983 The "drive" part of the root device. 3984 3985`saved_partition' 3986 The "partition" part of the root device. 3987 3988`part_start' 3989 The current partition starting address, in sectors. 3990 3991`part_length' 3992 The current partition length, in sectors. 3993 3994`print_possibilities' 3995 True when the `dir' function should print the possible completions 3996 of a file, and false when it should try to actually open a file of 3997 that name. 3998 3999`FSYS_BUF' 4000 Filesystem buffer which is 32K in size, to use in any way which the 4001 filesystem backend desires. 4002 4003 The variables which need to be written by a filesystem backend are: 4004 4005`filepos' 4006 The current position in the file, in sectors. 4007 4008 *Caution:* the value of FILEPOS can be changed out from under the 4009 filesystem code in the current implementation. Don't depend on it 4010 being the same for later calls into the backend code! 4011 4012`filemax' 4013 The length of the file. 4014 4015`disk_read_func' 4016 The value of DISK_READ_HOOK _only_ during reading of data for the 4017 file, not any other fs data, inodes, FAT tables, whatever, then 4018 set to `NULL' at all other times (it will be `NULL' by default). 4019 If this isn't done correctly, then the `testload' and `install' 4020 commands won't work correctly. 4021 4022 The functions expected to be used by the filesystem backend are: 4023 4024`devread' 4025 Only read sectors from within a partition. Sector 0 is the first 4026 sector in the partition. 4027 4028`grub_read' 4029 If the backend uses the block list code, then `grub_read' can be 4030 used, after setting BLOCK_FILE to 1. 4031 4032`print_a_completion' 4033 If PRINT_POSSIBILITIES is true, call `print_a_completion' for each 4034 possible file name. Otherwise, the file name completion won't work. 4035 4036 The functions expected to be defined by the filesystem backend are 4037described at least moderately in the file `filesys.h'. Their usage is 4038fairly evident from their use in the functions in `disk_io.c', look for 4039the use of the FSYS_TABLE array. 4040 4041 *Caution:* The semantics are such that then `mount'ing the 4042filesystem, presume the filesystem buffer `FSYS_BUF' is corrupted, and 4043(re-)load all important contents. When opening and reading a file, 4044presume that the data from the `mount' is available, and doesn't get 4045corrupted by the open/read (i.e. multiple opens and/or reads will be 4046done with only one mount if in the same filesystem). 4047 4048 4049File: grub.info, Node: Command interface, Next: Bootstrap tricks, Prev: Filesystem interface, Up: Internals 4050 4051D.4 The generic interface for built-ins 4052======================================= 4053 4054GRUB built-in commands are defined in a uniformal interface, whether 4055they are menu-specific or can be used anywhere. The definition of a 4056builtin command consists of two parts: the code itself and the table of 4057the information. 4058 4059 The code must be a function which takes two arguments, a command-line 4060string and flags, and returns an `int' value. The "flags" argument 4061specifies how the function is called, using a bit mask. The return 4062value must be zero if successful, otherwise non-zero. So it is normally 4063enough to return ERRNUM. 4064 4065 The table of the information is represented by the structure `struct 4066builtin', which contains the name of the command, a pointer to the 4067function, flags, a short description of the command and a long 4068description of the command. Since the descriptions are used only for 4069help messages interactively, you don't have to define them, if the 4070command may not be called interactively (such as `title'). 4071 4072 The table is finally registered in the table BUILTIN_TABLE, so that 4073`run_script' and `enter_cmdline' can find the command. See the files 4074`cmdline.c' and `builtins.c', for more details. 4075 4076 4077File: grub.info, Node: Bootstrap tricks, Next: I/O ports detection, Prev: Command interface, Up: Internals 4078 4079D.5 The bootstrap mechanism used in GRUB 4080======================================== 4081 4082The disk space can be used in a boot loader is very restricted because 4083a MBR (*note MBR::) is only 512 bytes but it also contains a partition 4084table (*note Partition table::) and a BPB. So the question is how to 4085make a boot loader code enough small to be fit in a MBR. 4086 4087 However, GRUB is a very large program, so we break GRUB into 2 (or 3) 4088distinct components, "Stage 1" and "Stage 2" (and optionally "Stage 40891.5"). *Note Memory map::, for more information. 4090 4091 We embed Stage 1 in a MBR or in the boot sector of a partition, and 4092place Stage 2 in a filesystem. The optional Stage 1.5 can be installed 4093in a filesystem, in the "boot loader" area in a FFS or a ReiserFS, and 4094in the sectors right after a MBR, because Stage 1.5 is enough small and 4095the sectors right after a MBR is normally an unused region. The size of 4096this region is the number of sectors per head minus 1. 4097 4098 Thus, all Stage1 must do is just load Stage2 or Stage1.5. But even if 4099Stage 1 needs not to support the user interface or the filesystem 4100interface, it is impossible to make Stage 1 less than 400 bytes, because 4101GRUB should support both the CHS mode and the LBA mode (*note Low-level 4102disk I/O::). 4103 4104 The solution used by GRUB is that Stage 1 loads only the first 4105sector of Stage 2 (or Stage 1.5) and Stage 2 itself loads the rest. The 4106flow of Stage 1 is: 4107 4108 1. Initialize the system briefly. 4109 4110 2. Detect the geometry and the accessing mode of the "loading drive". 4111 4112 3. Load the first sector of Stage 2. 4113 4114 4. Jump to the starting address of the Stage 2. 4115 4116 The flow of Stage 2 (and Stage 1.5) is: 4117 4118 1. Load the rest of itself to the real starting address, that is, the 4119 starting address plus 512 bytes. The block lists are stored in the 4120 last part of the first sector. 4121 4122 2. Long jump to the real starting address. 4123 4124 Note that Stage 2 (or Stage 1.5) does not probe the geometry or the 4125accessing mode of the "loading drive", since Stage 1 has already probed 4126them. 4127 4128 4129File: grub.info, Node: I/O ports detection, Next: Memory detection, Prev: Bootstrap tricks, Up: Internals 4130 4131D.6 How to probe I/O ports used by INT 13H 4132========================================== 4133 4134FIXME: I will write this chapter after implementing the new technique. 4135 4136 4137File: grub.info, Node: Memory detection, Next: Low-level disk I/O, Prev: I/O ports detection, Up: Internals 4138 4139D.7 How to detect all installed RAM 4140=================================== 4141 4142FIXME: I doubt if Erich didn't write this chapter only himself wholly, 4143so I will rewrite this chapter. 4144 4145 4146File: grub.info, Node: Low-level disk I/O, Next: MBR, Prev: Memory detection, Up: Internals 4147 4148D.8 INT 13H disk I/O interrupts 4149=============================== 4150 4151FIXME: I'm not sure where some part of the original chapter is derived, 4152so I will rewrite this chapter. 4153 4154 4155File: grub.info, Node: MBR, Next: Partition table, Prev: Low-level disk I/O, Up: Internals 4156 4157D.9 The structure of Master Boot Record 4158======================================= 4159 4160FIXME: Likewise. 4161 4162 4163File: grub.info, Node: Partition table, Next: Submitting patches, Prev: MBR, Up: Internals 4164 4165D.10 The format of partition tables 4166=================================== 4167 4168FIXME: Probably the original chapter is derived from "How It Works", so 4169I will rewrite this chapter. 4170 4171 4172File: grub.info, Node: Submitting patches, Prev: Partition table, Up: Internals 4173 4174D.11 Where and how you should send patches 4175========================================== 4176 4177When you write patches for GRUB, please send them to the mailing list 4178<bug-grub@gnu.org>. Here is the list of items of which you should take 4179care: 4180 4181 * Please make your patch as small as possible. Generally, it is not 4182 a good thing to make one big patch which changes many things. 4183 Instead, segregate features and produce many patches. 4184 4185 * Use as late code as possible, for the original code. The CVS 4186 repository always has the current version (*note Obtaining and 4187 Building GRUB::). 4188 4189 * Write ChangeLog entries. *Note Change Logs: (standards)Change 4190 Logs, if you don't know how to write ChangeLog. 4191 4192 * Make patches in unified diff format. `diff -urN' is appropriate in 4193 most cases. 4194 4195 * Don't make patches reversely. Reverse patches are difficult to 4196 read and use. 4197 4198 * Be careful enough of the license term and the copyright. Because 4199 GRUB is under GNU General Public License, you may not steal code 4200 from software whose license is incompatible against GPL. And, if 4201 you copy code written by others, you must not ignore their 4202 copyrights. Feel free to ask GRUB maintainers, whenever you are 4203 not sure what you should do. 4204 4205 * If your patch is too large to send in e-mail, put it at somewhere 4206 we can see. Usually, you shouldn't send e-mail over 20K. 4207 4208 4209File: grub.info, Node: Index, Prev: Internals, Up: Top 4210 4211Index 4212***** 4213 4214[index] 4215* Menu: 4216 4217* blocklist: blocklist. (line 7) 4218* boot: boot. (line 7) 4219* bootp: bootp. (line 7) 4220* cat: cat. (line 7) 4221* chainloader: chainloader. (line 7) 4222* cmp: cmp. (line 7) 4223* color: color. (line 7) 4224* configfile: configfile. (line 7) 4225* current_drive: Filesystem interface. (line 19) 4226* current_partition: Filesystem interface. (line 23) 4227* current_slice: Filesystem interface. (line 26) 4228* debug: debug. (line 7) 4229* default: default. (line 7) 4230* device: device. (line 7) 4231* devread: Filesystem interface. (line 71) 4232* dhcp: dhcp. (line 7) 4233* disk_read_func: Filesystem interface. (line 62) 4234* displayapm: displayapm. (line 7) 4235* displaymem: displaymem. (line 7) 4236* embed: embed. (line 7) 4237* fallback: fallback. (line 7) 4238* filemax: Filesystem interface. (line 59) 4239* filepos: Filesystem interface. (line 52) 4240* find: find. (line 7) 4241* fstest: fstest. (line 7) 4242* FSYS_BUF: Filesystem interface. (line 46) 4243* geometry: geometry. (line 7) 4244* grub_read: Filesystem interface. (line 75) 4245* halt: halt. (line 7) 4246* help: help. (line 7) 4247* hiddenmenu: hiddenmenu. (line 7) 4248* hide: hide. (line 7) 4249* ifconfig: ifconfig. (line 8) 4250* impsprobe: impsprobe. (line 7) 4251* initrd: initrd. (line 7) 4252* install: install. (line 9) 4253* ioprobe: ioprobe. (line 7) 4254* kernel: kernel. (line 7) 4255* lock: lock. (line 7) 4256* makeactive: makeactive. (line 7) 4257* map: map. (line 7) 4258* md5crypt: md5crypt. (line 7) 4259* module: module. (line 7) 4260* modulenounzip: modulenounzip. (line 7) 4261* pager: pager. (line 7) 4262* part_length: Filesystem interface. (line 38) 4263* part_start: Filesystem interface. (line 35) 4264* partnew: partnew. (line 7) 4265* parttype: parttype. (line 7) 4266* password: password. (line 7) 4267* pause: pause. (line 7) 4268* print_a_completion: Filesystem interface. (line 79) 4269* print_possibilities: Filesystem interface. (line 41) 4270* quit: quit. (line 7) 4271* rarp: rarp. (line 7) 4272* read: read. (line 7) 4273* reboot: reboot. (line 7) 4274* root: root. (line 7) 4275* rootnoverify: rootnoverify. (line 7) 4276* saved_drive: Filesystem interface. (line 29) 4277* saved_partition: Filesystem interface. (line 32) 4278* savedefault: savedefault. (line 7) 4279* serial: serial. (line 9) 4280* setkey: setkey. (line 7) 4281* setup: setup. (line 8) 4282* terminal: terminal. (line 9) 4283* terminfo: terminfo. (line 9) 4284* testload: testload. (line 7) 4285* testvbe: testvbe. (line 7) 4286* tftpserver: tftpserver. (line 7) 4287* timeout: timeout. (line 7) 4288* title: title. (line 7) 4289* unhide: unhide. (line 7) 4290* uppermem: uppermem. (line 7) 4291* vbeprobe: vbeprobe. (line 7) 4292 4293 4294 4295Tag Table: 4296Node: Top1487 4297Node: Introduction3266 4298Node: Overview3643 4299Node: Overview-Footnotes5865 4300Ref: Overview-Footnote-15926 4301Node: History6087 4302Node: Features7208 4303Node: Features-Footnotes12976 4304Ref: Features-Footnote-113037 4305Node: Role of a boot loader13182 4306Node: Role of a boot loader-Footnotes14520 4307Ref: Role of a boot loader-Footnote-114607 4308Node: Naming convention14686 4309Node: Installation17621 4310Node: Creating a GRUB boot floppy19363 4311Node: Installing GRUB natively20181 4312Node: Installing GRUB natively-Footnotes22461 4313Ref: Installing GRUB natively-Footnote-122554 4314Node: Installing GRUB using grub-install22739 4315Node: Making a GRUB bootable CD-ROM25685 4316Node: Making a GRUB bootable CD-ROM-Footnotes27730 4317Ref: Making a GRUB bootable CD-ROM-Footnote-127833 4318Node: Booting27908 4319Node: General boot methods28363 4320Node: Loading an operating system directly29104 4321Node: Chain-loading30408 4322Node: Chain-loading-Footnotes31718 4323Ref: Chain-loading-Footnote-131789 4324Node: OS-specific notes31861 4325Node: GNU/Hurd32237 4326Node: GNU/Linux32856 4327Node: FreeBSD34104 4328Node: NetBSD34617 4329Node: OpenBSD35275 4330Node: DOS/Windows35475 4331Node: SCO UnixWare37301 4332Node: QNX37719 4333Node: Making your system robust37969 4334Node: Booting once-only39294 4335Node: Booting fallback systems41219 4336Node: Configuration44066 4337Node: Network48495 4338Node: General usage of network support48989 4339Node: General usage of network support-Footnotes50850 4340Ref: General usage of network support-Footnote-150959 4341Node: Diskless51027 4342Node: Serial terminal53211 4343Node: Preset Menu55444 4344Node: Security57812 4345Node: Images60620 4346Node: Filesystem63131 4347Node: Device syntax63814 4348Node: File name syntax65308 4349Node: Block list syntax66051 4350Node: Interface66784 4351Node: Command-line interface67661 4352Node: Command-line interface-Footnotes69602 4353Ref: Command-line interface-Footnote-169691 4354Node: Menu interface69786 4355Node: Menu entry editor70796 4356Node: Hidden menu interface71875 4357Node: Commands72452 4358Node: Menu-specific commands73029 4359Node: default74200 4360Node: fallback74678 4361Node: hiddenmenu75229 4362Node: timeout75717 4363Node: title75995 4364Node: General commands76266 4365Node: bootp77579 4366Node: color78058 4367Node: device79532 4368Node: dhcp80104 4369Node: hide80689 4370Node: ifconfig81066 4371Node: pager81642 4372Node: partnew81976 4373Node: parttype82412 4374Node: password82779 4375Node: rarp83598 4376Node: serial83899 4377Node: setkey85172 4378Node: terminal87341 4379Node: terminfo88878 4380Node: tftpserver89565 4381Node: unhide90111 4382Node: Command-line and menu entry commands90486 4383Node: blocklist93017 4384Node: boot93259 4385Node: cat93580 4386Node: chainloader93884 4387Node: cmp94500 4388Node: configfile95051 4389Node: debug95265 4390Node: displayapm95649 4391Node: displaymem95860 4392Node: embed96562 4393Node: embed-Footnotes97096 4394Ref: embed-Footnote-197151 4395Node: find97208 4396Node: fstest97588 4397Node: geometry98273 4398Node: halt98885 4399Node: help99212 4400Node: impsprobe99833 4401Node: initrd100232 4402Node: install100571 4403Node: install-Footnotes103415 4404Ref: install-Footnote-1103474 4405Node: ioprobe103571 4406Node: kernel103896 4407Node: lock105016 4408Node: makeactive105591 4409Node: map105903 4410Node: md5crypt106470 4411Node: module106817 4412Node: modulenounzip107394 4413Node: pause107687 4414Node: quit108101 4415Node: reboot108377 4416Node: read108558 4417Node: root108800 4418Node: rootnoverify109677 4419Node: savedefault110232 4420Node: setup111208 4421Node: testload112274 4422Node: testvbe112884 4423Node: uppermem113255 4424Node: vbeprobe113837 4425Node: Troubleshooting114220 4426Node: Stage1 errors114758 4427Node: Stage1.5 errors116135 4428Node: Stage2 errors116573 4429Node: Invoking the grub shell124033 4430Node: Basic usage124786 4431Node: Installation under UNIX127073 4432Node: Device map128748 4433Node: Invoking grub-install129896 4434Node: Invoking grub-md5-crypt131484 4435Node: Invoking grub-terminfo132133 4436Node: Invoking grub-set-default132899 4437Node: Invoking mbchk134700 4438Node: Obtaining and Building GRUB135214 4439Node: Reporting bugs136631 4440Node: Future139435 4441Node: Internals139926 4442Node: Memory map141149 4443Node: Embedded data142627 4444Node: Filesystem interface144644 4445Node: Command interface148077 4446Node: Bootstrap tricks149392 4447Node: I/O ports detection151541 4448Node: Memory detection151813 4449Node: Low-level disk I/O152105 4450Node: MBR152374 4451Node: Partition table152571 4452Node: Submitting patches152844 4453Node: Index154332 4454 4455End Tag Table 4456