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/AThis is the documentation of GNU GRUB, the GRand Unified Bootloader, a
1N/Aflexible and powerful boot loader program for PCs.
1N/A This edition documents version 0.97.
1N/A* Introduction:: Capturing the spirit of GRUB
1N/A* Naming convention:: Names of your drives in GRUB
1N/A* Installation:: Installing GRUB on your drive
1N/A* Booting:: How to boot different operating systems
1N/A* Configuration:: Writing your own configuration file
1N/A* Network:: Downloading OS images from a network
1N/A* Serial terminal:: Using GRUB via a serial line
1N/A* Preset Menu:: Embedding a configuration file into GRUB
1N/A* Security:: Improving the security
1N/A* Images:: GRUB image files
1N/A* Filesystem:: Filesystem syntax and semantics
1N/A* Interface:: The menu and the command-line
1N/A* Commands:: The list of available builtin commands
1N/A* Troubleshooting:: Error messages produced by GRUB
1N/A* Invoking the grub shell:: How to use the grub shell
1N/A* Invoking grub-install:: How to use the GRUB installer
1N/A* Invoking grub-md5-crypt:: How to generate a cryptic password
1N/A* Invoking grub-terminfo:: How to generate a terminfo command
1N/A* Invoking grub-set-default:: How to set a default boot entry
1N/A* Invoking mbchk:: How to use the Multiboot checker
1N/A* Obtaining and Building GRUB:: How to obtain and build GRUB
1N/A* Reporting bugs:: Where you should send a bug report
1N/A* Future:: Some future plans on GRUB
1N/A* Internals:: Hacking GRUB
1N/AFile:
grub.info, Node: Introduction, Next: Naming convention, Prev: Top, Up: Top
1N/A1 Introduction to GRUB
1N/A**********************
1N/A* Overview:: What exactly GRUB is and how to use it
1N/A* History:: From maggot to house fly
1N/A* Features:: GRUB features
1N/A* Role of a boot loader:: The role of a boot loader
1N/AFile:
grub.info, Node: Overview, Next: History, Up: Introduction
1N/ABriefly, a "boot loader" is the first software program that runs when a
1N/Acomputer starts. It is responsible for loading and transferring
1N/Acontrol to an operating system "kernel" software (such as Linux or GNU
1N/AMach). The kernel, in turn, initializes the rest of the operating
1N/A GNU GRUB is a very powerful boot loader, which can load a wide
1N/Avariety of free operating systems, as well as proprietary operating
1N/Asystems with chain-loading(1) (*note Overview-Footnote-1::). GRUB is
1N/Adesigned to address the complexity of booting a personal computer; both
1N/Athe program and this manual are tightly bound to that computer platform,
1N/Aalthough porting to other platforms may be addressed in the future.
1N/A One of the important features in GRUB is flexibility; GRUB
1N/Aunderstands filesystems and kernel executable formats, so you can load
1N/Aan arbitrary operating system the way you like, without recording the
1N/Aphysical position of your kernel on the disk. Thus you can load the
1N/Akernel just by specifying its file name and the drive and partition
1N/Awhere the kernel resides.
1N/A When booting with GRUB, you can use either a command-line interface
1N/A(*note Command-line interface::), or a menu interface (*note Menu
1N/Ainterface::). Using the command-line interface, you type the drive
1N/Aspecification and file name of the kernel manually. In the menu
1N/Ainterface, you just select an OS using the arrow keys. The menu is
1N/Abased on a configuration file which you prepare beforehand (*note
1N/AConfiguration::). While in the menu, you can switch to the command-line
1N/Amode, and vice-versa. You can even edit menu entries before using them.
1N/A In the following chapters, you will learn how to specify a drive, a
1N/Apartition, and a file name (*note Naming convention::) to GRUB, how to
1N/Ainstall GRUB on your drive (*note Installation::), and how to boot your
1N/AOSes (*note Booting::), step by step.
1N/A Besides the GRUB boot loader itself, there is a "grub shell" `grub'
1N/A(*note Invoking the grub shell::) which can be run when you are in your
1N/Aoperating system. It emulates the boot loader and can be used for
1N/Ainstalling the boot loader.
1N/A (1) "chain-load" is the mechanism for loading unsupported operating
1N/Asystems by loading another boot loader. It is typically used for
1N/Aloading DOS or Windows.
1N/AFile:
grub.info, Node: History, Next: Features, Prev: Overview, Up: Introduction
1N/AGRUB originated in 1995 when Erich Boleyn was trying to boot the GNU
1N/AHurd with the University of Utah's Mach 4 microkernel (now known as GNU
1N/AMach). Erich and Brian Ford designed the Multiboot Specification
1N/A(*note Multiboot Specification: (multiboot)Top.), because they were
1N/Adetermined not to add to the large number of mutually-incompatible PC
1N/A Erich then began modifying the FreeBSD boot loader so that it would
1N/Aunderstand Multiboot. He soon realized that it would be a lot easier to
1N/Awrite his own boot loader from scratch than to keep working on the
1N/AFreeBSD boot loader, and so GRUB was born.
1N/A Erich added many features to GRUB, but other priorities prevented him
1N/Afrom keeping up with the demands of its quickly-expanding user base. In
1N/A1999, Gordon Matzigkeit and Yoshinori K. Okuji adopted GRUB as an
1N/Aofficial GNU package, and opened its development by making the latest
1N/Asources available via anonymous CVS. *Note Obtaining and Building
1N/AGRUB::, for more information.
1N/AFile:
grub.info, Node: Features, Next: Role of a boot loader, Prev: History, Up: Introduction
1N/AThe primary requirement for GRUB is that it be compliant with the
1N/A"Multiboot Specification", which is described in *Note Multiboot
1N/ASpecification: (multiboot)Top.
1N/A The other goals, listed in approximate order of importance, are:
1N/A * Basic functions must be straightforward for end-users.
1N/A * Rich functionality to support kernel experts and designers.
1N/A * Backward compatibility for booting FreeBSD, NetBSD, OpenBSD, and
1N/A Linux. Proprietary kernels (such as DOS, Windows NT, and OS/2) are
1N/A supported via a chain-loading function.
1N/A Except for specific compatibility modes (chain-loading and the Linux
1N/A"piggyback" format), all kernels will be started in much the same state
1N/Aas in the Multiboot Specification. Only kernels loaded at 1 megabyte or
1N/Aabove are presently supported. Any attempt to load below that boundary
1N/Awill simply result in immediate failure and an error message reporting
1N/A In addition to the requirements above, GRUB has the following
1N/Afeatures (note that the Multiboot Specification doesn't require all the
1N/Afeatures that GRUB supports):
1N/ARecognize multiple executable formats
1N/A Support many of the "
a.out" variants plus "ELF". Symbol tables are
1N/ASupport non-Multiboot kernels
1N/A Support many of the various free 32-bit kernels that lack Multiboot
1N/A compliance (primarily FreeBSD, NetBSD, OpenBSD, and Linux).
1N/A Chain-loading of other boot loaders is also supported.
1N/ALoad multiples modules
1N/A Fully support the Multiboot feature of loading multiple modules.
1N/ALoad a configuration file
1N/A Support a human-readable text configuration file with preset boot
1N/A commands. You can also load another configuration file dynamically
1N/A and embed a preset configuration file in a GRUB image file. The
1N/A list of commands (*note Commands::) are a superset of those
1N/A supported on the command-line. An example configuration file is
1N/A provided in *Note Configuration::.
1N/AProvide a menu interface
1N/A A menu interface listing preset boot commands, with a programmable
1N/A timeout, is available. There is no fixed limit on the number of
1N/A boot entries, and the current implementation has space for several
1N/AHave a flexible command-line interface
1N/A A fairly flexible command-line interface, accessible from the menu,
1N/A is available to edit any preset commands, or write a new boot
1N/A command set from scratch. If no configuration file is present,
1N/A GRUB drops to the command-line.
1N/A The list of commands (*note Commands::) are a subset of those
1N/A supported for configuration files. Editing commands closely
1N/A resembles the Bash command-line (*note Bash: (features)Command
1N/A Line Editing.), with <TAB>-completion of commands, devices,
1N/A partitions, and files in a directory depending on context.
1N/ASupport multiple filesystem types
1N/A Support multiple filesystem types transparently, plus a useful
1N/A explicit blocklist notation. The currently supported filesystem
1N/A types are "BSD FFS", "DOS FAT16 and FAT32", "Minix fs", "Linux
1N/A ext2fs", "ReiserFS", "JFS", "XFS", and "VSTa fs". *Note
1N/A Filesystem::, for more information.
1N/ASupport automatic decompression
1N/A Can decompress files which were compressed by `gzip'. This
1N/A function is both automatic and transparent to the user (
i.e. all
1N/A functions operate upon the uncompressed contents of the specified
1N/A files). This greatly reduces a file size and loading time, a
1N/A particularly great benefit for floppies.(1) (*note
1N/A Features-Footnote-1::)
1N/A It is conceivable that some kernel modules should be loaded in a
1N/A compressed state, so a different module-loading command can be
1N/A specified to avoid uncompressing the modules.
1N/AAccess data on any installed device
1N/A Support reading data from any or all floppies or hard disk(s)
1N/A recognized by the BIOS, independent of the setting of the root
1N/ABe independent of drive geometry translations
1N/A Unlike many other boot loaders, GRUB makes the particular drive
1N/A translation irrelevant. A drive installed and running with one
1N/A translation may be converted to another translation without any
1N/A adverse effects or changes in GRUB's configuration.
1N/ADetect all installed RAM
1N/A GRUB can generally find all the installed RAM on a PC-compatible
1N/A machine. It uses an advanced BIOS query technique for finding all
1N/A memory regions. As described on the Multiboot Specification (*note
1N/A Multiboot Specification: (multiboot)Top.), not all kernels make
1N/A use of this information, but GRUB provides it for those who do.
1N/ASupport Logical Block Address mode
1N/A In traditional disk calls (called "CHS mode"), there is a geometry
1N/A translation problem, that is, the BIOS cannot access over 1024
1N/A cylinders, so the accessible space is limited to at least 508 MB
1N/A and to at most 8GB. GRUB can't universally solve this problem, as
1N/A there is no standard interface used in all machines. However,
1N/A several newer machines have the new interface, Logical Block
1N/A Address ("LBA") mode. GRUB automatically detects if LBA mode is
1N/A available and uses it if available. In LBA mode, GRUB can access
1N/ASupport network booting
1N/A GRUB is basically a disk-based boot loader but also has network
1N/A support. You can load OS images from a network by using the "TFTP"
1N/ASupport remote terminals
1N/A To support computers with no console, GRUB provides remote terminal
1N/A support, so that you can control GRUB from a remote host. Only
1N/A serial terminal support is implemented at the moment.
1N/A (1) There are a few pathological cases where loading a very badly
1N/Aorganized ELF kernel might take longer, but in practice this never
1N/AFile:
grub.info, Node: Role of a boot loader, Prev: Features, Up: Introduction
1N/A1.4 The role of a boot loader
1N/A=============================
1N/AThe following is a quotation from Gordon Matzigkeit, a GRUB fanatic:
1N/A Some people like to acknowledge both the operating system and
1N/A kernel when they talk about their computers, so they might say
1N/A that the kernel is the most important part of the system, so they
1N/A like to call their GNU operating systems "Linux systems."
1N/A I, personally, believe that this is a grave injustice, because the
1N/A _boot loader_ is the most important software of all. I used to
1N/A refer to the above systems as either "LILO"(1) (*note Role of a
1N/A boot loader-Footnote-1::) or "GRUB" systems.
1N/A Unfortunately, nobody ever understood what I was talking about;
1N/A now I just use the word "GNU" as a pseudonym for GRUB.
1N/A So, if you ever hear people talking about their alleged "GNU"
1N/A systems, remember that they are actually paying homage to the best
1N/A boot loader around... GRUB!
1N/A We, the GRUB maintainers, do not (usually) encourage Gordon's level
1N/Aof fanaticism, but it helps to remember that boot loaders deserve
1N/Arecognition. We hope that you enjoy using GNU GRUB as much as we did
1N/AFile:
grub.info, Node: Role of a boot loader-Footnotes, Up: Role of a boot loader
1N/A (1) The LInux LOader, a boot loader that everybody uses, but nobody
1N/AFile:
grub.info, Node: Naming convention, Next: Installation, Prev: Introduction, Up: Top
1N/AThe device syntax used in GRUB is a wee bit different from what you may
1N/Ahave seen before in your operating system(s), and you need to know it so
1N/A Look at the following examples and explanations:
1N/A First of all, GRUB requires that the device name be enclosed with
1N/A`(' and `)'. The `fd' part means that it is a floppy disk. The number
1N/A`0' is the drive number, which is counted from _zero_. This expression
1N/Ameans that GRUB will use the whole floppy disk.
1N/A Here, `hd' means it is a hard disk drive. The first integer `0'
1N/Aindicates the drive number, that is, the first hard disk, while the
1N/Asecond integer, `1', indicates the partition number (or the PC slice
1N/Anumber in the BSD terminology). Once again, please note that the
1N/Apartition numbers are counted from _zero_, not from one. This
1N/Aexpression means the second partition of the first hard disk drive. In
1N/Athis case, GRUB uses one partition of the disk, instead of the whole
1N/A This specifies the first "extended partition" of the first hard disk
1N/Adrive. Note that the partition numbers for extended partitions are
1N/Acounted from `4', regardless of the actual number of primary partitions
1N/A This means the BSD `a' partition of the second hard disk. If you
1N/Aneed to specify which PC slice number should be used, use something
1N/Alike this: `(hd1,0,a)'. If the PC slice number is omitted, GRUB
1N/Asearches for the first PC slice which has a BSD `a' partition.
1N/A Of course, to actually access the disks or partitions with GRUB, you
1N/Aneed to use the device specification in a command, like `root (fd0)' or
1N/A`unhide (hd0,2)'. To help you find out which number specifies a
1N/Apartition you want, the GRUB command-line (*note Command-line
1N/Ainterface::) options have argument completion. This means that, for
1N/Aexample, you only need to type
1N/A followed by a <TAB>, and GRUB will display the list of drives,
1N/Apartitions, or file names. So it should be quite easy to determine the
1N/Aname of your target partition, even with minimal knowledge of the
1N/A Note that GRUB does _not_ distinguish IDE from SCSI - it simply
1N/Acounts the drive numbers from zero, regardless of their type. Normally,
1N/Aany IDE drive number is less than any SCSI drive number, although that
1N/Ais not true if you change the boot sequence by swapping IDE and SCSI
1N/A Now the question is, how to specify a file? Again, consider an
1N/A This specifies the file named `vmlinuz', found on the first
1N/Apartition of the first hard disk drive. Note that the argument
1N/Acompletion works with file names, too.
1N/A That was easy, admit it. Now read the next chapter, to find out how
1N/Ato actually install GRUB on your drive.
1N/AFile:
grub.info, Node: Installation, Next: Booting, Prev: Naming convention, Up: Top
1N/AIn order to install GRUB as your boot loader, you need to first install
1N/Athe GRUB system and utilities under your UNIX-like operating system
1N/A(*note Obtaining and Building GRUB::). You can do this either from the
1N/Asource tarball, or as a package for your OS.
1N/A After you have done that, you need to install the boot loader on a
1N/Adrive (floppy or hard disk). There are two ways of doing that - either
1N/Ausing the utility `grub-install' (*note Invoking grub-install::) on a
1N/AUNIX-like OS, or by running GRUB itself from a floppy. These are quite
1N/Asimilar, however the utility might probe a wrong BIOS drive, so you
1N/A Also, if you install GRUB on a UNIX-like OS, please make sure that
1N/Ayou have an emergency boot disk ready, so that you can rescue your
1N/Acomputer if, by any chance, your hard drive becomes unusable
1N/A GRUB comes with boot images, which are normally put in the directory
1N/Ato copy the files `stage1', `stage2', and `*stage1_5' to the directory
1N/Agrub-set-default::) if you intend to use `default saved' (*note
1N/Adefault::) in your configuration file. Hereafter, the directory where
1N/Awill be called the "image directory", and the directory where the boot
1N/Aloader needs to find them (usually `
/boot/grub') will be called the
1N/A* Creating a GRUB boot floppy::
1N/A* Installing GRUB natively::
1N/A* Installing GRUB using grub-install::
1N/A* Making a GRUB bootable CD-ROM::
1N/AFile:
grub.info, Node: Creating a GRUB boot floppy, Next: Installing GRUB natively, Up: Installation
1N/A3.1 Creating a GRUB boot floppy
1N/A===============================
1N/ATo create a GRUB boot floppy, you need to take the files `stage1' and
1N/A`stage2' from the image directory, and write them to the first and the
1N/Asecond block of the floppy disk, respectively.
1N/A *Caution:* This procedure will destroy any data currently stored on
1N/A On a UNIX-like operating system, that is done with the following
1N/A The device file name may be different. Consult the manual for your
1N/AFile:
grub.info, Node: Installing GRUB natively, Next: Installing GRUB using grub-install, Prev: Creating a GRUB boot floppy, Up: Installation
1N/A3.2 Installing GRUB natively
1N/A============================
1N/A*Caution:* Installing GRUB's stage1 in this manner will erase the
1N/Anormal boot-sector used by an OS.
1N/A GRUB can currently boot GNU Mach, Linux, FreeBSD, NetBSD, and OpenBSD
1N/Adirectly, so using it on a boot sector (the first sector of a
1N/Apartition) should be okay. But generally, it would be a good idea to
1N/Aback up the first sector of the partition on which you are installing
1N/AGRUB's stage1. This isn't as important if you are installing GRUB on
1N/Athe first sector of a hard disk, since it's easy to reinitialize it
1N/A(
e.g. by running `FDISK /MBR' from DOS).
1N/A If you decide to install GRUB in the native environment, which is
1N/Adefinitely desirable, you'll need to create a GRUB boot disk, and
1N/Areboot your computer with it. Otherwise, see *Note Installing GRUB
1N/Ausing grub-install::.
1N/A Once started, GRUB will show the command-line interface (*note
1N/ACommand-line interface::). First, set the GRUB's "root device"(1)
1N/A(*note Installing GRUB natively-Footnote-1::) to the partition
1N/Acontaining the boot directory, like this:
1N/A If you are not sure which partition actually holds this directory,
1N/Ause the command `find' (*note find::), like this:
1N/Adevices which contain the file.
1N/A Once you've set the root device correctly, run the command `setup'
1N/A This command will install the GRUB boot loader on the Master Boot
1N/ARecord (MBR) of the first drive. If you want to put GRUB into the boot
1N/Asector of a partition instead of putting it in the MBR, specify the
1N/Apartition into which you want to install GRUB:
1N/A If you install GRUB into a partition or a drive other than the first
1N/Aone, you must chain-load GRUB from another boot loader. Refer to the
1N/Amanual for the boot loader to know how to chain-load GRUB.
1N/A After using the setup command, you will boot into GRUB without the
1N/AGRUB floppy. See the chapter *Note Booting:: to find out how to boot
1N/Ayour operating systems from GRUB.
1N/AFile:
grub.info, Node: Installing GRUB natively-Footnotes, Up: Installing GRUB natively
1N/A (1) Note that GRUB's root device doesn't necessarily mean your OS's
1N/Aroot partition; if you need to specify a root partition for your OS,
1N/Aadd the argument into the command `kernel'.
1N/AFile:
grub.info, Node: Installing GRUB using grub-install, Next: Making a GRUB bootable CD-ROM, Prev: Installing GRUB natively, Up: Installation
1N/A3.3 Installing GRUB using grub-install
1N/A======================================
1N/A*Caution:* This procedure is definitely less safe, because there are
1N/Aseveral ways in which your computer can become unbootable. For example,
1N/Amost operating systems don't tell GRUB how to map BIOS drives to OS
1N/Adevices correctly--GRUB merely "guesses" the mapping. This will succeed
1N/Ain most cases, but not always. Therefore, GRUB provides you with a map
1N/Afile called the "device map", which you must fix if it is wrong. *Note
1N/ADevice map::, for more details.
1N/A If you still do want to install GRUB under a UNIX-like OS (such as
1N/AGNU), invoke the program `grub-install' (*note Invoking grub-install::)
1N/Aas the superuser ("root").
1N/A The usage is basically very simple. You only need to specify one
1N/Aargument to the program, namely, where to install the boot loader. The
1N/Aargument can be either a device file (like `
/dev/hda') or a partition
1N/Aspecified in GRUB's notation. For example, under Linux the following
1N/Awill install GRUB into the MBR of the first IDE disk:
1N/A If it is the first BIOS drive, this is the same as well:
1N/A # grub-install '(hd0)'
1N/A Or you can omit the parentheses:
1N/A But all the above examples assume that GRUB should use images under
1N/Athe root directory. If you want GRUB to use images under a directory
1N/Aother than the root directory, you need to specify the option
1N/A`--root-directory'. The typical usage is that you create a GRUB boot
1N/Afloppy with a filesystem. Here is an example:
1N/A # grub-install --root-directory=/mnt fd0
1N/A Another example is when you have a separate boot partition which is
1N/Amounted at `/boot'. Since GRUB is a boot loader, it doesn't know
1N/Aanything about mountpoints at all. Thus, you need to run `grub-install'
1N/A By the way, as noted above, it is quite difficult to guess BIOS
1N/Adrives correctly under a UNIX-like OS. Thus, `grub-install' will prompt
1N/Ayou to check if it could really guess the correct mappings, after the
1N/Ainstallation. The format is defined in *Note Device map::. Please be
1N/Aquite careful. If the output is wrong, it is unlikely that your
1N/Acomputer will be able to boot with no problem.
1N/A Note that `grub-install' is actually just a shell script and the
1N/Areal task is done by the grub shell `grub' (*note Invoking the grub
1N/Ashell::). Therefore, you may run `grub' directly to install GRUB,
1N/Awithout using `grub-install'. Don't do that, however, unless you are
1N/Avery familiar with the internals of GRUB. Installing a boot loader on a
1N/Arunning OS may be extremely dangerous.
1N/AFile:
grub.info, Node: Making a GRUB bootable CD-ROM, Prev: Installing GRUB using grub-install, Up: Installation
1N/A3.4 Making a GRUB bootable CD-ROM
1N/A=================================
1N/AGRUB supports the "no emulation mode" in the El Torito specification(1)
1N/A(*note Making a GRUB bootable CD-ROM-Footnote-1::). This means that you
1N/Acan use the whole CD-ROM from GRUB and you don't have to make a floppy
1N/Aor hard disk image file, which can cause compatibility problems.
1N/A For booting from a CD-ROM, GRUB uses a special Stage 2 called
1N/A`stage2_eltorito'. The only GRUB files you need to have in your
1N/Abootable CD-ROM are this `stage2_eltorito' and optionally a config file
1N/A`
menu.lst'. You don't need to use `stage1' or `stage2', because El
1N/ATorito is quite different from the standard boot process.
1N/A Here is an example of procedures to make a bootable CD-ROM image.
1N/AFirst, make a top directory for the bootable image, say, `iso':
1N/A Make a directory for GRUB:
1N/A Copy the file `stage2_eltorito':
1N/A(*note Configuration::), and copy any files and directories for the
1N/Adisc to the directory `iso/'.
1N/A Finally, make a ISO9660 image file like this:
1N/A This produces a file named `
grub.iso', which then can be burned into
1N/Aa CD (or a DVD). `mkisofs' has already set up the disc to boot from
1N/Aon the disc. (Note that the `-boot-load-size 4' bit is required for
1N/Acompatibility with the BIOS on many older machines.)
1N/A You can use the device `(cd)' to access a CD-ROM in your config
1N/Afile. This is not required; GRUB automatically sets the root device to
1N/A`(cd)' when booted from a CD-ROM. It is only necessary to refer to
1N/A`(cd)' if you want to access other drives as well.
1N/AFile:
grub.info, Node: Making a GRUB bootable CD-ROM-Footnotes, Up: Making a GRUB bootable CD-ROM
1N/A (1) El Torito is a specification for bootable CD using BIOS
1N/AFile:
grub.info, Node: Booting, Next: Configuration, Prev: Installation, Up: Top
1N/AGRUB can load Multiboot-compliant kernels in a consistent way, but for
1N/Asome free operating systems you need to use some OS-specific magic.
1N/A* General boot methods:: How to boot OSes with GRUB generally
1N/A* OS-specific notes:: Notes on some operating systems
1N/A* Making your system robust:: How to make your system robust
1N/AFile:
grub.info, Node: General boot methods, Next: OS-specific notes, Up: Booting
1N/A4.1 How to boot operating systems
1N/A=================================
1N/AGRUB has two distinct boot methods. One of the two is to load an
1N/Aoperating system directly, and the other is to chain-load another boot
1N/Aloader which then will load an operating system actually. Generally
1N/Aspeaking, the former is more desirable, because you don't need to
1N/Ainstall or maintain other boot loaders and GRUB is flexible enough to
1N/Alatter is sometimes required, since GRUB doesn't support all the
1N/Aexisting operating systems natively.
1N/A* Loading an operating system directly::
1N/AFile:
grub.info, Node: Loading an operating system directly, Next: Chain-loading, Up: General boot methods
1N/A4.1.1 How to boot an OS directly with GRUB
1N/A------------------------------------------
1N/AMultiboot (*note Multiboot Specification: (multiboot)Top.) is the
1N/Anative format supported by GRUB. For the sake of convenience, there is
1N/Aalso support for Linux, FreeBSD, NetBSD and OpenBSD. If you want to
1N/Aboot other operating systems, you will have to chain-load them (*note
1N/A Generally, GRUB can boot any Multiboot-compliant OS in the following
1N/A 1. Set GRUB's root device to the drive where the OS images are stored
1N/A with the command `root' (*note root::).
1N/A 2. Load the kernel image with the command `kernel' (*note kernel::).
1N/A 3. If you need modules, load them with the command `module' (*note
1N/A module::) or `modulenounzip' (*note modulenounzip::).
1N/A 4. Run the command `boot' (*note boot::).
1N/A Linux, FreeBSD, NetBSD and OpenBSD can be booted in a similar
1N/Amanner. You load a kernel image with the command `kernel' and then run
1N/Athe command `boot'. If the kernel requires some parameters, just append
1N/Athe parameters to `kernel', after the file name of the kernel. Also,
1N/Aplease refer to *Note OS-specific notes::, for information on your
1N/AFile:
grub.info, Node: Chain-loading, Prev: Loading an operating system directly, Up: General boot methods
1N/A4.1.2 Load another boot loader to boot unsupported operating systems
1N/A--------------------------------------------------------------------
1N/AIf you want to boot an unsupported operating system (
e.g. Windows 95),
1N/Achain-load a boot loader for the operating system. Normally, the boot
1N/Aloader is embedded in the "boot sector" of the partition on which the
1N/Aoperating system is installed.
1N/A 1. Set GRUB's root device to the partition by the command
1N/A `rootnoverify' (*note rootnoverify::):
1N/A grub> rootnoverify (hd0,0)
1N/A 2. Set the "active" flag in the partition using the command
1N/A `makeactive'(1) (*note Chain-loading-Footnote-1::) (*note
1N/A 3. Load the boot loader with the command `chainloader' (*note
1N/A grub> chainloader +1
1N/A `+1' indicates that GRUB should read one sector from the start of
1N/A the partition. The complete description about this syntax can be
1N/A found in *Note Block list syntax::.
1N/A 4. Run the command `boot' (*note boot::).
1N/A However, DOS and Windows have some deficiencies, so you might have to
1N/AFile:
grub.info, Node: Chain-loading-Footnotes, Up: Chain-loading
1N/A (1) This is not necessary for most of the modern operating systems.
1N/AFile:
grub.info, Node: OS-specific notes, Next: Making your system robust, Prev: General boot methods, Up: Booting
1N/A4.2 Some caveats on OS-specific issues
1N/A======================================
1N/AHere, we describe some caveats on several operating systems.
1N/ASince
GNU/Hurd is Multiboot-compliant, it is easy to boot it; there is
1N/Anothing special about it. But do not forget that you have to specify a
1N/Aroot partition to the kernel.
1N/A 1. Set GRUB's root device to the same drive as
GNU/Hurd's. Probably
1N/A 2. Load the kernel and the module, like this:
1N/A 3. Run the command `boot' (*note boot::).
1N/AIt is relatively easy to boot
GNU/Linux from GRUB, because it somewhat
1N/Aresembles to boot a Multiboot-compliant OS.
1N/A 1. Set GRUB's root device to the same drive as
GNU/Linux's. Probably
1N/A the command `find /vmlinuz' or similar can help you (*note find::).
1N/A If you need to specify some kernel parameters, just append them to
1N/A the command. For example, to set `vga' to `ext', do this:
1N/A See the documentation in the Linux source tree for complete
1N/A information on the available options.
1N/A 3. If you use an initrd, execute the command `initrd' (*note
1N/A initrd::) after `kernel':
1N/A grub> initrd /initrd
1N/A 4. Finally, run the command `boot' (*note boot::).
1N/A *Caution:* If you use an initrd and specify the `mem=' option to the
1N/Akernel to let it use less than actual memory size, you will also have
1N/Ato specify the same memory size to GRUB. To let GRUB know the size, run
1N/Athe command `uppermem' _before_ loading the kernel. *Note uppermem::,
1N/Afor more information.
1N/AGRUB can load the kernel directly, either in ELF or
a.out format. But
1N/Athis is not recommended, since FreeBSD's bootstrap interface sometimes
1N/Achanges heavily, so GRUB can't guarantee to pass kernel parameters
1N/Ainstead. See this example:
1N/AFile:
grub.info, Node: NetBSD, Next: OpenBSD, Prev: FreeBSD, Up: OS-specific notes
1N/AGRUB can load NetBSD
a.out and ELF directly, follow these steps:
1N/A 1. Set GRUB's root device with `root' (*note root::).
1N/A 2. Load the kernel with `kernel' (*note kernel::). You should append
1N/A the ugly option `--type=netbsd', if you want to load an ELF
1N/A grub> kernel --type=netbsd /netbsd-elf
1N/A 3. Run `boot' (*note boot::).
1N/A For now, however, GRUB doesn't allow you to pass kernel parameters,
1N/Aso it may be better to chain-load it instead. For more information,
1N/Aplease see *Note Chain-loading::.
1N/AThe booting instruction is exactly the same as for NetBSD (*note
1N/AGRUB cannot boot DOS or Windows directly, so you must chain-load them
1N/A(*note Chain-loading::). However, their boot loaders have some critical
1N/Adeficiencies, so it may not work to just chain-load them. To overcome
1N/Athe problems, GRUB provides you with two helper functions.
1N/A If you have installed DOS (or Windows) on a non-first hard disk, you
1N/Ahave to use the disk swapping technique, because that OS cannot boot
1N/Afrom any disks but the first one. The workaround used in GRUB is the
1N/Acommand `map' (*note map::), like this:
1N/A grub> map (hd0) (hd1)
1N/A grub> map (hd1) (hd0)
1N/A This performs a "virtual" swap between your first and second hard
1N/A *Caution:* This is effective only if DOS (or Windows) uses BIOS to
1N/Aaccess the swapped disks. If that OS uses a special driver for the
1N/Adisks, this probably won't work.
1N/A Another problem arises if you installed more than one set of
1N/Aavoid doing this, but there is a solution if you do want to do so. Use
1N/A If GRUB "hide"s a DOS (or Windows) partition (*note hide::), DOS (or
1N/AWindows) will ignore the partition. If GRUB "unhide"s a DOS (or
1N/AWindows) partition (*note unhide::), DOS (or Windows) will detect the
1N/Apartition. Thus, if you have installed DOS (or Windows) on the first
1N/Aand the second partition of the first hard disk, and you want to boot
1N/Athe copy on the first partition, do the following:
1N/A grub> unhide (hd0,0)
1N/A grub> rootnoverify (hd0,0)
1N/A grub> chainloader +1
1N/AIt is known that the signature in the boot loader for SCO UnixWare is
1N/Awrong, so you will have to specify the option `--force' to
1N/A`chainloader' (*note chainloader::), like this:
1N/A grub> rootnoverify (hd1,0)
1N/A grub> chainloader --force +1
1N/AFile:
grub.info, Node: QNX, Prev: SCO UnixWare, Up: OS-specific notes
1N/AQNX seems to use a bigger boot loader, so you need to boot it up, like
1N/A grub> rootnoverify (hd1,1)
1N/A grub> chainloader +4
1N/AFile:
grub.info, Node: Making your system robust, Prev: OS-specific notes, Up: Booting
1N/A4.3 How to make your system robust
1N/A==================================
1N/AWhen you test a new kernel or a new OS, it is important to make sure
1N/Athat your computer can boot even if the new system is unbootable. This
1N/Ais crucial especially if you maintain servers or remote systems. To
1N/Aaccomplish this goal, you need to set up two things:
1N/A 1. You must maintain a system which is always bootable. For instance,
1N/A if you test a new kernel, you need to keep a working kernel in a
1N/A different place. And, it would sometimes be very nice to even have
1N/A a complete copy of a working system in a different partition or
1N/A 2. You must direct GRUB to boot a working system when the new system
1N/A fails. This is possible with the "fallback" system in GRUB.
1N/A The former requirement is very specific to each OS, so this
1N/Adocumentation does not cover that topic. It is better to consult some
1N/A So let's see the GRUB part. There are two possibilities: one of them
1N/Ais quite simple but not very robust, and the other is a bit complex to
1N/Aset up but probably the best solution to make sure that your system can
1N/Astart as long as GRUB itself is bootable.
1N/A* Booting once-only::
1N/A* Booting fallback systems::
1N/AFile:
grub.info, Node: Booting once-only, Next: Booting fallback systems, Up: Making your system robust
1N/A4.3.1 Booting once-only
1N/A-----------------------
1N/AYou can teach GRUB to boot an entry only at next boot time. Suppose
1N/Athat your have an old kernel `old_kernel' and a new kernel
1N/A`new_kernel'. You know that `old_kernel' can boot your system
1N/Acorrectly, and you want to test `new_kernel'.
1N/A To ensure that your system will go back to the old kernel even if the
1N/Anew kernel fails (
e.g. it panics), you can specify that GRUB should try
1N/Athe new kernel only once and boot the old kernel after that.
1N/A First, modify your configuration file. Here is an example:
1N/A default saved # This is important!!!
1N/A title the old kernel
1N/A title the new kernel
1N/A savedefault 0 # This is important!!!
1N/A Note that this configuration file uses `default saved' (*note
1N/Adefault::) at the head and `savedefault 0' (*note savedefault::) in the
1N/Aentry for the new kernel. This means that GRUB boots a saved entry by
1N/Adefault, and booting the entry for the new kernel saves `0' as the
1N/A With this configuration file, after all, GRUB always tries to boot
1N/Athe old kernel after it booted the new one, because `0' is the entry of
1N/A The next step is to tell GRUB to boot the new kernel at next boot
1N/Atime. For this, execute `grub-set-default' (*note Invoking
1N/A # grub-set-default 1
1N/A This command sets the saved entry to `1', that is, to the new kernel.
1N/A This method is useful, but still not very robust, because GRUB stops
1N/Abooting, if there is any error in the boot entry, such that the new
1N/Akernel has an invalid executable format. Thus, it it even better to use
1N/Athe "fallback" mechanism of GRUB. Look at next subsection for this
1N/AFile:
grub.info, Node: Booting fallback systems, Prev: Booting once-only, Up: Making your system robust
1N/A4.3.2 Booting fallback systems
1N/A------------------------------
1N/AGRUB supports a fallback mechanism of booting one or more other entries
1N/Aif a default boot entry fails. You can specify multiple fallback
1N/A Suppose that you have three systems, `A', `B' and `C'. `A' is a
1N/Asystem which you want to boot by default. `B' is a backup system which
1N/Ais supposed to boot safely. `C' is another backup system which is used
1N/Ain case where `B' is broken.
1N/A Then you may want GRUB to boot the first system which is bootable
1N/Aamong `A', `B' and `C'. A configuration file can be written in this way:
1N/A default saved # This is important!!!
1N/A fallback 1 2 # This is important!!!
1N/A savedefault fallback # This is important!!!
1N/A savedefault fallback # This is important!!!
1N/A Note that `default saved' (*note default::), `fallback 1 2' and
1N/A`savedefault fallback' are used. GRUB will boot a saved entry by
1N/Adefault and save a fallback entry as next boot entry with this
1N/A When GRUB tries to boot `A', GRUB saves `1' as next boot entry,
1N/Abecause the command `fallback' specifies that `1' is the first fallback
1N/Aentry. The entry `1' is `B', so GRUB will try to boot `B' at next boot
1N/A Likewise, when GRUB tries to boot `B', GRUB saves `2' as next boot
1N/Aentry, because `fallback' specifies `2' as next fallback entry. This
1N/Amakes sure that GRUB will boot `C' after booting `B'.
1N/A It is noteworthy that GRUB uses fallback entries both when GRUB
1N/Aitself fails in booting an entry and when `A' or `B' fails in starting
1N/Aup your system. So this solution ensures that your system is started
1N/Aeven if GRUB cannot find your kernel or if your kernel panics.
1N/A However, you need to run `grub-set-default' (*note Invoking
1N/Agrub-set-default::) when `A' starts correctly or you fix `A' after it
1N/Acrashes, since GRUB always sets next boot entry to a fallback entry.
1N/AYou should run this command in a startup script such as `
rc.local' to
1N/A # grub-set-default 0
1N/A where `0' is the number of the boot entry for the system `A'.
1N/A If you want to see what is current default entry, you can look at the
1N/Athis file is plain-text, you can just `cat' this file. But it is
1N/Astrongly recommended *not to modify this file directly*, because GRUB
1N/Amay fail in saving a default entry in this file, if you change this
1N/Afile in an unintended manner. Therefore, you should use
1N/A`grub-set-default' when you need to change the default entry.
1N/AFile:
grub.info, Node: Configuration, Next: Network, Prev: Booting, Up: Top
1N/AYou've probably noticed that you need to type several commands to boot
1N/Ayour OS. There's a solution to that - GRUB provides a menu interface
1N/A(*note Menu interface::) from which you can select an item (using arrow
1N/Akeys) that will do everything to boot an OS.
1N/A To enable the menu, you need a configuration file, `
menu.lst' under
1N/Athe boot directory. We'll analyze an example file.
1N/A The file first contains some general settings, the menu interface
1N/Arelated options. You can put these commands (*note Menu-specific
1N/Acommands::) before any of the items (starting with `title' (*note
1N/A # Sample boot menu configuration file
1N/A As you may have guessed, these lines are comments. Lines starting
1N/Awith a hash character (`#'), and blank lines, are ignored by GRUB.
1N/A # By default, boot the first entry.
1N/A The first entry (here, counting starts with number zero, not one!)
1N/Awill be the default choice.
1N/A # Boot automatically after 30 secs.
1N/A As the comment says, GRUB will boot automatically in 30 seconds,
1N/Aunless interrupted with a keypress.
1N/A # Fallback to the second entry.
1N/A If, for any reason, the default entry doesn't work, fall back to the
1N/Asecond one (this is rarely used, for obvious reasons).
1N/A Note that the complete descriptions of these commands, which are menu
1N/Ainterface specific, can be found in *Note Menu-specific commands::.
1N/AOther descriptions can be found in *Note Commands::.
1N/A Now, on to the actual OS definitions. You will see that each entry
1N/Abegins with a special command, `title' (*note title::), and the action
1N/Ais described after it. Note that there is no command `boot' (*note
1N/Aboot::) at the end of each item. That is because GRUB automatically
1N/Aexecutes `boot' if it loads other commands successfully.
1N/A The argument for the command `title' is used to display a short
1N/Aargument as is, you can write basically anything there.
1N/A # For booting Mach (getting kernel from floppy)
1N/A title Utah Mach4 multiboot
1N/A pause Insert the diskette now^G!!
1N/A This boots Mach with a kernel on a floppy, but the root filesystem at
1N/Ahd0s3. It also contains a `pause' line (*note pause::), which will
1N/Acause GRUB to display a prompt and delay, before actually executing the
1N/Arest of the commands and booting.
1N/A # For booting FreeBSD
1N/A This item will boot FreeBSD kernel loaded from the `a' partition of
1N/Athe third PC slice of the first hard disk.
1N/A # chainload OS/2 bootloader from the first sector
1N/A # This is similar to "chainload", but loads a specific file
1N/A This will boot OS/2, using a chain-loader (*note Chain-loading::).
1N/A # For booting Windows NT or Windows95
1N/A title Windows NT / Windows 95 boot menu
1N/A # For loading DOS if Windows NT is installed
1N/A The same as the above, but for Windows.
1N/A # For installing GRUB into the hard disk
1N/A title Install GRUB into the hard disk
1N/A This will just (re)install GRUB onto the hard disk.
1N/A # Change the colors.
1N/A title Change the colors
1N/A In the last entry, the command `color' is used (*note color::), to
1N/Achange the menu colors (try it!). This command is somewhat special,
1N/Abecause it can be used both in the command-line and in the menu. GRUB
1N/Ahas several such commands, see *Note General commands::.
1N/A We hope that you now understand how to use the basic features of
1N/AGRUB. To learn more about GRUB, see the following chapters.
1N/AFile:
grub.info, Node: Network, Next: Serial terminal, Prev: Configuration, Up: Top
1N/A6 Downloading OS images from a network
1N/A**************************************
1N/AAlthough GRUB is a disk-based boot loader, it does provide network
1N/Asupport. To use the network support, you need to enable at least one
1N/Anetwork driver in the GRUB build process. For more information please
1N/A* General usage of network support::
1N/AFile:
grub.info, Node: General usage of network support, Next: Diskless, Up: Network
1N/A6.1 How to set up your network
1N/A==============================
1N/AGRUB requires a file server and optionally a server that will assign an
1N/AIP address to the machine on which GRUB is running. For the former, only
1N/ATFTP is supported at the moment. The latter is either BOOTP, DHCP or a
1N/ARARP server(1) (*note General usage of network support-Footnote-1::).
1N/AIt is not necessary to run both the servers on one computer. How to
1N/Aconfigure these servers is beyond the scope of this document, so please
1N/A If you decided to use a server to assign an IP address, set up the
1N/Aserver and run `bootp' (*note bootp::), `dhcp' (*note dhcp::) or `rarp'
1N/A(*note rarp::) for BOOTP, DHCP or RARP, respectively. Each command will
1N/Ashow an assigned IP address, a netmask, an IP address for your TFTP
1N/Aserver and a gateway. If any of the addresses is wrong or it causes an
1N/Aerror, probably the configuration of your servers isn't set up properly.
1N/A Otherwise, run `ifconfig', like this:
1N/A grub> ifconfig --address=192.168.110.23 --server=192.168.110.14
1N/A You can also use `ifconfig' in conjuction with `bootp', `dhcp' or
1N/A`rarp' (
e.g. to reassign the server address manually). *Note
1N/Aifconfig::, for more details.
1N/A Finally, download your OS images from your network. The network can
1N/Abe accessed using the network drive `(nd)'. Everything else is very
1N/Asimilar to the normal instructions (*note Booting::).
1N/A Address: 192.168.110.23 Netmask: 255.255.255.0
1N/A Server: 192.168.110.14 Gateway: 192.168.110.1
1N/AFile:
grub.info, Node: General usage of network support-Footnotes, Up: General usage of network support
1N/A (1) RARP is not advised, since it cannot serve much information
1N/AFile:
grub.info, Node: Diskless, Prev: General usage of network support, Up: Network
1N/A6.2 Booting from a network
1N/A==========================
1N/AIt is sometimes very useful to boot from a network, especially when you
1N/Ause a machine which has no local disk. In this case, you need to obtain
1N/Aa kind of Net Boot ROM, such as a PXE ROM or a free software package
1N/Alike Etherboot. Such a Boot ROM first boots the machine, sets up the
1N/Anetwork card installed into the machine, and downloads a second stage
1N/Aboot image from the network. Then, the second image will try to boot an
1N/Aoperating system actually from the network.
1N/A GRUB provides two second stage images, `nbgrub' and `pxegrub' (*note
1N/AImages::). These images are the same as the normal Stage 2, except that
1N/Athey set up a network automatically, and try to load a configuration
1N/Afile from the network, if specified. The usage is very simple: If the
1N/Amachine has a PXE ROM, use `pxegrub'. If the machine has an NBI loader
1N/Asuch as Etherboot, use `nbgrub'. There is no difference between them
1N/Aexcept their formats. Since the way to load a second stage image you
1N/Awant to use should be described in the manual on your Net Boot ROM,
1N/Aplease refer to the manual, for more information.
1N/A However, there is one thing specific to GRUB. Namely, how to specify
1N/Aa configuration file in a
BOOTP/DHCP server. For now, GRUB uses the tag
1N/A`150', to get the name of a configuration file. The following is an
1N/Aexample with a BOOTP configuration:
1N/A .allhost:hd=/tmp:bf=null:\
1N/A :ds=145.71.35.1 145.71.32.1:\
1N/A foo:ht=1:ha=63655d0334a7:ip=145.71.35.127:\
1N/A Note that you should specify the drive name `(nd)' in the name of
1N/Athe configuration file. This is because you might change the root drive
1N/Abefore downloading the configuration from the TFTP server when the
1N/Apreset menu feature is used (*note Preset Menu::).
1N/A See the manual of your
BOOTP/DHCP server for more information. The
1N/Aexact syntax should differ a little from the example.
1N/AFile:
grub.info, Node: Serial terminal, Next: Preset Menu, Prev: Network, Up: Top
1N/A7 Using GRUB via a serial line
1N/A******************************
1N/AThis chapter describes how to use the serial terminal support in GRUB.
1N/Acould be very useful to control the computers through serial
1N/Acommunications. To connect one computer with another via a serial line,
1N/Ayou need to prepare a null-modem (cross) serial cable, and you may need
1N/Ato have multiport serial boards, if your computer doesn't have extra
1N/Aserial ports. In addition, a terminal emulator is also required, such as
1N/Aminicom. Refer to a manual of your operating system, for more
1N/A As for GRUB, the instruction to set up a serial terminal is quite
1N/Asimple. First of all, make sure that you haven't specified the option
1N/A`--disable-serial' to the configure script when you built your GRUB
1N/Aimages. If you get them in binary form, probably they have serial
1N/Aterminal support already.
1N/A Then, initialize your serial terminal after GRUB starts up. Here is
1N/A grub> serial --unit=0 --speed=9600
1N/A grub> terminal serial
1N/A The command `serial' initializes the serial unit 0 with the speed
1N/A9600bps. The serial unit 0 is usually called `COM1', so, if you want to
1N/Ause COM2, you must specify `--unit=1' instead. This command accepts
1N/Amany other options, so please refer to *Note serial::, for more details.
1N/A The command `terminal' (*note terminal::) chooses which type of
1N/Aterminal you want to use. In the case above, the terminal will be a
1N/Aserial terminal, but you can also pass `console' to the command, as
1N/A`terminal serial console'. In this case, a terminal in which you press
1N/Aany key will be selected as a GRUB terminal.
1N/A However, note that GRUB assumes that your terminal emulator is
1N/Acompatible with VT100 by default. This is true for most terminal
1N/Aemulators nowadays, but you should pass the option `--dumb' to the
1N/Acommand if your terminal emulator is not VT100-compatible or implements
1N/Afew VT100 escape sequences. If you specify this option then GRUB
1N/Aprovides you with an alternative menu interface, because the normal
1N/Amenu requires several fancy features of your terminal.
1N/AFile:
grub.info, Node: Preset Menu, Next: Security, Prev: Serial terminal, Up: Top
1N/A8 Embedding a configuration file into GRUB
1N/A******************************************
1N/AGRUB supports a "preset menu" which is to be always loaded before
1N/Astarting. The preset menu feature is useful, for example, when your
1N/Acomputer has no console but a serial cable. In this case, it is
1N/Acritical to set up the serial terminal as soon as possible, since you
1N/Acannot see any message until the serial terminal begins to work. So it
1N/Ais good to run the commands `serial' (*note serial::) and `terminal'
1N/A(*note terminal::) before anything else at the start-up time.
1N/A How the preset menu works is slightly complicated:
1N/A 1. GRUB checks if the preset menu feature is used, and loads the
1N/A preset menu, if available. This includes running commands and
1N/A reading boot entries, like an ordinary configuration file.
1N/A 2. GRUB checks if the configuration file is available. Note that this
1N/A check is performed *regardless of the existence of the preset
1N/A menu*. The configuration file is loaded even if the preset menu was
1N/A 3. If the preset menu includes any boot entries, they are cleared when
1N/A the configuration file is loaded. It doesn't matter whether the
1N/A configuration file has any entries or no entry. The boot entries
1N/A in the preset menu are used only when GRUB fails in loading the
1N/A To enable the preset menu feature, you must rebuild GRUB specifying a
1N/Afile to the configure script with the option `--enable-preset-menu'.
1N/AThe file has the same semantics as normal configuration files (*note
1N/A Another point you should take care is that the diskless support
1N/A(*note Diskless::) diverts the preset menu. Diskless images embed a
1N/Apreset menu to execute the command `bootp' (*note bootp::)
1N/Aautomatically, unless you specify your own preset menu to the configure
1N/Ascript. This means that you must put commands to initialize a network in
1N/Athe preset menu yourself, because diskless images don't set it up
1N/Aimplicitly, when you use the preset menu explicitly.
1N/A Therefore, a typical preset menu used with diskless support would be
1N/A # Set up the serial terminal, first of all.
1N/A serial --unit=0 --speed=19200
1N/A terminal --timeout=0 serial
1N/A # Initialize the network.
1N/AFile:
grub.info, Node: Security, Next: Images, Prev: Preset Menu, Up: Top
1N/A9 Protecting your computer from cracking
1N/A****************************************
1N/AYou may be interested in how to prevent ordinary users from doing
1N/Awhatever they like, if you share your computer with other people. So
1N/Athis chapter describes how to improve the security of GRUB.
1N/A One thing which could be a security hole is that the user can do too
1N/Amany things with GRUB, because GRUB allows one to modify its
1N/Aconfiguration and run arbitrary commands at run-time. For example, the
1N/Acommand `cat' (*note cat::). So it is necessary to disable all the
1N/Ainteractive operations.
1N/A Thus, GRUB provides a "password" feature, so that only administrators
1N/Acan start the interactive operations (
i.e. editing menu entries and
1N/Aentering the command-line interface). To use this feature, you need to
1N/Arun the command `password' in your configuration file (*note
1N/Apassword::), like this:
1N/A password --md5 PASSWORD
1N/A If this is specified, GRUB disallows any interactive control, until
1N/Ayou press the key <p> and enter a correct password. The option `--md5'
1N/Atells GRUB that `PASSWORD' is in MD5 format. If it is omitted, GRUB
1N/Aassumes the `PASSWORD' is in clear text.
1N/A You can encrypt your password with the command `md5crypt' (*note
1N/Amd5crypt::). For example, run the grub shell (*note Invoking the grub
1N/Ashell::), and enter your password:
1N/A Password: **********
1N/A Encrypted: $1$U$JK7xFegdxWH6VuppCUSIb.
1N/A Then, cut and paste the encrypted password to your configuration
1N/A Also, you can specify an optional argument to `password'. See this
1N/Aconfiguration file when you enter the valid password.
1N/A Another thing which may be dangerous is that any user can choose any
1N/Amenu entry. Usually, this wouldn't be problematic, but you might want to
1N/Apermit only administrators to run some of your menu entries, such as an
1N/Aentry for booting an insecure OS like DOS.
1N/A GRUB provides the command `lock' (*note lock::). This command always
1N/Afails until you enter the valid password, so you can use it, like this:
1N/A rootnoverify (hd0,1)
1N/A You should insert `lock' right after `title', because any user can
1N/Aexecute commands in an entry until GRUB encounters `lock'.
1N/A You can also use the command `password' instead of `lock'. In this
1N/Acase the boot process will ask for the password and stop if it was
1N/Aentered incorrectly. Since the `password' takes its own PASSWORD
1N/Aargument this is useful if you want different passwords for different
1N/AFile:
grub.info, Node: Images, Next: Filesystem, Prev: Security, Up: Top
1N/AGRUB consists of several images: two essential stages, optional stages
1N/Acalled "Stage 1.5", one image for bootable CD-ROM, and two network boot
1N/Aimages. Here is a short overview of them. *Note Internals::, for more
1N/A This is an essential image used for booting up GRUB. Usually, this
1N/A is embedded in an MBR or the boot sector of a partition. Because a
1N/A PC boot sector is 512 bytes, the size of this image is exactly 512
1N/A All `stage1' must do is to load Stage 2 or Stage 1.5 from a local
1N/A disk. Because of the size restriction, `stage1' encodes the
1N/A location of Stage 2 (or Stage 1.5) in a block list format, so it
1N/A never understand any filesystem structure.
1N/A This is the core image of GRUB. It does everything but booting up
1N/A itself. Usually, this is put in a filesystem, but that is not
1N/A These are called "Stage 1.5", because they serve as a bridge
1N/A between `stage1' and `stage2', that is to say, Stage 1.5 is loaded
1N/A by Stage 1 and Stage 1.5 loads Stage 2. The difference between
1N/A `stage1' and `*_stage1_5' is that the former doesn't understand
1N/A any filesystem while the latter understands one filesystem (
e.g. 1N/A `e2fs_stage1_5' understands ext2fs). So you can move the Stage 2
1N/A image to another location safely, even after GRUB has been
1N/A While Stage 2 cannot generally be embedded in a fixed area as the
1N/A size is so large, Stage 1.5 can be installed into the area right
1N/A after an MBR, or the boot loader area of a ReiserFS or a FFS.
1N/A This is a boot image for CD-ROMs using the "no emulation mode" in
1N/A El Torito specification. This is identical to Stage 2, except that
1N/A this boots up without Stage 1 and sets up a special drive `(cd)'.
1N/A This is a network boot image for the Network Image Proposal used
1N/A by some network boot loaders, such as Etherboot. This is mostly
1N/A the same as Stage 2, but it also sets up a network and loads a
1N/A configuration file from the network.
1N/A This is another network boot image for the Preboot Execution
1N/A Environment used by several Netboot ROMs. This is identical to
1N/A `nbgrub', except for the format.
1N/AFile:
grub.info, Node: Filesystem, Next: Interface, Prev: Images, Up: Top
1N/A11 Filesystem syntax and semantics
1N/A**********************************
1N/AGRUB uses a special syntax for specifying disk drives which can be
1N/Aaccessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish
1N/Abetween IDE, ESDI, SCSI, or others. You must know yourself which BIOS
1N/Adevice is equivalent to which OS device. Normally, that will be clear if
1N/Ayou see the files in a device or use the command `find' (*note find::).
1N/A* Device syntax:: How to specify devices
1N/A* File name syntax:: How to specify files
1N/A* Block list syntax:: How to specify block lists
1N/AFile:
grub.info, Node: Device syntax, Next: File name syntax, Up: Filesystem
1N/A11.1 How to specify devices
1N/A===========================
1N/AThe device syntax is like this:
1N/A `(DEVICE[,PART-NUM][,BSD-SUBPART-LETTER])'
1N/A `[]' means the parameter is optional. DEVICE should be either `fd'
1N/Aor `hd' followed by a digit, like `fd0'. But you can also set DEVICE
1N/Ato a hexadecimal or a decimal number which is a BIOS drive number, so
1N/Athe following are equivalent:
1N/A PART-NUM represents the partition number of DEVICE, starting from
1N/Azero for primary partitions and from four for extended partitions, and
1N/ABSD-SUBPART-LETTER represents the BSD disklabel subpartition, such as
1N/A A shortcut for specifying BSD subpartitions is
1N/A`(DEVICE,BSD-SUBPART-LETTER)', in this case, GRUB searches for the
1N/Afirst PC partition containing a BSD disklabel, then finds the
1N/Asubpartition BSD-SUBPART-LETTER. Here is an example:
1N/A The syntax `(hd0)' represents using the entire disk (or the MBR when
1N/Ainstalling GRUB), while the syntax `(hd0,0)' represents using the first
1N/Apartition of the disk (or the boot sector of the partition when
1N/A If you enabled the network support, the special drive, `(nd)', is
1N/Aalso available. Before using the network drive, you must initialize the
1N/Anetwork. *Note Network::, for more information.
1N/A If you boot GRUB from a CD-ROM, `(cd)' is available. *Note Making a
1N/AGRUB bootable CD-ROM::, for details.
1N/AFile:
grub.info, Node: File name syntax, Next: Block list syntax, Prev: Device syntax, Up: Filesystem
1N/A11.2 How to specify files
1N/A=========================
1N/AThere are two ways to specify files, by "absolute file name" and by
1N/A An absolute file name resembles a Unix absolute file name, using `/'
1N/Afor the directory separator (not `\' as in DOS). One example is
1N/Ain the first partition of the first hard disk. If you omit the device
1N/Aname in an absolute file name, GRUB uses GRUB's "root device"
1N/Aimplicitly. So if you set the root device to, say, `(hd1,0)' by the
1N/AFile:
grub.info, Node: Block list syntax, Prev: File name syntax, Up: Filesystem
1N/A11.3 How to specify block lists
1N/A===============================
1N/AA block list is used for specifying a file that doesn't appear in the
1N/Afilesystem, like a chainloader. The syntax is
1N/A`[OFFSET]+LENGTH[,[OFFSET]+LENGTH]...'. Here is an example:
1N/A `0+100,200+1,300+300'
1N/A This represents that GRUB should read blocks 0 through 99, block 200,
1N/Aand blocks 300 through 599. If you omit an offset, then GRUB assumes
1N/A Like the file name syntax (*note File name syntax::), if a blocklist
1N/Adoes not contain a device name, then GRUB uses GRUB's "root device". So
1N/A`(hd0,1)+1' is the same as `+1' when the root device is `(hd0,1)'.
1N/AFile:
grub.info, Node: Interface, Next: Commands, Prev: Filesystem, Up: Top
1N/A12 GRUB's user interface
1N/A************************
1N/AGRUB has both a simple menu interface for choosing preset entries from a
1N/Aconfiguration file, and a highly flexible command-line for performing
1N/Aany desired combination of boot commands.
1N/A GRUB looks for its configuration file as soon as it is loaded. If one
1N/Ais found, then the full menu interface is activated using whatever
1N/Aentries were found in the file. If you choose the "command-line" menu
1N/Aoption, or if the configuration file was not found, then GRUB drops to
1N/Athe command-line interface.
1N/A* Command-line interface:: The flexible command-line interface
1N/A* Menu interface:: The simple menu interface
1N/A* Menu entry editor:: Editing a menu entry
1N/A* Hidden menu interface:: The hidden menu interface
1N/AFile:
grub.info, Node: Command-line interface, Next: Menu interface, Up: Interface
1N/A12.1 The flexible command-line interface
1N/A========================================
1N/AThe command-line interface provides a prompt and after it an editable
1N/Atext area much like a command-line in Unix or DOS. Each command is
1N/Aimmediately executed after it is entered(1) (*note Command-line
1N/Ainterface-Footnote-1::). The commands (*note Command-line and menu
1N/Aentry commands::) are a subset of those available in the configuration
1N/Afile, used with exactly the same syntax.
1N/A Cursor movement and editing of the text on the line can be done via a
1N/Asubset of the functions available in the Bash shell:
1N/A Move forward one character.
1N/A Move back one character.
1N/A Move to the start of the line.
1N/A Move the the end of the line.
1N/A Delete the character underneath the cursor.
1N/A Delete the character to the left of the cursor.
1N/A Kill the text from the current cursor position to the end of the
1N/A Kill backward from the cursor to the beginning of the line.
1N/A Yank the killed text back into the buffer at the cursor.
1N/A Move up through the history list.
1N/A Move down through the history list.
1N/A When typing commands interactively, if the cursor is within or before
1N/Athe first word in the command-line, pressing the <TAB> key (or <C-i>)
1N/Awill display a listing of the available commands, and if the cursor is
1N/Aafter the first word, the `<TAB>' will provide a completion listing of
1N/Adisks, partitions, and file names depending on the context. Note that
1N/Ato obtain a list of drives, one must open a parenthesis, as `root ('.
1N/A Note that you cannot use the completion functionality in the TFTP
1N/Afilesystem. This is because TFTP doesn't support file name listing for
1N/AFile:
grub.info, Node: Command-line interface-Footnotes, Up: Command-line interface
1N/A (1) However, this behavior will be changed in the future version, in
1N/Aa user-invisible way.
1N/AFile:
grub.info, Node: Menu interface, Next: Menu entry editor, Prev: Command-line interface, Up: Interface
1N/A12.2 The simple menu interface
1N/A==============================
1N/AThe menu interface is quite easy to use. Its commands are both
1N/Areasonably intuitive and described on screen.
1N/A Basically, the menu interface provides a list of "boot entries" to
1N/Athe user to choose from. Use the arrow keys to select the entry of
1N/Achoice, then press <RET> to run it. An optional timeout is available
1N/Ato boot the default entry (the first one if not set), which is aborted
1N/A Commands are available to enter a bare command-line by pressing <c>
1N/A(which operates exactly like the non-config-file version of GRUB, but
1N/Aallows one to return to the menu if desired by pressing <ESC>) or to
1N/Aedit any of the "boot entries" by pressing <e>.
1N/A If you protect the menu interface with a password (*note Security::),
1N/Aall you can do is choose an entry by pressing <RET>, or press <p> to
1N/AFile:
grub.info, Node: Menu entry editor, Next: Hidden menu interface, Prev: Menu interface, Up: Interface
1N/A12.3 Editing a menu entry
1N/A=========================
1N/AThe menu entry editor looks much like the main menu interface, but the
1N/Alines in the menu are individual commands in the selected entry instead
1N/A If an <ESC> is pressed in the editor, it aborts all the changes made
1N/Ato the configuration entry and returns to the main menu interface.
1N/A When a particular line is selected, the editor places the user in a
1N/Aspecial version of the GRUB command-line to edit that line. When the
1N/Auser hits <RET>, GRUB replaces the line in question in the boot entry
1N/Awith the changes (unless it was aborted via <ESC>, in which case the
1N/Achanges are thrown away).
1N/A If you want to add a new line to the menu entry, press <o> if adding
1N/Aa line after the current line or press <O> if before the current line.
1N/A To delete a line, hit the key <d>. Although GRUB unfortunately does
1N/Anot support "undo", you can do almost the same thing by just returning
1N/AFile:
grub.info, Node: Hidden menu interface, Prev: Menu entry editor, Up: Interface
1N/A12.4 The hidden menu interface
1N/A==============================
1N/AWhen your terminal is dumb or you request GRUB to hide the menu
1N/Ainterface explicitly with the command `hiddenmenu' (*note
1N/Ahiddenmenu::), GRUB doesn't show the menu interface (*note Menu
1N/Ainterface::) and automatically boots the default entry, unless
1N/Ainterrupted by pressing <ESC>.
1N/A When you interrupt the timeout and your terminal is dumb, GRUB falls
1N/Aback to the command-line interface (*note Command-line interface::).
1N/AFile:
grub.info, Node: Commands, Next: Troubleshooting, Prev: Interface, Up: Top
1N/A13 The list of available commands
1N/A*********************************
1N/AIn this chapter, we list all commands that are available in GRUB.
1N/A Commands belong to different groups. A few can only be used in the
1N/Aglobal section of the configuration file (or "menu"); most of them can
1N/Abe entered on the command-line and can be used either anywhere in the
1N/Amenu or specifically in the menu entries.
1N/A* Menu-specific commands::
1N/A* Command-line and menu entry commands::
1N/AFile:
grub.info, Node: Menu-specific commands, Next: General commands, Up: Commands
1N/A13.1 The list of commands for the menu only
1N/A===========================================
1N/AThe semantics used in parsing the configuration file are the following:
1N/A * The menu-specific commands have to be used before any others.
1N/A * The files _must_ be in plain-text format.
1N/A * `#' at the beginning of a line in a configuration file means it is
1N/A * Options are separated by spaces.
1N/A * All numbers can be either decimal or hexadecimal. A hexadecimal
1N/A number must be preceded by `0x', and is case-insensitive.
1N/A * Extra options or text at the end of the line are ignored unless
1N/A otherwise specified.
1N/A * Unrecognized commands are added to the current entry, except
1N/A before entries start, where they are ignored.
1N/A These commands can only be used in the menu:
1N/A* default:: Set the default entry
1N/A* fallback:: Set the fallback entry
1N/A* hiddenmenu:: Hide the menu interface
1N/A* timeout:: Set the timeout
1N/A* title:: Start a menu entry
1N/AFile:
grub.info, Node: default, Next: fallback, Up: Menu-specific commands
1N/A -- Command: default num
1N/A Set the default entry to the entry number NUM. Numbering starts
1N/A from 0, and the entry number 0 is the default if the command is not
1N/A You can specify `saved' instead of a number. In this case, the
1N/A default entry is the entry saved with the command `savedefault'.
1N/A *Note savedefault::, for more information.
1N/AFile:
grub.info, Node: fallback, Next: hiddenmenu, Prev: default, Up: Menu-specific commands
1N/A -- Command: fallback num...
1N/A Go into unattended boot mode: if the default boot entry has any
1N/A errors, instead of waiting for the user to do something,
1N/A immediately start over using the NUM entry (same numbering as the
1N/A `default' command (*note default::)). This obviously won't help if
1N/A the machine was rebooted by a kernel that GRUB loaded. You can
1N/A specify multiple fallback entry numbers.
1N/AFile:
grub.info, Node: hiddenmenu, Next: timeout, Prev: fallback, Up: Menu-specific commands
1N/A -- Command: hiddenmenu
1N/A Don't display the menu. If the command is used, no menu will be
1N/A displayed on the control terminal, and the default entry will be
1N/A booted after the timeout expired. The user can still request the
1N/A menu to be displayed by pressing <ESC> before the timeout expires.
1N/A See also *Note Hidden menu interface::.
1N/AFile:
grub.info, Node: timeout, Next: title, Prev: hiddenmenu, Up: Menu-specific commands
1N/A -- Command: timeout sec
1N/A Set a timeout, in SEC seconds, before automatically booting the
1N/A default entry (normally the first entry defined).
1N/AFile:
grub.info, Node: title, Prev: timeout, Up: Menu-specific commands
1N/A -- Command: title name ...
1N/A Start a new boot entry, and set its name to the contents of the
1N/A rest of the line, starting with the first non-space character.
1N/AFile:
grub.info, Node: General commands, Next: Command-line and menu entry commands, Prev: Menu-specific commands, Up: Commands
1N/A13.2 The list of general commands
1N/A=================================
1N/ACommands usable anywhere in the menu and in the command-line.
1N/A* bootp:: Initialize a network device via BOOTP
1N/A* color:: Color the menu interface
1N/A* device:: Specify a file as a drive
1N/A* dhcp:: Initialize a network device via DHCP
1N/A* hide:: Hide a partition
1N/A* ifconfig:: Configure a network device manually
1N/A* pager:: Change the state of the internal pager
1N/A* partnew:: Make a primary partition
1N/A* parttype:: Change the type of a partition
1N/A* password:: Set a password for the menu interface
1N/A* rarp:: Initialize a network device via RARP
1N/A* serial:: Set up a serial device
1N/A* setkey:: Configure the key map
1N/A* terminal:: Choose a terminal
1N/A* terminfo:: Define escape sequences for a terminal
1N/A* tftpserver:: Specify a TFTP server
1N/A* unhide:: Unhide a partition
1N/AFile:
grub.info, Node: bootp, Next: color, Up: General commands
1N/A -- Command: bootp [`--with-configfile']
1N/A Initialize a network device via the "BOOTP" protocol. This command
1N/A is only available if GRUB is compiled with netboot support. See
1N/A also *Note Network::.
1N/A If you specify `--with-configfile' to this command, GRUB will
1N/A fetch and load a configuration file specified by your BOOTP server
1N/A with the vendor tag `150'.
1N/AFile:
grub.info, Node: color, Next: device, Prev: bootp, Up: General commands
1N/A -- Command: color normal [highlight]
1N/A Change the menu colors. The color NORMAL is used for most lines in
1N/A the menu (*note Menu interface::), and the color HIGHLIGHT is used
1N/A to highlight the line where the cursor points. If you omit
1N/A HIGHLIGHT, then the inverted color of NORMAL is used for the
1N/A highlighted line. The format of a color is
1N/A color names. A symbolic color name must be one of these:
1N/A *These below can be specified only for the foreground.*
1N/A But only the first eight names can be used for BACKGROUND. You can
1N/A prefix `blink-' to FOREGROUND if you want a blinking foreground
1N/A This command can be used in the configuration file and on the
1N/A command line, so you may write something like this in your
1N/A # Set default colors.
1N/A # Change the colors.
1N/AFile:
grub.info, Node: device, Next: dhcp, Prev: color, Up: General commands
1N/A -- Command: device drive file
1N/A In the grub shell, specify the file FILE as the actual drive for a
1N/A BIOS drive DRIVE. You can use this command to create a disk image,
1N/A and/or to fix the drives guessed by GRUB when GRUB fails to
1N/A determine them correctly, like this:
1N/A grub> device (fd0) /floppy-image
1N/A This command can be used only in the grub shell (*note Invoking
1N/AFile:
grub.info, Node: dhcp, Next: hide, Prev: device, Up: General commands
1N/A -- Command: dhcp [-with-configfile]
1N/A Initialize a network device via the "DHCP" protocol. Currently,
1N/A this command is just an alias for `bootp', since the two protocols
1N/A are very similar. This command is only available if GRUB is
1N/A compiled with netboot support. See also *Note Network::.
1N/A If you specify `--with-configfile' to this command, GRUB will
1N/A fetch and load a configuration file specified by your DHCP server
1N/A with the vendor tag `150'.
1N/AFile:
grub.info, Node: hide, Next: ifconfig, Prev: dhcp, Up: General commands
1N/A -- Command: hide partition
1N/A Hide the partition PARTITION by setting the "hidden" bit in its
1N/A partition type code. This is useful only when booting DOS or
1N/A Windows and multiple primary FAT partitions exist in one disk. See
1N/AFile:
grub.info, Node: ifconfig, Next: pager, Prev: hide, Up: General commands
1N/A -- Command: ifconfig [`--server=server'] [`--gateway=gateway']
1N/A [`--mask=mask'] [`--address=address']
1N/A Configure the IP address, the netmask, the gateway, and the server
1N/A address of a network device manually. The values must be in dotted
1N/A decimal format, like `192.168.11.178'. The order of the options is
1N/A not important. This command shows current network configuration,
1N/A if no option is specified. See also *Note Network::.
1N/AFile:
grub.info, Node: pager, Next: partnew, Prev: ifconfig, Up: General commands
1N/A -- Command: pager [flag]
1N/A Toggle or set the state of the internal pager. If FLAG is `on',
1N/A the internal pager is enabled. If FLAG is `off', it is disabled.
1N/A If no argument is given, the state is toggled.
1N/AFile:
grub.info, Node: partnew, Next: parttype, Prev: pager, Up: General commands
1N/A -- Command: partnew part type from len
1N/A Create a new primary partition. PART is a partition specification
1N/A in GRUB syntax (*note Naming convention::); TYPE is the partition
1N/A type and must be a number in the range `0-0xff'; FROM is the
1N/A starting address and LEN is the length, both in sector units.
1N/AFile:
grub.info, Node: parttype, Next: password, Prev: partnew, Up: General commands
1N/A -- Command: parttype part type
1N/A Change the type of an existing partition. PART is a partition
1N/A specification in GRUB syntax (*note Naming convention::); TYPE is
1N/A the new partition type and must be a number in the range 0-0xff.
1N/AFile:
grub.info, Node: password, Next: rarp, Prev: parttype, Up: General commands
1N/A -- Command: password [`--md5'] passwd [new-config-file]
1N/A If used in the first section of a menu file, disable all
1N/A interactive editing control (menu entry editor and command-line)
1N/A and entries protected by the command `lock'. If the password
1N/A PASSWD is entered, it loads the NEW-CONFIG-FILE as a new config
1N/A file and restarts the GRUB Stage 2, if NEW-CONFIG-FILE is
1N/A specified. Otherwise, GRUB will just unlock the privileged
1N/A instructions. You can also use this command in the script
1N/A section, in which case it will ask for the password, before
1N/A continuing. The option `--md5' tells GRUB that PASSWD is
1N/A encrypted with `md5crypt' (*note md5crypt::).
1N/AFile:
grub.info, Node: rarp, Next: serial, Prev: password, Up: General commands
1N/A Initialize a network device via the "RARP" protocol. This command
1N/A is only available if GRUB is compiled with netboot support. See
1N/A also *Note Network::.
1N/AFile:
grub.info, Node: serial, Next: setkey, Prev: rarp, Up: General commands
1N/A -- Command: serial [`--unit=unit'] [`--port=port'] [`--speed=speed']
1N/A [`--word=word'] [`--parity=parity'] [`--stop=stop']
1N/A Initialize a serial device. UNIT is a number in the range 0-3
1N/A specifying which serial port to use; default is 0, which
1N/A corresponds to the port often called COM1. PORT is the I/O port
1N/A where the UART is to be found; if specified it takes precedence
1N/A over UNIT. SPEED is the transmission speed; default is 9600. WORD
1N/A and STOP are the number of data bits and stop bits. Data bits must
1N/A be in the range 5-8 and stop bits must be 1 or 2. Default is 8 data
1N/A bits and one stop bit. PARITY is one of `no', `odd', `even' and
1N/A defaults to `no'. The option `--device' can only be used in the
1N/A grub shell and is used to specify the tty device to be used in the
1N/A host operating system (*note Invoking the grub shell::).
1N/A The serial port is not used as a communication channel unless the
1N/A `terminal' command is used (*note terminal::).
1N/A This command is only available if GRUB is compiled with serial
1N/A support. See also *Note Serial terminal::.
1N/AFile:
grub.info, Node: setkey, Next: terminal, Prev: serial, Up: General commands
1N/A -- Command: setkey [to_key from_key]
1N/A Change the keyboard map. The key FROM_KEY is mapped to the key
1N/A TO_KEY. If no argument is specified, reset key mappings. Note that
1N/A this command _does not_ exchange the keys. If you want to exchange
1N/A the keys, run this command again with the arguments exchanged,
1N/A grub> setkey capslock control
1N/A grub> setkey control capslock
1N/A A key must be an alphabet letter, a digit, or one of these symbols:
1N/A `escape', `exclam', `at', `numbersign', `dollar', `percent',
1N/A `caret', `ampersand', `asterisk', `parenleft', `parenright',
1N/A `minus', `underscore', `equal', `plus', `backspace', `tab',
1N/A `bracketleft', `braceleft', `bracketright', `braceright', `enter',
1N/A `control', `semicolon', `colon', `quote', `doublequote',
1N/A `backquote', `tilde', `shift', `backslash', `bar', `comma',
1N/A `less', `period', `greater', `slash', `question', `alt', `space',
1N/A `capslock', `FX' (`X' is a digit), and `delete'. This table
1N/A describes to which character each of the symbols corresponds:
1N/AFile:
grub.info, Node: terminal, Next: terminfo, Prev: setkey, Up: General commands
1N/A -- Command: terminal [`--dumb'] [`--no-echo'] [`--no-edit']
1N/A [`--timeout=secs'] [`--lines=lines'] [`--silent'] [`console']
1N/A [`serial'] [`hercules']
1N/A Select a terminal for user interaction. The terminal is assumed to
1N/A be VT100-compatible unless `--dumb' is specified. If both
1N/A `console' and `serial' are specified, then GRUB will use the one
1N/A where a key is entered first or the first when the timeout
1N/A expires. If neither are specified, the current setting is
1N/A reported. This command is only available if GRUB is compiled with
1N/A serial support. See also *Note Serial terminal::.
1N/A This may not make sense for most users, but GRUB supports Hercules
1N/A console as well. Hercules console is usable like the ordinary
1N/A console, and the usage is quite similar to that for serial
1N/A terminals: specify `hercules' as the argument.
1N/A The option `--lines' defines the number of lines in your terminal,
1N/A and it is used for the internal pager function. If you don't
1N/A specify this option, the number is assumed as 24.
1N/A The option `--silent' suppresses the message to prompt you to hit
1N/A any key. This might be useful if your system has no terminal
1N/A The option `--no-echo' has GRUB not to echo back input characters.
1N/A This implies the option `--no-edit'.
1N/A The option `--no-edit' disables the BASH-like editing feature.
1N/AFile:
grub.info, Node: terminfo, Next: tftpserver, Prev: terminal, Up: General commands
1N/A -- Command: terminfo `--name=name' `--cursor-address=seq'
1N/A [`--clear-screen=seq'] [`--enter-standout-mode=seq']
1N/A [`--exit-standout-mode=seq']
1N/A Define the capabilities of your terminal. Use this command to
1N/A define escape sequences, if it is not vt100-compatible. You may
1N/A use `\e' for <ESC> and `^X' for a control character.
1N/A You can use the utility `grub-terminfo' to generate appropriate
1N/A arguments to this command. *Note Invoking grub-terminfo::.
1N/A If no option is specified, the current settings are printed.
1N/AFile:
grub.info, Node: tftpserver, Next: unhide, Prev: terminfo, Up: General commands
1N/A -- Command: tftpserver ipaddr
1N/A *Caution:* This command exists only for backward compatibility.
1N/A Use `ifconfig' (*note ifconfig::) instead.
1N/A server. The argument IPADDR must be in dotted decimal format, like
1N/A `192.168.0.15'. This command is only available if GRUB is compiled
1N/A with netboot support. See also *Note Network::.
1N/AFile:
grub.info, Node: unhide, Prev: tftpserver, Up: General commands
1N/A -- Command: unhide partition
1N/A Unhide the partition PARTITION by clearing the "hidden" bit in its
1N/A partition type code. This is useful only when booting DOS or
1N/A Windows and multiple primary partitions exist on one disk. See also
1N/AFile:
grub.info, Node: Command-line and menu entry commands, Prev: General commands, Up: Commands
1N/A13.3 The list of command-line and menu entry commands
1N/A=====================================================
1N/AThese commands are usable in the command-line and in menu entries. If
1N/Ayou forget a command, you can run the command `help' (*note help::).
1N/A* blocklist:: Get the block list notation of a file
1N/A* boot:: Start up your operating system
1N/A* cat:: Show the contents of a file
1N/A* chainloader:: Chain-load another boot loader
1N/A* cmp:: Compare two files
1N/A* configfile:: Load a configuration file
1N/A* debug:: Toggle the debug flag
1N/A* displayapm:: Display APM information
1N/A* displaymem:: Display memory configuration
1N/A* embed:: Embed Stage 1.5
1N/A* fstest:: Test a filesystem
1N/A* geometry:: Manipulate the geometry of a drive
1N/A* halt:: Shut down your computer
1N/A* help:: Show help messages
1N/A* impsprobe:: Probe SMP
1N/A* initrd:: Load an initrd
1N/A* install:: Install GRUB
1N/A* ioprobe:: Probe I/O ports used for a drive
1N/A* kernel:: Load a kernel
1N/A* lock:: Lock a menu entry
1N/A* makeactive:: Make a partition active
1N/A* map:: Map a drive to another
1N/A* md5crypt:: Encrypt a password in MD5 format
1N/A* module:: Load a module
1N/A* modulenounzip:: Load a module without decompression
1N/A* pause:: Wait for a key press
1N/A* quit:: Exit from the grub shell
1N/A* reboot:: Reboot your computer
1N/A* read:: Read data from memory
1N/A* root:: Set GRUB's root device
1N/A* rootnoverify:: Set GRUB's root device without mounting
1N/A* savedefault:: Save current entry as the default entry
1N/A* setup:: Set up GRUB's installation automatically
1N/A* testload:: Load a file for testing a filesystem
1N/A* testvbe:: Test VESA BIOS EXTENSION
1N/A* uppermem:: Set the upper memory size
1N/A* vbeprobe:: Probe VESA BIOS EXTENSION
1N/AFile:
grub.info, Node: blocklist, Next: boot, Up: Command-line and menu entry commands
1N/A -- Command: blocklist file
1N/A Print the block list notation of the file FILE. *Note Block list
1N/AFile:
grub.info, Node: boot, Next: cat, Prev: blocklist, Up: Command-line and menu entry commands
1N/A Boot the OS or chain-loader which has been loaded. Only necessary
1N/A if running the fully interactive command-line (it is implicit at
1N/A the end of a menu entry).
1N/AFile:
grub.info, Node: cat, Next: chainloader, Prev: boot, Up: Command-line and menu entry commands
1N/A -- Command: cat file
1N/A Display the contents of the file FILE. This command may be useful
1N/A to remind you of your OS's root partition:
1N/AFile:
grub.info, Node: chainloader, Next: cmp, Prev: cat, Up: Command-line and menu entry commands
1N/A -- Command: chainloader [`--force'] file
1N/A Load FILE as a chain-loader. Like any other file loaded by the
1N/A filesystem code, it can use the blocklist notation to grab the
1N/A first sector of the current partition with `+1'. If you specify the
1N/A option `--force', then load FILE forcibly, whether it has a
1N/A correct signature or not. This is required when you want to load a
1N/A defective boot loader, such as SCO UnixWare 7.1 (*note SCO
1N/AFile:
grub.info, Node: cmp, Next: configfile, Prev: chainloader, Up: Command-line and menu entry commands
1N/A -- Command: cmp file1 file2
1N/A Compare the file FILE1 with the file FILE2. If they differ in
1N/A size, print the sizes like this:
1N/A Differ in size: 0x1234 [foo], 0x4321 [bar]
1N/A If the sizes are equal but the bytes at an offset differ, then
1N/A print the bytes like this:
1N/A Differ at the offset 777: 0xbe [foo], 0xef [bar]
1N/A If they are completely identical, nothing will be printed.
1N/AFile:
grub.info, Node: configfile, Next: debug, Prev: cmp, Up: Command-line and menu entry commands
1N/A -- Command: configfile file
1N/A Load FILE as a configuration file.
1N/AFile:
grub.info, Node: debug, Next: displayapm, Prev: configfile, Up: Command-line and menu entry commands
1N/A Toggle debug mode (by default it is off). When debug mode is on,
1N/A some extra messages are printed to show disk activity. This global
1N/A debug flag is mainly useful for GRUB developers when testing new
1N/AFile:
grub.info, Node: displayapm, Next: displaymem, Prev: debug, Up: Command-line and menu entry commands
1N/A -- Command: displayapm
1N/A Display APM BIOS information.
1N/AFile:
grub.info, Node: displaymem, Next: embed, Prev: displayapm, Up: Command-line and menu entry commands
1N/A -- Command: displaymem
1N/A Display what GRUB thinks the system address space map of the
1N/A machine is, including all regions of physical RAM installed. GRUB's
1N/A the available memory in the first megabyte, or "lower memory", and
1N/A a synthesized number from various BIOS interfaces of the memory
1N/A starting at 1MB and going up to the first chipset hole for "upper
1N/A memory" (the standard PC "upper memory" interface is limited to
1N/A reporting a maximum of 64MB).
1N/AFile:
grub.info, Node: embed, Next: find, Prev: displaymem, Up: Command-line and menu entry commands
1N/A -- Command: embed stage1_5 device
1N/A Embed the Stage 1.5 STAGE1_5 in the sectors after the MBR if
1N/A DEVICE is a drive, or in the "boot loader" area if DEVICE is a FFS
1N/A partition or a ReiserFS partition.(1) (*note embed-Footnote-1::)
1N/A Print the number of sectors which STAGE1_5 occupies, if successful.
1N/A Usually, you don't need to run this command directly. *Note
1N/A (1) The latter feature has not been implemented yet.
1N/AFile:
grub.info, Node: find, Next: fstest, Prev: embed, Up: Command-line and menu entry commands
1N/A -- Command: find filename
1N/A Search for the file name FILENAME in all mountable partitions and
1N/A print the list of the devices which contain the file. The file
1N/A name FILENAME should be an absolute file name like
1N/AFile:
grub.info, Node: fstest, Next: geometry, Prev: find, Up: Command-line and menu entry commands
1N/A Toggle filesystem test mode. Filesystem test mode, when turned
1N/A on, prints out data corresponding to all the device reads and what
1N/A values are being sent to the low-level routines. The format is
1N/A `<PARTITION-OFFSET-SECTOR, BYTE-OFFSET, BYTE-LENGTH>' for
1N/A high-level reads inside a partition, and `[DISK-OFFSET-SECTOR]'
1N/A for low-level sector requests from the disk. Filesystem test mode
1N/A is turned off by any use of the `install' (*note install::) or
1N/A `testload' (*note testload::) commands.
1N/AFile:
grub.info, Node: geometry, Next: halt, Prev: fstest, Up: Command-line and menu entry commands
1N/A -- Command: geometry drive [cylinder head sector [total_sector]]
1N/A Print the information for the drive DRIVE. In the grub shell, you
1N/A can set the geometry of the drive arbitrarily. The number of
1N/A cylinders, the number of heads, the number of sectors and the
1N/A number of total sectors are set to CYLINDER, HEAD, SECTOR and
1N/A TOTAL_SECTOR, respectively. If you omit TOTAL_SECTOR, then it will
1N/A be calculated based on the C/H/S values automatically.
1N/AFile:
grub.info, Node: halt, Next: help, Prev: geometry, Up: Command-line and menu entry commands
1N/A -- Command: halt `--no-apm'
1N/A The command halts the computer. If the `--no-apm' option is
1N/A specified, no APM BIOS call is performed. Otherwise, the computer
1N/A is shut down using APM.
1N/AFile:
grub.info, Node: help, Next: impsprobe, Prev: halt, Up: Command-line and menu entry commands
1N/A -- Command: help `--all' [pattern ...]
1N/A Display helpful information about builtin commands. If you do not
1N/A specify PATTERN, this command shows short descriptions of most of
1N/A available commands. If you specify the option `--all' to this
1N/A command, short descriptions of rarely used commands (such as *Note
1N/A testload::) are displayed as well.
1N/A If you specify any PATTERNS, it displays longer information about
1N/A each of the commands which match those PATTERNS.
1N/AFile:
grub.info, Node: impsprobe, Next: initrd, Prev: help, Up: Command-line and menu entry commands
1N/A -- Command: impsprobe
1N/A Probe the Intel Multiprocessor Specification 1.1 or 1.4
1N/A configuration table and boot the various CPUs which are found into
1N/A a tight loop. This command can be used only in the Stage 2, but
1N/A not in the grub shell.
1N/AFile:
grub.info, Node: initrd, Next: install, Prev: impsprobe, Up: Command-line and menu entry commands
1N/A -- Command: initrd file ...
1N/A Load an initial ramdisk for a Linux format boot image and set the
1N/A appropriate parameters in the Linux setup area in memory. See also
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 -- Command: md5crypt
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/A13.3.26 modulenounzip
1N/A---------------------
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/A14 Error messages reported by GRUB
1N/A**********************************
1N/AThis 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/A14.1 Errors reported by the Stage 1
1N/A===================================
1N/AThe 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/A14.2 Errors reported by the Stage 1.5
1N/A=====================================
1N/AThe general way that the Stage 1.5 handles errors is to print an error
1N/Anumber 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/A14.3 Errors reported by the Stage 2
1N/A===================================
1N/AThe 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/A15 Invoking the grub shell
1N/A**************************
1N/AThis chapter documents the grub shell `grub'. Note that the grub shell
1N/Ais 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/A15.1 Introduction into the grub shell
1N/A=====================================
1N/AYou can use the command `grub' for installing GRUB under your operating
1N/Asystems and for a testbed when you add a new feature into GRUB or when
1N/Afixing a bug. `grub' is almost the same as the Stage 2, and, in fact,
1N/Ait shares the source code with the Stage 2 and you can use the same
1N/Acommands (*note Commands::) in `grub'. It is emulated by replacing BIOS
1N/Acalls 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/A15.2 How to install GRUB via `grub'
1N/A===================================
1N/AThe installation procedure is the same as under the "native" Stage 2.
1N/A*Note Installation::, for more information. The command `grub'-specific
1N/Ainformation 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/A15.3 The map between BIOS drives and OS devices
1N/A===============================================
1N/AWhen you specify the option `--device-map' (*note Basic usage::), the
1N/Agrub 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/A16 Invoking grub-install
1N/A************************
1N/AThe program `grub-install' installs GRUB on your drive using the grub
1N/Ashell (*note Invoking the grub shell::). You must specify the device
1N/Aname 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/A17 Invoking grub-md5-crypt
1N/A**************************
1N/AThe program `grub-md5-crypt' encrypts a password in MD5 format. This
1N/Ais just a frontend of the grub shell (*note Invoking the grub shell::).
1N/APasswords encrypted by this program can be used with the command
1N/A`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/A18 Invoking grub-terminfo
1N/A*************************
1N/AThe 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/A19 Invoking grub-set-default
1N/A****************************
1N/AThe 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/AThe 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/AAppendix A How 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.97' 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/AAppendix B Reporting bugs
1N/A*************************
1N/AThese 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/AAppendix C Where GRUB will go
1N/A*****************************
1N/AWe 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/AAppendix D Hacking GRUB
1N/A***********************
1N/AThis 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/AD.1 The memory map of various components
1N/A========================================
1N/AGRUB 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/AD.2 Embedded variables in GRUB
1N/A==============================
1N/AStage 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/AD.3 The generic interface for filesystems
1N/A=========================================
1N/AFor 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/AD.4 The generic interface for built-ins
1N/A=======================================
1N/AGRUB 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
1N/AFile:
grub.info, Node: Bootstrap tricks, Next: I/O ports detection, Prev: Command interface, Up: Internals
1N/AD.5 The bootstrap mechanism used in GRUB
1N/A========================================
1N/AThe disk space can be used in a boot loader is very restricted because
1N/Aa MBR (*note MBR::) is only 512 bytes but it also contains a partition
1N/Atable (*note Partition table::) and a BPB. So the question is how to
1N/Amake a boot loader code enough small to be fit in a MBR.
1N/A However, GRUB is a very large program, so we break GRUB into 2 (or 3)
1N/Adistinct components, "Stage 1" and "Stage 2" (and optionally "Stage
1N/A1.5"). *Note Memory map::, for more information.
1N/A We embed Stage 1 in a MBR or in the boot sector of a partition, and
1N/Aplace Stage 2 in a filesystem. The optional Stage 1.5 can be installed
1N/Ain a filesystem, in the "boot loader" area in a FFS or a ReiserFS, and
1N/Ain the sectors right after a MBR, because Stage 1.5 is enough small and
1N/Athe sectors right after a MBR is normally an unused region. The size of
1N/Athis region is the number of sectors per head minus 1.
1N/A Thus, all Stage1 must do is just load Stage2 or Stage1.5. But even if
1N/AStage 1 needs not to support the user interface or the filesystem
1N/Ainterface, it is impossible to make Stage 1 less than 400 bytes, because
1N/AGRUB should support both the CHS mode and the LBA mode (*note Low-level
1N/A The solution used by GRUB is that Stage 1 loads only the first
1N/Asector of Stage 2 (or Stage 1.5) and Stage 2 itself loads the rest. The
1N/A 1. Initialize the system briefly.
1N/A 2. Detect the geometry and the accessing mode of the "loading drive".
1N/A 3. Load the first sector of Stage 2.
1N/A 4. Jump to the starting address of the Stage 2.
1N/A The flow of Stage 2 (and Stage 1.5) is:
1N/A 1. Load the rest of itself to the real starting address, that is, the
1N/A starting address plus 512 bytes. The block lists are stored in the
1N/A last part of the first sector.
1N/A 2. Long jump to the real starting address.
1N/A Note that Stage 2 (or Stage 1.5) does not probe the geometry or the
1N/Aaccessing mode of the "loading drive", since Stage 1 has already probed
1N/AFile:
grub.info, Node: I/O ports detection, Next: Memory detection, Prev: Bootstrap tricks, Up: Internals
1N/AD.6 How to probe I/O ports used by INT 13H
1N/A==========================================
1N/AFIXME: I will write this chapter after implementing the new technique.
1N/AFile:
grub.info, Node: Memory detection, Next: Low-level disk I/O, Prev: I/O ports detection, Up: Internals
1N/AD.7 How to detect all installed RAM
1N/A===================================
1N/AFIXME: I doubt if Erich didn't write this chapter only himself wholly,
1N/Aso I will rewrite this chapter.
1N/AFile:
grub.info, Node: Low-level disk I/O, Next: MBR, Prev: Memory detection, Up: Internals
1N/AD.8 INT 13H disk I/O interrupts
1N/A===============================
1N/AFIXME: I'm not sure where some part of the original chapter is derived,
1N/Aso I will rewrite this chapter.
1N/AFile:
grub.info, Node: MBR, Next: Partition table, Prev: Low-level disk I/O, Up: Internals
1N/AD.9 The structure of Master Boot Record
1N/A=======================================
1N/AFile:
grub.info, Node: Partition table, Next: Submitting patches, Prev: MBR, Up: Internals
1N/AD.10 The format of partition tables
1N/A===================================
1N/AFIXME: Probably the original chapter is derived from "How It Works", so
1N/AI will rewrite this chapter.
1N/AFile:
grub.info, Node: Submitting patches, Prev: Partition table, Up: Internals
1N/AD.11 Where and how you should send patches
1N/A==========================================
1N/AWhen you write patches for GRUB, please send them to the mailing list
1N/A<bug-grub@gnu.org>. Here is the list of items of which you should take
1N/A * Please make your patch as small as possible. Generally, it is not
1N/A a good thing to make one big patch which changes many things.
1N/A Instead, segregate features and produce many patches.
1N/A * Use as late code as possible, for the original code. The CVS
1N/A repository always has the current version (*note Obtaining and
1N/A * Write ChangeLog entries. *Note Change Logs: (standards)Change
1N/A Logs, if you don't know how to write ChangeLog.
1N/A * Make patches in unified diff format. `diff -urN' is appropriate in
1N/A * Don't make patches reversely. Reverse patches are difficult to
1N/A * Be careful enough of the license term and the copyright. Because
1N/A GRUB is under GNU General Public License, you may not steal code
1N/A from software whose license is incompatible against GPL. And, if
1N/A you copy code written by others, you must not ignore their
1N/A copyrights. Feel free to ask GRUB maintainers, whenever you are
1N/A not sure what you should do.
1N/A * If your patch is too large to send in e-mail, put it at somewhere
1N/A we can see. Usually, you shouldn't send e-mail over 20K.
1N/A* blocklist: blocklist. (line 7)
1N/A* boot: boot. (line 7)
1N/A* bootp: bootp. (line 7)
1N/A* chainloader: chainloader. (line 7)
1N/A* color: color. (line 7)
1N/A* configfile: configfile. (line 7)
1N/A* current_drive: Filesystem interface. (line 19)
1N/A* current_partition: Filesystem interface. (line 23)
1N/A* current_slice: Filesystem interface. (line 26)
1N/A* debug: debug. (line 7)
1N/A* default: default. (line 7)
1N/A* device: device. (line 7)
1N/A* devread: Filesystem interface. (line 71)
1N/A* dhcp: dhcp. (line 7)
1N/A* disk_read_func: Filesystem interface. (line 62)
1N/A* displayapm: displayapm. (line 7)
1N/A* displaymem: displaymem. (line 7)
1N/A* embed: embed. (line 7)
1N/A* fallback: fallback. (line 7)
1N/A* filemax: Filesystem interface. (line 59)
1N/A* filepos: Filesystem interface. (line 52)
1N/A* find: find. (line 7)
1N/A* fstest: fstest. (line 7)
1N/A* FSYS_BUF: Filesystem interface. (line 46)
1N/A* geometry: geometry. (line 7)
1N/A* grub_read: Filesystem interface. (line 75)
1N/A* halt: halt. (line 7)
1N/A* help: help. (line 7)
1N/A* hiddenmenu: hiddenmenu. (line 7)
1N/A* hide: hide. (line 7)
1N/A* ifconfig: ifconfig. (line 8)
1N/A* impsprobe: impsprobe. (line 7)
1N/A* initrd: initrd. (line 7)
1N/A* install: install. (line 9)
1N/A* ioprobe: ioprobe. (line 7)
1N/A* kernel: kernel. (line 7)
1N/A* lock: lock. (line 7)
1N/A* makeactive: makeactive. (line 7)
1N/A* md5crypt: md5crypt. (line 7)
1N/A* module: module. (line 7)
1N/A* modulenounzip: modulenounzip. (line 7)
1N/A* pager: pager. (line 7)
1N/A* part_length: Filesystem interface. (line 38)
1N/A* part_start: Filesystem interface. (line 35)
1N/A* partnew: partnew. (line 7)
1N/A* parttype: parttype. (line 7)
1N/A* password: password. (line 7)
1N/A* pause: pause. (line 7)
1N/A* print_a_completion: Filesystem interface. (line 79)
1N/A* print_possibilities: Filesystem interface. (line 41)
1N/A* quit: quit. (line 7)
1N/A* rarp: rarp. (line 7)
1N/A* read: read. (line 7)
1N/A* reboot: reboot. (line 7)
1N/A* root: root. (line 7)
1N/A* rootnoverify: rootnoverify. (line 7)
1N/A* saved_drive: Filesystem interface. (line 29)
1N/A* saved_partition: Filesystem interface. (line 32)
1N/A* savedefault: savedefault. (line 7)
1N/A* serial: serial. (line 9)
1N/A* setkey: setkey. (line 7)
1N/A* setup: setup. (line 8)
1N/A* terminal: terminal. (line 9)
1N/A* terminfo: terminfo. (line 9)
1N/A* testload: testload. (line 7)
1N/A* testvbe: testvbe. (line 7)
1N/A* tftpserver: tftpserver. (line 7)
1N/A* timeout: timeout. (line 7)
1N/A* title: title. (line 7)
1N/A* unhide: unhide. (line 7)
1N/A* uppermem: uppermem. (line 7)
1N/A* vbeprobe: vbeprobe. (line 7)
1N/ANode: Introduction3266
1N/ANode: Overview-Footnotes5865
1N/ARef: Overview-Footnote-15926
1N/ANode: Features-Footnotes12976
1N/ARef: Features-Footnote-113037
1N/ANode: Role of a boot loader13182
1N/ANode: Role of a boot loader-Footnotes14520
1N/ARef: Role of a boot loader-Footnote-114607
1N/ANode: Naming convention14686
1N/ANode: Installation17621
1N/ANode: Creating a GRUB boot floppy19363
1N/ANode: Installing GRUB natively20181
1N/ANode: Installing GRUB natively-Footnotes22461
1N/ARef: Installing GRUB natively-Footnote-122554
1N/ANode: Installing GRUB using grub-install22739
1N/ANode: Making a GRUB bootable CD-ROM25685
1N/ANode: Making a GRUB bootable CD-ROM-Footnotes27730
1N/ARef: Making a GRUB bootable CD-ROM-Footnote-127833
1N/ANode: General boot methods28363
1N/ANode: Loading an operating system directly29104
1N/ANode: Chain-loading30408
1N/ANode: Chain-loading-Footnotes31718
1N/ARef: Chain-loading-Footnote-131789
1N/ANode: OS-specific notes31861
1N/ANode: SCO UnixWare37301
1N/ANode: Making your system robust37969
1N/ANode: Booting once-only39294
1N/ANode: Booting fallback systems41219
1N/ANode: Configuration44066
1N/ANode: General usage of network support48989
1N/ANode: General usage of network support-Footnotes50850
1N/ARef: General usage of network support-Footnote-150959
1N/ANode: Serial terminal53211
1N/ANode: Preset Menu55444
1N/ANode: Filesystem63131
1N/ANode: Device syntax63814
1N/ANode: File name syntax65308
1N/ANode: Block list syntax66051
1N/ANode: Interface66784
1N/ANode: Command-line interface67661
1N/ANode: Command-line interface-Footnotes69602
1N/ARef: Command-line interface-Footnote-169691
1N/ANode: Menu interface69786
1N/ANode: Menu entry editor70796
1N/ANode: Hidden menu interface71875
1N/ANode: Menu-specific commands73029
1N/ANode: hiddenmenu75229
1N/ANode: General commands76266
1N/ANode: tftpserver89565
1N/ANode: Command-line and menu entry commands90486
1N/ANode: blocklist93017
1N/ANode: chainloader93884
1N/ANode: configfile95051
1N/ANode: displayapm95649
1N/ANode: displaymem95860
1N/ANode: embed-Footnotes97096
1N/ARef: embed-Footnote-197151
1N/ANode: impsprobe99833
1N/ANode: install-Footnotes103415
1N/ARef: install-Footnote-1103474
1N/ANode: makeactive105591
1N/ANode: md5crypt106470
1N/ANode: modulenounzip107394
1N/ANode: rootnoverify109677
1N/ANode: savedefault110232
1N/ANode: testload112274
1N/ANode: uppermem113255
1N/ANode: vbeprobe113837
1N/ANode: Troubleshooting114220
1N/ANode: Stage1 errors114758
1N/ANode: Stage1.5 errors116135
1N/ANode: Stage2 errors116573
1N/ANode: Invoking the grub shell124033
1N/ANode: Basic usage124786
1N/ANode: Installation under UNIX127073
1N/ANode: Device map128748
1N/ANode: Invoking grub-install129896
1N/ANode: Invoking grub-md5-crypt131484
1N/ANode: Invoking grub-terminfo132133
1N/ANode: Invoking grub-set-default132899
1N/ANode: Invoking mbchk134700
1N/ANode: Obtaining and Building GRUB135214
1N/ANode: Reporting bugs136631
1N/ANode: Internals139926
1N/ANode: Memory map141149
1N/ANode: Embedded data142627
1N/ANode: Filesystem interface144644
1N/ANode: Command interface148077
1N/ANode: Bootstrap tricks149392
1N/ANode: I/O ports detection151541
1N/ANode: Memory detection151813
1N/ANode: Low-level disk I/O152105
1N/ANode: Partition table152571
1N/ANode: Submitting patches152844