1 This is grub.info, produced by makeinfo version 4.0 from grub.texi.
3 INFO-DIR-SECTION Kernel
5 * GRUB: (grub). The GRand Unified Bootloader
6 * grub-install: (grub)Invoking grub-install. Install GRUB on your drive
7 * grub-md5-crypt: (grub)Invoking grub-md5-crypt. Encrypt a password
9 * grub-terminfo: (grub)Invoking grub-terminfo. Generate a terminfo
12 * grub-set-default: (grub)Invoking grub-set-default. Set a default boot
14 * mbchk: (grub)Invoking mbchk. Check for the format of a Multiboot kernel
17 Copyright (C) 1999,2000,2001,2002,2004 Free Software Foundation, Inc.
19 Permission is granted to make and distribute verbatim copies of this
20 manual provided the copyright notice and this permission notice are
21 preserved on all copies.
23 Permission is granted to copy and distribute modified versions of
24 this manual under the conditions for verbatim copying, provided also
25 that the entire resulting derived work is distributed under the terms
26 of a permission notice identical to this one.
28 Permission is granted to copy and distribute translations of this
29 manual into another language, under the above conditions for modified
33 File: grub.info, Node: install, Next: ioprobe, Prev: initrd, Up: Command-line and menu entry commands
38 - Command: install [`--force-lba'] [`--stage2=os_stage2_file']
39 stage1_file [`d'] dest_dev stage2_file [addr] [`p']
40 [config_file] [real_config_file]
41 This command is fairly complex, and you should not use this command
42 unless you are familiar with GRUB. Use `setup' (*note setup::)
45 In short, it will perform a full install presuming the Stage 2 or
46 Stage 1.5(1) (*note install-Footnote-1::) is in its final install
49 In slightly more detail, it will load STAGE1_FILE, validate that
50 it is a GRUB Stage 1 of the right version number, install in it a
51 blocklist for loading STAGE2_FILE as a Stage 2. If the option `d'
52 is present, the Stage 1 will always look for the actual disk
53 STAGE2_FILE was installed on, rather than using the booting drive.
54 The Stage 2 will be loaded at address ADDR, which must be `0x8000'
55 for a true Stage 2, and `0x2000' for a Stage 1.5. If ADDR is not
56 present, GRUB will determine the address automatically. It then
57 writes the completed Stage 1 to the first block of the device
58 DEST_DEV. If the options `p' or CONFIG_FILE are present, then it
59 reads the first block of stage2, modifies it with the values of
60 the partition STAGE2_FILE was found on (for `p') or places the
61 string CONFIG_FILE into the area telling the stage2 where to look
62 for a configuration file at boot time. Likewise, if
63 REAL_CONFIG_FILE is present and STAGE2_FILE is a Stage 1.5, then
64 the Stage 2 CONFIG_FILE is patched with the configuration file
65 name REAL_CONFIG_FILE. This command preserves the DOS BPB (and for
66 hard disks, the partition table) of the sector the Stage 1 is to
69 *Caution:* Several buggy BIOSes don't pass a booting drive
70 properly when booting from a hard disk drive. Therefore, you will
71 unfortunately have to specify the option `d', whether your Stage2
72 resides at the booting drive or not, if you have such a BIOS. We
73 know these are defective in this way:
76 Fujitsu LifeBook 400 BIOS version 31J0103A
79 HP Vectra XU 6/200 BIOS version GG.06.11
81 *Caution2:* A number of BIOSes don't return a correct LBA support
82 bitmap even if they do have the support. So GRUB provides a
83 solution to ignore the wrong bitmap, that is, the option
84 `--force-lba'. Don't use this option if you know that your BIOS
85 doesn't have LBA support.
87 *Caution3:* You must specify the option `--stage2' in the grub
88 shell, if you cannot unmount the filesystem where your stage2 file
89 resides. The argument should be the file name in your operating
93 File: grub.info, Node: install-Footnotes, Up: install
95 (1) They're loaded the same way, so we will refer to the Stage 1.5
96 as a Stage 2 from now on.
99 File: grub.info, Node: ioprobe, Next: kernel, Prev: install, Up: Command-line and menu entry commands
104 - Command: ioprobe drive
105 Probe I/O ports used for the drive DRIVE. This command will list
106 the I/O ports on the screen. For technical information, *Note
110 File: grub.info, Node: kernel, Next: lock, Prev: ioprobe, Up: Command-line and menu entry commands
115 - Command: kernel [`--type=type'] [`--no-mem-option'] file ...
116 Attempt to load the primary boot image (Multiboot a.out or ELF,
117 Linux zImage or bzImage, FreeBSD a.out, NetBSD a.out, etc.) from
118 FILE. The rest of the line is passed verbatim as the "kernel
119 command-line". Any modules must be reloaded after using this
122 This command also accepts the option `--type' so that you can
123 specify the kernel type of FILE explicitly. The argument TYPE must
124 be one of these: `netbsd', `freebsd', `openbsd', `linux',
125 `biglinux', and `multiboot'. However, you need to specify it only
126 if you want to load a NetBSD ELF kernel, because GRUB can
127 automatically determine a kernel type in the other cases, quite
130 The option `--no-mem-option' is effective only for Linux. If the
131 option is specified, GRUB doesn't pass the option `mem=' to the
132 kernel. This option is implied for Linux kernels 2.4.18 and newer.
135 File: grub.info, Node: lock, Next: makeactive, Prev: kernel, Up: Command-line and menu entry commands
141 Prevent normal users from executing arbitrary menu entries. You
142 must use the command `password' if you really want this command to
143 be useful (*note password::).
145 This command is used in a menu, as shown in this example:
147 title This entry is too dangerous to be executed by normal users
150 kernel /no-security-os
152 See also *Note Security::.
155 File: grub.info, Node: makeactive, Next: map, Prev: lock, Up: Command-line and menu entry commands
160 - Command: makeactive
161 Set the active partition on the root disk to GRUB's root device.
162 This command is limited to _primary_ PC partitions on a hard disk.
165 File: grub.info, Node: map, Next: md5crypt, Prev: makeactive, Up: Command-line and menu entry commands
170 - Command: map to_drive from_drive
171 Map the drive FROM_DRIVE to the drive TO_DRIVE. This is necessary
172 when you chain-load some operating systems, such as DOS, if such
173 an OS resides at a non-first drive. Here is an example:
175 grub> map (hd0) (hd1)
176 grub> map (hd1) (hd0)
178 The example exchanges the order between the first hard disk and the
179 second hard disk. See also *Note DOS/Windows::.
182 File: grub.info, Node: md5crypt, Next: module, Prev: map, Up: Command-line and menu entry commands
188 Prompt to enter a password, and encrypt it in MD5 format. The
189 encrypted password can be used with the command `password' (*note
190 password::). See also *Note Security::.
193 File: grub.info, Node: module, Next: modulenounzip, Prev: md5crypt, Up: Command-line and menu entry commands
198 - Command: module file ...
199 Load a boot module FILE for a Multiboot format boot image (no
200 interpretation of the file contents are made, so the user of this
201 command must know what the kernel in question expects). The rest
202 of the line is passed as the "module command-line", like the
203 `kernel' command. You must load a Multiboot kernel image before
204 loading any module. See also *Note modulenounzip::.
207 File: grub.info, Node: modulenounzip, Next: pause, Prev: module, Up: Command-line and menu entry commands
212 - Command: modulenounzip file ...
213 The same as `module' (*note module::), except that automatic
214 decompression is disabled.
217 File: grub.info, Node: pause, Next: quit, Prev: modulenounzip, Up: Command-line and menu entry commands
222 - Command: pause message ...
223 Print the MESSAGE, then wait until a key is pressed. Note that
224 placing <^G> (ASCII code 7) in the message will cause the speaker
225 to emit the standard beep sound, which is useful when prompting
226 the user to change floppies.
229 File: grub.info, Node: quit, Next: reboot, Prev: pause, Up: Command-line and menu entry commands
235 Exit from the grub shell `grub' (*note Invoking the grub shell::).
236 This command can be used only in the grub shell.
239 File: grub.info, Node: reboot, Next: read, Prev: quit, Up: Command-line and menu entry commands
248 File: grub.info, Node: read, Next: root, Prev: reboot, Up: Command-line and menu entry commands
254 Read a 32-bit value from memory at address ADDR and display it in
258 File: grub.info, Node: root, Next: rootnoverify, Prev: read, Up: Command-line and menu entry commands
263 - Command: root device [hdbias]
264 Set the current "root device" to the device DEVICE, then attempt
265 to mount it to get the partition size (for passing the partition
266 descriptor in `ES:ESI', used by some chain-loaded boot loaders),
267 the BSD drive-type (for booting BSD kernels using their native
268 boot format), and correctly determine the PC partition where a BSD
269 sub-partition is located. The optional HDBIAS parameter is a
270 number to tell a BSD kernel how many BIOS drive numbers are on
271 controllers before the current one. For example, if there is an
272 IDE disk and a SCSI disk, and your FreeBSD root partition is on
273 the SCSI disk, then use a `1' for HDBIAS.
275 See also *Note rootnoverify::.
278 File: grub.info, Node: rootnoverify, Next: savedefault, Prev: root, Up: Command-line and menu entry commands
283 - Command: rootnoverify device [hdbias]
284 Similar to `root' (*note root::), but don't attempt to mount the
285 partition. This is useful for when an OS is outside of the area of
286 the disk that GRUB can read, but setting the correct root device
287 is still desired. Note that the items mentioned in `root' above
288 which derived from attempting the mount will _not_ work correctly.
291 File: grub.info, Node: savedefault, Next: setup, Prev: rootnoverify, Up: Command-line and menu entry commands
296 - Command: savedefault num
297 Save the current menu entry or NUM if specified as a default
298 entry. Here is an example:
305 kernel /boot/vmlinuz root=/dev/sda1 vga=ext
314 With this configuration, GRUB will choose the entry booted
315 previously as the default entry.
317 You can specify `fallback' instead of a number. Then, next
318 fallback entry is saved. Next fallback entry is chosen from
319 fallback entries. Normally, this will be the first entry in
322 See also *Note default:: and *Note Invoking grub-set-default::.
325 File: grub.info, Node: setup, Next: testload, Prev: savedefault, Up: Command-line and menu entry commands
330 - Command: setup [`--force-lba'] [`--stage2=os_stage2_file']
331 [`--prefix=dir'] install_device [image_device]
332 Set up the installation of GRUB automatically. This command uses
333 the more flexible command `install' (*note install::) in the
334 backend and installs GRUB into the device INSTALL_DEVICE. If
335 IMAGE_DEVICE is specified, then find the GRUB images (*note
336 Images::) in the device IMAGE_DEVICE, otherwise use the current
337 "root device", which can be set by the command `root'. If
338 INSTALL_DEVICE is a hard disk, then embed a Stage 1.5 in the disk
341 The option `--prefix' specifies the directory under which GRUB
342 images are put. If it is not specified, GRUB automatically
343 searches them in `/boot/grub' and `/grub'.
345 The options `--force-lba' and `--stage2' are just passed to
346 `install' if specified. *Note install::, for more information.
349 File: grub.info, Node: testload, Next: testvbe, Prev: setup, Up: Command-line and menu entry commands
354 - Command: testload file
355 Read the entire contents of FILE in several different ways and
356 compare them, to test the filesystem code. The output is somewhat
357 cryptic, but if no errors are reported and the final `i=X,
358 filepos=Y' reading has X and Y equal, then it is definitely
359 consistent, and very likely works correctly subject to a
360 consistent offset error. If this test succeeds, then a good next
361 step is to try loading a kernel.
364 File: grub.info, Node: testvbe, Next: uppermem, Prev: testload, Up: Command-line and menu entry commands
369 - Command: testvbe mode
370 Test the VESA BIOS EXTENSION mode MODE. This command will switch
371 your video card to the graphics mode, and show an endless
372 animation. Hit any key to return. See also *Note vbeprobe::.
375 File: grub.info, Node: uppermem, Next: vbeprobe, Prev: testvbe, Up: Command-line and menu entry commands
380 - Command: uppermem kbytes
381 Force GRUB to assume that only KBYTES kilobytes of upper memory
382 are installed. Any system address range maps are discarded.
384 *Caution:* This should be used with great caution, and should only
385 be necessary on some old machines. GRUB's BIOS probe can pick up
386 all RAM on all new machines the author has ever heard of. It can
387 also be used for debugging purposes to lie to an OS.
390 File: grub.info, Node: vbeprobe, Prev: uppermem, Up: Command-line and menu entry commands
395 - Command: vbeprobe [mode]
396 Probe VESA BIOS EXTENSION information. If the mode MODE is
397 specified, show only the information about MODE. Otherwise, this
398 command lists up available VBE modes on the screen. See also *Note
402 File: grub.info, Node: Troubleshooting, Next: Invoking the grub shell, Prev: Commands, Up: Top
404 Error messages reported by GRUB
405 *******************************
407 This chapter describes error messages reported by GRUB when you
408 encounter trouble. *Note Invoking the grub shell::, if your problem is
409 specific to the grub shell.
413 * Stage1 errors:: Errors reported by the Stage 1
414 * Stage1.5 errors:: Errors reported by the Stage 1.5
415 * Stage2 errors:: Errors reported by the Stage 2
418 File: grub.info, Node: Stage1 errors, Next: Stage1.5 errors, Up: Troubleshooting
420 Errors reported by the Stage 1
421 ==============================
423 The general way that the Stage 1 handles errors is to print an error
424 string and then halt. Pressing `<CTRL>-<ALT>-<DEL>' will reboot.
426 The following is a comprehensive list of error messages for the
430 The stage2 or stage1.5 is being read from a hard disk, and the
431 attempt to determine the size and geometry of the hard disk failed.
434 The stage2 or stage1.5 is being read from a floppy disk, and the
435 attempt to determine the size and geometry of the floppy disk
436 failed. It's listed as a separate error since the probe sequence
437 is different than for hard disks.
440 A disk read error happened while trying to read the stage2 or
444 The location of the stage2 or stage1.5 is not in the portion of
445 the disk supported directly by the BIOS read calls. This could
446 occur because the BIOS translated geometry has been changed by the
447 user or the disk is moved to another machine or controller after
448 installation, or GRUB was not installed using itself (if it was,
449 the Stage 2 version of this error would have been seen during that
450 process and it would not have completed the install).
453 File: grub.info, Node: Stage1.5 errors, Next: Stage2 errors, Prev: Stage1 errors, Up: Troubleshooting
455 Errors reported by the Stage 1.5
456 ================================
458 The general way that the Stage 1.5 handles errors is to print an
459 error number in the form `Error NUM' and then halt. Pressing
460 `<CTRL>-<ALT>-<DEL>' will reboot.
462 The error numbers correspond to the errors reported by Stage 2.
463 *Note Stage2 errors::.
466 File: grub.info, Node: Stage2 errors, Prev: Stage1.5 errors, Up: Troubleshooting
468 Errors reported by the Stage 2
469 ==============================
471 The general way that the Stage 2 handles errors is to abort the
472 operation in question, print an error string, then (if possible) either
473 continue based on the fact that an error occurred or wait for the user
474 to deal with the error.
476 The following is a comprehensive list of error messages for the
477 Stage 2 (error numbers for the Stage 1.5 are listed before the colon in
480 1 : Filename must be either an absolute filename or blocklist
481 This error is returned if a file name is requested which doesn't
482 fit the syntax/rules listed in the *Note Filesystem::.
484 2 : Bad file or directory type
485 This error is returned if a file requested is not a regular file,
486 but something like a symbolic link, directory, or FIFO.
488 3 : Bad or corrupt data while decompressing file
489 This error is returned if the run-length decompression code gets an
490 internal error. This is usually from a corrupt file.
492 4 : Bad or incompatible header in compressed file
493 This error is returned if the file header for a supposedly
494 compressed file is bad.
496 5 : Partition table invalid or corrupt
497 This error is returned if the sanity checks on the integrity of the
498 partition table fail. This is a bad sign.
500 6 : Mismatched or corrupt version of stage1/stage2
501 This error is returned if the install command points to
502 incompatible or corrupt versions of the stage1 or stage2. It can't
503 detect corruption in general, but this is a sanity check on the
504 version numbers, which should be correct.
506 7 : Loading below 1MB is not supported
507 This error is returned if the lowest address in a kernel is below
508 the 1MB boundary. The Linux zImage format is a special case and
509 can be handled since it has a fixed loading address and maximum
512 8 : Kernel must be loaded before booting
513 This error is returned if GRUB is told to execute the boot sequence
514 without having a kernel to start.
516 9 : Unknown boot failure
517 This error is returned if the boot attempt did not succeed for
518 reasons which are unknown.
520 10 : Unsupported Multiboot features requested
521 This error is returned when the Multiboot features word in the
522 Multiboot header requires a feature that is not recognized. The
523 point of this is that the kernel requires special handling which
524 GRUB is probably unable to provide.
526 11 : Unrecognized device string
527 This error is returned if a device string was expected, and the
528 string encountered didn't fit the syntax/rules listed in the *Note
531 12 : Invalid device requested
532 This error is returned if a device string is recognizable but does
533 not fall under the other device errors.
535 13 : Invalid or unsupported executable format
536 This error is returned if the kernel image being loaded is not
537 recognized as Multiboot or one of the supported native formats
538 (Linux zImage or bzImage, FreeBSD, or NetBSD).
540 14 : Filesystem compatibility error, cannot read whole file
541 Some of the filesystem reading code in GRUB has limits on the
542 length of the files it can read. This error is returned when the
543 user runs into such a limit.
546 This error is returned if the specified file name cannot be found,
547 but everything else (like the disk/partition info) is OK.
549 16 : Inconsistent filesystem structure
550 This error is returned by the filesystem code to denote an internal
551 error caused by the sanity checks of the filesystem structure on
552 disk not matching what it expects. This is usually caused by a
553 corrupt filesystem or bugs in the code handling it in GRUB.
555 17 : Cannot mount selected partition
556 This error is returned if the partition requested exists, but the
557 filesystem type cannot be recognized by GRUB.
559 18 : Selected cylinder exceeds maximum supported by BIOS
560 This error is returned when a read is attempted at a linear block
561 address beyond the end of the BIOS translated area. This generally
562 happens if your disk is larger than the BIOS can handle (512MB for
563 (E)IDE disks on older machines or larger than 8GB in general).
565 19 : Linux kernel must be loaded before initrd
566 This error is returned if the initrd command is used before
567 loading a Linux kernel.
569 20 : Multiboot kernel must be loaded before modules
570 This error is returned if the module load command is used before
571 loading a Multiboot kernel. It only makes sense in this case
572 anyway, as GRUB has no idea how to communicate the presence of
573 such modules to a non-Multiboot-aware kernel.
575 21 : Selected disk does not exist
576 This error is returned if the device part of a device- or full
577 file name refers to a disk or BIOS device that is not present or
578 not recognized by the BIOS in the system.
580 22 : No such partition
581 This error is returned if a partition is requested in the device
582 part of a device- or full file name which isn't on the selected
585 23 : Error while parsing number
586 This error is returned if GRUB was expecting to read a number and
587 encountered bad data.
589 24 : Attempt to access block outside partition
590 This error is returned if a linear block address is outside of the
591 disk partition. This generally happens because of a corrupt
592 filesystem on the disk or a bug in the code handling it in GRUB
593 (it's a great debugging tool).
596 This error is returned if there is a disk read error when trying to
597 probe or read data from a particular disk.
599 26 : Too many symbolic links
600 This error is returned if the link count is beyond the maximum
601 (currently 5), possibly the symbolic links are looped.
603 27 : Unrecognized command
604 This error is returned if an unrecognized command is entered on the
605 command-line or in a boot sequence section of a configuration file
606 and that entry is selected.
608 28 : Selected item cannot fit into memory
609 This error is returned if a kernel, module, or raw file load
610 command is either trying to load its data such that it won't fit
611 into memory or it is simply too big.
613 29 : Disk write error
614 This error is returned if there is a disk write error when trying
615 to write to a particular disk. This would generally only occur
616 during an install of set active partition command.
618 30 : Invalid argument
619 This error is returned if an argument specified to a command is
622 31 : File is not sector aligned
623 This error may occur only when you access a ReiserFS partition by
624 block-lists (e.g. the command `install'). In this case, you should
625 mount the partition with the `-o notail' option.
627 32 : Must be authenticated
628 This error is returned if you try to run a locked entry. You should
629 enter a correct password before running such an entry.
631 33 : Serial device not configured
632 This error is returned if you try to change your terminal to a
633 serial one before initializing any serial device.
635 34 : No spare sectors on the disk
636 This error is returned if a disk doesn't have enough spare space.
637 This happens when you try to embed Stage 1.5 into the unused
638 sectors after the MBR, but the first partition starts right after
639 the MBR or they are used by EZ-BIOS.
642 File: grub.info, Node: Invoking the grub shell, Next: Invoking grub-install, Prev: Troubleshooting, Up: Top
644 Invoking the grub shell
645 ***********************
647 This chapter documents the grub shell `grub'. Note that the grub
648 shell is an emulator; it doesn't run under the native environment, so it
649 sometimes does something wrong. Therefore, you shouldn't trust it too
650 much. If there is anything wrong with it, don't hesitate to try the
651 native GRUB environment, especially when it guesses a wrong map between
652 BIOS drives and OS devices.
656 * Basic usage:: How to use the grub shell
657 * Installation under UNIX:: How to install GRUB via `grub'
658 * Device map:: The map between BIOS drives and OS devices
661 File: grub.info, Node: Basic usage, Next: Installation under UNIX, Up: Invoking the grub shell
663 Introduction into the grub shell
664 ================================
666 You can use the command `grub' for installing GRUB under your
667 operating systems and for a testbed when you add a new feature into GRUB
668 or when fixing a bug. `grub' is almost the same as the Stage 2, and, in
669 fact, it shares the source code with the Stage 2 and you can use the
670 same commands (*note Commands::) in `grub'. It is emulated by replacing
671 BIOS calls with UNIX system calls and libc functions.
673 The command `grub' accepts the following options:
676 Print a summary of the command-line options and exit.
679 Print the version number of GRUB and exit.
682 Print some verbose messages for debugging purpose.
685 Use the device map file FILE. The format is described in *Note
689 Do not probe any floppy drive. This option has no effect if the
690 option `--device-map' is specified (*note Device map::).
692 `--probe-second-floppy'
693 Probe the second floppy drive. If this option is not specified,
694 the grub shell does not probe it, as that sometimes takes a long
695 time. If you specify the device map file (*note Device map::), the
696 grub shell just ignores this option.
699 Read the configuration file FILE instead of `/boot/grub/menu.lst'.
700 The format is the same as the normal GRUB syntax. See *Note
701 Filesystem::, for more information.
704 Set the stage2 BOOT_DRIVE to DRIVE. This argument should be an
705 integer (decimal, octal or hexadecimal).
707 `--install-partition=PAR'
708 Set the stage2 INSTALL_PARTITION to PAR. This argument should be
709 an integer (decimal, octal or hexadecimal).
712 Do not use the configuration file even if it can be read.
715 Do not use the screen handling interface by the curses even if it
719 This option has the same meaning as `--no-config-file --no-curses'.
722 Disable writing to any disk.
725 Wait until a debugger will attach. This option is useful when you
726 want to debug the startup code.
729 File: grub.info, Node: Installation under UNIX, Next: Device map, Prev: Basic usage, Up: Invoking the grub shell
731 How to install GRUB via `grub'
732 ==============================
734 The installation procedure is the same as under the "native" Stage
735 2. *Note Installation::, for more information. The command
736 `grub'-specific information is described here.
738 What you should be careful about is "buffer cache". `grub' makes use
739 of raw devices instead of filesystems that your operating systems
740 serve, so there exists a potential problem that some cache
741 inconsistency may corrupt your filesystems. What we recommend is:
743 * If you can unmount drives to which GRUB may write any amount of
744 data, unmount them before running `grub'.
746 * If a drive cannot be unmounted but can be mounted with the
747 read-only flag, mount it in read-only mode. That should be secure.
749 * If a drive must be mounted with the read-write flag, make sure
750 that no activity is being done on it while the command `grub' is
753 * Reboot your operating system as soon as possible. This is probably
754 not required if you follow the rules above, but reboot is the most
757 In addition, enter the command `quit' when you finish the
758 installation. That is _very important_ because `quit' makes the buffer
759 cache consistent. Do not push <C-c>.
761 If you want to install GRUB non-interactively, specify `--batch'
762 option in the command-line. This is a simple example:
766 # Use /usr/sbin/grub if you are on an older system.
767 /sbin/grub --batch <<EOT 1>/dev/null 2>/dev/null
774 File: grub.info, Node: Device map, Prev: Installation under UNIX, Up: Invoking the grub shell
776 The map between BIOS drives and OS devices
777 ==========================================
779 When you specify the option `--device-map' (*note Basic usage::),
780 the grub shell creates the "device map file" automatically unless it
781 already exists. The file name `/boot/grub/device.map' is preferred.
783 If the device map file exists, the grub shell reads it to map BIOS
784 drives to OS devices. This file consists of lines like this:
788 DEVICE is a drive specified in the GRUB syntax (*note Device
789 syntax::), and FILE is an OS file, which is normally a device file.
791 The reason why the grub shell gives you the device map file is that
792 it cannot guess the map between BIOS drives and OS devices correctly in
793 some environments. For example, if you exchange the boot sequence
794 between IDE and SCSI in your BIOS, it gets the order wrong.
796 Thus, edit the file if the grub shell makes a mistake. You can put
797 any comments in the file if needed, as the grub shell assumes that a
798 line is just a comment if the first character is `#'.
801 File: grub.info, Node: Invoking grub-install, Next: Invoking grub-md5-crypt, Prev: Invoking the grub shell, Up: Top
803 Invoking grub-install
804 *********************
806 The program `grub-install' installs GRUB on your drive using the
807 grub shell (*note Invoking the grub shell::). You must specify the
808 device name on which you want to install GRUB, like this:
810 grub-install INSTALL_DEVICE
812 The device name INSTALL_DEVICE is an OS device name or a GRUB device
815 `grub-install' accepts the following options:
818 Print a summary of the command-line options and exit.
821 Print the version number of GRUB and exit.
824 Force GRUB to use LBA mode even for a buggy BIOS. Use this option
825 only if your BIOS doesn't work properly in LBA mode even though it
828 `--root-directory=DIR'
829 Install GRUB images under the directory DIR instead of the root
830 directory. This option is useful when you want to install GRUB
831 into a separate partition or a removable disk. Here is an example
832 in which you have a separate "boot" partition which is mounted on
835 grub-install --root-directory=/boot hd0
838 Use FILE as the grub shell. You can append arbitrary options to
839 FILE after the file name, like this:
841 grub-install --grub-shell="grub --read-only" /dev/fd0
844 Recheck the device map, even if `/boot/grub/device.map' already
845 exists. You should use this option whenever you add/remove a disk
846 into/from your computer.
849 File: grub.info, Node: Invoking grub-md5-crypt, Next: Invoking grub-terminfo, Prev: Invoking grub-install, Up: Top
851 Invoking grub-md5-crypt
852 ***********************
854 The program `grub-md5-crypt' encrypts a password in MD5 format.
855 This is just a frontend of the grub shell (*note Invoking the grub
856 shell::). Passwords encrypted by this program can be used with the
857 command `password' (*note password::).
859 `grub-md5-crypt' accepts the following options:
862 Print a summary of the command-line options and exit.
865 Print the version information and exit.
868 Use FILE as the grub shell.
871 File: grub.info, Node: Invoking grub-terminfo, Next: Invoking grub-set-default, Prev: Invoking grub-md5-crypt, Up: Top
873 Invoking grub-terminfo
874 **********************
876 The program `grub-terminfo' generates a terminfo command from a
877 terminfo name (*note terminfo::). The result can be used in the
878 configuration file, to define escape sequences. Because GRUB assumes
879 that your terminal is vt100-compatible by default, this would be useful
880 only if your terminal is uncommon (such as vt52).
882 `grub-terminfo' accepts the following options:
885 Print a summary of the command-line options and exit.
888 Print the version information and exit.
890 You must specify one argument to this command. For example:
895 File: grub.info, Node: Invoking grub-set-default, Next: Invoking mbchk, Prev: Invoking grub-terminfo, Up: Top
897 Invoking grub-set-default
898 *************************
900 The program `grub-set-default' sets the default boot entry for GRUB.
901 This automatically creates a file named `default' under your GRUB
902 directory (i.e. `/boot/grub'), if it is not present. This file is used
903 to determine the default boot entry when GRUB boots up your system when
904 you use `default saved' in your configuration file (*note default::),
905 and to save next default boot entry when you use `savedefault' in a
906 boot entry (*note savedefault::).
908 `grub-set-default' accepts the following options:
911 Print a summary of the command-line options and exit.
914 Print the version information and exit.
916 `--root-directory=DIR'
917 Use the directory DIR instead of the root directory (i.e. `/') to
918 define the location of the default file. This is useful when you
919 mount a disk which is used for another system.
921 You must specify a single argument to `grub-set-default'. This
922 argument is normally the number of a default boot entry. For example,
923 if you have this configuration file:
936 and if you want to set the next default boot entry to GNU/Linux, you
937 may execute this command:
941 Because the entry for GNU/Linux is `1'. Note that entries are
942 counted from zero. So, if you want to specify GNU/Hurd here, then you
945 This feature is very useful if you want to test a new kernel or to
946 make your system quite robust. *Note Making your system robust::, for
947 more hints about how to set up a robust system.
950 File: grub.info, Node: Invoking mbchk, Next: Obtaining and Building GRUB, Prev: Invoking grub-set-default, Up: Top
955 The program `mbchk' checks for the format of a Multiboot kernel. We
956 recommend using this program before booting your own kernel by GRUB.
958 `mbchk' accepts the following options:
961 Print a summary of the command-line options and exit.
964 Print the version number of GRUB and exit.
967 Suppress all normal output.
970 File: grub.info, Node: Obtaining and Building GRUB, Next: Reporting bugs, Prev: Invoking mbchk, Up: Top
972 How to obtain and build GRUB
973 ****************************
975 *Caution:* GRUB requires binutils-2.9.1.0.23 or later because the
976 GNU assembler has been changed so that it can produce real 16bits
977 machine code between 2.9.1 and 2.9.1.0.x. See
978 `http://sources.redhat.com/binutils/', to obtain information on
979 how to get the latest version.
981 GRUB is available from the GNU alpha archive site
982 `ftp://alpha.gnu.org/gnu/grub' or any of its mirrors. The file will be
983 named grub-version.tar.gz. The current version is 0.95, so the file you
986 `ftp://alpha.gnu.org/gnu/grub/grub-0.95.tar.gz'
988 To unbundle GRUB use the instruction:
990 zcat grub-0.95.tar.gz | tar xvf -
992 which will create a directory called `grub-0.95' with all the
993 sources. You can look at the file `INSTALL' for detailed instructions
994 on how to build and install GRUB, but you should be able to just do:
1000 This will install the grub shell `grub' (*note Invoking the grub
1001 shell::), the Multiboot checker `mbchk' (*note Invoking mbchk::), and
1002 the GRUB images. This will also install the GRUB manual.
1004 Also, the latest version is available from the CVS. See
1005 `http://savannah.gnu.org/cvs/?group=grub' for more information.
1008 File: grub.info, Node: Reporting bugs, Next: Future, Prev: Obtaining and Building GRUB, Up: Top
1013 These are the guideline for how to report bugs. Take a look at this
1014 list below before you submit bugs:
1016 1. Before getting unsettled, read this manual through and through.
1017 Also, see the GNU GRUB FAQ
1018 (http://www.gnu.org/software/grub/grub-faq.html).
1020 2. Always mention the information on your GRUB. The version number
1021 and the configuration are quite important. If you build it
1022 yourself, write the options specified to the configure script and
1023 your operating system, including the versions of gcc and binutils.
1025 3. If you have trouble with the installation, inform us of how you
1026 installed GRUB. Don't omit error messages, if any. Just `GRUB hangs
1027 up when it boots' is not enough.
1029 The information on your hardware is also essential. These are
1030 especially important: the geometries and the partition tables of
1031 your hard disk drives and your BIOS.
1033 4. If GRUB cannot boot your operating system, write down _everything_
1034 you see on the screen. Don't paraphrase them, like `The foo OS
1035 crashes with GRUB, even though it can boot with the bar boot
1036 loader just fine'. Mention the commands you executed, the messages
1037 printed by them, and information on your operating system
1038 including the version number.
1040 5. Explain what you wanted to do. It is very useful to know your
1041 purpose and your wish, and how GRUB didn't satisfy you.
1043 6. If you can investigate the problem yourself, please do. That will
1044 give you and us much more information on the problem. Attaching a
1045 patch is even better.
1047 When you attach a patch, make the patch in unified diff format, and
1048 write ChangeLog entries. But, even when you make a patch, don't
1049 forget to explain the problem, so that we can understand what your
1052 7. Write down anything that you think might be related. Please
1053 understand that we often need to reproduce the same problem you
1054 encounterred in our environment. So your information should be
1055 sufficient for us to do the same thing--Don't forget that we
1056 cannot see your computer directly. If you are not sure whether to
1057 state a fact or leave it out, state it! Reporting too many things
1058 is much better than omitting something important.
1060 If you follow the guideline above, submit a report to the Bug
1061 Tracking System (http://savannah.gnu.org/bugs/?group=grub).
1062 Alternatively, you can submit a report via electronic mail to
1063 <bug-grub@gnu.org>, but we strongly recommend that you use the Bug
1064 Tracking System, because e-mail can be passed over easily.
1066 Once we get your report, we will try to fix the bugs.
1069 File: grub.info, Node: Future, Next: Internals, Prev: Reporting bugs, Up: Top
1074 We started the next generation of GRUB, GRUB 2. This will include
1075 internationalization, dynamic module loading, real memory management,
1076 multiple architecture support, a scripting language, and many other
1077 nice feature. If you are interested in the development of GRUB 2, take
1078 a look at the homepage (http://www.gnu.org/software/grub/grub.html).
1081 File: grub.info, Node: Internals, Next: Index, Prev: Future, Up: Top
1086 This chapter documents the user-invisible aspect of GRUB.
1088 As a general rule of software development, it is impossible to keep
1089 the descriptions of the internals up-to-date, and it is quite hard to
1090 document everything. So refer to the source code, whenever you are not
1091 satisfied with this documentation. Please assume that this gives just
1096 * Memory map:: The memory map of various components
1097 * Embedded data:: Embedded variables in GRUB
1098 * Filesystem interface:: The generic interface for filesystems
1099 * Command interface:: The generic interface for built-ins
1100 * Bootstrap tricks:: The bootstrap mechanism used in GRUB
1101 * I/O ports detection:: How to probe I/O ports used by INT 13H
1102 * Memory detection:: How to detect all installed RAM
1103 * Low-level disk I/O:: INT 13H disk I/O interrupts
1104 * MBR:: The structure of Master Boot Record
1105 * Partition table:: The format of partition tables
1106 * Submitting patches:: Where and how you should send patches
1109 File: grub.info, Node: Memory map, Next: Embedded data, Up: Internals
1111 The memory map of various components
1112 ====================================
1114 GRUB consists of two distinct components, called "stages", which are
1115 loaded at different times in the boot process. Because they run
1116 mutual-exclusively, sometimes a memory area overlaps with another
1117 memory area. And, even in one stage, a single memory area can be used
1118 for various purposes, because their usages are mutually exclusive.
1120 Here is the memory map of the various components:
1123 BIOS and real mode interrupts
1126 Partition table passed to another boot loader
1132 The optional Stage 1.5 is loaded here
1135 Command-line buffer for Multiboot kernels and modules
1138 Stage 1 is loaded here by BIOS or another boot loader
1141 LBA drive parameters
1144 Stage2 is loaded here
1146 The end of Stage 2 to 416K-1
1147 Heap, in particular used for the menu
1150 Protected mode stack
1159 512-byte scratch area
1162 Buffers for various functions, such as password, command-line, cut
1163 and paste, and completion.
1165 The last 1K of lower memory
1166 Disk swapping code and data
1168 See the file `stage2/shared.h', for more information.
1171 File: grub.info, Node: Embedded data, Next: Filesystem interface, Prev: Memory map, Up: Internals
1173 Embedded variables in GRUB
1174 ==========================
1176 Stage 1 and Stage 2 have embedded variables whose locations are
1177 well-defined, so that the installation can patch the binary file
1178 directly without recompilation of the stages.
1180 In Stage 1, these are defined:
1183 The version number (not GRUB's, but the installation mechanism's).
1186 The boot drive. If it is 0xFF, use a drive passed by BIOS.
1189 The flag for if forcing LBA.
1192 The starting address of Stage 2.
1195 The first sector of Stage 2.
1198 The starting segment of Stage 2.
1201 The signature (`0xAA55').
1203 See the file `stage1/stage1.S', for more information.
1205 In the first sector of Stage 1.5 and Stage 2, the block lists are
1206 recorded between `firstlist' and `lastlist'. The address of `lastlist'
1207 is determined when assembling the file `stage2/start.S'.
1209 The trick here is that it is actually read backward, and the first
1210 8-byte block list is not read here, but after the pointer is decremented
1211 8 bytes, then after reading it, it decrements again, reads, and so on,
1212 until it is finished. The terminating condition is when the number of
1213 sectors to be read in the next block list is zero.
1215 The format of a block list can be seen from the example in the code
1216 just before the `firstlist' label. Note that it is always from the
1217 beginning of the disk, but _not_ relative to the partition boundaries.
1219 In the second sector of Stage 1.5 and Stage 2, these are defined:
1222 The version number (likewise, the installation mechanism's).
1225 The installed partition.
1228 The saved entry number.
1234 The flag for if forcing LBA.
1237 The version string (GRUB's).
1239 `0x12' + "the length of the version string"
1240 The name of a configuration file.
1242 See the file `stage2/asm.S', for more information.
1245 File: grub.info, Node: Filesystem interface, Next: Command interface, Prev: Embedded data, Up: Internals
1247 The generic interface for filesystems
1248 =====================================
1250 For any particular partition, it is presumed that only one of the
1251 "normal" filesystems such as FAT, FFS, or ext2fs can be used, so there
1252 is a switch table managed by the functions in `disk_io.c'. The notation
1253 is that you can only "mount" one at a time.
1255 The block list filesystem has a special place in the system. In
1256 addition to the "normal" filesystem (or even without one mounted), you
1257 can access disk blocks directly (in the indicated partition) via the
1258 block list notation. Using the block list filesystem doesn't effect any
1259 other filesystem mounts.
1261 The variables which can be read by the filesystem backend are:
1264 The current BIOS drive number (numbered from 0, if a floppy, and
1265 numbered from 0x80, if a hard disk).
1268 The current partition number.
1271 The current partition type.
1274 The "drive" part of the root device.
1277 The "partition" part of the root device.
1280 The current partition starting address, in sectors.
1283 The current partition length, in sectors.
1285 `print_possibilities'
1286 True when the `dir' function should print the possible completions
1287 of a file, and false when it should try to actually open a file of
1291 Filesystem buffer which is 32K in size, to use in any way which the
1292 filesystem backend desires.
1294 The variables which need to be written by a filesystem backend are:
1297 The current position in the file, in sectors.
1299 *Caution:* the value of FILEPOS can be changed out from under the
1300 filesystem code in the current implementation. Don't depend on it
1301 being the same for later calls into the backend code!
1304 The length of the file.
1307 The value of DISK_READ_HOOK _only_ during reading of data for the
1308 file, not any other fs data, inodes, FAT tables, whatever, then
1309 set to `NULL' at all other times (it will be `NULL' by default).
1310 If this isn't done correctly, then the `testload' and `install'
1311 commands won't work correctly.
1313 The functions expected to be used by the filesystem backend are:
1316 Only read sectors from within a partition. Sector 0 is the first
1317 sector in the partition.
1320 If the backend uses the block list code, then `grub_read' can be
1321 used, after setting BLOCK_FILE to 1.
1323 `print_a_completion'
1324 If PRINT_POSSIBILITIES is true, call `print_a_completion' for each
1325 possible file name. Otherwise, the file name completion won't work.
1327 The functions expected to be defined by the filesystem backend are
1328 described at least moderately in the file `filesys.h'. Their usage is
1329 fairly evident from their use in the functions in `disk_io.c', look for
1330 the use of the FSYS_TABLE array.
1332 *Caution:* The semantics are such that then `mount'ing the
1333 filesystem, presume the filesystem buffer `FSYS_BUF' is corrupted, and
1334 (re-)load all important contents. When opening and reading a file,
1335 presume that the data from the `mount' is available, and doesn't get
1336 corrupted by the open/read (i.e. multiple opens and/or reads will be
1337 done with only one mount if in the same filesystem).
1340 File: grub.info, Node: Command interface, Next: Bootstrap tricks, Prev: Filesystem interface, Up: Internals
1342 The generic interface for built-ins
1343 ===================================
1345 GRUB built-in commands are defined in a uniformal interface, whether
1346 they are menu-specific or can be used anywhere. The definition of a
1347 builtin command consists of two parts: the code itself and the table of
1350 The code must be a function which takes two arguments, a command-line
1351 string and flags, and returns an `int' value. The "flags" argument
1352 specifies how the function is called, using a bit mask. The return
1353 value must be zero if successful, otherwise non-zero. So it is normally
1354 enough to return ERRNUM.
1356 The table of the information is represented by the structure `struct
1357 builtin', which contains the name of the command, a pointer to the
1358 function, flags, a short description of the command and a long
1359 description of the command. Since the descriptions are used only for
1360 help messages interactively, you don't have to define them, if the
1361 command may not be called interactively (such as `title').
1363 The table is finally registered in the table BUILTIN_TABLE, so that
1364 `run_script' and `enter_cmdline' can find the command. See the files
1365 `cmdline.c' and `builtins.c', for more details.