This is grub.info, produced by makeinfo version 4.0 from grub.texi. INFO-DIR-SECTION Kernel START-INFO-DIR-ENTRY * GRUB: (grub). The GRand Unified Bootloader * grub-install: (grub)Invoking grub-install. Install GRUB on your drive * grub-md5-crypt: (grub)Invoking grub-md5-crypt. Encrypt a password in MD5 format * grub-terminfo: (grub)Invoking grub-terminfo. Generate a terminfo command from a terminfo name * grub-set-default: (grub)Invoking grub-set-default. Set a default boot entry * mbchk: (grub)Invoking mbchk. Check for the format of a Multiboot kernel END-INFO-DIR-ENTRY Copyright (C) 1999,2000,2001,2002,2004 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.  File: grub.info, Node: install, Next: ioprobe, Prev: initrd, Up: Command-line and menu entry commands install ------- - Command: install [`--force-lba'] [`--stage2=os_stage2_file'] stage1_file [`d'] dest_dev stage2_file [addr] [`p'] [config_file] [real_config_file] This command is fairly complex, and you should not use this command unless you are familiar with GRUB. Use `setup' (*note setup::) instead. In short, it will perform a full install presuming the Stage 2 or Stage 1.5(1) (*note install-Footnote-1::) is in its final install location. In slightly more detail, it will load STAGE1_FILE, validate that it is a GRUB Stage 1 of the right version number, install in it a blocklist for loading STAGE2_FILE as a Stage 2. If the option `d' is present, the Stage 1 will always look for the actual disk STAGE2_FILE was installed on, rather than using the booting drive. The Stage 2 will be loaded at address ADDR, which must be `0x8000' for a true Stage 2, and `0x2000' for a Stage 1.5. If ADDR is not present, GRUB will determine the address automatically. It then writes the completed Stage 1 to the first block of the device DEST_DEV. If the options `p' or CONFIG_FILE are present, then it reads the first block of stage2, modifies it with the values of the partition STAGE2_FILE was found on (for `p') or places the string CONFIG_FILE into the area telling the stage2 where to look for a configuration file at boot time. Likewise, if REAL_CONFIG_FILE is present and STAGE2_FILE is a Stage 1.5, then the Stage 2 CONFIG_FILE is patched with the configuration file name REAL_CONFIG_FILE. This command preserves the DOS BPB (and for hard disks, the partition table) of the sector the Stage 1 is to be installed into. *Caution:* Several buggy BIOSes don't pass a booting drive properly when booting from a hard disk drive. Therefore, you will unfortunately have to specify the option `d', whether your Stage2 resides at the booting drive or not, if you have such a BIOS. We know these are defective in this way: Fujitsu LifeBook 400 BIOS version 31J0103A HP Vectra XU 6/200 BIOS version GG.06.11 *Caution2:* A number of BIOSes don't return a correct LBA support bitmap even if they do have the support. So GRUB provides a solution to ignore the wrong bitmap, that is, the option `--force-lba'. Don't use this option if you know that your BIOS doesn't have LBA support. *Caution3:* You must specify the option `--stage2' in the grub shell, if you cannot unmount the filesystem where your stage2 file resides. The argument should be the file name in your operating system.  File: grub.info, Node: install-Footnotes, Up: install (1) They're loaded the same way, so we will refer to the Stage 1.5 as a Stage 2 from now on.  File: grub.info, Node: ioprobe, Next: kernel, Prev: install, Up: Command-line and menu entry commands ioprobe ------- - Command: ioprobe drive Probe I/O ports used for the drive DRIVE. This command will list the I/O ports on the screen. For technical information, *Note Internals::.  File: grub.info, Node: kernel, Next: lock, Prev: ioprobe, Up: Command-line and menu entry commands kernel ------ - Command: kernel [`--type=type'] [`--no-mem-option'] file ... Attempt to load the primary boot image (Multiboot a.out or ELF, Linux zImage or bzImage, FreeBSD a.out, NetBSD a.out, etc.) from FILE. The rest of the line is passed verbatim as the "kernel command-line". Any modules must be reloaded after using this command. This command also accepts the option `--type' so that you can specify the kernel type of FILE explicitly. The argument TYPE must be one of these: `netbsd', `freebsd', `openbsd', `linux', `biglinux', and `multiboot'. However, you need to specify it only if you want to load a NetBSD ELF kernel, because GRUB can automatically determine a kernel type in the other cases, quite safely. The option `--no-mem-option' is effective only for Linux. If the option is specified, GRUB doesn't pass the option `mem=' to the kernel. This option is implied for Linux kernels 2.4.18 and newer.  File: grub.info, Node: lock, Next: makeactive, Prev: kernel, Up: Command-line and menu entry commands lock ---- - Command: lock Prevent normal users from executing arbitrary menu entries. You must use the command `password' if you really want this command to be useful (*note password::). This command is used in a menu, as shown in this example: title This entry is too dangerous to be executed by normal users lock root (hd0,a) kernel /no-security-os See also *Note Security::.  File: grub.info, Node: makeactive, Next: map, Prev: lock, Up: Command-line and menu entry commands makeactive ---------- - Command: makeactive Set the active partition on the root disk to GRUB's root device. This command is limited to _primary_ PC partitions on a hard disk.  File: grub.info, Node: map, Next: md5crypt, Prev: makeactive, Up: Command-line and menu entry commands map --- - Command: map to_drive from_drive Map the drive FROM_DRIVE to the drive TO_DRIVE. This is necessary when you chain-load some operating systems, such as DOS, if such an OS resides at a non-first drive. Here is an example: grub> map (hd0) (hd1) grub> map (hd1) (hd0) The example exchanges the order between the first hard disk and the second hard disk. See also *Note DOS/Windows::.  File: grub.info, Node: md5crypt, Next: module, Prev: map, Up: Command-line and menu entry commands md5crypt -------- - Command: md5crypt Prompt to enter a password, and encrypt it in MD5 format. The encrypted password can be used with the command `password' (*note password::). See also *Note Security::.  File: grub.info, Node: module, Next: modulenounzip, Prev: md5crypt, Up: Command-line and menu entry commands module ------ - Command: module file ... Load a boot module FILE for a Multiboot format boot image (no interpretation of the file contents are made, so the user of this command must know what the kernel in question expects). The rest of the line is passed as the "module command-line", like the `kernel' command. You must load a Multiboot kernel image before loading any module. See also *Note modulenounzip::.  File: grub.info, Node: modulenounzip, Next: pause, Prev: module, Up: Command-line and menu entry commands modulenounzip ------------- - Command: modulenounzip file ... The same as `module' (*note module::), except that automatic decompression is disabled.  File: grub.info, Node: pause, Next: quit, Prev: modulenounzip, Up: Command-line and menu entry commands pause ----- - Command: pause message ... Print the MESSAGE, then wait until a key is pressed. Note that placing <^G> (ASCII code 7) in the message will cause the speaker to emit the standard beep sound, which is useful when prompting the user to change floppies.  File: grub.info, Node: quit, Next: reboot, Prev: pause, Up: Command-line and menu entry commands quit ---- - Command: quit Exit from the grub shell `grub' (*note Invoking the grub shell::). This command can be used only in the grub shell.  File: grub.info, Node: reboot, Next: read, Prev: quit, Up: Command-line and menu entry commands reboot ------ - Command: reboot Reboot the computer.  File: grub.info, Node: read, Next: root, Prev: reboot, Up: Command-line and menu entry commands read ---- - Command: read addr Read a 32-bit value from memory at address ADDR and display it in hex format.  File: grub.info, Node: root, Next: rootnoverify, Prev: read, Up: Command-line and menu entry commands root ---- - Command: root device [hdbias] Set the current "root device" to the device DEVICE, then attempt to mount it to get the partition size (for passing the partition descriptor in `ES:ESI', used by some chain-loaded boot loaders), the BSD drive-type (for booting BSD kernels using their native boot format), and correctly determine the PC partition where a BSD sub-partition is located. The optional HDBIAS parameter is a number to tell a BSD kernel how many BIOS drive numbers are on controllers before the current one. For example, if there is an IDE disk and a SCSI disk, and your FreeBSD root partition is on the SCSI disk, then use a `1' for HDBIAS. See also *Note rootnoverify::.  File: grub.info, Node: rootnoverify, Next: savedefault, Prev: root, Up: Command-line and menu entry commands rootnoverify ------------ - Command: rootnoverify device [hdbias] Similar to `root' (*note root::), but don't attempt to mount the partition. This is useful for when an OS is outside of the area of the disk that GRUB can read, but setting the correct root device is still desired. Note that the items mentioned in `root' above which derived from attempting the mount will _not_ work correctly.  File: grub.info, Node: savedefault, Next: setup, Prev: rootnoverify, Up: Command-line and menu entry commands savedefault ----------- - Command: savedefault num Save the current menu entry or NUM if specified as a default entry. Here is an example: default saved timeout 10 title GNU/Linux root (hd0,0) kernel /boot/vmlinuz root=/dev/sda1 vga=ext initrd /boot/initrd savedefault title FreeBSD root (hd0,a) kernel /boot/loader savedefault With this configuration, GRUB will choose the entry booted previously as the default entry. You can specify `fallback' instead of a number. Then, next fallback entry is saved. Next fallback entry is chosen from fallback entries. Normally, this will be the first entry in fallback ones. See also *Note default:: and *Note Invoking grub-set-default::.  File: grub.info, Node: setup, Next: testload, Prev: savedefault, Up: Command-line and menu entry commands setup ----- - Command: setup [`--force-lba'] [`--stage2=os_stage2_file'] [`--prefix=dir'] install_device [image_device] Set up the installation of GRUB automatically. This command uses the more flexible command `install' (*note install::) in the backend and installs GRUB into the device INSTALL_DEVICE. If IMAGE_DEVICE is specified, then find the GRUB images (*note Images::) in the device IMAGE_DEVICE, otherwise use the current "root device", which can be set by the command `root'. If INSTALL_DEVICE is a hard disk, then embed a Stage 1.5 in the disk if possible. The option `--prefix' specifies the directory under which GRUB images are put. If it is not specified, GRUB automatically searches them in `/boot/grub' and `/grub'. The options `--force-lba' and `--stage2' are just passed to `install' if specified. *Note install::, for more information.  File: grub.info, Node: testload, Next: testvbe, Prev: setup, Up: Command-line and menu entry commands testload -------- - Command: testload file Read the entire contents of FILE in several different ways and compare them, to test the filesystem code. The output is somewhat cryptic, but if no errors are reported and the final `i=X, filepos=Y' reading has X and Y equal, then it is definitely consistent, and very likely works correctly subject to a consistent offset error. If this test succeeds, then a good next step is to try loading a kernel.  File: grub.info, Node: testvbe, Next: uppermem, Prev: testload, Up: Command-line and menu entry commands testvbe ------- - Command: testvbe mode Test the VESA BIOS EXTENSION mode MODE. This command will switch your video card to the graphics mode, and show an endless animation. Hit any key to return. See also *Note vbeprobe::.  File: grub.info, Node: uppermem, Next: vbeprobe, Prev: testvbe, Up: Command-line and menu entry commands uppermem -------- - Command: uppermem kbytes Force GRUB to assume that only KBYTES kilobytes of upper memory are installed. Any system address range maps are discarded. *Caution:* This should be used with great caution, and should only be necessary on some old machines. GRUB's BIOS probe can pick up all RAM on all new machines the author has ever heard of. It can also be used for debugging purposes to lie to an OS.  File: grub.info, Node: vbeprobe, Prev: uppermem, Up: Command-line and menu entry commands vbeprobe -------- - Command: vbeprobe [mode] Probe VESA BIOS EXTENSION information. If the mode MODE is specified, show only the information about MODE. Otherwise, this command lists up available VBE modes on the screen. See also *Note testvbe::.  File: grub.info, Node: Troubleshooting, Next: Invoking the grub shell, Prev: Commands, Up: Top Error messages reported by GRUB ******************************* This chapter describes error messages reported by GRUB when you encounter trouble. *Note Invoking the grub shell::, if your problem is specific to the grub shell. * Menu: * Stage1 errors:: Errors reported by the Stage 1 * Stage1.5 errors:: Errors reported by the Stage 1.5 * Stage2 errors:: Errors reported by the Stage 2  File: grub.info, Node: Stage1 errors, Next: Stage1.5 errors, Up: Troubleshooting Errors reported by the Stage 1 ============================== The general way that the Stage 1 handles errors is to print an error string and then halt. Pressing `--' will reboot. The following is a comprehensive list of error messages for the Stage 1: Hard Disk Error The stage2 or stage1.5 is being read from a hard disk, and the attempt to determine the size and geometry of the hard disk failed. Floppy Error The stage2 or stage1.5 is being read from a floppy disk, and the attempt to determine the size and geometry of the floppy disk failed. It's listed as a separate error since the probe sequence is different than for hard disks. Read Error A disk read error happened while trying to read the stage2 or stage1.5. Geom Error The location of the stage2 or stage1.5 is not in the portion of the disk supported directly by the BIOS read calls. This could occur because the BIOS translated geometry has been changed by the user or the disk is moved to another machine or controller after installation, or GRUB was not installed using itself (if it was, the Stage 2 version of this error would have been seen during that process and it would not have completed the install).  File: grub.info, Node: Stage1.5 errors, Next: Stage2 errors, Prev: Stage1 errors, Up: Troubleshooting Errors reported by the Stage 1.5 ================================ The general way that the Stage 1.5 handles errors is to print an error number in the form `Error NUM' and then halt. Pressing `--' will reboot. The error numbers correspond to the errors reported by Stage 2. *Note Stage2 errors::.  File: grub.info, Node: Stage2 errors, Prev: Stage1.5 errors, Up: Troubleshooting Errors reported by the Stage 2 ============================== The general way that the Stage 2 handles errors is to abort the operation in question, print an error string, then (if possible) either continue based on the fact that an error occurred or wait for the user to deal with the error. The following is a comprehensive list of error messages for the Stage 2 (error numbers for the Stage 1.5 are listed before the colon in each description): 1 : Filename must be either an absolute filename or blocklist This error is returned if a file name is requested which doesn't fit the syntax/rules listed in the *Note Filesystem::. 2 : Bad file or directory type This error is returned if a file requested is not a regular file, but something like a symbolic link, directory, or FIFO. 3 : Bad or corrupt data while decompressing file This error is returned if the run-length decompression code gets an internal error. This is usually from a corrupt file. 4 : Bad or incompatible header in compressed file This error is returned if the file header for a supposedly compressed file is bad. 5 : Partition table invalid or corrupt This error is returned if the sanity checks on the integrity of the partition table fail. This is a bad sign. 6 : Mismatched or corrupt version of stage1/stage2 This error is returned if the install command points to incompatible or corrupt versions of the stage1 or stage2. It can't detect corruption in general, but this is a sanity check on the version numbers, which should be correct. 7 : Loading below 1MB is not supported This error is returned if the lowest address in a kernel is below the 1MB boundary. The Linux zImage format is a special case and can be handled since it has a fixed loading address and maximum size. 8 : Kernel must be loaded before booting This error is returned if GRUB is told to execute the boot sequence without having a kernel to start. 9 : Unknown boot failure This error is returned if the boot attempt did not succeed for reasons which are unknown. 10 : Unsupported Multiboot features requested This error is returned when the Multiboot features word in the Multiboot header requires a feature that is not recognized. The point of this is that the kernel requires special handling which GRUB is probably unable to provide. 11 : Unrecognized device string This error is returned if a device string was expected, and the string encountered didn't fit the syntax/rules listed in the *Note Filesystem::. 12 : Invalid device requested This error is returned if a device string is recognizable but does not fall under the other device errors. 13 : Invalid or unsupported executable format This error is returned if the kernel image being loaded is not recognized as Multiboot or one of the supported native formats (Linux zImage or bzImage, FreeBSD, or NetBSD). 14 : Filesystem compatibility error, cannot read whole file Some of the filesystem reading code in GRUB has limits on the length of the files it can read. This error is returned when the user runs into such a limit. 15 : File not found This error is returned if the specified file name cannot be found, but everything else (like the disk/partition info) is OK. 16 : Inconsistent filesystem structure This error is returned by the filesystem code to denote an internal error caused by the sanity checks of the filesystem structure on disk not matching what it expects. This is usually caused by a corrupt filesystem or bugs in the code handling it in GRUB. 17 : Cannot mount selected partition This error is returned if the partition requested exists, but the filesystem type cannot be recognized by GRUB. 18 : Selected cylinder exceeds maximum supported by BIOS This error is returned when a read is attempted at a linear block address beyond the end of the BIOS translated area. This generally happens if your disk is larger than the BIOS can handle (512MB for (E)IDE disks on older machines or larger than 8GB in general). 19 : Linux kernel must be loaded before initrd This error is returned if the initrd command is used before loading a Linux kernel. 20 : Multiboot kernel must be loaded before modules This error is returned if the module load command is used before loading a Multiboot kernel. It only makes sense in this case anyway, as GRUB has no idea how to communicate the presence of such modules to a non-Multiboot-aware kernel. 21 : Selected disk does not exist This error is returned if the device part of a device- or full file name refers to a disk or BIOS device that is not present or not recognized by the BIOS in the system. 22 : No such partition This error is returned if a partition is requested in the device part of a device- or full file name which isn't on the selected disk. 23 : Error while parsing number This error is returned if GRUB was expecting to read a number and encountered bad data. 24 : Attempt to access block outside partition This error is returned if a linear block address is outside of the disk partition. This generally happens because of a corrupt filesystem on the disk or a bug in the code handling it in GRUB (it's a great debugging tool). 25 : Disk read error This error is returned if there is a disk read error when trying to probe or read data from a particular disk. 26 : Too many symbolic links This error is returned if the link count is beyond the maximum (currently 5), possibly the symbolic links are looped. 27 : Unrecognized command This error is returned if an unrecognized command is entered on the command-line or in a boot sequence section of a configuration file and that entry is selected. 28 : Selected item cannot fit into memory This error is returned if a kernel, module, or raw file load command is either trying to load its data such that it won't fit into memory or it is simply too big. 29 : Disk write error This error is returned if there is a disk write error when trying to write to a particular disk. This would generally only occur during an install of set active partition command. 30 : Invalid argument This error is returned if an argument specified to a command is invalid. 31 : File is not sector aligned This error may occur only when you access a ReiserFS partition by block-lists (e.g. the command `install'). In this case, you should mount the partition with the `-o notail' option. 32 : Must be authenticated This error is returned if you try to run a locked entry. You should enter a correct password before running such an entry. 33 : Serial device not configured This error is returned if you try to change your terminal to a serial one before initializing any serial device. 34 : No spare sectors on the disk This error is returned if a disk doesn't have enough spare space. This happens when you try to embed Stage 1.5 into the unused sectors after the MBR, but the first partition starts right after the MBR or they are used by EZ-BIOS.  File: grub.info, Node: Invoking the grub shell, Next: Invoking grub-install, Prev: Troubleshooting, Up: Top Invoking the grub shell *********************** This chapter documents the grub shell `grub'. Note that the grub shell is an emulator; it doesn't run under the native environment, so it sometimes does something wrong. Therefore, you shouldn't trust it too much. If there is anything wrong with it, don't hesitate to try the native GRUB environment, especially when it guesses a wrong map between BIOS drives and OS devices. * Menu: * Basic usage:: How to use the grub shell * Installation under UNIX:: How to install GRUB via `grub' * Device map:: The map between BIOS drives and OS devices  File: grub.info, Node: Basic usage, Next: Installation under UNIX, Up: Invoking the grub shell Introduction into the grub shell ================================ You can use the command `grub' for installing GRUB under your operating systems and for a testbed when you add a new feature into GRUB or when fixing a bug. `grub' is almost the same as the Stage 2, and, in fact, it shares the source code with the Stage 2 and you can use the same commands (*note Commands::) in `grub'. It is emulated by replacing BIOS calls with UNIX system calls and libc functions. The command `grub' accepts the following options: `--help' Print a summary of the command-line options and exit. `--version' Print the version number of GRUB and exit. `--verbose' Print some verbose messages for debugging purpose. `--device-map=FILE' Use the device map file FILE. The format is described in *Note Device map::. `--no-floppy' Do not probe any floppy drive. This option has no effect if the option `--device-map' is specified (*note Device map::). `--probe-second-floppy' Probe the second floppy drive. If this option is not specified, the grub shell does not probe it, as that sometimes takes a long time. If you specify the device map file (*note Device map::), the grub shell just ignores this option. `--config-file=FILE' Read the configuration file FILE instead of `/boot/grub/menu.lst'. The format is the same as the normal GRUB syntax. See *Note Filesystem::, for more information. `--boot-drive=DRIVE' Set the stage2 BOOT_DRIVE to DRIVE. This argument should be an integer (decimal, octal or hexadecimal). `--install-partition=PAR' Set the stage2 INSTALL_PARTITION to PAR. This argument should be an integer (decimal, octal or hexadecimal). `--no-config-file' Do not use the configuration file even if it can be read. `--no-curses' Do not use the screen handling interface by the curses even if it is available. `--batch' This option has the same meaning as `--no-config-file --no-curses'. `--read-only' Disable writing to any disk. `--hold' Wait until a debugger will attach. This option is useful when you want to debug the startup code.  File: grub.info, Node: Installation under UNIX, Next: Device map, Prev: Basic usage, Up: Invoking the grub shell How to install GRUB via `grub' ============================== The installation procedure is the same as under the "native" Stage 2. *Note Installation::, for more information. The command `grub'-specific information is described here. What you should be careful about is "buffer cache". `grub' makes use of raw devices instead of filesystems that your operating systems serve, so there exists a potential problem that some cache inconsistency may corrupt your filesystems. What we recommend is: * If you can unmount drives to which GRUB may write any amount of data, unmount them before running `grub'. * If a drive cannot be unmounted but can be mounted with the read-only flag, mount it in read-only mode. That should be secure. * If a drive must be mounted with the read-write flag, make sure that no activity is being done on it while the command `grub' is running. * Reboot your operating system as soon as possible. This is probably not required if you follow the rules above, but reboot is the most secure way. In addition, enter the command `quit' when you finish the installation. That is _very important_ because `quit' makes the buffer cache consistent. Do not push . If you want to install GRUB non-interactively, specify `--batch' option in the command-line. This is a simple example: #!/bin/sh # Use /usr/sbin/grub if you are on an older system. /sbin/grub --batch </dev/null 2>/dev/null root (hd0,0) setup (hd0) quit EOT  File: grub.info, Node: Device map, Prev: Installation under UNIX, Up: Invoking the grub shell The map between BIOS drives and OS devices ========================================== When you specify the option `--device-map' (*note Basic usage::), the grub shell creates the "device map file" automatically unless it already exists. The file name `/boot/grub/device.map' is preferred. If the device map file exists, the grub shell reads it to map BIOS drives to OS devices. This file consists of lines like this: DEVICE FILE DEVICE is a drive specified in the GRUB syntax (*note Device syntax::), and FILE is an OS file, which is normally a device file. The reason why the grub shell gives you the device map file is that it cannot guess the map between BIOS drives and OS devices correctly in some environments. For example, if you exchange the boot sequence between IDE and SCSI in your BIOS, it gets the order wrong. Thus, edit the file if the grub shell makes a mistake. You can put any comments in the file if needed, as the grub shell assumes that a line is just a comment if the first character is `#'.  File: grub.info, Node: Invoking grub-install, Next: Invoking grub-md5-crypt, Prev: Invoking the grub shell, Up: Top Invoking grub-install ********************* The program `grub-install' installs GRUB on your drive using the grub shell (*note Invoking the grub shell::). You must specify the device name on which you want to install GRUB, like this: grub-install INSTALL_DEVICE The device name INSTALL_DEVICE is an OS device name or a GRUB device name. `grub-install' accepts the following options: `--help' Print a summary of the command-line options and exit. `--version' Print the version number of GRUB and exit. `--force-lba' Force GRUB to use LBA mode even for a buggy BIOS. Use this option only if your BIOS doesn't work properly in LBA mode even though it supports LBA mode. `--root-directory=DIR' Install GRUB images under the directory DIR instead of the root directory. This option is useful when you want to install GRUB into a separate partition or a removable disk. Here is an example in which you have a separate "boot" partition which is mounted on `/boot': grub-install --root-directory=/boot hd0 `--grub-shell=FILE' Use FILE as the grub shell. You can append arbitrary options to FILE after the file name, like this: grub-install --grub-shell="grub --read-only" /dev/fd0 `--recheck' Recheck the device map, even if `/boot/grub/device.map' already exists. You should use this option whenever you add/remove a disk into/from your computer.  File: grub.info, Node: Invoking grub-md5-crypt, Next: Invoking grub-terminfo, Prev: Invoking grub-install, Up: Top Invoking grub-md5-crypt *********************** The program `grub-md5-crypt' encrypts a password in MD5 format. This is just a frontend of the grub shell (*note Invoking the grub shell::). Passwords encrypted by this program can be used with the command `password' (*note password::). `grub-md5-crypt' accepts the following options: `--help' Print a summary of the command-line options and exit. `--version' Print the version information and exit. `--grub-shell=FILE' Use FILE as the grub shell.  File: grub.info, Node: Invoking grub-terminfo, Next: Invoking grub-set-default, Prev: Invoking grub-md5-crypt, Up: Top Invoking grub-terminfo ********************** The program `grub-terminfo' generates a terminfo command from a terminfo name (*note terminfo::). The result can be used in the configuration file, to define escape sequences. Because GRUB assumes that your terminal is vt100-compatible by default, this would be useful only if your terminal is uncommon (such as vt52). `grub-terminfo' accepts the following options: `--help' Print a summary of the command-line options and exit. `--version' Print the version information and exit. You must specify one argument to this command. For example: grub-terminfo vt52  File: grub.info, Node: Invoking grub-set-default, Next: Invoking mbchk, Prev: Invoking grub-terminfo, Up: Top Invoking grub-set-default ************************* The program `grub-set-default' sets the default boot entry for GRUB. This automatically creates a file named `default' under your GRUB directory (i.e. `/boot/grub'), if it is not present. This file is used to determine the default boot entry when GRUB boots up your system when you use `default saved' in your configuration file (*note default::), and to save next default boot entry when you use `savedefault' in a boot entry (*note savedefault::). `grub-set-default' accepts the following options: `--help' Print a summary of the command-line options and exit. `--version' Print the version information and exit. `--root-directory=DIR' Use the directory DIR instead of the root directory (i.e. `/') to define the location of the default file. This is useful when you mount a disk which is used for another system. You must specify a single argument to `grub-set-default'. This argument is normally the number of a default boot entry. For example, if you have this configuration file: default saved timeout 10 title GNU/Hurd root (hd0,0) ... title GNU/Linux root (hd0,1) ... and if you want to set the next default boot entry to GNU/Linux, you may execute this command: grub-set-default 1 Because the entry for GNU/Linux is `1'. Note that entries are counted from zero. So, if you want to specify GNU/Hurd here, then you should specify `0'. This feature is very useful if you want to test a new kernel or to make your system quite robust. *Note Making your system robust::, for more hints about how to set up a robust system.  File: grub.info, Node: Invoking mbchk, Next: Obtaining and Building GRUB, Prev: Invoking grub-set-default, Up: Top Invoking mbchk ************** The program `mbchk' checks for the format of a Multiboot kernel. We recommend using this program before booting your own kernel by GRUB. `mbchk' accepts the following options: `--help' Print a summary of the command-line options and exit. `--version' Print the version number of GRUB and exit. `--quiet' Suppress all normal output.  File: grub.info, Node: Obtaining and Building GRUB, Next: Reporting bugs, Prev: Invoking mbchk, Up: Top How to obtain and build GRUB **************************** *Caution:* GRUB requires binutils-2.9.1.0.23 or later because the GNU assembler has been changed so that it can produce real 16bits machine code between 2.9.1 and 2.9.1.0.x. See `http://sources.redhat.com/binutils/', to obtain information on how to get the latest version. GRUB is available from the GNU alpha archive site `ftp://alpha.gnu.org/gnu/grub' or any of its mirrors. The file will be named grub-version.tar.gz. The current version is 0.95, so the file you should grab is: `ftp://alpha.gnu.org/gnu/grub/grub-0.95.tar.gz' To unbundle GRUB use the instruction: zcat grub-0.95.tar.gz | tar xvf - which will create a directory called `grub-0.95' with all the sources. You can look at the file `INSTALL' for detailed instructions on how to build and install GRUB, but you should be able to just do: cd grub-0.95 ./configure make install This will install the grub shell `grub' (*note Invoking the grub shell::), the Multiboot checker `mbchk' (*note Invoking mbchk::), and the GRUB images. This will also install the GRUB manual. Also, the latest version is available from the CVS. See `http://savannah.gnu.org/cvs/?group=grub' for more information.  File: grub.info, Node: Reporting bugs, Next: Future, Prev: Obtaining and Building GRUB, Up: Top Reporting bugs ************** These are the guideline for how to report bugs. Take a look at this list below before you submit bugs: 1. Before getting unsettled, read this manual through and through. Also, see the GNU GRUB FAQ (http://www.gnu.org/software/grub/grub-faq.html). 2. Always mention the information on your GRUB. The version number and the configuration are quite important. If you build it yourself, write the options specified to the configure script and your operating system, including the versions of gcc and binutils. 3. If you have trouble with the installation, inform us of how you installed GRUB. Don't omit error messages, if any. Just `GRUB hangs up when it boots' is not enough. The information on your hardware is also essential. These are especially important: the geometries and the partition tables of your hard disk drives and your BIOS. 4. If GRUB cannot boot your operating system, write down _everything_ you see on the screen. Don't paraphrase them, like `The foo OS crashes with GRUB, even though it can boot with the bar boot loader just fine'. Mention the commands you executed, the messages printed by them, and information on your operating system including the version number. 5. Explain what you wanted to do. It is very useful to know your purpose and your wish, and how GRUB didn't satisfy you. 6. If you can investigate the problem yourself, please do. That will give you and us much more information on the problem. Attaching a patch is even better. When you attach a patch, make the patch in unified diff format, and write ChangeLog entries. But, even when you make a patch, don't forget to explain the problem, so that we can understand what your patch is for. 7. Write down anything that you think might be related. Please understand that we often need to reproduce the same problem you encounterred in our environment. So your information should be sufficient for us to do the same thing--Don't forget that we cannot see your computer directly. If you are not sure whether to state a fact or leave it out, state it! Reporting too many things is much better than omitting something important. If you follow the guideline above, submit a report to the Bug Tracking System (http://savannah.gnu.org/bugs/?group=grub). Alternatively, you can submit a report via electronic mail to , but we strongly recommend that you use the Bug Tracking System, because e-mail can be passed over easily. Once we get your report, we will try to fix the bugs.  File: grub.info, Node: Future, Next: Internals, Prev: Reporting bugs, Up: Top Where GRUB will go ****************** We started the next generation of GRUB, GRUB 2. This will include internationalization, dynamic module loading, real memory management, multiple architecture support, a scripting language, and many other nice feature. If you are interested in the development of GRUB 2, take a look at the homepage (http://www.gnu.org/software/grub/grub.html).  File: grub.info, Node: Internals, Next: Index, Prev: Future, Up: Top Hacking GRUB ************ This chapter documents the user-invisible aspect of GRUB. As a general rule of software development, it is impossible to keep the descriptions of the internals up-to-date, and it is quite hard to document everything. So refer to the source code, whenever you are not satisfied with this documentation. Please assume that this gives just hints to you. * Menu: * Memory map:: The memory map of various components * Embedded data:: Embedded variables in GRUB * Filesystem interface:: The generic interface for filesystems * Command interface:: The generic interface for built-ins * Bootstrap tricks:: The bootstrap mechanism used in GRUB * I/O ports detection:: How to probe I/O ports used by INT 13H * Memory detection:: How to detect all installed RAM * Low-level disk I/O:: INT 13H disk I/O interrupts * MBR:: The structure of Master Boot Record * Partition table:: The format of partition tables * Submitting patches:: Where and how you should send patches  File: grub.info, Node: Memory map, Next: Embedded data, Up: Internals The memory map of various components ==================================== GRUB consists of two distinct components, called "stages", which are loaded at different times in the boot process. Because they run mutual-exclusively, sometimes a memory area overlaps with another memory area. And, even in one stage, a single memory area can be used for various purposes, because their usages are mutually exclusive. Here is the memory map of the various components: 0 to 4K-1 BIOS and real mode interrupts 0x07BE to 0x07FF Partition table passed to another boot loader down from 8K-1 Real mode stack 0x2000 to ? The optional Stage 1.5 is loaded here 0x2000 to 0x7FFF Command-line buffer for Multiboot kernels and modules 0x7C00 to 0x7DFF Stage 1 is loaded here by BIOS or another boot loader 0x7F00 to 0x7F42 LBA drive parameters 0x8000 to ? Stage2 is loaded here The end of Stage 2 to 416K-1 Heap, in particular used for the menu down from 416K-1 Protected mode stack 416K to 448K-1 Filesystem buffer 448K to 479.5K-1 Raw device buffer 479.5K to 480K-1 512-byte scratch area 480K to 512K-1 Buffers for various functions, such as password, command-line, cut and paste, and completion. The last 1K of lower memory Disk swapping code and data See the file `stage2/shared.h', for more information.  File: grub.info, Node: Embedded data, Next: Filesystem interface, Prev: Memory map, Up: Internals Embedded variables in GRUB ========================== Stage 1 and Stage 2 have embedded variables whose locations are well-defined, so that the installation can patch the binary file directly without recompilation of the stages. In Stage 1, these are defined: `0x3E' The version number (not GRUB's, but the installation mechanism's). `0x40' The boot drive. If it is 0xFF, use a drive passed by BIOS. `0x41' The flag for if forcing LBA. `0x42' The starting address of Stage 2. `0x44' The first sector of Stage 2. `0x48' The starting segment of Stage 2. `0x1FE' The signature (`0xAA55'). See the file `stage1/stage1.S', for more information. In the first sector of Stage 1.5 and Stage 2, the block lists are recorded between `firstlist' and `lastlist'. The address of `lastlist' is determined when assembling the file `stage2/start.S'. The trick here is that it is actually read backward, and the first 8-byte block list is not read here, but after the pointer is decremented 8 bytes, then after reading it, it decrements again, reads, and so on, until it is finished. The terminating condition is when the number of sectors to be read in the next block list is zero. The format of a block list can be seen from the example in the code just before the `firstlist' label. Note that it is always from the beginning of the disk, but _not_ relative to the partition boundaries. In the second sector of Stage 1.5 and Stage 2, these are defined: `0x6' The version number (likewise, the installation mechanism's). `0x8' The installed partition. `0xC' The saved entry number. `0x10' The identifier. `0x11' The flag for if forcing LBA. `0x12' The version string (GRUB's). `0x12' + "the length of the version string" The name of a configuration file. See the file `stage2/asm.S', for more information.  File: grub.info, Node: Filesystem interface, Next: Command interface, Prev: Embedded data, Up: Internals The generic interface for filesystems ===================================== For any particular partition, it is presumed that only one of the "normal" filesystems such as FAT, FFS, or ext2fs can be used, so there is a switch table managed by the functions in `disk_io.c'. The notation is that you can only "mount" one at a time. The block list filesystem has a special place in the system. In addition to the "normal" filesystem (or even without one mounted), you can access disk blocks directly (in the indicated partition) via the block list notation. Using the block list filesystem doesn't effect any other filesystem mounts. The variables which can be read by the filesystem backend are: `current_drive' The current BIOS drive number (numbered from 0, if a floppy, and numbered from 0x80, if a hard disk). `current_partition' The current partition number. `current_slice' The current partition type. `saved_drive' The "drive" part of the root device. `saved_partition' The "partition" part of the root device. `part_start' The current partition starting address, in sectors. `part_length' The current partition length, in sectors. `print_possibilities' True when the `dir' function should print the possible completions of a file, and false when it should try to actually open a file of that name. `FSYS_BUF' Filesystem buffer which is 32K in size, to use in any way which the filesystem backend desires. The variables which need to be written by a filesystem backend are: `filepos' The current position in the file, in sectors. *Caution:* the value of FILEPOS can be changed out from under the filesystem code in the current implementation. Don't depend on it being the same for later calls into the backend code! `filemax' The length of the file. `disk_read_func' The value of DISK_READ_HOOK _only_ during reading of data for the file, not any other fs data, inodes, FAT tables, whatever, then set to `NULL' at all other times (it will be `NULL' by default). If this isn't done correctly, then the `testload' and `install' commands won't work correctly. The functions expected to be used by the filesystem backend are: `devread' Only read sectors from within a partition. Sector 0 is the first sector in the partition. `grub_read' If the backend uses the block list code, then `grub_read' can be used, after setting BLOCK_FILE to 1. `print_a_completion' If PRINT_POSSIBILITIES is true, call `print_a_completion' for each possible file name. Otherwise, the file name completion won't work. The functions expected to be defined by the filesystem backend are described at least moderately in the file `filesys.h'. Their usage is fairly evident from their use in the functions in `disk_io.c', look for the use of the FSYS_TABLE array. *Caution:* The semantics are such that then `mount'ing the filesystem, presume the filesystem buffer `FSYS_BUF' is corrupted, and (re-)load all important contents. When opening and reading a file, presume that the data from the `mount' is available, and doesn't get corrupted by the open/read (i.e. multiple opens and/or reads will be done with only one mount if in the same filesystem).  File: grub.info, Node: Command interface, Next: Bootstrap tricks, Prev: Filesystem interface, Up: Internals The generic interface for built-ins =================================== GRUB built-in commands are defined in a uniformal interface, whether they are menu-specific or can be used anywhere. The definition of a builtin command consists of two parts: the code itself and the table of the information. The code must be a function which takes two arguments, a command-line string and flags, and returns an `int' value. The "flags" argument specifies how the function is called, using a bit mask. The return value must be zero if successful, otherwise non-zero. So it is normally enough to return ERRNUM. The table of the information is represented by the structure `struct builtin', which contains the name of the command, a pointer to the function, flags, a short description of the command and a long description of the command. Since the descriptions are used only for help messages interactively, you don't have to define them, if the command may not be called interactively (such as `title'). The table is finally registered in the table BUILTIN_TABLE, so that `run_script' and `enter_cmdline' can find the command. See the files `cmdline.c' and `builtins.c', for more details.