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