1 This is ../../docs/grub.info, produced by makeinfo version 4.8 from
4 INFO-DIR-SECTION Kernel
6 * GRUB: (grub). The GRand Unified Bootloader
7 * grub-install: (grub)Invoking grub-install. Install GRUB on your drive
8 * grub-md5-crypt: (grub)Invoking grub-md5-crypt. Encrypt a password
10 * grub-terminfo: (grub)Invoking grub-terminfo. Generate a terminfo
13 * grub-set-default: (grub)Invoking grub-set-default. Set a default boot
15 * mbchk: (grub)Invoking mbchk. Check for the format of a Multiboot kernel
18 Copyright (C) 1999,2000,2001,2002,2004 Free Software Foundation, Inc.
20 Permission is granted to make and distribute verbatim copies of this
21 manual provided the copyright notice and this permission notice are
22 preserved on all copies.
24 Permission is granted to copy and distribute modified versions of
25 this manual under the conditions for verbatim copying, provided also
26 that the entire resulting derived work is distributed under the terms
27 of a permission notice identical to this one.
29 Permission is granted to copy and distribute translations of this
30 manual into another language, under the above conditions for modified
34 File: grub.info, Node: Top, Next: Introduction, Up: (dir)
39 This is the documentation of GNU GRUB, the GRand Unified Bootloader, a
40 flexible and powerful boot loader program for PCs.
42 This edition documents version 0.97.
46 * Introduction:: Capturing the spirit of GRUB
47 * Naming convention:: Names of your drives in GRUB
48 * Installation:: Installing GRUB on your drive
49 * Booting:: How to boot different operating systems
50 * Configuration:: Writing your own configuration file
51 * Network:: Downloading OS images from a network
52 * Serial terminal:: Using GRUB via a serial line
53 * Preset Menu:: Embedding a configuration file into GRUB
54 * Security:: Improving the security
55 * Images:: GRUB image files
56 * Filesystem:: Filesystem syntax and semantics
57 * Interface:: The menu and the command-line
58 * Commands:: The list of available builtin commands
59 * Troubleshooting:: Error messages produced by GRUB
60 * Invoking the grub shell:: How to use the grub shell
61 * Invoking grub-install:: How to use the GRUB installer
62 * Invoking grub-md5-crypt:: How to generate a cryptic password
63 * Invoking grub-terminfo:: How to generate a terminfo command
64 * Invoking grub-set-default:: How to set a default boot entry
65 * Invoking mbchk:: How to use the Multiboot checker
66 * Obtaining and Building GRUB:: How to obtain and build GRUB
67 * Reporting bugs:: Where you should send a bug report
68 * Future:: Some future plans on GRUB
69 * Internals:: Hacking GRUB
73 File: grub.info, Node: Introduction, Next: Naming convention, Prev: Top, Up: Top
75 1 Introduction to GRUB
76 **********************
80 * Overview:: What exactly GRUB is and how to use it
81 * History:: From maggot to house fly
82 * Features:: GRUB features
83 * Role of a boot loader:: The role of a boot loader
86 File: grub.info, Node: Overview, Next: History, Up: Introduction
91 Briefly, a "boot loader" is the first software program that runs when a
92 computer starts. It is responsible for loading and transferring
93 control to an operating system "kernel" software (such as Linux or GNU
94 Mach). The kernel, in turn, initializes the rest of the operating
95 system (e.g. a GNU system).
97 GNU GRUB is a very powerful boot loader, which can load a wide
98 variety of free operating systems, as well as proprietary operating
99 systems with chain-loading(1) (*note Overview-Footnote-1::). GRUB is
100 designed to address the complexity of booting a personal computer; both
101 the program and this manual are tightly bound to that computer platform,
102 although porting to other platforms may be addressed in the future.
104 One of the important features in GRUB is flexibility; GRUB
105 understands filesystems and kernel executable formats, so you can load
106 an arbitrary operating system the way you like, without recording the
107 physical position of your kernel on the disk. Thus you can load the
108 kernel just by specifying its file name and the drive and partition
109 where the kernel resides.
111 When booting with GRUB, you can use either a command-line interface
112 (*note Command-line interface::), or a menu interface (*note Menu
113 interface::). Using the command-line interface, you type the drive
114 specification and file name of the kernel manually. In the menu
115 interface, you just select an OS using the arrow keys. The menu is
116 based on a configuration file which you prepare beforehand (*note
117 Configuration::). While in the menu, you can switch to the command-line
118 mode, and vice-versa. You can even edit menu entries before using them.
120 In the following chapters, you will learn how to specify a drive, a
121 partition, and a file name (*note Naming convention::) to GRUB, how to
122 install GRUB on your drive (*note Installation::), and how to boot your
123 OSes (*note Booting::), step by step.
125 Besides the GRUB boot loader itself, there is a "grub shell" `grub'
126 (*note Invoking the grub shell::) which can be run when you are in your
127 operating system. It emulates the boot loader and can be used for
128 installing the boot loader.
131 File: grub.info, Node: Overview-Footnotes, Up: Overview
133 (1) "chain-load" is the mechanism for loading unsupported operating
134 systems by loading another boot loader. It is typically used for
135 loading DOS or Windows.
138 File: grub.info, Node: History, Next: Features, Prev: Overview, Up: Introduction
143 GRUB originated in 1995 when Erich Boleyn was trying to boot the GNU
144 Hurd with the University of Utah's Mach 4 microkernel (now known as GNU
145 Mach). Erich and Brian Ford designed the Multiboot Specification
146 (*note Multiboot Specification: (multiboot)Top.), because they were
147 determined not to add to the large number of mutually-incompatible PC
150 Erich then began modifying the FreeBSD boot loader so that it would
151 understand Multiboot. He soon realized that it would be a lot easier to
152 write his own boot loader from scratch than to keep working on the
153 FreeBSD boot loader, and so GRUB was born.
155 Erich added many features to GRUB, but other priorities prevented him
156 from keeping up with the demands of its quickly-expanding user base. In
157 1999, Gordon Matzigkeit and Yoshinori K. Okuji adopted GRUB as an
158 official GNU package, and opened its development by making the latest
159 sources available via anonymous CVS. *Note Obtaining and Building
160 GRUB::, for more information.
163 File: grub.info, Node: Features, Next: Role of a boot loader, Prev: History, Up: Introduction
168 The primary requirement for GRUB is that it be compliant with the
169 "Multiboot Specification", which is described in *Note Multiboot
170 Specification: (multiboot)Top.
172 The other goals, listed in approximate order of importance, are:
174 * Basic functions must be straightforward for end-users.
176 * Rich functionality to support kernel experts and designers.
178 * Backward compatibility for booting FreeBSD, NetBSD, OpenBSD, and
179 Linux. Proprietary kernels (such as DOS, Windows NT, and OS/2) are
180 supported via a chain-loading function.
182 Except for specific compatibility modes (chain-loading and the Linux
183 "piggyback" format), all kernels will be started in much the same state
184 as in the Multiboot Specification. Only kernels loaded at 1 megabyte or
185 above are presently supported. Any attempt to load below that boundary
186 will simply result in immediate failure and an error message reporting
189 In addition to the requirements above, GRUB has the following
190 features (note that the Multiboot Specification doesn't require all the
191 features that GRUB supports):
193 Recognize multiple executable formats
194 Support many of the "a.out" variants plus "ELF". Symbol tables are
197 Support non-Multiboot kernels
198 Support many of the various free 32-bit kernels that lack Multiboot
199 compliance (primarily FreeBSD, NetBSD, OpenBSD, and Linux).
200 Chain-loading of other boot loaders is also supported.
202 Load multiples modules
203 Fully support the Multiboot feature of loading multiple modules.
205 Load a configuration file
206 Support a human-readable text configuration file with preset boot
207 commands. You can also load another configuration file dynamically
208 and embed a preset configuration file in a GRUB image file. The
209 list of commands (*note Commands::) are a superset of those
210 supported on the command-line. An example configuration file is
211 provided in *Note Configuration::.
213 Provide a menu interface
214 A menu interface listing preset boot commands, with a programmable
215 timeout, is available. There is no fixed limit on the number of
216 boot entries, and the current implementation has space for several
219 Have a flexible command-line interface
220 A fairly flexible command-line interface, accessible from the menu,
221 is available to edit any preset commands, or write a new boot
222 command set from scratch. If no configuration file is present,
223 GRUB drops to the command-line.
225 The list of commands (*note Commands::) are a subset of those
226 supported for configuration files. Editing commands closely
227 resembles the Bash command-line (*note Bash: (features)Command
228 Line Editing.), with <TAB>-completion of commands, devices,
229 partitions, and files in a directory depending on context.
231 Support multiple filesystem types
232 Support multiple filesystem types transparently, plus a useful
233 explicit blocklist notation. The currently supported filesystem
234 types are "BSD FFS", "DOS FAT16 and FAT32", "Minix fs", "Linux
235 ext2fs", "ReiserFS", "JFS", "XFS", and "VSTa fs". *Note
236 Filesystem::, for more information.
238 Support automatic decompression
239 Can decompress files which were compressed by `gzip'. This
240 function is both automatic and transparent to the user (i.e. all
241 functions operate upon the uncompressed contents of the specified
242 files). This greatly reduces a file size and loading time, a
243 particularly great benefit for floppies.(1) (*note
244 Features-Footnote-1::)
246 It is conceivable that some kernel modules should be loaded in a
247 compressed state, so a different module-loading command can be
248 specified to avoid uncompressing the modules.
250 Access data on any installed device
251 Support reading data from any or all floppies or hard disk(s)
252 recognized by the BIOS, independent of the setting of the root
255 Be independent of drive geometry translations
256 Unlike many other boot loaders, GRUB makes the particular drive
257 translation irrelevant. A drive installed and running with one
258 translation may be converted to another translation without any
259 adverse effects or changes in GRUB's configuration.
261 Detect all installed RAM
262 GRUB can generally find all the installed RAM on a PC-compatible
263 machine. It uses an advanced BIOS query technique for finding all
264 memory regions. As described on the Multiboot Specification (*note
265 Multiboot Specification: (multiboot)Top.), not all kernels make
266 use of this information, but GRUB provides it for those who do.
268 Support Logical Block Address mode
269 In traditional disk calls (called "CHS mode"), there is a geometry
270 translation problem, that is, the BIOS cannot access over 1024
271 cylinders, so the accessible space is limited to at least 508 MB
272 and to at most 8GB. GRUB can't universally solve this problem, as
273 there is no standard interface used in all machines. However,
274 several newer machines have the new interface, Logical Block
275 Address ("LBA") mode. GRUB automatically detects if LBA mode is
276 available and uses it if available. In LBA mode, GRUB can access
279 Support network booting
280 GRUB is basically a disk-based boot loader but also has network
281 support. You can load OS images from a network by using the "TFTP"
284 Support remote terminals
285 To support computers with no console, GRUB provides remote terminal
286 support, so that you can control GRUB from a remote host. Only
287 serial terminal support is implemented at the moment.
290 File: grub.info, Node: Features-Footnotes, Up: Features
292 (1) There are a few pathological cases where loading a very badly
293 organized ELF kernel might take longer, but in practice this never
297 File: grub.info, Node: Role of a boot loader, Prev: Features, Up: Introduction
299 1.4 The role of a boot loader
300 =============================
302 The following is a quotation from Gordon Matzigkeit, a GRUB fanatic:
304 Some people like to acknowledge both the operating system and
305 kernel when they talk about their computers, so they might say
306 they use "GNU/Linux" or "GNU/Hurd". Other people seem to think
307 that the kernel is the most important part of the system, so they
308 like to call their GNU operating systems "Linux systems."
310 I, personally, believe that this is a grave injustice, because the
311 _boot loader_ is the most important software of all. I used to
312 refer to the above systems as either "LILO"(1) (*note Role of a
313 boot loader-Footnote-1::) or "GRUB" systems.
315 Unfortunately, nobody ever understood what I was talking about;
316 now I just use the word "GNU" as a pseudonym for GRUB.
318 So, if you ever hear people talking about their alleged "GNU"
319 systems, remember that they are actually paying homage to the best
320 boot loader around... GRUB!
322 We, the GRUB maintainers, do not (usually) encourage Gordon's level
323 of fanaticism, but it helps to remember that boot loaders deserve
324 recognition. We hope that you enjoy using GNU GRUB as much as we did
328 File: grub.info, Node: Role of a boot loader-Footnotes, Up: Role of a boot loader
330 (1) The LInux LOader, a boot loader that everybody uses, but nobody
334 File: grub.info, Node: Naming convention, Next: Installation, Prev: Introduction, Up: Top
339 The device syntax used in GRUB is a wee bit different from what you may
340 have seen before in your operating system(s), and you need to know it so
341 that you can specify a drive/partition.
343 Look at the following examples and explanations:
347 First of all, GRUB requires that the device name be enclosed with
348 `(' and `)'. The `fd' part means that it is a floppy disk. The number
349 `0' is the drive number, which is counted from _zero_. This expression
350 means that GRUB will use the whole floppy disk.
354 Here, `hd' means it is a hard disk drive. The first integer `0'
355 indicates the drive number, that is, the first hard disk, while the
356 second integer, `1', indicates the partition number (or the PC slice
357 number in the BSD terminology). Once again, please note that the
358 partition numbers are counted from _zero_, not from one. This
359 expression means the second partition of the first hard disk drive. In
360 this case, GRUB uses one partition of the disk, instead of the whole
365 This specifies the first "extended partition" of the first hard disk
366 drive. Note that the partition numbers for extended partitions are
367 counted from `4', regardless of the actual number of primary partitions
372 This means the BSD `a' partition of the second hard disk. If you
373 need to specify which PC slice number should be used, use something
374 like this: `(hd1,0,a)'. If the PC slice number is omitted, GRUB
375 searches for the first PC slice which has a BSD `a' partition.
377 Of course, to actually access the disks or partitions with GRUB, you
378 need to use the device specification in a command, like `root (fd0)' or
379 `unhide (hd0,2)'. To help you find out which number specifies a
380 partition you want, the GRUB command-line (*note Command-line
381 interface::) options have argument completion. This means that, for
382 example, you only need to type
386 followed by a <TAB>, and GRUB will display the list of drives,
387 partitions, or file names. So it should be quite easy to determine the
388 name of your target partition, even with minimal knowledge of the
391 Note that GRUB does _not_ distinguish IDE from SCSI - it simply
392 counts the drive numbers from zero, regardless of their type. Normally,
393 any IDE drive number is less than any SCSI drive number, although that
394 is not true if you change the boot sequence by swapping IDE and SCSI
397 Now the question is, how to specify a file? Again, consider an
402 This specifies the file named `vmlinuz', found on the first
403 partition of the first hard disk drive. Note that the argument
404 completion works with file names, too.
406 That was easy, admit it. Now read the next chapter, to find out how
407 to actually install GRUB on your drive.
410 File: grub.info, Node: Installation, Next: Booting, Prev: Naming convention, Up: Top
415 In order to install GRUB as your boot loader, you need to first install
416 the GRUB system and utilities under your UNIX-like operating system
417 (*note Obtaining and Building GRUB::). You can do this either from the
418 source tarball, or as a package for your OS.
420 After you have done that, you need to install the boot loader on a
421 drive (floppy or hard disk). There are two ways of doing that - either
422 using the utility `grub-install' (*note Invoking grub-install::) on a
423 UNIX-like OS, or by running GRUB itself from a floppy. These are quite
424 similar, however the utility might probe a wrong BIOS drive, so you
427 Also, if you install GRUB on a UNIX-like OS, please make sure that
428 you have an emergency boot disk ready, so that you can rescue your
429 computer if, by any chance, your hard drive becomes unusable
432 GRUB comes with boot images, which are normally put in the directory
433 `/usr/lib/grub/i386-pc'. If you do not use grub-install, then you need
434 to copy the files `stage1', `stage2', and `*stage1_5' to the directory
435 `/boot/grub', and run the `grub-set-default' (*note Invoking
436 grub-set-default::) if you intend to use `default saved' (*note
437 default::) in your configuration file. Hereafter, the directory where
438 GRUB images are initially placed (normally `/usr/lib/grub/i386-pc')
439 will be called the "image directory", and the directory where the boot
440 loader needs to find them (usually `/boot/grub') will be called the
445 * Creating a GRUB boot floppy::
446 * Installing GRUB natively::
447 * Installing GRUB using grub-install::
448 * Making a GRUB bootable CD-ROM::
451 File: grub.info, Node: Creating a GRUB boot floppy, Next: Installing GRUB natively, Up: Installation
453 3.1 Creating a GRUB boot floppy
454 ===============================
456 To create a GRUB boot floppy, you need to take the files `stage1' and
457 `stage2' from the image directory, and write them to the first and the
458 second block of the floppy disk, respectively.
460 *Caution:* This procedure will destroy any data currently stored on
463 On a UNIX-like operating system, that is done with the following
466 # cd /usr/lib/grub/i386-pc
467 # dd if=stage1 of=/dev/fd0 bs=512 count=1
470 # dd if=stage2 of=/dev/fd0 bs=512 seek=1
475 The device file name may be different. Consult the manual for your
479 File: grub.info, Node: Installing GRUB natively, Next: Installing GRUB using grub-install, Prev: Creating a GRUB boot floppy, Up: Installation
481 3.2 Installing GRUB natively
482 ============================
484 *Caution:* Installing GRUB's stage1 in this manner will erase the
485 normal boot-sector used by an OS.
487 GRUB can currently boot GNU Mach, Linux, FreeBSD, NetBSD, and OpenBSD
488 directly, so using it on a boot sector (the first sector of a
489 partition) should be okay. But generally, it would be a good idea to
490 back up the first sector of the partition on which you are installing
491 GRUB's stage1. This isn't as important if you are installing GRUB on
492 the first sector of a hard disk, since it's easy to reinitialize it
493 (e.g. by running `FDISK /MBR' from DOS).
495 If you decide to install GRUB in the native environment, which is
496 definitely desirable, you'll need to create a GRUB boot disk, and
497 reboot your computer with it. Otherwise, see *Note Installing GRUB
498 using grub-install::.
500 Once started, GRUB will show the command-line interface (*note
501 Command-line interface::). First, set the GRUB's "root device"(1)
502 (*note Installing GRUB natively-Footnote-1::) to the partition
503 containing the boot directory, like this:
507 If you are not sure which partition actually holds this directory,
508 use the command `find' (*note find::), like this:
510 grub> find /boot/grub/stage1
512 This will search for the file name `/boot/grub/stage1' and show the
513 devices which contain the file.
515 Once you've set the root device correctly, run the command `setup'
520 This command will install the GRUB boot loader on the Master Boot
521 Record (MBR) of the first drive. If you want to put GRUB into the boot
522 sector of a partition instead of putting it in the MBR, specify the
523 partition into which you want to install GRUB:
527 If you install GRUB into a partition or a drive other than the first
528 one, you must chain-load GRUB from another boot loader. Refer to the
529 manual for the boot loader to know how to chain-load GRUB.
531 After using the setup command, you will boot into GRUB without the
532 GRUB floppy. See the chapter *Note Booting:: to find out how to boot
533 your operating systems from GRUB.
536 File: grub.info, Node: Installing GRUB natively-Footnotes, Up: Installing GRUB natively
538 (1) Note that GRUB's root device doesn't necessarily mean your OS's
539 root partition; if you need to specify a root partition for your OS,
540 add the argument into the command `kernel'.
543 File: grub.info, Node: Installing GRUB using grub-install, Next: Making a GRUB bootable CD-ROM, Prev: Installing GRUB natively, Up: Installation
545 3.3 Installing GRUB using grub-install
546 ======================================
548 *Caution:* This procedure is definitely less safe, because there are
549 several ways in which your computer can become unbootable. For example,
550 most operating systems don't tell GRUB how to map BIOS drives to OS
551 devices correctly--GRUB merely "guesses" the mapping. This will succeed
552 in most cases, but not always. Therefore, GRUB provides you with a map
553 file called the "device map", which you must fix if it is wrong. *Note
554 Device map::, for more details.
556 If you still do want to install GRUB under a UNIX-like OS (such as
557 GNU), invoke the program `grub-install' (*note Invoking grub-install::)
558 as the superuser ("root").
560 The usage is basically very simple. You only need to specify one
561 argument to the program, namely, where to install the boot loader. The
562 argument can be either a device file (like `/dev/hda') or a partition
563 specified in GRUB's notation. For example, under Linux the following
564 will install GRUB into the MBR of the first IDE disk:
566 # grub-install /dev/hda
568 Likewise, under GNU/Hurd, this has the same effect:
570 # grub-install /dev/hd0
572 If it is the first BIOS drive, this is the same as well:
574 # grub-install '(hd0)'
576 Or you can omit the parentheses:
580 But all the above examples assume that GRUB should use images under
581 the root directory. If you want GRUB to use images under a directory
582 other than the root directory, you need to specify the option
583 `--root-directory'. The typical usage is that you create a GRUB boot
584 floppy with a filesystem. Here is an example:
587 # mount -t ext2 /dev/fd0 /mnt
588 # grub-install --root-directory=/mnt fd0
591 Another example is when you have a separate boot partition which is
592 mounted at `/boot'. Since GRUB is a boot loader, it doesn't know
593 anything about mountpoints at all. Thus, you need to run `grub-install'
596 # grub-install --root-directory=/boot /dev/hda
598 By the way, as noted above, it is quite difficult to guess BIOS
599 drives correctly under a UNIX-like OS. Thus, `grub-install' will prompt
600 you to check if it could really guess the correct mappings, after the
601 installation. The format is defined in *Note Device map::. Please be
602 quite careful. If the output is wrong, it is unlikely that your
603 computer will be able to boot with no problem.
605 Note that `grub-install' is actually just a shell script and the
606 real task is done by the grub shell `grub' (*note Invoking the grub
607 shell::). Therefore, you may run `grub' directly to install GRUB,
608 without using `grub-install'. Don't do that, however, unless you are
609 very familiar with the internals of GRUB. Installing a boot loader on a
610 running OS may be extremely dangerous.
613 File: grub.info, Node: Making a GRUB bootable CD-ROM, Prev: Installing GRUB using grub-install, Up: Installation
615 3.4 Making a GRUB bootable CD-ROM
616 =================================
618 GRUB supports the "no emulation mode" in the El Torito specification(1)
619 (*note Making a GRUB bootable CD-ROM-Footnote-1::). This means that you
620 can use the whole CD-ROM from GRUB and you don't have to make a floppy
621 or hard disk image file, which can cause compatibility problems.
623 For booting from a CD-ROM, GRUB uses a special Stage 2 called
624 `stage2_eltorito'. The only GRUB files you need to have in your
625 bootable CD-ROM are this `stage2_eltorito' and optionally a config file
626 `menu.lst'. You don't need to use `stage1' or `stage2', because El
627 Torito is quite different from the standard boot process.
629 Here is an example of procedures to make a bootable CD-ROM image.
630 First, make a top directory for the bootable image, say, `iso':
634 Make a directory for GRUB:
636 $ mkdir -p iso/boot/grub
638 Copy the file `stage2_eltorito':
640 $ cp /usr/lib/grub/i386-pc/stage2_eltorito iso/boot/grub
642 If desired, make the config file `menu.lst' under `iso/boot/grub'
643 (*note Configuration::), and copy any files and directories for the
644 disc to the directory `iso/'.
646 Finally, make a ISO9660 image file like this:
648 $ mkisofs -R -b boot/grub/stage2_eltorito -no-emul-boot \
649 -boot-load-size 4 -boot-info-table -o grub.iso iso
651 This produces a file named `grub.iso', which then can be burned into
652 a CD (or a DVD). `mkisofs' has already set up the disc to boot from
653 the `boot/grub/stage2_eltorito' file, so there is no need to setup GRUB
654 on the disc. (Note that the `-boot-load-size 4' bit is required for
655 compatibility with the BIOS on many older machines.)
657 You can use the device `(cd)' to access a CD-ROM in your config
658 file. This is not required; GRUB automatically sets the root device to
659 `(cd)' when booted from a CD-ROM. It is only necessary to refer to
660 `(cd)' if you want to access other drives as well.
663 File: grub.info, Node: Making a GRUB bootable CD-ROM-Footnotes, Up: Making a GRUB bootable CD-ROM
665 (1) El Torito is a specification for bootable CD using BIOS
669 File: grub.info, Node: Booting, Next: Configuration, Prev: Installation, Up: Top
674 GRUB can load Multiboot-compliant kernels in a consistent way, but for
675 some free operating systems you need to use some OS-specific magic.
679 * General boot methods:: How to boot OSes with GRUB generally
680 * OS-specific notes:: Notes on some operating systems
681 * Making your system robust:: How to make your system robust
684 File: grub.info, Node: General boot methods, Next: OS-specific notes, Up: Booting
686 4.1 How to boot operating systems
687 =================================
689 GRUB has two distinct boot methods. One of the two is to load an
690 operating system directly, and the other is to chain-load another boot
691 loader which then will load an operating system actually. Generally
692 speaking, the former is more desirable, because you don't need to
693 install or maintain other boot loaders and GRUB is flexible enough to
694 load an operating system from an arbitrary disk/partition. However, the
695 latter is sometimes required, since GRUB doesn't support all the
696 existing operating systems natively.
700 * Loading an operating system directly::
704 File: grub.info, Node: Loading an operating system directly, Next: Chain-loading, Up: General boot methods
706 4.1.1 How to boot an OS directly with GRUB
707 ------------------------------------------
709 Multiboot (*note Multiboot Specification: (multiboot)Top.) is the
710 native format supported by GRUB. For the sake of convenience, there is
711 also support for Linux, FreeBSD, NetBSD and OpenBSD. If you want to
712 boot other operating systems, you will have to chain-load them (*note
715 Generally, GRUB can boot any Multiboot-compliant OS in the following
718 1. Set GRUB's root device to the drive where the OS images are stored
719 with the command `root' (*note root::).
721 2. Load the kernel image with the command `kernel' (*note kernel::).
723 3. If you need modules, load them with the command `module' (*note
724 module::) or `modulenounzip' (*note modulenounzip::).
726 4. Run the command `boot' (*note boot::).
728 Linux, FreeBSD, NetBSD and OpenBSD can be booted in a similar
729 manner. You load a kernel image with the command `kernel' and then run
730 the command `boot'. If the kernel requires some parameters, just append
731 the parameters to `kernel', after the file name of the kernel. Also,
732 please refer to *Note OS-specific notes::, for information on your
736 File: grub.info, Node: Chain-loading, Prev: Loading an operating system directly, Up: General boot methods
738 4.1.2 Load another boot loader to boot unsupported operating systems
739 --------------------------------------------------------------------
741 If you want to boot an unsupported operating system (e.g. Windows 95),
742 chain-load a boot loader for the operating system. Normally, the boot
743 loader is embedded in the "boot sector" of the partition on which the
744 operating system is installed.
746 1. Set GRUB's root device to the partition by the command
747 `rootnoverify' (*note rootnoverify::):
749 grub> rootnoverify (hd0,0)
751 2. Set the "active" flag in the partition using the command
752 `makeactive'(1) (*note Chain-loading-Footnote-1::) (*note
757 3. Load the boot loader with the command `chainloader' (*note
762 `+1' indicates that GRUB should read one sector from the start of
763 the partition. The complete description about this syntax can be
764 found in *Note Block list syntax::.
766 4. Run the command `boot' (*note boot::).
768 However, DOS and Windows have some deficiencies, so you might have to
769 use more complicated instructions. *Note DOS/Windows::, for more
773 File: grub.info, Node: Chain-loading-Footnotes, Up: Chain-loading
775 (1) This is not necessary for most of the modern operating systems.
778 File: grub.info, Node: OS-specific notes, Next: Making your system robust, Prev: General boot methods, Up: Booting
780 4.2 Some caveats on OS-specific issues
781 ======================================
783 Here, we describe some caveats on several operating systems.
797 File: grub.info, Node: GNU/Hurd, Next: GNU/Linux, Up: OS-specific notes
802 Since GNU/Hurd is Multiboot-compliant, it is easy to boot it; there is
803 nothing special about it. But do not forget that you have to specify a
804 root partition to the kernel.
806 1. Set GRUB's root device to the same drive as GNU/Hurd's. Probably
807 the command `find /boot/gnumach' or similar can help you (*note
810 2. Load the kernel and the module, like this:
812 grub> kernel /boot/gnumach root=hd0s1
813 grub> module /boot/serverboot
815 3. Run the command `boot' (*note boot::).
818 File: grub.info, Node: GNU/Linux, Next: FreeBSD, Prev: GNU/Hurd, Up: OS-specific notes
823 It is relatively easy to boot GNU/Linux from GRUB, because it somewhat
824 resembles to boot a Multiboot-compliant OS.
826 1. Set GRUB's root device to the same drive as GNU/Linux's. Probably
827 the command `find /vmlinuz' or similar can help you (*note find::).
831 grub> kernel /vmlinuz root=/dev/hda1
833 If you need to specify some kernel parameters, just append them to
834 the command. For example, to set `vga' to `ext', do this:
836 grub> kernel /vmlinuz root=/dev/hda1 vga=ext
838 See the documentation in the Linux source tree for complete
839 information on the available options.
841 3. If you use an initrd, execute the command `initrd' (*note
842 initrd::) after `kernel':
846 4. Finally, run the command `boot' (*note boot::).
848 *Caution:* If you use an initrd and specify the `mem=' option to the
849 kernel to let it use less than actual memory size, you will also have
850 to specify the same memory size to GRUB. To let GRUB know the size, run
851 the command `uppermem' _before_ loading the kernel. *Note uppermem::,
852 for more information.
855 File: grub.info, Node: FreeBSD, Next: NetBSD, Prev: GNU/Linux, Up: OS-specific notes
860 GRUB can load the kernel directly, either in ELF or a.out format. But
861 this is not recommended, since FreeBSD's bootstrap interface sometimes
862 changes heavily, so GRUB can't guarantee to pass kernel parameters
865 Thus, we'd recommend loading the very flexible loader `/boot/loader'
866 instead. See this example:
869 grub> kernel /boot/loader
873 File: grub.info, Node: NetBSD, Next: OpenBSD, Prev: FreeBSD, Up: OS-specific notes
878 GRUB can load NetBSD a.out and ELF directly, follow these steps:
880 1. Set GRUB's root device with `root' (*note root::).
882 2. Load the kernel with `kernel' (*note kernel::). You should append
883 the ugly option `--type=netbsd', if you want to load an ELF
886 grub> kernel --type=netbsd /netbsd-elf
888 3. Run `boot' (*note boot::).
890 For now, however, GRUB doesn't allow you to pass kernel parameters,
891 so it may be better to chain-load it instead. For more information,
892 please see *Note Chain-loading::.
895 File: grub.info, Node: OpenBSD, Next: DOS/Windows, Prev: NetBSD, Up: OS-specific notes
900 The booting instruction is exactly the same as for NetBSD (*note
904 File: grub.info, Node: DOS/Windows, Next: SCO UnixWare, Prev: OpenBSD, Up: OS-specific notes
909 GRUB cannot boot DOS or Windows directly, so you must chain-load them
910 (*note Chain-loading::). However, their boot loaders have some critical
911 deficiencies, so it may not work to just chain-load them. To overcome
912 the problems, GRUB provides you with two helper functions.
914 If you have installed DOS (or Windows) on a non-first hard disk, you
915 have to use the disk swapping technique, because that OS cannot boot
916 from any disks but the first one. The workaround used in GRUB is the
917 command `map' (*note map::), like this:
919 grub> map (hd0) (hd1)
920 grub> map (hd1) (hd0)
922 This performs a "virtual" swap between your first and second hard
925 *Caution:* This is effective only if DOS (or Windows) uses BIOS to
926 access the swapped disks. If that OS uses a special driver for the
927 disks, this probably won't work.
929 Another problem arises if you installed more than one set of
930 DOS/Windows onto one disk, because they could be confused if there are
931 more than one primary partitions for DOS/Windows. Certainly you should
932 avoid doing this, but there is a solution if you do want to do so. Use
933 the partition hiding/unhiding technique.
935 If GRUB "hide"s a DOS (or Windows) partition (*note hide::), DOS (or
936 Windows) will ignore the partition. If GRUB "unhide"s a DOS (or
937 Windows) partition (*note unhide::), DOS (or Windows) will detect the
938 partition. Thus, if you have installed DOS (or Windows) on the first
939 and the second partition of the first hard disk, and you want to boot
940 the copy on the first partition, do the following:
944 grub> rootnoverify (hd0,0)
950 File: grub.info, Node: SCO UnixWare, Next: QNX, Prev: DOS/Windows, Up: OS-specific notes
955 It is known that the signature in the boot loader for SCO UnixWare is
956 wrong, so you will have to specify the option `--force' to
957 `chainloader' (*note chainloader::), like this:
959 grub> rootnoverify (hd1,0)
960 grub> chainloader --force +1
965 File: grub.info, Node: QNX, Prev: SCO UnixWare, Up: OS-specific notes
970 QNX seems to use a bigger boot loader, so you need to boot it up, like
973 grub> rootnoverify (hd1,1)
978 File: grub.info, Node: Making your system robust, Prev: OS-specific notes, Up: Booting
980 4.3 How to make your system robust
981 ==================================
983 When you test a new kernel or a new OS, it is important to make sure
984 that your computer can boot even if the new system is unbootable. This
985 is crucial especially if you maintain servers or remote systems. To
986 accomplish this goal, you need to set up two things:
988 1. You must maintain a system which is always bootable. For instance,
989 if you test a new kernel, you need to keep a working kernel in a
990 different place. And, it would sometimes be very nice to even have
991 a complete copy of a working system in a different partition or
994 2. You must direct GRUB to boot a working system when the new system
995 fails. This is possible with the "fallback" system in GRUB.
997 The former requirement is very specific to each OS, so this
998 documentation does not cover that topic. It is better to consult some
1001 So let's see the GRUB part. There are two possibilities: one of them
1002 is quite simple but not very robust, and the other is a bit complex to
1003 set up but probably the best solution to make sure that your system can
1004 start as long as GRUB itself is bootable.
1008 * Booting once-only::
1009 * Booting fallback systems::
1012 File: grub.info, Node: Booting once-only, Next: Booting fallback systems, Up: Making your system robust
1014 4.3.1 Booting once-only
1015 -----------------------
1017 You can teach GRUB to boot an entry only at next boot time. Suppose
1018 that your have an old kernel `old_kernel' and a new kernel
1019 `new_kernel'. You know that `old_kernel' can boot your system
1020 correctly, and you want to test `new_kernel'.
1022 To ensure that your system will go back to the old kernel even if the
1023 new kernel fails (e.g. it panics), you can specify that GRUB should try
1024 the new kernel only once and boot the old kernel after that.
1026 First, modify your configuration file. Here is an example:
1028 default saved # This is important!!!
1031 title the old kernel
1036 title the new kernel
1039 savedefault 0 # This is important!!!
1041 Note that this configuration file uses `default saved' (*note
1042 default::) at the head and `savedefault 0' (*note savedefault::) in the
1043 entry for the new kernel. This means that GRUB boots a saved entry by
1044 default, and booting the entry for the new kernel saves `0' as the
1047 With this configuration file, after all, GRUB always tries to boot
1048 the old kernel after it booted the new one, because `0' is the entry of
1051 The next step is to tell GRUB to boot the new kernel at next boot
1052 time. For this, execute `grub-set-default' (*note Invoking
1053 grub-set-default::):
1055 # grub-set-default 1
1057 This command sets the saved entry to `1', that is, to the new kernel.
1059 This method is useful, but still not very robust, because GRUB stops
1060 booting, if there is any error in the boot entry, such that the new
1061 kernel has an invalid executable format. Thus, it it even better to use
1062 the "fallback" mechanism of GRUB. Look at next subsection for this
1066 File: grub.info, Node: Booting fallback systems, Prev: Booting once-only, Up: Making your system robust
1068 4.3.2 Booting fallback systems
1069 ------------------------------
1071 GRUB supports a fallback mechanism of booting one or more other entries
1072 if a default boot entry fails. You can specify multiple fallback
1073 entries if you wish.
1075 Suppose that you have three systems, `A', `B' and `C'. `A' is a
1076 system which you want to boot by default. `B' is a backup system which
1077 is supposed to boot safely. `C' is another backup system which is used
1078 in case where `B' is broken.
1080 Then you may want GRUB to boot the first system which is bootable
1081 among `A', `B' and `C'. A configuration file can be written in this way:
1083 default saved # This is important!!!
1085 fallback 1 2 # This is important!!!
1090 savedefault fallback # This is important!!!
1095 savedefault fallback # This is important!!!
1102 Note that `default saved' (*note default::), `fallback 1 2' and
1103 `savedefault fallback' are used. GRUB will boot a saved entry by
1104 default and save a fallback entry as next boot entry with this
1107 When GRUB tries to boot `A', GRUB saves `1' as next boot entry,
1108 because the command `fallback' specifies that `1' is the first fallback
1109 entry. The entry `1' is `B', so GRUB will try to boot `B' at next boot
1112 Likewise, when GRUB tries to boot `B', GRUB saves `2' as next boot
1113 entry, because `fallback' specifies `2' as next fallback entry. This
1114 makes sure that GRUB will boot `C' after booting `B'.
1116 It is noteworthy that GRUB uses fallback entries both when GRUB
1117 itself fails in booting an entry and when `A' or `B' fails in starting
1118 up your system. So this solution ensures that your system is started
1119 even if GRUB cannot find your kernel or if your kernel panics.
1121 However, you need to run `grub-set-default' (*note Invoking
1122 grub-set-default::) when `A' starts correctly or you fix `A' after it
1123 crashes, since GRUB always sets next boot entry to a fallback entry.
1124 You should run this command in a startup script such as `rc.local' to
1125 boot `A' by default:
1127 # grub-set-default 0
1129 where `0' is the number of the boot entry for the system `A'.
1131 If you want to see what is current default entry, you can look at the
1132 file `/boot/grub/default' (or `/grub/default' in some systems). Because
1133 this file is plain-text, you can just `cat' this file. But it is
1134 strongly recommended *not to modify this file directly*, because GRUB
1135 may fail in saving a default entry in this file, if you change this
1136 file in an unintended manner. Therefore, you should use
1137 `grub-set-default' when you need to change the default entry.
1140 File: grub.info, Node: Configuration, Next: Network, Prev: Booting, Up: Top
1145 You've probably noticed that you need to type several commands to boot
1146 your OS. There's a solution to that - GRUB provides a menu interface
1147 (*note Menu interface::) from which you can select an item (using arrow
1148 keys) that will do everything to boot an OS.
1150 To enable the menu, you need a configuration file, `menu.lst' under
1151 the boot directory. We'll analyze an example file.
1153 The file first contains some general settings, the menu interface
1154 related options. You can put these commands (*note Menu-specific
1155 commands::) before any of the items (starting with `title' (*note
1159 # Sample boot menu configuration file
1162 As you may have guessed, these lines are comments. Lines starting
1163 with a hash character (`#'), and blank lines, are ignored by GRUB.
1165 # By default, boot the first entry.
1168 The first entry (here, counting starts with number zero, not one!)
1169 will be the default choice.
1171 # Boot automatically after 30 secs.
1174 As the comment says, GRUB will boot automatically in 30 seconds,
1175 unless interrupted with a keypress.
1177 # Fallback to the second entry.
1180 If, for any reason, the default entry doesn't work, fall back to the
1181 second one (this is rarely used, for obvious reasons).
1183 Note that the complete descriptions of these commands, which are menu
1184 interface specific, can be found in *Note Menu-specific commands::.
1185 Other descriptions can be found in *Note Commands::.
1187 Now, on to the actual OS definitions. You will see that each entry
1188 begins with a special command, `title' (*note title::), and the action
1189 is described after it. Note that there is no command `boot' (*note
1190 boot::) at the end of each item. That is because GRUB automatically
1191 executes `boot' if it loads other commands successfully.
1193 The argument for the command `title' is used to display a short
1194 title/description of the entry in the menu. Since `title' displays the
1195 argument as is, you can write basically anything there.
1197 # For booting GNU/Hurd
1200 kernel /boot/gnumach.gz root=hd0s1
1201 module /boot/serverboot.gz
1203 This boots GNU/Hurd from the first hard disk.
1205 # For booting GNU/Linux
1207 kernel (hd1,0)/vmlinuz root=/dev/hdb1
1209 This boots GNU/Linux, but from the second hard disk.
1211 # For booting Mach (getting kernel from floppy)
1212 title Utah Mach4 multiboot
1214 pause Insert the diskette now^G!!
1215 kernel (fd0)/boot/kernel root=hd0s3
1216 module (fd0)/boot/bootstrap
1218 This boots Mach with a kernel on a floppy, but the root filesystem at
1219 hd0s3. It also contains a `pause' line (*note pause::), which will
1220 cause GRUB to display a prompt and delay, before actually executing the
1221 rest of the commands and booting.
1223 # For booting FreeBSD
1228 This item will boot FreeBSD kernel loaded from the `a' partition of
1229 the third PC slice of the first hard disk.
1235 # chainload OS/2 bootloader from the first sector
1237 # This is similar to "chainload", but loads a specific file
1238 #chainloader /boot/chain.os2
1240 This will boot OS/2, using a chain-loader (*note Chain-loading::).
1242 # For booting Windows NT or Windows95
1243 title Windows NT / Windows 95 boot menu
1247 # For loading DOS if Windows NT is installed
1248 # chainload /bootsect.dos
1250 The same as the above, but for Windows.
1252 # For installing GRUB into the hard disk
1253 title Install GRUB into the hard disk
1257 This will just (re)install GRUB onto the hard disk.
1259 # Change the colors.
1260 title Change the colors
1261 color light-green/brown blink-red/blue
1263 In the last entry, the command `color' is used (*note color::), to
1264 change the menu colors (try it!). This command is somewhat special,
1265 because it can be used both in the command-line and in the menu. GRUB
1266 has several such commands, see *Note General commands::.
1268 We hope that you now understand how to use the basic features of
1269 GRUB. To learn more about GRUB, see the following chapters.
1272 File: grub.info, Node: Network, Next: Serial terminal, Prev: Configuration, Up: Top
1274 6 Downloading OS images from a network
1275 **************************************
1277 Although GRUB is a disk-based boot loader, it does provide network
1278 support. To use the network support, you need to enable at least one
1279 network driver in the GRUB build process. For more information please
1280 see `netboot/README.netboot' in the source distribution.
1284 * General usage of network support::
1288 File: grub.info, Node: General usage of network support, Next: Diskless, Up: Network
1290 6.1 How to set up your network
1291 ==============================
1293 GRUB requires a file server and optionally a server that will assign an
1294 IP address to the machine on which GRUB is running. For the former, only
1295 TFTP is supported at the moment. The latter is either BOOTP, DHCP or a
1296 RARP server(1) (*note General usage of network support-Footnote-1::).
1297 It is not necessary to run both the servers on one computer. How to
1298 configure these servers is beyond the scope of this document, so please
1299 refer to the manuals specific to those protocols/servers.
1301 If you decided to use a server to assign an IP address, set up the
1302 server and run `bootp' (*note bootp::), `dhcp' (*note dhcp::) or `rarp'
1303 (*note rarp::) for BOOTP, DHCP or RARP, respectively. Each command will
1304 show an assigned IP address, a netmask, an IP address for your TFTP
1305 server and a gateway. If any of the addresses is wrong or it causes an
1306 error, probably the configuration of your servers isn't set up properly.
1308 Otherwise, run `ifconfig', like this:
1310 grub> ifconfig --address=192.168.110.23 --server=192.168.110.14
1312 You can also use `ifconfig' in conjuction with `bootp', `dhcp' or
1313 `rarp' (e.g. to reassign the server address manually). *Note
1314 ifconfig::, for more details.
1316 Finally, download your OS images from your network. The network can
1317 be accessed using the network drive `(nd)'. Everything else is very
1318 similar to the normal instructions (*note Booting::).
1325 Address: 192.168.110.23 Netmask: 255.255.255.0
1326 Server: 192.168.110.14 Gateway: 192.168.110.1
1329 grub> kernel /tftproot/gnumach.gz root=sd0s1
1330 grub> module /tftproot/serverboot.gz
1334 File: grub.info, Node: General usage of network support-Footnotes, Up: General usage of network support
1336 (1) RARP is not advised, since it cannot serve much information
1339 File: grub.info, Node: Diskless, Prev: General usage of network support, Up: Network
1341 6.2 Booting from a network
1342 ==========================
1344 It is sometimes very useful to boot from a network, especially when you
1345 use a machine which has no local disk. In this case, you need to obtain
1346 a kind of Net Boot ROM, such as a PXE ROM or a free software package
1347 like Etherboot. Such a Boot ROM first boots the machine, sets up the
1348 network card installed into the machine, and downloads a second stage
1349 boot image from the network. Then, the second image will try to boot an
1350 operating system actually from the network.
1352 GRUB provides two second stage images, `nbgrub' and `pxegrub' (*note
1353 Images::). These images are the same as the normal Stage 2, except that
1354 they set up a network automatically, and try to load a configuration
1355 file from the network, if specified. The usage is very simple: If the
1356 machine has a PXE ROM, use `pxegrub'. If the machine has an NBI loader
1357 such as Etherboot, use `nbgrub'. There is no difference between them
1358 except their formats. Since the way to load a second stage image you
1359 want to use should be described in the manual on your Net Boot ROM,
1360 please refer to the manual, for more information.
1362 However, there is one thing specific to GRUB. Namely, how to specify
1363 a configuration file in a BOOTP/DHCP server. For now, GRUB uses the tag
1364 `150', to get the name of a configuration file. The following is an
1365 example with a BOOTP configuration:
1367 .allhost:hd=/tmp:bf=null:\
1368 :ds=145.71.35.1 145.71.32.1:\
1373 foo:ht=1:ha=63655d0334a7:ip=145.71.35.127:\
1376 :T150="(nd)/tftpboot/menu.lst.foo":
1378 Note that you should specify the drive name `(nd)' in the name of
1379 the configuration file. This is because you might change the root drive
1380 before downloading the configuration from the TFTP server when the
1381 preset menu feature is used (*note Preset Menu::).
1383 See the manual of your BOOTP/DHCP server for more information. The
1384 exact syntax should differ a little from the example.
1387 File: grub.info, Node: Serial terminal, Next: Preset Menu, Prev: Network, Up: Top
1389 7 Using GRUB via a serial line
1390 ******************************
1392 This chapter describes how to use the serial terminal support in GRUB.
1394 If you have many computers or computers with no display/keyboard, it
1395 could be very useful to control the computers through serial
1396 communications. To connect one computer with another via a serial line,
1397 you need to prepare a null-modem (cross) serial cable, and you may need
1398 to have multiport serial boards, if your computer doesn't have extra
1399 serial ports. In addition, a terminal emulator is also required, such as
1400 minicom. Refer to a manual of your operating system, for more
1403 As for GRUB, the instruction to set up a serial terminal is quite
1404 simple. First of all, make sure that you haven't specified the option
1405 `--disable-serial' to the configure script when you built your GRUB
1406 images. If you get them in binary form, probably they have serial
1407 terminal support already.
1409 Then, initialize your serial terminal after GRUB starts up. Here is
1412 grub> serial --unit=0 --speed=9600
1413 grub> terminal serial
1415 The command `serial' initializes the serial unit 0 with the speed
1416 9600bps. The serial unit 0 is usually called `COM1', so, if you want to
1417 use COM2, you must specify `--unit=1' instead. This command accepts
1418 many other options, so please refer to *Note serial::, for more details.
1420 The command `terminal' (*note terminal::) chooses which type of
1421 terminal you want to use. In the case above, the terminal will be a
1422 serial terminal, but you can also pass `console' to the command, as
1423 `terminal serial console'. In this case, a terminal in which you press
1424 any key will be selected as a GRUB terminal.
1426 However, note that GRUB assumes that your terminal emulator is
1427 compatible with VT100 by default. This is true for most terminal
1428 emulators nowadays, but you should pass the option `--dumb' to the
1429 command if your terminal emulator is not VT100-compatible or implements
1430 few VT100 escape sequences. If you specify this option then GRUB
1431 provides you with an alternative menu interface, because the normal
1432 menu requires several fancy features of your terminal.
1435 File: grub.info, Node: Preset Menu, Next: Security, Prev: Serial terminal, Up: Top
1437 8 Embedding a configuration file into GRUB
1438 ******************************************
1440 GRUB supports a "preset menu" which is to be always loaded before
1441 starting. The preset menu feature is useful, for example, when your
1442 computer has no console but a serial cable. In this case, it is
1443 critical to set up the serial terminal as soon as possible, since you
1444 cannot see any message until the serial terminal begins to work. So it
1445 is good to run the commands `serial' (*note serial::) and `terminal'
1446 (*note terminal::) before anything else at the start-up time.
1448 How the preset menu works is slightly complicated:
1450 1. GRUB checks if the preset menu feature is used, and loads the
1451 preset menu, if available. This includes running commands and
1452 reading boot entries, like an ordinary configuration file.
1454 2. GRUB checks if the configuration file is available. Note that this
1455 check is performed *regardless of the existence of the preset
1456 menu*. The configuration file is loaded even if the preset menu was
1459 3. If the preset menu includes any boot entries, they are cleared when
1460 the configuration file is loaded. It doesn't matter whether the
1461 configuration file has any entries or no entry. The boot entries
1462 in the preset menu are used only when GRUB fails in loading the
1465 To enable the preset menu feature, you must rebuild GRUB specifying a
1466 file to the configure script with the option `--enable-preset-menu'.
1467 The file has the same semantics as normal configuration files (*note
1470 Another point you should take care is that the diskless support
1471 (*note Diskless::) diverts the preset menu. Diskless images embed a
1472 preset menu to execute the command `bootp' (*note bootp::)
1473 automatically, unless you specify your own preset menu to the configure
1474 script. This means that you must put commands to initialize a network in
1475 the preset menu yourself, because diskless images don't set it up
1476 implicitly, when you use the preset menu explicitly.
1478 Therefore, a typical preset menu used with diskless support would be
1481 # Set up the serial terminal, first of all.
1482 serial --unit=0 --speed=19200
1483 terminal --timeout=0 serial
1485 # Initialize the network.
1489 File: grub.info, Node: Security, Next: Images, Prev: Preset Menu, Up: Top
1491 9 Protecting your computer from cracking
1492 ****************************************
1494 You may be interested in how to prevent ordinary users from doing
1495 whatever they like, if you share your computer with other people. So
1496 this chapter describes how to improve the security of GRUB.
1498 One thing which could be a security hole is that the user can do too
1499 many things with GRUB, because GRUB allows one to modify its
1500 configuration and run arbitrary commands at run-time. For example, the
1501 user can even read `/etc/passwd' in the command-line interface by the
1502 command `cat' (*note cat::). So it is necessary to disable all the
1503 interactive operations.
1505 Thus, GRUB provides a "password" feature, so that only administrators
1506 can start the interactive operations (i.e. editing menu entries and
1507 entering the command-line interface). To use this feature, you need to
1508 run the command `password' in your configuration file (*note
1509 password::), like this:
1511 password --md5 PASSWORD
1513 If this is specified, GRUB disallows any interactive control, until
1514 you press the key <p> and enter a correct password. The option `--md5'
1515 tells GRUB that `PASSWORD' is in MD5 format. If it is omitted, GRUB
1516 assumes the `PASSWORD' is in clear text.
1518 You can encrypt your password with the command `md5crypt' (*note
1519 md5crypt::). For example, run the grub shell (*note Invoking the grub
1520 shell::), and enter your password:
1523 Password: **********
1524 Encrypted: $1$U$JK7xFegdxWH6VuppCUSIb.
1526 Then, cut and paste the encrypted password to your configuration
1529 Also, you can specify an optional argument to `password'. See this
1532 password PASSWORD /boot/grub/menu-admin.lst
1534 In this case, GRUB will load `/boot/grub/menu-admin.lst' as a
1535 configuration file when you enter the valid password.
1537 Another thing which may be dangerous is that any user can choose any
1538 menu entry. Usually, this wouldn't be problematic, but you might want to
1539 permit only administrators to run some of your menu entries, such as an
1540 entry for booting an insecure OS like DOS.
1542 GRUB provides the command `lock' (*note lock::). This command always
1543 fails until you enter the valid password, so you can use it, like this:
1547 rootnoverify (hd0,1)
1551 You should insert `lock' right after `title', because any user can
1552 execute commands in an entry until GRUB encounters `lock'.
1554 You can also use the command `password' instead of `lock'. In this
1555 case the boot process will ask for the password and stop if it was
1556 entered incorrectly. Since the `password' takes its own PASSWORD
1557 argument this is useful if you want different passwords for different
1561 File: grub.info, Node: Images, Next: Filesystem, Prev: Security, Up: Top
1566 GRUB consists of several images: two essential stages, optional stages
1567 called "Stage 1.5", one image for bootable CD-ROM, and two network boot
1568 images. Here is a short overview of them. *Note Internals::, for more
1572 This is an essential image used for booting up GRUB. Usually, this
1573 is embedded in an MBR or the boot sector of a partition. Because a
1574 PC boot sector is 512 bytes, the size of this image is exactly 512
1577 All `stage1' must do is to load Stage 2 or Stage 1.5 from a local
1578 disk. Because of the size restriction, `stage1' encodes the
1579 location of Stage 2 (or Stage 1.5) in a block list format, so it
1580 never understand any filesystem structure.
1583 This is the core image of GRUB. It does everything but booting up
1584 itself. Usually, this is put in a filesystem, but that is not
1595 These are called "Stage 1.5", because they serve as a bridge
1596 between `stage1' and `stage2', that is to say, Stage 1.5 is loaded
1597 by Stage 1 and Stage 1.5 loads Stage 2. The difference between
1598 `stage1' and `*_stage1_5' is that the former doesn't understand
1599 any filesystem while the latter understands one filesystem (e.g.
1600 `e2fs_stage1_5' understands ext2fs). So you can move the Stage 2
1601 image to another location safely, even after GRUB has been
1604 While Stage 2 cannot generally be embedded in a fixed area as the
1605 size is so large, Stage 1.5 can be installed into the area right
1606 after an MBR, or the boot loader area of a ReiserFS or a FFS.
1609 This is a boot image for CD-ROMs using the "no emulation mode" in
1610 El Torito specification. This is identical to Stage 2, except that
1611 this boots up without Stage 1 and sets up a special drive `(cd)'.
1614 This is a network boot image for the Network Image Proposal used
1615 by some network boot loaders, such as Etherboot. This is mostly
1616 the same as Stage 2, but it also sets up a network and loads a
1617 configuration file from the network.
1620 This is another network boot image for the Preboot Execution
1621 Environment used by several Netboot ROMs. This is identical to
1622 `nbgrub', except for the format.
1625 File: grub.info, Node: Filesystem, Next: Interface, Prev: Images, Up: Top
1627 11 Filesystem syntax and semantics
1628 **********************************
1630 GRUB uses a special syntax for specifying disk drives which can be
1631 accessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish
1632 between IDE, ESDI, SCSI, or others. You must know yourself which BIOS
1633 device is equivalent to which OS device. Normally, that will be clear if
1634 you see the files in a device or use the command `find' (*note find::).
1638 * Device syntax:: How to specify devices
1639 * File name syntax:: How to specify files
1640 * Block list syntax:: How to specify block lists
1643 File: grub.info, Node: Device syntax, Next: File name syntax, Up: Filesystem
1645 11.1 How to specify devices
1646 ===========================
1648 The device syntax is like this:
1650 `(DEVICE[,PART-NUM][,BSD-SUBPART-LETTER])'
1652 `[]' means the parameter is optional. DEVICE should be either `fd'
1653 or `hd' followed by a digit, like `fd0'. But you can also set DEVICE
1654 to a hexadecimal or a decimal number which is a BIOS drive number, so
1655 the following are equivalent:
1661 PART-NUM represents the partition number of DEVICE, starting from
1662 zero for primary partitions and from four for extended partitions, and
1663 BSD-SUBPART-LETTER represents the BSD disklabel subpartition, such as
1666 A shortcut for specifying BSD subpartitions is
1667 `(DEVICE,BSD-SUBPART-LETTER)', in this case, GRUB searches for the
1668 first PC partition containing a BSD disklabel, then finds the
1669 subpartition BSD-SUBPART-LETTER. Here is an example:
1673 The syntax `(hd0)' represents using the entire disk (or the MBR when
1674 installing GRUB), while the syntax `(hd0,0)' represents using the first
1675 partition of the disk (or the boot sector of the partition when
1678 If you enabled the network support, the special drive, `(nd)', is
1679 also available. Before using the network drive, you must initialize the
1680 network. *Note Network::, for more information.
1682 If you boot GRUB from a CD-ROM, `(cd)' is available. *Note Making a
1683 GRUB bootable CD-ROM::, for details.
1686 File: grub.info, Node: File name syntax, Next: Block list syntax, Prev: Device syntax, Up: Filesystem
1688 11.2 How to specify files
1689 =========================
1691 There are two ways to specify files, by "absolute file name" and by
1694 An absolute file name resembles a Unix absolute file name, using `/'
1695 for the directory separator (not `\' as in DOS). One example is
1696 `(hd0,0)/boot/grub/menu.lst'. This means the file `/boot/grub/menu.lst'
1697 in the first partition of the first hard disk. If you omit the device
1698 name in an absolute file name, GRUB uses GRUB's "root device"
1699 implicitly. So if you set the root device to, say, `(hd1,0)' by the
1700 command `root' (*note root::), then `/boot/kernel' is the same as
1701 `(hd1,0)/boot/kernel'.
1704 File: grub.info, Node: Block list syntax, Prev: File name syntax, Up: Filesystem
1706 11.3 How to specify block lists
1707 ===============================
1709 A block list is used for specifying a file that doesn't appear in the
1710 filesystem, like a chainloader. The syntax is
1711 `[OFFSET]+LENGTH[,[OFFSET]+LENGTH]...'. Here is an example:
1713 `0+100,200+1,300+300'
1715 This represents that GRUB should read blocks 0 through 99, block 200,
1716 and blocks 300 through 599. If you omit an offset, then GRUB assumes
1719 Like the file name syntax (*note File name syntax::), if a blocklist
1720 does not contain a device name, then GRUB uses GRUB's "root device". So
1721 `(hd0,1)+1' is the same as `+1' when the root device is `(hd0,1)'.
1724 File: grub.info, Node: Interface, Next: Commands, Prev: Filesystem, Up: Top
1726 12 GRUB's user interface
1727 ************************
1729 GRUB has both a simple menu interface for choosing preset entries from a
1730 configuration file, and a highly flexible command-line for performing
1731 any desired combination of boot commands.
1733 GRUB looks for its configuration file as soon as it is loaded. If one
1734 is found, then the full menu interface is activated using whatever
1735 entries were found in the file. If you choose the "command-line" menu
1736 option, or if the configuration file was not found, then GRUB drops to
1737 the command-line interface.
1741 * Command-line interface:: The flexible command-line interface
1742 * Menu interface:: The simple menu interface
1743 * Menu entry editor:: Editing a menu entry
1744 * Hidden menu interface:: The hidden menu interface
1747 File: grub.info, Node: Command-line interface, Next: Menu interface, Up: Interface
1749 12.1 The flexible command-line interface
1750 ========================================
1752 The command-line interface provides a prompt and after it an editable
1753 text area much like a command-line in Unix or DOS. Each command is
1754 immediately executed after it is entered(1) (*note Command-line
1755 interface-Footnote-1::). The commands (*note Command-line and menu
1756 entry commands::) are a subset of those available in the configuration
1757 file, used with exactly the same syntax.
1759 Cursor movement and editing of the text on the line can be done via a
1760 subset of the functions available in the Bash shell:
1764 Move forward one character.
1768 Move back one character.
1772 Move to the start of the line.
1776 Move the the end of the line.
1780 Delete the character underneath the cursor.
1784 Delete the character to the left of the cursor.
1787 Kill the text from the current cursor position to the end of the
1791 Kill backward from the cursor to the beginning of the line.
1794 Yank the killed text back into the buffer at the cursor.
1798 Move up through the history list.
1802 Move down through the history list.
1804 When typing commands interactively, if the cursor is within or before
1805 the first word in the command-line, pressing the <TAB> key (or <C-i>)
1806 will display a listing of the available commands, and if the cursor is
1807 after the first word, the `<TAB>' will provide a completion listing of
1808 disks, partitions, and file names depending on the context. Note that
1809 to obtain a list of drives, one must open a parenthesis, as `root ('.
1811 Note that you cannot use the completion functionality in the TFTP
1812 filesystem. This is because TFTP doesn't support file name listing for
1816 File: grub.info, Node: Command-line interface-Footnotes, Up: Command-line interface
1818 (1) However, this behavior will be changed in the future version, in
1819 a user-invisible way.
1822 File: grub.info, Node: Menu interface, Next: Menu entry editor, Prev: Command-line interface, Up: Interface
1824 12.2 The simple menu interface
1825 ==============================
1827 The menu interface is quite easy to use. Its commands are both
1828 reasonably intuitive and described on screen.
1830 Basically, the menu interface provides a list of "boot entries" to
1831 the user to choose from. Use the arrow keys to select the entry of
1832 choice, then press <RET> to run it. An optional timeout is available
1833 to boot the default entry (the first one if not set), which is aborted
1834 by pressing any key.
1836 Commands are available to enter a bare command-line by pressing <c>
1837 (which operates exactly like the non-config-file version of GRUB, but
1838 allows one to return to the menu if desired by pressing <ESC>) or to
1839 edit any of the "boot entries" by pressing <e>.
1841 If you protect the menu interface with a password (*note Security::),
1842 all you can do is choose an entry by pressing <RET>, or press <p> to
1846 File: grub.info, Node: Menu entry editor, Next: Hidden menu interface, Prev: Menu interface, Up: Interface
1848 12.3 Editing a menu entry
1849 =========================
1851 The menu entry editor looks much like the main menu interface, but the
1852 lines in the menu are individual commands in the selected entry instead
1855 If an <ESC> is pressed in the editor, it aborts all the changes made
1856 to the configuration entry and returns to the main menu interface.
1858 When a particular line is selected, the editor places the user in a
1859 special version of the GRUB command-line to edit that line. When the
1860 user hits <RET>, GRUB replaces the line in question in the boot entry
1861 with the changes (unless it was aborted via <ESC>, in which case the
1862 changes are thrown away).
1864 If you want to add a new line to the menu entry, press <o> if adding
1865 a line after the current line or press <O> if before the current line.
1867 To delete a line, hit the key <d>. Although GRUB unfortunately does
1868 not support "undo", you can do almost the same thing by just returning
1872 File: grub.info, Node: Hidden menu interface, Prev: Menu entry editor, Up: Interface
1874 12.4 The hidden menu interface
1875 ==============================
1877 When your terminal is dumb or you request GRUB to hide the menu
1878 interface explicitly with the command `hiddenmenu' (*note
1879 hiddenmenu::), GRUB doesn't show the menu interface (*note Menu
1880 interface::) and automatically boots the default entry, unless
1881 interrupted by pressing <ESC>.
1883 When you interrupt the timeout and your terminal is dumb, GRUB falls
1884 back to the command-line interface (*note Command-line interface::).
1887 File: grub.info, Node: Commands, Next: Troubleshooting, Prev: Interface, Up: Top
1889 13 The list of available commands
1890 *********************************
1892 In this chapter, we list all commands that are available in GRUB.
1894 Commands belong to different groups. A few can only be used in the
1895 global section of the configuration file (or "menu"); most of them can
1896 be entered on the command-line and can be used either anywhere in the
1897 menu or specifically in the menu entries.
1901 * Menu-specific commands::
1902 * General commands::
1903 * Command-line and menu entry commands::
1906 File: grub.info, Node: Menu-specific commands, Next: General commands, Up: Commands
1908 13.1 The list of commands for the menu only
1909 ===========================================
1911 The semantics used in parsing the configuration file are the following:
1913 * The menu-specific commands have to be used before any others.
1915 * The files _must_ be in plain-text format.
1917 * `#' at the beginning of a line in a configuration file means it is
1920 * Options are separated by spaces.
1922 * All numbers can be either decimal or hexadecimal. A hexadecimal
1923 number must be preceded by `0x', and is case-insensitive.
1925 * Extra options or text at the end of the line are ignored unless
1926 otherwise specified.
1928 * Unrecognized commands are added to the current entry, except
1929 before entries start, where they are ignored.
1931 These commands can only be used in the menu:
1935 * default:: Set the default entry
1936 * fallback:: Set the fallback entry
1937 * hiddenmenu:: Hide the menu interface
1938 * timeout:: Set the timeout
1939 * title:: Start a menu entry
1942 File: grub.info, Node: default, Next: fallback, Up: Menu-specific commands
1947 -- Command: default num
1948 Set the default entry to the entry number NUM. Numbering starts
1949 from 0, and the entry number 0 is the default if the command is not
1952 You can specify `saved' instead of a number. In this case, the
1953 default entry is the entry saved with the command `savedefault'.
1954 *Note savedefault::, for more information.
1957 File: grub.info, Node: fallback, Next: hiddenmenu, Prev: default, Up: Menu-specific commands
1962 -- Command: fallback num...
1963 Go into unattended boot mode: if the default boot entry has any
1964 errors, instead of waiting for the user to do something,
1965 immediately start over using the NUM entry (same numbering as the
1966 `default' command (*note default::)). This obviously won't help if
1967 the machine was rebooted by a kernel that GRUB loaded. You can
1968 specify multiple fallback entry numbers.
1971 File: grub.info, Node: hiddenmenu, Next: timeout, Prev: fallback, Up: Menu-specific commands
1976 -- Command: hiddenmenu
1977 Don't display the menu. If the command is used, no menu will be
1978 displayed on the control terminal, and the default entry will be
1979 booted after the timeout expired. The user can still request the
1980 menu to be displayed by pressing <ESC> before the timeout expires.
1981 See also *Note Hidden menu interface::.
1984 File: grub.info, Node: timeout, Next: title, Prev: hiddenmenu, Up: Menu-specific commands
1989 -- Command: timeout sec
1990 Set a timeout, in SEC seconds, before automatically booting the
1991 default entry (normally the first entry defined).
1994 File: grub.info, Node: title, Prev: timeout, Up: Menu-specific commands
1999 -- Command: title name ...
2000 Start a new boot entry, and set its name to the contents of the
2001 rest of the line, starting with the first non-space character.
2004 File: grub.info, Node: General commands, Next: Command-line and menu entry commands, Prev: Menu-specific commands, Up: Commands
2006 13.2 The list of general commands
2007 =================================
2009 Commands usable anywhere in the menu and in the command-line.
2013 * bootp:: Initialize a network device via BOOTP
2014 * color:: Color the menu interface
2015 * device:: Specify a file as a drive
2016 * dhcp:: Initialize a network device via DHCP
2017 * hide:: Hide a partition
2018 * ifconfig:: Configure a network device manually
2019 * pager:: Change the state of the internal pager
2020 * partnew:: Make a primary partition
2021 * parttype:: Change the type of a partition
2022 * password:: Set a password for the menu interface
2023 * rarp:: Initialize a network device via RARP
2024 * serial:: Set up a serial device
2025 * setkey:: Configure the key map
2026 * terminal:: Choose a terminal
2027 * terminfo:: Define escape sequences for a terminal
2028 * tftpserver:: Specify a TFTP server
2029 * unhide:: Unhide a partition
2032 File: grub.info, Node: bootp, Next: color, Up: General commands
2037 -- Command: bootp [`--with-configfile']
2038 Initialize a network device via the "BOOTP" protocol. This command
2039 is only available if GRUB is compiled with netboot support. See
2040 also *Note Network::.
2042 If you specify `--with-configfile' to this command, GRUB will
2043 fetch and load a configuration file specified by your BOOTP server
2044 with the vendor tag `150'.
2047 File: grub.info, Node: color, Next: device, Prev: bootp, Up: General commands
2052 -- Command: color normal [highlight]
2053 Change the menu colors. The color NORMAL is used for most lines in
2054 the menu (*note Menu interface::), and the color HIGHLIGHT is used
2055 to highlight the line where the cursor points. If you omit
2056 HIGHLIGHT, then the inverted color of NORMAL is used for the
2057 highlighted line. The format of a color is
2058 `FOREGROUND/BACKGROUND'. FOREGROUND and BACKGROUND are symbolic
2059 color names. A symbolic color name must be one of these:
2077 *These below can be specified only for the foreground.*
2095 But only the first eight names can be used for BACKGROUND. You can
2096 prefix `blink-' to FOREGROUND if you want a blinking foreground
2099 This command can be used in the configuration file and on the
2100 command line, so you may write something like this in your
2103 # Set default colors.
2104 color light-gray/blue black/light-gray
2106 # Change the colors.
2108 color magenta/blue black/magenta
2111 File: grub.info, Node: device, Next: dhcp, Prev: color, Up: General commands
2116 -- Command: device drive file
2117 In the grub shell, specify the file FILE as the actual drive for a
2118 BIOS drive DRIVE. You can use this command to create a disk image,
2119 and/or to fix the drives guessed by GRUB when GRUB fails to
2120 determine them correctly, like this:
2122 grub> device (fd0) /floppy-image
2123 grub> device (hd0) /dev/sd0
2125 This command can be used only in the grub shell (*note Invoking
2129 File: grub.info, Node: dhcp, Next: hide, Prev: device, Up: General commands
2134 -- Command: dhcp [-with-configfile]
2135 Initialize a network device via the "DHCP" protocol. Currently,
2136 this command is just an alias for `bootp', since the two protocols
2137 are very similar. This command is only available if GRUB is
2138 compiled with netboot support. See also *Note Network::.
2140 If you specify `--with-configfile' to this command, GRUB will
2141 fetch and load a configuration file specified by your DHCP server
2142 with the vendor tag `150'.
2145 File: grub.info, Node: hide, Next: ifconfig, Prev: dhcp, Up: General commands
2150 -- Command: hide partition
2151 Hide the partition PARTITION by setting the "hidden" bit in its
2152 partition type code. This is useful only when booting DOS or
2153 Windows and multiple primary FAT partitions exist in one disk. See
2154 also *Note DOS/Windows::.
2157 File: grub.info, Node: ifconfig, Next: pager, Prev: hide, Up: General commands
2162 -- Command: ifconfig [`--server=server'] [`--gateway=gateway']
2163 [`--mask=mask'] [`--address=address']
2164 Configure the IP address, the netmask, the gateway, and the server
2165 address of a network device manually. The values must be in dotted
2166 decimal format, like `192.168.11.178'. The order of the options is
2167 not important. This command shows current network configuration,
2168 if no option is specified. See also *Note Network::.
2171 File: grub.info, Node: pager, Next: partnew, Prev: ifconfig, Up: General commands
2176 -- Command: pager [flag]
2177 Toggle or set the state of the internal pager. If FLAG is `on',
2178 the internal pager is enabled. If FLAG is `off', it is disabled.
2179 If no argument is given, the state is toggled.
2182 File: grub.info, Node: partnew, Next: parttype, Prev: pager, Up: General commands
2187 -- Command: partnew part type from len
2188 Create a new primary partition. PART is a partition specification
2189 in GRUB syntax (*note Naming convention::); TYPE is the partition
2190 type and must be a number in the range `0-0xff'; FROM is the
2191 starting address and LEN is the length, both in sector units.
2194 File: grub.info, Node: parttype, Next: password, Prev: partnew, Up: General commands
2199 -- Command: parttype part type
2200 Change the type of an existing partition. PART is a partition
2201 specification in GRUB syntax (*note Naming convention::); TYPE is
2202 the new partition type and must be a number in the range 0-0xff.
2205 File: grub.info, Node: password, Next: rarp, Prev: parttype, Up: General commands
2210 -- Command: password [`--md5'] passwd [new-config-file]
2211 If used in the first section of a menu file, disable all
2212 interactive editing control (menu entry editor and command-line)
2213 and entries protected by the command `lock'. If the password
2214 PASSWD is entered, it loads the NEW-CONFIG-FILE as a new config
2215 file and restarts the GRUB Stage 2, if NEW-CONFIG-FILE is
2216 specified. Otherwise, GRUB will just unlock the privileged
2217 instructions. You can also use this command in the script
2218 section, in which case it will ask for the password, before
2219 continuing. The option `--md5' tells GRUB that PASSWD is
2220 encrypted with `md5crypt' (*note md5crypt::).
2223 File: grub.info, Node: rarp, Next: serial, Prev: password, Up: General commands
2229 Initialize a network device via the "RARP" protocol. This command
2230 is only available if GRUB is compiled with netboot support. See
2231 also *Note Network::.
2234 File: grub.info, Node: serial, Next: setkey, Prev: rarp, Up: General commands
2239 -- Command: serial [`--unit=unit'] [`--port=port'] [`--speed=speed']
2240 [`--word=word'] [`--parity=parity'] [`--stop=stop']
2242 Initialize a serial device. UNIT is a number in the range 0-3
2243 specifying which serial port to use; default is 0, which
2244 corresponds to the port often called COM1. PORT is the I/O port
2245 where the UART is to be found; if specified it takes precedence
2246 over UNIT. SPEED is the transmission speed; default is 9600. WORD
2247 and STOP are the number of data bits and stop bits. Data bits must
2248 be in the range 5-8 and stop bits must be 1 or 2. Default is 8 data
2249 bits and one stop bit. PARITY is one of `no', `odd', `even' and
2250 defaults to `no'. The option `--device' can only be used in the
2251 grub shell and is used to specify the tty device to be used in the
2252 host operating system (*note Invoking the grub shell::).
2254 The serial port is not used as a communication channel unless the
2255 `terminal' command is used (*note terminal::).
2257 This command is only available if GRUB is compiled with serial
2258 support. See also *Note Serial terminal::.
2261 File: grub.info, Node: setkey, Next: terminal, Prev: serial, Up: General commands
2266 -- Command: setkey [to_key from_key]
2267 Change the keyboard map. The key FROM_KEY is mapped to the key
2268 TO_KEY. If no argument is specified, reset key mappings. Note that
2269 this command _does not_ exchange the keys. If you want to exchange
2270 the keys, run this command again with the arguments exchanged,
2273 grub> setkey capslock control
2274 grub> setkey control capslock
2276 A key must be an alphabet letter, a digit, or one of these symbols:
2277 `escape', `exclam', `at', `numbersign', `dollar', `percent',
2278 `caret', `ampersand', `asterisk', `parenleft', `parenright',
2279 `minus', `underscore', `equal', `plus', `backspace', `tab',
2280 `bracketleft', `braceleft', `bracketright', `braceright', `enter',
2281 `control', `semicolon', `colon', `quote', `doublequote',
2282 `backquote', `tilde', `shift', `backslash', `bar', `comma',
2283 `less', `period', `greater', `slash', `question', `alt', `space',
2284 `capslock', `FX' (`X' is a digit), and `delete'. This table
2285 describes to which character each of the symbols corresponds:
2387 File: grub.info, Node: terminal, Next: terminfo, Prev: setkey, Up: General commands
2392 -- Command: terminal [`--dumb'] [`--no-echo'] [`--no-edit']
2393 [`--timeout=secs'] [`--lines=lines'] [`--silent'] [`console']
2394 [`serial'] [`hercules']
2395 Select a terminal for user interaction. The terminal is assumed to
2396 be VT100-compatible unless `--dumb' is specified. If both
2397 `console' and `serial' are specified, then GRUB will use the one
2398 where a key is entered first or the first when the timeout
2399 expires. If neither are specified, the current setting is
2400 reported. This command is only available if GRUB is compiled with
2401 serial support. See also *Note Serial terminal::.
2403 This may not make sense for most users, but GRUB supports Hercules
2404 console as well. Hercules console is usable like the ordinary
2405 console, and the usage is quite similar to that for serial
2406 terminals: specify `hercules' as the argument.
2408 The option `--lines' defines the number of lines in your terminal,
2409 and it is used for the internal pager function. If you don't
2410 specify this option, the number is assumed as 24.
2412 The option `--silent' suppresses the message to prompt you to hit
2413 any key. This might be useful if your system has no terminal
2416 The option `--no-echo' has GRUB not to echo back input characters.
2417 This implies the option `--no-edit'.
2419 The option `--no-edit' disables the BASH-like editing feature.
2422 File: grub.info, Node: terminfo, Next: tftpserver, Prev: terminal, Up: General commands
2427 -- Command: terminfo `--name=name' `--cursor-address=seq'
2428 [`--clear-screen=seq'] [`--enter-standout-mode=seq']
2429 [`--exit-standout-mode=seq']
2430 Define the capabilities of your terminal. Use this command to
2431 define escape sequences, if it is not vt100-compatible. You may
2432 use `\e' for <ESC> and `^X' for a control character.
2434 You can use the utility `grub-terminfo' to generate appropriate
2435 arguments to this command. *Note Invoking grub-terminfo::.
2437 If no option is specified, the current settings are printed.
2440 File: grub.info, Node: tftpserver, Next: unhide, Prev: terminfo, Up: General commands
2445 -- Command: tftpserver ipaddr
2446 *Caution:* This command exists only for backward compatibility.
2447 Use `ifconfig' (*note ifconfig::) instead.
2449 Override a TFTP server address returned by a BOOTP/DHCP/RARP
2450 server. The argument IPADDR must be in dotted decimal format, like
2451 `192.168.0.15'. This command is only available if GRUB is compiled
2452 with netboot support. See also *Note Network::.
2455 File: grub.info, Node: unhide, Prev: tftpserver, Up: General commands
2460 -- Command: unhide partition
2461 Unhide the partition PARTITION by clearing the "hidden" bit in its
2462 partition type code. This is useful only when booting DOS or
2463 Windows and multiple primary partitions exist on one disk. See also
2464 *Note DOS/Windows::.
2467 File: grub.info, Node: Command-line and menu entry commands, Prev: General commands, Up: Commands
2469 13.3 The list of command-line and menu entry commands
2470 =====================================================
2472 These commands are usable in the command-line and in menu entries. If
2473 you forget a command, you can run the command `help' (*note help::).
2477 * blocklist:: Get the block list notation of a file
2478 * boot:: Start up your operating system
2479 * cat:: Show the contents of a file
2480 * chainloader:: Chain-load another boot loader
2481 * cmp:: Compare two files
2482 * configfile:: Load a configuration file
2483 * debug:: Toggle the debug flag
2484 * displayapm:: Display APM information
2485 * displaymem:: Display memory configuration
2486 * embed:: Embed Stage 1.5
2487 * find:: Find a file
2488 * fstest:: Test a filesystem
2489 * geometry:: Manipulate the geometry of a drive
2490 * halt:: Shut down your computer
2491 * help:: Show help messages
2492 * impsprobe:: Probe SMP
2493 * initrd:: Load an initrd
2494 * install:: Install GRUB
2495 * ioprobe:: Probe I/O ports used for a drive
2496 * kernel:: Load a kernel
2497 * lock:: Lock a menu entry
2498 * makeactive:: Make a partition active
2499 * map:: Map a drive to another
2500 * md5crypt:: Encrypt a password in MD5 format
2501 * module:: Load a module
2502 * modulenounzip:: Load a module without decompression
2503 * pause:: Wait for a key press
2504 * quit:: Exit from the grub shell
2505 * reboot:: Reboot your computer
2506 * read:: Read data from memory
2507 * root:: Set GRUB's root device
2508 * rootnoverify:: Set GRUB's root device without mounting
2509 * savedefault:: Save current entry as the default entry
2510 * setup:: Set up GRUB's installation automatically
2511 * testload:: Load a file for testing a filesystem
2512 * testvbe:: Test VESA BIOS EXTENSION
2513 * uppermem:: Set the upper memory size
2514 * vbeprobe:: Probe VESA BIOS EXTENSION
2517 File: grub.info, Node: blocklist, Next: boot, Up: Command-line and menu entry commands
2522 -- Command: blocklist file
2523 Print the block list notation of the file FILE. *Note Block list
2527 File: grub.info, Node: boot, Next: cat, Prev: blocklist, Up: Command-line and menu entry commands
2533 Boot the OS or chain-loader which has been loaded. Only necessary
2534 if running the fully interactive command-line (it is implicit at
2535 the end of a menu entry).
2538 File: grub.info, Node: cat, Next: chainloader, Prev: boot, Up: Command-line and menu entry commands
2543 -- Command: cat file
2544 Display the contents of the file FILE. This command may be useful
2545 to remind you of your OS's root partition:
2547 grub> cat /etc/fstab
2550 File: grub.info, Node: chainloader, Next: cmp, Prev: cat, Up: Command-line and menu entry commands
2555 -- Command: chainloader [`--force'] file
2556 Load FILE as a chain-loader. Like any other file loaded by the
2557 filesystem code, it can use the blocklist notation to grab the
2558 first sector of the current partition with `+1'. If you specify the
2559 option `--force', then load FILE forcibly, whether it has a
2560 correct signature or not. This is required when you want to load a
2561 defective boot loader, such as SCO UnixWare 7.1 (*note SCO
2565 File: grub.info, Node: cmp, Next: configfile, Prev: chainloader, Up: Command-line and menu entry commands
2570 -- Command: cmp file1 file2
2571 Compare the file FILE1 with the file FILE2. If they differ in
2572 size, print the sizes like this:
2574 Differ in size: 0x1234 [foo], 0x4321 [bar]
2576 If the sizes are equal but the bytes at an offset differ, then
2577 print the bytes like this:
2579 Differ at the offset 777: 0xbe [foo], 0xef [bar]
2581 If they are completely identical, nothing will be printed.
2584 File: grub.info, Node: configfile, Next: debug, Prev: cmp, Up: Command-line and menu entry commands
2589 -- Command: configfile file
2590 Load FILE as a configuration file.
2593 File: grub.info, Node: debug, Next: displayapm, Prev: configfile, Up: Command-line and menu entry commands
2599 Toggle debug mode (by default it is off). When debug mode is on,
2600 some extra messages are printed to show disk activity. This global
2601 debug flag is mainly useful for GRUB developers when testing new
2605 File: grub.info, Node: displayapm, Next: displaymem, Prev: debug, Up: Command-line and menu entry commands
2610 -- Command: displayapm
2611 Display APM BIOS information.
2614 File: grub.info, Node: displaymem, Next: embed, Prev: displayapm, Up: Command-line and menu entry commands
2619 -- Command: displaymem
2620 Display what GRUB thinks the system address space map of the
2621 machine is, including all regions of physical RAM installed. GRUB's
2622 "upper/lower memory" display uses the standard BIOS interface for
2623 the available memory in the first megabyte, or "lower memory", and
2624 a synthesized number from various BIOS interfaces of the memory
2625 starting at 1MB and going up to the first chipset hole for "upper
2626 memory" (the standard PC "upper memory" interface is limited to
2627 reporting a maximum of 64MB).
2630 File: grub.info, Node: embed, Next: find, Prev: displaymem, Up: Command-line and menu entry commands
2635 -- Command: embed stage1_5 device
2636 Embed the Stage 1.5 STAGE1_5 in the sectors after the MBR if
2637 DEVICE is a drive, or in the "boot loader" area if DEVICE is a FFS
2638 partition or a ReiserFS partition.(1) (*note embed-Footnote-1::)
2639 Print the number of sectors which STAGE1_5 occupies, if successful.
2641 Usually, you don't need to run this command directly. *Note
2645 File: grub.info, Node: embed-Footnotes, Up: embed
2647 (1) The latter feature has not been implemented yet.
2650 File: grub.info, Node: find, Next: fstest, Prev: embed, Up: Command-line and menu entry commands
2655 -- Command: find filename
2656 Search for the file name FILENAME in all mountable partitions and
2657 print the list of the devices which contain the file. The file
2658 name FILENAME should be an absolute file name like
2659 `/boot/grub/stage1'.
2662 File: grub.info, Node: fstest, Next: geometry, Prev: find, Up: Command-line and menu entry commands
2668 Toggle filesystem test mode. Filesystem test mode, when turned
2669 on, prints out data corresponding to all the device reads and what
2670 values are being sent to the low-level routines. The format is
2671 `<PARTITION-OFFSET-SECTOR, BYTE-OFFSET, BYTE-LENGTH>' for
2672 high-level reads inside a partition, and `[DISK-OFFSET-SECTOR]'
2673 for low-level sector requests from the disk. Filesystem test mode
2674 is turned off by any use of the `install' (*note install::) or
2675 `testload' (*note testload::) commands.
2678 File: grub.info, Node: geometry, Next: halt, Prev: fstest, Up: Command-line and menu entry commands
2683 -- Command: geometry drive [cylinder head sector [total_sector]]
2684 Print the information for the drive DRIVE. In the grub shell, you
2685 can set the geometry of the drive arbitrarily. The number of
2686 cylinders, the number of heads, the number of sectors and the
2687 number of total sectors are set to CYLINDER, HEAD, SECTOR and
2688 TOTAL_SECTOR, respectively. If you omit TOTAL_SECTOR, then it will
2689 be calculated based on the C/H/S values automatically.
2692 File: grub.info, Node: halt, Next: help, Prev: geometry, Up: Command-line and menu entry commands
2697 -- Command: halt `--no-apm'
2698 The command halts the computer. If the `--no-apm' option is
2699 specified, no APM BIOS call is performed. Otherwise, the computer
2700 is shut down using APM.
2703 File: grub.info, Node: help, Next: impsprobe, Prev: halt, Up: Command-line and menu entry commands
2708 -- Command: help `--all' [pattern ...]
2709 Display helpful information about builtin commands. If you do not
2710 specify PATTERN, this command shows short descriptions of most of
2711 available commands. If you specify the option `--all' to this
2712 command, short descriptions of rarely used commands (such as *Note
2713 testload::) are displayed as well.
2715 If you specify any PATTERNS, it displays longer information about
2716 each of the commands which match those PATTERNS.
2719 File: grub.info, Node: impsprobe, Next: initrd, Prev: help, Up: Command-line and menu entry commands
2724 -- Command: impsprobe
2725 Probe the Intel Multiprocessor Specification 1.1 or 1.4
2726 configuration table and boot the various CPUs which are found into
2727 a tight loop. This command can be used only in the Stage 2, but
2728 not in the grub shell.
2731 File: grub.info, Node: initrd, Next: install, Prev: impsprobe, Up: Command-line and menu entry commands
2736 -- Command: initrd file ...
2737 Load an initial ramdisk for a Linux format boot image and set the
2738 appropriate parameters in the Linux setup area in memory. See also
2742 File: grub.info, Node: install, Next: ioprobe, Prev: initrd, Up: Command-line and menu entry commands
2747 -- Command: install [`--force-lba'] [`--stage2=os_stage2_file']
2748 stage1_file [`d'] dest_dev stage2_file [addr] [`p']
2749 [config_file] [real_config_file]
2750 This command is fairly complex, and you should not use this command
2751 unless you are familiar with GRUB. Use `setup' (*note setup::)
2754 In short, it will perform a full install presuming the Stage 2 or
2755 Stage 1.5(1) (*note install-Footnote-1::) is in its final install
2758 In slightly more detail, it will load STAGE1_FILE, validate that
2759 it is a GRUB Stage 1 of the right version number, install in it a
2760 blocklist for loading STAGE2_FILE as a Stage 2. If the option `d'
2761 is present, the Stage 1 will always look for the actual disk
2762 STAGE2_FILE was installed on, rather than using the booting drive.
2763 The Stage 2 will be loaded at address ADDR, which must be `0x8000'
2764 for a true Stage 2, and `0x2000' for a Stage 1.5. If ADDR is not
2765 present, GRUB will determine the address automatically. It then
2766 writes the completed Stage 1 to the first block of the device
2767 DEST_DEV. If the options `p' or CONFIG_FILE are present, then it
2768 reads the first block of stage2, modifies it with the values of
2769 the partition STAGE2_FILE was found on (for `p') or places the
2770 string CONFIG_FILE into the area telling the stage2 where to look
2771 for a configuration file at boot time. Likewise, if
2772 REAL_CONFIG_FILE is present and STAGE2_FILE is a Stage 1.5, then
2773 the Stage 2 CONFIG_FILE is patched with the configuration file
2774 name REAL_CONFIG_FILE. This command preserves the DOS BPB (and for
2775 hard disks, the partition table) of the sector the Stage 1 is to
2778 *Caution:* Several buggy BIOSes don't pass a booting drive
2779 properly when booting from a hard disk drive. Therefore, you will
2780 unfortunately have to specify the option `d', whether your Stage2
2781 resides at the booting drive or not, if you have such a BIOS. We
2782 know these are defective in this way:
2785 Fujitsu LifeBook 400 BIOS version 31J0103A
2788 HP Vectra XU 6/200 BIOS version GG.06.11
2790 *Caution2:* A number of BIOSes don't return a correct LBA support
2791 bitmap even if they do have the support. So GRUB provides a
2792 solution to ignore the wrong bitmap, that is, the option
2793 `--force-lba'. Don't use this option if you know that your BIOS
2794 doesn't have LBA support.
2796 *Caution3:* You must specify the option `--stage2' in the grub
2797 shell, if you cannot unmount the filesystem where your stage2 file
2798 resides. The argument should be the file name in your operating
2802 File: grub.info, Node: install-Footnotes, Up: install
2804 (1) They're loaded the same way, so we will refer to the Stage 1.5
2805 as a Stage 2 from now on.
2808 File: grub.info, Node: ioprobe, Next: kernel, Prev: install, Up: Command-line and menu entry commands
2813 -- Command: ioprobe drive
2814 Probe I/O ports used for the drive DRIVE. This command will list
2815 the I/O ports on the screen. For technical information, *Note
2819 File: grub.info, Node: kernel, Next: lock, Prev: ioprobe, Up: Command-line and menu entry commands
2824 -- Command: kernel [`--type=type'] [`--no-mem-option'] file ...
2825 Attempt to load the primary boot image (Multiboot a.out or ELF,
2826 Linux zImage or bzImage, FreeBSD a.out, NetBSD a.out, etc.) from
2827 FILE. The rest of the line is passed verbatim as the "kernel
2828 command-line". Any modules must be reloaded after using this
2831 This command also accepts the option `--type' so that you can
2832 specify the kernel type of FILE explicitly. The argument TYPE must
2833 be one of these: `netbsd', `freebsd', `openbsd', `linux',
2834 `biglinux', and `multiboot'. However, you need to specify it only
2835 if you want to load a NetBSD ELF kernel, because GRUB can
2836 automatically determine a kernel type in the other cases, quite
2839 The option `--no-mem-option' is effective only for Linux. If the
2840 option is specified, GRUB doesn't pass the option `mem=' to the
2841 kernel. This option is implied for Linux kernels 2.4.18 and newer.
2844 File: grub.info, Node: lock, Next: makeactive, Prev: kernel, Up: Command-line and menu entry commands
2850 Prevent normal users from executing arbitrary menu entries. You
2851 must use the command `password' if you really want this command to
2852 be useful (*note password::).
2854 This command is used in a menu, as shown in this example:
2856 title This entry is too dangerous to be executed by normal users
2859 kernel /no-security-os
2861 See also *Note Security::.
2864 File: grub.info, Node: makeactive, Next: map, Prev: lock, Up: Command-line and menu entry commands
2869 -- Command: makeactive
2870 Set the active partition on the root disk to GRUB's root device.
2871 This command is limited to _primary_ PC partitions on a hard disk.
2874 File: grub.info, Node: map, Next: md5crypt, Prev: makeactive, Up: Command-line and menu entry commands
2879 -- Command: map to_drive from_drive
2880 Map the drive FROM_DRIVE to the drive TO_DRIVE. This is necessary
2881 when you chain-load some operating systems, such as DOS, if such
2882 an OS resides at a non-first drive. Here is an example:
2884 grub> map (hd0) (hd1)
2885 grub> map (hd1) (hd0)
2887 The example exchanges the order between the first hard disk and the
2888 second hard disk. See also *Note DOS/Windows::.
2891 File: grub.info, Node: md5crypt, Next: module, Prev: map, Up: Command-line and menu entry commands
2896 -- Command: md5crypt
2897 Prompt to enter a password, and encrypt it in MD5 format. The
2898 encrypted password can be used with the command `password' (*note
2899 password::). See also *Note Security::.
2902 File: grub.info, Node: module, Next: modulenounzip, Prev: md5crypt, Up: Command-line and menu entry commands
2907 -- Command: module file ...
2908 Load a boot module FILE for a Multiboot format boot image (no
2909 interpretation of the file contents are made, so the user of this
2910 command must know what the kernel in question expects). The rest
2911 of the line is passed as the "module command-line", like the
2912 `kernel' command. You must load a Multiboot kernel image before
2913 loading any module. See also *Note modulenounzip::.
2916 File: grub.info, Node: modulenounzip, Next: pause, Prev: module, Up: Command-line and menu entry commands
2918 13.3.26 modulenounzip
2919 ---------------------
2921 -- Command: modulenounzip file ...
2922 The same as `module' (*note module::), except that automatic
2923 decompression is disabled.
2926 File: grub.info, Node: pause, Next: quit, Prev: modulenounzip, Up: Command-line and menu entry commands
2931 -- Command: pause message ...
2932 Print the MESSAGE, then wait until a key is pressed. Note that
2933 placing <^G> (ASCII code 7) in the message will cause the speaker
2934 to emit the standard beep sound, which is useful when prompting
2935 the user to change floppies.
2938 File: grub.info, Node: quit, Next: reboot, Prev: pause, Up: Command-line and menu entry commands
2944 Exit from the grub shell `grub' (*note Invoking the grub shell::).
2945 This command can be used only in the grub shell.
2948 File: grub.info, Node: reboot, Next: read, Prev: quit, Up: Command-line and menu entry commands
2954 Reboot the computer.
2957 File: grub.info, Node: read, Next: root, Prev: reboot, Up: Command-line and menu entry commands
2962 -- Command: read addr
2963 Read a 32-bit value from memory at address ADDR and display it in
2967 File: grub.info, Node: root, Next: rootnoverify, Prev: read, Up: Command-line and menu entry commands
2972 -- Command: root device [hdbias]
2973 Set the current "root device" to the device DEVICE, then attempt
2974 to mount it to get the partition size (for passing the partition
2975 descriptor in `ES:ESI', used by some chain-loaded boot loaders),
2976 the BSD drive-type (for booting BSD kernels using their native
2977 boot format), and correctly determine the PC partition where a BSD
2978 sub-partition is located. The optional HDBIAS parameter is a
2979 number to tell a BSD kernel how many BIOS drive numbers are on
2980 controllers before the current one. For example, if there is an
2981 IDE disk and a SCSI disk, and your FreeBSD root partition is on
2982 the SCSI disk, then use a `1' for HDBIAS.
2984 See also *Note rootnoverify::.
2987 File: grub.info, Node: rootnoverify, Next: savedefault, Prev: root, Up: Command-line and menu entry commands
2989 13.3.32 rootnoverify
2990 --------------------
2992 -- Command: rootnoverify device [hdbias]
2993 Similar to `root' (*note root::), but don't attempt to mount the
2994 partition. This is useful for when an OS is outside of the area of
2995 the disk that GRUB can read, but setting the correct root device
2996 is still desired. Note that the items mentioned in `root' above
2997 which derived from attempting the mount will _not_ work correctly.
3000 File: grub.info, Node: savedefault, Next: setup, Prev: rootnoverify, Up: Command-line and menu entry commands
3005 -- Command: savedefault num
3006 Save the current menu entry or NUM if specified as a default
3007 entry. Here is an example:
3014 kernel /boot/vmlinuz root=/dev/sda1 vga=ext
3023 With this configuration, GRUB will choose the entry booted
3024 previously as the default entry.
3026 You can specify `fallback' instead of a number. Then, next
3027 fallback entry is saved. Next fallback entry is chosen from
3028 fallback entries. Normally, this will be the first entry in
3031 See also *Note default:: and *Note Invoking grub-set-default::.
3034 File: grub.info, Node: setup, Next: testload, Prev: savedefault, Up: Command-line and menu entry commands
3039 -- Command: setup [`--force-lba'] [`--stage2=os_stage2_file']
3040 [`--prefix=dir'] install_device [image_device]
3041 Set up the installation of GRUB automatically. This command uses
3042 the more flexible command `install' (*note install::) in the
3043 backend and installs GRUB into the device INSTALL_DEVICE. If
3044 IMAGE_DEVICE is specified, then find the GRUB images (*note
3045 Images::) in the device IMAGE_DEVICE, otherwise use the current
3046 "root device", which can be set by the command `root'. If
3047 INSTALL_DEVICE is a hard disk, then embed a Stage 1.5 in the disk
3050 The option `--prefix' specifies the directory under which GRUB
3051 images are put. If it is not specified, GRUB automatically
3052 searches them in `/boot/grub' and `/grub'.
3054 The options `--force-lba' and `--stage2' are just passed to
3055 `install' if specified. *Note install::, for more information.
3058 File: grub.info, Node: testload, Next: testvbe, Prev: setup, Up: Command-line and menu entry commands
3063 -- Command: testload file
3064 Read the entire contents of FILE in several different ways and
3065 compare them, to test the filesystem code. The output is somewhat
3066 cryptic, but if no errors are reported and the final `i=X,
3067 filepos=Y' reading has X and Y equal, then it is definitely
3068 consistent, and very likely works correctly subject to a
3069 consistent offset error. If this test succeeds, then a good next
3070 step is to try loading a kernel.
3073 File: grub.info, Node: testvbe, Next: uppermem, Prev: testload, Up: Command-line and menu entry commands
3078 -- Command: testvbe mode
3079 Test the VESA BIOS EXTENSION mode MODE. This command will switch
3080 your video card to the graphics mode, and show an endless
3081 animation. Hit any key to return. See also *Note vbeprobe::.
3084 File: grub.info, Node: uppermem, Next: vbeprobe, Prev: testvbe, Up: Command-line and menu entry commands
3089 -- Command: uppermem kbytes
3090 Force GRUB to assume that only KBYTES kilobytes of upper memory
3091 are installed. Any system address range maps are discarded.
3093 *Caution:* This should be used with great caution, and should only
3094 be necessary on some old machines. GRUB's BIOS probe can pick up
3095 all RAM on all new machines the author has ever heard of. It can
3096 also be used for debugging purposes to lie to an OS.
3099 File: grub.info, Node: vbeprobe, Prev: uppermem, Up: Command-line and menu entry commands
3104 -- Command: vbeprobe [mode]
3105 Probe VESA BIOS EXTENSION information. If the mode MODE is
3106 specified, show only the information about MODE. Otherwise, this
3107 command lists up available VBE modes on the screen. See also *Note
3111 File: grub.info, Node: Troubleshooting, Next: Invoking the grub shell, Prev: Commands, Up: Top
3113 14 Error messages reported by GRUB
3114 **********************************
3116 This chapter describes error messages reported by GRUB when you
3117 encounter trouble. *Note Invoking the grub shell::, if your problem is
3118 specific to the grub shell.
3122 * Stage1 errors:: Errors reported by the Stage 1
3123 * Stage1.5 errors:: Errors reported by the Stage 1.5
3124 * Stage2 errors:: Errors reported by the Stage 2
3127 File: grub.info, Node: Stage1 errors, Next: Stage1.5 errors, Up: Troubleshooting
3129 14.1 Errors reported by the Stage 1
3130 ===================================
3132 The general way that the Stage 1 handles errors is to print an error
3133 string and then halt. Pressing `<CTRL>-<ALT>-<DEL>' will reboot.
3135 The following is a comprehensive list of error messages for the
3139 The stage2 or stage1.5 is being read from a hard disk, and the
3140 attempt to determine the size and geometry of the hard disk failed.
3143 The stage2 or stage1.5 is being read from a floppy disk, and the
3144 attempt to determine the size and geometry of the floppy disk
3145 failed. It's listed as a separate error since the probe sequence
3146 is different than for hard disks.
3149 A disk read error happened while trying to read the stage2 or
3153 The location of the stage2 or stage1.5 is not in the portion of
3154 the disk supported directly by the BIOS read calls. This could
3155 occur because the BIOS translated geometry has been changed by the
3156 user or the disk is moved to another machine or controller after
3157 installation, or GRUB was not installed using itself (if it was,
3158 the Stage 2 version of this error would have been seen during that
3159 process and it would not have completed the install).
3162 File: grub.info, Node: Stage1.5 errors, Next: Stage2 errors, Prev: Stage1 errors, Up: Troubleshooting
3164 14.2 Errors reported by the Stage 1.5
3165 =====================================
3167 The general way that the Stage 1.5 handles errors is to print an error
3168 number in the form `Error NUM' and then halt. Pressing
3169 `<CTRL>-<ALT>-<DEL>' will reboot.
3171 The error numbers correspond to the errors reported by Stage 2.
3172 *Note Stage2 errors::.
3175 File: grub.info, Node: Stage2 errors, Prev: Stage1.5 errors, Up: Troubleshooting
3177 14.3 Errors reported by the Stage 2
3178 ===================================
3180 The general way that the Stage 2 handles errors is to abort the
3181 operation in question, print an error string, then (if possible) either
3182 continue based on the fact that an error occurred or wait for the user
3183 to deal with the error.
3185 The following is a comprehensive list of error messages for the
3186 Stage 2 (error numbers for the Stage 1.5 are listed before the colon in
3189 1 : Filename must be either an absolute filename or blocklist
3190 This error is returned if a file name is requested which doesn't
3191 fit the syntax/rules listed in the *Note Filesystem::.
3193 2 : Bad file or directory type
3194 This error is returned if a file requested is not a regular file,
3195 but something like a symbolic link, directory, or FIFO.
3197 3 : Bad or corrupt data while decompressing file
3198 This error is returned if the run-length decompression code gets an
3199 internal error. This is usually from a corrupt file.
3201 4 : Bad or incompatible header in compressed file
3202 This error is returned if the file header for a supposedly
3203 compressed file is bad.
3205 5 : Partition table invalid or corrupt
3206 This error is returned if the sanity checks on the integrity of the
3207 partition table fail. This is a bad sign.
3209 6 : Mismatched or corrupt version of stage1/stage2
3210 This error is returned if the install command points to
3211 incompatible or corrupt versions of the stage1 or stage2. It can't
3212 detect corruption in general, but this is a sanity check on the
3213 version numbers, which should be correct.
3215 7 : Loading below 1MB is not supported
3216 This error is returned if the lowest address in a kernel is below
3217 the 1MB boundary. The Linux zImage format is a special case and
3218 can be handled since it has a fixed loading address and maximum
3221 8 : Kernel must be loaded before booting
3222 This error is returned if GRUB is told to execute the boot sequence
3223 without having a kernel to start.
3225 9 : Unknown boot failure
3226 This error is returned if the boot attempt did not succeed for
3227 reasons which are unknown.
3229 10 : Unsupported Multiboot features requested
3230 This error is returned when the Multiboot features word in the
3231 Multiboot header requires a feature that is not recognized. The
3232 point of this is that the kernel requires special handling which
3233 GRUB is probably unable to provide.
3235 11 : Unrecognized device string
3236 This error is returned if a device string was expected, and the
3237 string encountered didn't fit the syntax/rules listed in the *Note
3240 12 : Invalid device requested
3241 This error is returned if a device string is recognizable but does
3242 not fall under the other device errors.
3244 13 : Invalid or unsupported executable format
3245 This error is returned if the kernel image being loaded is not
3246 recognized as Multiboot or one of the supported native formats
3247 (Linux zImage or bzImage, FreeBSD, or NetBSD).
3249 14 : Filesystem compatibility error, cannot read whole file
3250 Some of the filesystem reading code in GRUB has limits on the
3251 length of the files it can read. This error is returned when the
3252 user runs into such a limit.
3255 This error is returned if the specified file name cannot be found,
3256 but everything else (like the disk/partition info) is OK.
3258 16 : Inconsistent filesystem structure
3259 This error is returned by the filesystem code to denote an internal
3260 error caused by the sanity checks of the filesystem structure on
3261 disk not matching what it expects. This is usually caused by a
3262 corrupt filesystem or bugs in the code handling it in GRUB.
3264 17 : Cannot mount selected partition
3265 This error is returned if the partition requested exists, but the
3266 filesystem type cannot be recognized by GRUB.
3268 18 : Selected cylinder exceeds maximum supported by BIOS
3269 This error is returned when a read is attempted at a linear block
3270 address beyond the end of the BIOS translated area. This generally
3271 happens if your disk is larger than the BIOS can handle (512MB for
3272 (E)IDE disks on older machines or larger than 8GB in general).
3274 19 : Linux kernel must be loaded before initrd
3275 This error is returned if the initrd command is used before
3276 loading a Linux kernel.
3278 20 : Multiboot kernel must be loaded before modules
3279 This error is returned if the module load command is used before
3280 loading a Multiboot kernel. It only makes sense in this case
3281 anyway, as GRUB has no idea how to communicate the presence of
3282 such modules to a non-Multiboot-aware kernel.
3284 21 : Selected disk does not exist
3285 This error is returned if the device part of a device- or full
3286 file name refers to a disk or BIOS device that is not present or
3287 not recognized by the BIOS in the system.
3289 22 : No such partition
3290 This error is returned if a partition is requested in the device
3291 part of a device- or full file name which isn't on the selected
3294 23 : Error while parsing number
3295 This error is returned if GRUB was expecting to read a number and
3296 encountered bad data.
3298 24 : Attempt to access block outside partition
3299 This error is returned if a linear block address is outside of the
3300 disk partition. This generally happens because of a corrupt
3301 filesystem on the disk or a bug in the code handling it in GRUB
3302 (it's a great debugging tool).
3304 25 : Disk read error
3305 This error is returned if there is a disk read error when trying to
3306 probe or read data from a particular disk.
3308 26 : Too many symbolic links
3309 This error is returned if the link count is beyond the maximum
3310 (currently 5), possibly the symbolic links are looped.
3312 27 : Unrecognized command
3313 This error is returned if an unrecognized command is entered on the
3314 command-line or in a boot sequence section of a configuration file
3315 and that entry is selected.
3317 28 : Selected item cannot fit into memory
3318 This error is returned if a kernel, module, or raw file load
3319 command is either trying to load its data such that it won't fit
3320 into memory or it is simply too big.
3322 29 : Disk write error
3323 This error is returned if there is a disk write error when trying
3324 to write to a particular disk. This would generally only occur
3325 during an install of set active partition command.
3327 30 : Invalid argument
3328 This error is returned if an argument specified to a command is
3331 31 : File is not sector aligned
3332 This error may occur only when you access a ReiserFS partition by
3333 block-lists (e.g. the command `install'). In this case, you should
3334 mount the partition with the `-o notail' option.
3336 32 : Must be authenticated
3337 This error is returned if you try to run a locked entry. You should
3338 enter a correct password before running such an entry.
3340 33 : Serial device not configured
3341 This error is returned if you try to change your terminal to a
3342 serial one before initializing any serial device.
3344 34 : No spare sectors on the disk
3345 This error is returned if a disk doesn't have enough spare space.
3346 This happens when you try to embed Stage 1.5 into the unused
3347 sectors after the MBR, but the first partition starts right after
3348 the MBR or they are used by EZ-BIOS.
3351 File: grub.info, Node: Invoking the grub shell, Next: Invoking grub-install, Prev: Troubleshooting, Up: Top
3353 15 Invoking the grub shell
3354 **************************
3356 This chapter documents the grub shell `grub'. Note that the grub shell
3357 is an emulator; it doesn't run under the native environment, so it
3358 sometimes does something wrong. Therefore, you shouldn't trust it too
3359 much. If there is anything wrong with it, don't hesitate to try the
3360 native GRUB environment, especially when it guesses a wrong map between
3361 BIOS drives and OS devices.
3365 * Basic usage:: How to use the grub shell
3366 * Installation under UNIX:: How to install GRUB via `grub'
3367 * Device map:: The map between BIOS drives and OS devices
3370 File: grub.info, Node: Basic usage, Next: Installation under UNIX, Up: Invoking the grub shell
3372 15.1 Introduction into the grub shell
3373 =====================================
3375 You can use the command `grub' for installing GRUB under your operating
3376 systems and for a testbed when you add a new feature into GRUB or when
3377 fixing a bug. `grub' is almost the same as the Stage 2, and, in fact,
3378 it shares the source code with the Stage 2 and you can use the same
3379 commands (*note Commands::) in `grub'. It is emulated by replacing BIOS
3380 calls with UNIX system calls and libc functions.
3382 The command `grub' accepts the following options:
3385 Print a summary of the command-line options and exit.
3388 Print the version number of GRUB and exit.
3391 Print some verbose messages for debugging purpose.
3394 Use the device map file FILE. The format is described in *Note
3398 Do not probe any floppy drive. This option has no effect if the
3399 option `--device-map' is specified (*note Device map::).
3401 `--probe-second-floppy'
3402 Probe the second floppy drive. If this option is not specified,
3403 the grub shell does not probe it, as that sometimes takes a long
3404 time. If you specify the device map file (*note Device map::), the
3405 grub shell just ignores this option.
3407 `--config-file=FILE'
3408 Read the configuration file FILE instead of `/boot/grub/menu.lst'.
3409 The format is the same as the normal GRUB syntax. See *Note
3410 Filesystem::, for more information.
3412 `--boot-drive=DRIVE'
3413 Set the stage2 BOOT_DRIVE to DRIVE. This argument should be an
3414 integer (decimal, octal or hexadecimal).
3416 `--install-partition=PAR'
3417 Set the stage2 INSTALL_PARTITION to PAR. This argument should be
3418 an integer (decimal, octal or hexadecimal).
3421 Do not use the configuration file even if it can be read.
3424 Do not use the screen handling interface by the curses even if it
3428 This option has the same meaning as `--no-config-file --no-curses'.
3431 Disable writing to any disk.
3434 Wait until a debugger will attach. This option is useful when you
3435 want to debug the startup code.
3438 File: grub.info, Node: Installation under UNIX, Next: Device map, Prev: Basic usage, Up: Invoking the grub shell
3440 15.2 How to install GRUB via `grub'
3441 ===================================
3443 The installation procedure is the same as under the "native" Stage 2.
3444 *Note Installation::, for more information. The command `grub'-specific
3445 information is described here.
3447 What you should be careful about is "buffer cache". `grub' makes use
3448 of raw devices instead of filesystems that your operating systems
3449 serve, so there exists a potential problem that some cache
3450 inconsistency may corrupt your filesystems. What we recommend is:
3452 * If you can unmount drives to which GRUB may write any amount of
3453 data, unmount them before running `grub'.
3455 * If a drive cannot be unmounted but can be mounted with the
3456 read-only flag, mount it in read-only mode. That should be secure.
3458 * If a drive must be mounted with the read-write flag, make sure
3459 that no activity is being done on it while the command `grub' is
3462 * Reboot your operating system as soon as possible. This is probably
3463 not required if you follow the rules above, but reboot is the most
3466 In addition, enter the command `quit' when you finish the
3467 installation. That is _very important_ because `quit' makes the buffer
3468 cache consistent. Do not push <C-c>.
3470 If you want to install GRUB non-interactively, specify `--batch'
3471 option in the command-line. This is a simple example:
3475 # Use /usr/sbin/grub if you are on an older system.
3476 /sbin/grub --batch <<EOT 1>/dev/null 2>/dev/null
3483 File: grub.info, Node: Device map, Prev: Installation under UNIX, Up: Invoking the grub shell
3485 15.3 The map between BIOS drives and OS devices
3486 ===============================================
3488 When you specify the option `--device-map' (*note Basic usage::), the
3489 grub shell creates the "device map file" automatically unless it
3490 already exists. The file name `/boot/grub/device.map' is preferred.
3492 If the device map file exists, the grub shell reads it to map BIOS
3493 drives to OS devices. This file consists of lines like this:
3497 DEVICE is a drive specified in the GRUB syntax (*note Device
3498 syntax::), and FILE is an OS file, which is normally a device file.
3500 The reason why the grub shell gives you the device map file is that
3501 it cannot guess the map between BIOS drives and OS devices correctly in
3502 some environments. For example, if you exchange the boot sequence
3503 between IDE and SCSI in your BIOS, it gets the order wrong.
3505 Thus, edit the file if the grub shell makes a mistake. You can put
3506 any comments in the file if needed, as the grub shell assumes that a
3507 line is just a comment if the first character is `#'.
3510 File: grub.info, Node: Invoking grub-install, Next: Invoking grub-md5-crypt, Prev: Invoking the grub shell, Up: Top
3512 16 Invoking grub-install
3513 ************************
3515 The program `grub-install' installs GRUB on your drive using the grub
3516 shell (*note Invoking the grub shell::). You must specify the device
3517 name on which you want to install GRUB, like this:
3519 grub-install INSTALL_DEVICE
3521 The device name INSTALL_DEVICE is an OS device name or a GRUB device
3524 `grub-install' accepts the following options:
3527 Print a summary of the command-line options and exit.
3530 Print the version number of GRUB and exit.
3533 Force GRUB to use LBA mode even for a buggy BIOS. Use this option
3534 only if your BIOS doesn't work properly in LBA mode even though it
3537 `--root-directory=DIR'
3538 Install GRUB images under the directory DIR instead of the root
3539 directory. This option is useful when you want to install GRUB
3540 into a separate partition or a removable disk. Here is an example
3541 in which you have a separate "boot" partition which is mounted on
3544 grub-install --root-directory=/boot hd0
3547 Use FILE as the grub shell. You can append arbitrary options to
3548 FILE after the file name, like this:
3550 grub-install --grub-shell="grub --read-only" /dev/fd0
3553 Recheck the device map, even if `/boot/grub/device.map' already
3554 exists. You should use this option whenever you add/remove a disk
3555 into/from your computer.
3558 File: grub.info, Node: Invoking grub-md5-crypt, Next: Invoking grub-terminfo, Prev: Invoking grub-install, Up: Top
3560 17 Invoking grub-md5-crypt
3561 **************************
3563 The program `grub-md5-crypt' encrypts a password in MD5 format. This
3564 is just a frontend of the grub shell (*note Invoking the grub shell::).
3565 Passwords encrypted by this program can be used with the command
3566 `password' (*note password::).
3568 `grub-md5-crypt' accepts the following options:
3571 Print a summary of the command-line options and exit.
3574 Print the version information and exit.
3577 Use FILE as the grub shell.
3580 File: grub.info, Node: Invoking grub-terminfo, Next: Invoking grub-set-default, Prev: Invoking grub-md5-crypt, Up: Top
3582 18 Invoking grub-terminfo
3583 *************************
3585 The program `grub-terminfo' generates a terminfo command from a
3586 terminfo name (*note terminfo::). The result can be used in the
3587 configuration file, to define escape sequences. Because GRUB assumes
3588 that your terminal is vt100-compatible by default, this would be useful
3589 only if your terminal is uncommon (such as vt52).
3591 `grub-terminfo' accepts the following options:
3594 Print a summary of the command-line options and exit.
3597 Print the version information and exit.
3599 You must specify one argument to this command. For example:
3604 File: grub.info, Node: Invoking grub-set-default, Next: Invoking mbchk, Prev: Invoking grub-terminfo, Up: Top
3606 19 Invoking grub-set-default
3607 ****************************
3609 The program `grub-set-default' sets the default boot entry for GRUB.
3610 This automatically creates a file named `default' under your GRUB
3611 directory (i.e. `/boot/grub'), if it is not present. This file is used
3612 to determine the default boot entry when GRUB boots up your system when
3613 you use `default saved' in your configuration file (*note default::),
3614 and to save next default boot entry when you use `savedefault' in a
3615 boot entry (*note savedefault::).
3617 `grub-set-default' accepts the following options:
3620 Print a summary of the command-line options and exit.
3623 Print the version information and exit.
3625 `--root-directory=DIR'
3626 Use the directory DIR instead of the root directory (i.e. `/') to
3627 define the location of the default file. This is useful when you
3628 mount a disk which is used for another system.
3630 You must specify a single argument to `grub-set-default'. This
3631 argument is normally the number of a default boot entry. For example,
3632 if you have this configuration file:
3645 and if you want to set the next default boot entry to GNU/Linux, you
3646 may execute this command:
3650 Because the entry for GNU/Linux is `1'. Note that entries are
3651 counted from zero. So, if you want to specify GNU/Hurd here, then you
3654 This feature is very useful if you want to test a new kernel or to
3655 make your system quite robust. *Note Making your system robust::, for
3656 more hints about how to set up a robust system.
3659 File: grub.info, Node: Invoking mbchk, Next: Obtaining and Building GRUB, Prev: Invoking grub-set-default, Up: Top
3664 The program `mbchk' checks for the format of a Multiboot kernel. We
3665 recommend using this program before booting your own kernel by GRUB.
3667 `mbchk' accepts the following options:
3670 Print a summary of the command-line options and exit.
3673 Print the version number of GRUB and exit.
3676 Suppress all normal output.
3679 File: grub.info, Node: Obtaining and Building GRUB, Next: Reporting bugs, Prev: Invoking mbchk, Up: Top
3681 Appendix A How to obtain and build GRUB
3682 ***************************************
3684 *Caution:* GRUB requires binutils-2.9.1.0.23 or later because the
3685 GNU assembler has been changed so that it can produce real 16bits
3686 machine code between 2.9.1 and 2.9.1.0.x. See
3687 `http://sources.redhat.com/binutils/', to obtain information on
3688 how to get the latest version.
3690 GRUB is available from the GNU alpha archive site
3691 `ftp://alpha.gnu.org/gnu/grub' or any of its mirrors. The file will be
3692 named grub-version.tar.gz. The current version is 0.97, so the file you
3695 `ftp://alpha.gnu.org/gnu/grub/grub-0.97.tar.gz'
3697 To unbundle GRUB use the instruction:
3699 zcat grub-0.97.tar.gz | tar xvf -
3701 which will create a directory called `grub-0.97' with all the
3702 sources. You can look at the file `INSTALL' for detailed instructions
3703 on how to build and install GRUB, but you should be able to just do:
3709 This will install the grub shell `grub' (*note Invoking the grub
3710 shell::), the Multiboot checker `mbchk' (*note Invoking mbchk::), and
3711 the GRUB images. This will also install the GRUB manual.
3713 Also, the latest version is available from the CVS. See
3714 `http://savannah.gnu.org/cvs/?group=grub' for more information.
3717 File: grub.info, Node: Reporting bugs, Next: Future, Prev: Obtaining and Building GRUB, Up: Top
3719 Appendix B Reporting bugs
3720 *************************
3722 These are the guideline for how to report bugs. Take a look at this
3723 list below before you submit bugs:
3725 1. Before getting unsettled, read this manual through and through.
3726 Also, see the GNU GRUB FAQ
3727 (http://www.gnu.org/software/grub/grub-faq.html).
3729 2. Always mention the information on your GRUB. The version number
3730 and the configuration are quite important. If you build it
3731 yourself, write the options specified to the configure script and
3732 your operating system, including the versions of gcc and binutils.
3734 3. If you have trouble with the installation, inform us of how you
3735 installed GRUB. Don't omit error messages, if any. Just `GRUB hangs
3736 up when it boots' is not enough.
3738 The information on your hardware is also essential. These are
3739 especially important: the geometries and the partition tables of
3740 your hard disk drives and your BIOS.
3742 4. If GRUB cannot boot your operating system, write down _everything_
3743 you see on the screen. Don't paraphrase them, like `The foo OS
3744 crashes with GRUB, even though it can boot with the bar boot
3745 loader just fine'. Mention the commands you executed, the messages
3746 printed by them, and information on your operating system
3747 including the version number.
3749 5. Explain what you wanted to do. It is very useful to know your
3750 purpose and your wish, and how GRUB didn't satisfy you.
3752 6. If you can investigate the problem yourself, please do. That will
3753 give you and us much more information on the problem. Attaching a
3754 patch is even better.
3756 When you attach a patch, make the patch in unified diff format, and
3757 write ChangeLog entries. But, even when you make a patch, don't
3758 forget to explain the problem, so that we can understand what your
3761 7. Write down anything that you think might be related. Please
3762 understand that we often need to reproduce the same problem you
3763 encounterred in our environment. So your information should be
3764 sufficient for us to do the same thing--Don't forget that we
3765 cannot see your computer directly. If you are not sure whether to
3766 state a fact or leave it out, state it! Reporting too many things
3767 is much better than omitting something important.
3769 If you follow the guideline above, submit a report to the Bug
3770 Tracking System (http://savannah.gnu.org/bugs/?group=grub).
3771 Alternatively, you can submit a report via electronic mail to
3772 <bug-grub@gnu.org>, but we strongly recommend that you use the Bug
3773 Tracking System, because e-mail can be passed over easily.
3775 Once we get your report, we will try to fix the bugs.
3778 File: grub.info, Node: Future, Next: Internals, Prev: Reporting bugs, Up: Top
3780 Appendix C Where GRUB will go
3781 *****************************
3783 We started the next generation of GRUB, GRUB 2. This will include
3784 internationalization, dynamic module loading, real memory management,
3785 multiple architecture support, a scripting language, and many other
3786 nice feature. If you are interested in the development of GRUB 2, take
3787 a look at the homepage (http://www.gnu.org/software/grub/grub.html).
3790 File: grub.info, Node: Internals, Next: Index, Prev: Future, Up: Top
3792 Appendix D Hacking GRUB
3793 ***********************
3795 This chapter documents the user-invisible aspect of GRUB.
3797 As a general rule of software development, it is impossible to keep
3798 the descriptions of the internals up-to-date, and it is quite hard to
3799 document everything. So refer to the source code, whenever you are not
3800 satisfied with this documentation. Please assume that this gives just
3805 * Memory map:: The memory map of various components
3806 * Embedded data:: Embedded variables in GRUB
3807 * Filesystem interface:: The generic interface for filesystems
3808 * Command interface:: The generic interface for built-ins
3809 * Bootstrap tricks:: The bootstrap mechanism used in GRUB
3810 * I/O ports detection:: How to probe I/O ports used by INT 13H
3811 * Memory detection:: How to detect all installed RAM
3812 * Low-level disk I/O:: INT 13H disk I/O interrupts
3813 * MBR:: The structure of Master Boot Record
3814 * Partition table:: The format of partition tables
3815 * Submitting patches:: Where and how you should send patches
3818 File: grub.info, Node: Memory map, Next: Embedded data, Up: Internals
3820 D.1 The memory map of various components
3821 ========================================
3823 GRUB consists of two distinct components, called "stages", which are
3824 loaded at different times in the boot process. Because they run
3825 mutual-exclusively, sometimes a memory area overlaps with another
3826 memory area. And, even in one stage, a single memory area can be used
3827 for various purposes, because their usages are mutually exclusive.
3829 Here is the memory map of the various components:
3832 BIOS and real mode interrupts
3835 Partition table passed to another boot loader
3841 The optional Stage 1.5 is loaded here
3844 Command-line buffer for Multiboot kernels and modules
3847 Stage 1 is loaded here by BIOS or another boot loader
3850 LBA drive parameters
3853 Stage2 is loaded here
3855 The end of Stage 2 to 416K-1
3856 Heap, in particular used for the menu
3859 Protected mode stack
3868 512-byte scratch area
3871 Buffers for various functions, such as password, command-line, cut
3872 and paste, and completion.
3874 The last 1K of lower memory
3875 Disk swapping code and data
3877 See the file `stage2/shared.h', for more information.
3880 File: grub.info, Node: Embedded data, Next: Filesystem interface, Prev: Memory map, Up: Internals
3882 D.2 Embedded variables in GRUB
3883 ==============================
3885 Stage 1 and Stage 2 have embedded variables whose locations are
3886 well-defined, so that the installation can patch the binary file
3887 directly without recompilation of the stages.
3889 In Stage 1, these are defined:
3892 The version number (not GRUB's, but the installation mechanism's).
3895 The boot drive. If it is 0xFF, use a drive passed by BIOS.
3898 The flag for if forcing LBA.
3901 The starting address of Stage 2.
3904 The first sector of Stage 2.
3907 The starting segment of Stage 2.
3910 The signature (`0xAA55').
3912 See the file `stage1/stage1.S', for more information.
3914 In the first sector of Stage 1.5 and Stage 2, the block lists are
3915 recorded between `firstlist' and `lastlist'. The address of `lastlist'
3916 is determined when assembling the file `stage2/start.S'.
3918 The trick here is that it is actually read backward, and the first
3919 8-byte block list is not read here, but after the pointer is decremented
3920 8 bytes, then after reading it, it decrements again, reads, and so on,
3921 until it is finished. The terminating condition is when the number of
3922 sectors to be read in the next block list is zero.
3924 The format of a block list can be seen from the example in the code
3925 just before the `firstlist' label. Note that it is always from the
3926 beginning of the disk, but _not_ relative to the partition boundaries.
3928 In the second sector of Stage 1.5 and Stage 2, these are defined:
3931 The version number (likewise, the installation mechanism's).
3934 The installed partition.
3937 The saved entry number.
3943 The flag for if forcing LBA.
3946 The version string (GRUB's).
3948 `0x12' + "the length of the version string"
3949 The name of a configuration file.
3951 See the file `stage2/asm.S', for more information.
3954 File: grub.info, Node: Filesystem interface, Next: Command interface, Prev: Embedded data, Up: Internals
3956 D.3 The generic interface for filesystems
3957 =========================================
3959 For any particular partition, it is presumed that only one of the
3960 "normal" filesystems such as FAT, FFS, or ext2fs can be used, so there
3961 is a switch table managed by the functions in `disk_io.c'. The notation
3962 is that you can only "mount" one at a time.
3964 The block list filesystem has a special place in the system. In
3965 addition to the "normal" filesystem (or even without one mounted), you
3966 can access disk blocks directly (in the indicated partition) via the
3967 block list notation. Using the block list filesystem doesn't effect any
3968 other filesystem mounts.
3970 The variables which can be read by the filesystem backend are:
3973 The current BIOS drive number (numbered from 0, if a floppy, and
3974 numbered from 0x80, if a hard disk).
3977 The current partition number.
3980 The current partition type.
3983 The "drive" part of the root device.
3986 The "partition" part of the root device.
3989 The current partition starting address, in sectors.
3992 The current partition length, in sectors.
3994 `print_possibilities'
3995 True when the `dir' function should print the possible completions
3996 of a file, and false when it should try to actually open a file of
4000 Filesystem buffer which is 32K in size, to use in any way which the
4001 filesystem backend desires.
4003 The variables which need to be written by a filesystem backend are:
4006 The current position in the file, in sectors.
4008 *Caution:* the value of FILEPOS can be changed out from under the
4009 filesystem code in the current implementation. Don't depend on it
4010 being the same for later calls into the backend code!
4013 The length of the file.
4016 The value of DISK_READ_HOOK _only_ during reading of data for the
4017 file, not any other fs data, inodes, FAT tables, whatever, then
4018 set to `NULL' at all other times (it will be `NULL' by default).
4019 If this isn't done correctly, then the `testload' and `install'
4020 commands won't work correctly.
4022 The functions expected to be used by the filesystem backend are:
4025 Only read sectors from within a partition. Sector 0 is the first
4026 sector in the partition.
4029 If the backend uses the block list code, then `grub_read' can be
4030 used, after setting BLOCK_FILE to 1.
4032 `print_a_completion'
4033 If PRINT_POSSIBILITIES is true, call `print_a_completion' for each
4034 possible file name. Otherwise, the file name completion won't work.
4036 The functions expected to be defined by the filesystem backend are
4037 described at least moderately in the file `filesys.h'. Their usage is
4038 fairly evident from their use in the functions in `disk_io.c', look for
4039 the use of the FSYS_TABLE array.
4041 *Caution:* The semantics are such that then `mount'ing the
4042 filesystem, presume the filesystem buffer `FSYS_BUF' is corrupted, and
4043 (re-)load all important contents. When opening and reading a file,
4044 presume that the data from the `mount' is available, and doesn't get
4045 corrupted by the open/read (i.e. multiple opens and/or reads will be
4046 done with only one mount if in the same filesystem).
4049 File: grub.info, Node: Command interface, Next: Bootstrap tricks, Prev: Filesystem interface, Up: Internals
4051 D.4 The generic interface for built-ins
4052 =======================================
4054 GRUB built-in commands are defined in a uniformal interface, whether
4055 they are menu-specific or can be used anywhere. The definition of a
4056 builtin command consists of two parts: the code itself and the table of
4059 The code must be a function which takes two arguments, a command-line
4060 string and flags, and returns an `int' value. The "flags" argument
4061 specifies how the function is called, using a bit mask. The return
4062 value must be zero if successful, otherwise non-zero. So it is normally
4063 enough to return ERRNUM.
4065 The table of the information is represented by the structure `struct
4066 builtin', which contains the name of the command, a pointer to the
4067 function, flags, a short description of the command and a long
4068 description of the command. Since the descriptions are used only for
4069 help messages interactively, you don't have to define them, if the
4070 command may not be called interactively (such as `title').
4072 The table is finally registered in the table BUILTIN_TABLE, so that
4073 `run_script' and `enter_cmdline' can find the command. See the files
4074 `cmdline.c' and `builtins.c', for more details.
4077 File: grub.info, Node: Bootstrap tricks, Next: I/O ports detection, Prev: Command interface, Up: Internals
4079 D.5 The bootstrap mechanism used in GRUB
4080 ========================================
4082 The disk space can be used in a boot loader is very restricted because
4083 a MBR (*note MBR::) is only 512 bytes but it also contains a partition
4084 table (*note Partition table::) and a BPB. So the question is how to
4085 make a boot loader code enough small to be fit in a MBR.
4087 However, GRUB is a very large program, so we break GRUB into 2 (or 3)
4088 distinct components, "Stage 1" and "Stage 2" (and optionally "Stage
4089 1.5"). *Note Memory map::, for more information.
4091 We embed Stage 1 in a MBR or in the boot sector of a partition, and
4092 place Stage 2 in a filesystem. The optional Stage 1.5 can be installed
4093 in a filesystem, in the "boot loader" area in a FFS or a ReiserFS, and
4094 in the sectors right after a MBR, because Stage 1.5 is enough small and
4095 the sectors right after a MBR is normally an unused region. The size of
4096 this region is the number of sectors per head minus 1.
4098 Thus, all Stage1 must do is just load Stage2 or Stage1.5. But even if
4099 Stage 1 needs not to support the user interface or the filesystem
4100 interface, it is impossible to make Stage 1 less than 400 bytes, because
4101 GRUB should support both the CHS mode and the LBA mode (*note Low-level
4104 The solution used by GRUB is that Stage 1 loads only the first
4105 sector of Stage 2 (or Stage 1.5) and Stage 2 itself loads the rest. The
4108 1. Initialize the system briefly.
4110 2. Detect the geometry and the accessing mode of the "loading drive".
4112 3. Load the first sector of Stage 2.
4114 4. Jump to the starting address of the Stage 2.
4116 The flow of Stage 2 (and Stage 1.5) is:
4118 1. Load the rest of itself to the real starting address, that is, the
4119 starting address plus 512 bytes. The block lists are stored in the
4120 last part of the first sector.
4122 2. Long jump to the real starting address.
4124 Note that Stage 2 (or Stage 1.5) does not probe the geometry or the
4125 accessing mode of the "loading drive", since Stage 1 has already probed
4129 File: grub.info, Node: I/O ports detection, Next: Memory detection, Prev: Bootstrap tricks, Up: Internals
4131 D.6 How to probe I/O ports used by INT 13H
4132 ==========================================
4134 FIXME: I will write this chapter after implementing the new technique.
4137 File: grub.info, Node: Memory detection, Next: Low-level disk I/O, Prev: I/O ports detection, Up: Internals
4139 D.7 How to detect all installed RAM
4140 ===================================
4142 FIXME: I doubt if Erich didn't write this chapter only himself wholly,
4143 so I will rewrite this chapter.
4146 File: grub.info, Node: Low-level disk I/O, Next: MBR, Prev: Memory detection, Up: Internals
4148 D.8 INT 13H disk I/O interrupts
4149 ===============================
4151 FIXME: I'm not sure where some part of the original chapter is derived,
4152 so I will rewrite this chapter.
4155 File: grub.info, Node: MBR, Next: Partition table, Prev: Low-level disk I/O, Up: Internals
4157 D.9 The structure of Master Boot Record
4158 =======================================
4163 File: grub.info, Node: Partition table, Next: Submitting patches, Prev: MBR, Up: Internals
4165 D.10 The format of partition tables
4166 ===================================
4168 FIXME: Probably the original chapter is derived from "How It Works", so
4169 I will rewrite this chapter.
4172 File: grub.info, Node: Submitting patches, Prev: Partition table, Up: Internals
4174 D.11 Where and how you should send patches
4175 ==========================================
4177 When you write patches for GRUB, please send them to the mailing list
4178 <bug-grub@gnu.org>. Here is the list of items of which you should take
4181 * Please make your patch as small as possible. Generally, it is not
4182 a good thing to make one big patch which changes many things.
4183 Instead, segregate features and produce many patches.
4185 * Use as late code as possible, for the original code. The CVS
4186 repository always has the current version (*note Obtaining and
4189 * Write ChangeLog entries. *Note Change Logs: (standards)Change
4190 Logs, if you don't know how to write ChangeLog.
4192 * Make patches in unified diff format. `diff -urN' is appropriate in
4195 * Don't make patches reversely. Reverse patches are difficult to
4198 * Be careful enough of the license term and the copyright. Because
4199 GRUB is under GNU General Public License, you may not steal code
4200 from software whose license is incompatible against GPL. And, if
4201 you copy code written by others, you must not ignore their
4202 copyrights. Feel free to ask GRUB maintainers, whenever you are
4203 not sure what you should do.
4205 * If your patch is too large to send in e-mail, put it at somewhere
4206 we can see. Usually, you shouldn't send e-mail over 20K.
4209 File: grub.info, Node: Index, Prev: Internals, Up: Top
4217 * blocklist: blocklist. (line 7)
4218 * boot: boot. (line 7)
4219 * bootp: bootp. (line 7)
4220 * cat: cat. (line 7)
4221 * chainloader: chainloader. (line 7)
4222 * cmp: cmp. (line 7)
4223 * color: color. (line 7)
4224 * configfile: configfile. (line 7)
4225 * current_drive: Filesystem interface. (line 19)
4226 * current_partition: Filesystem interface. (line 23)
4227 * current_slice: Filesystem interface. (line 26)
4228 * debug: debug. (line 7)
4229 * default: default. (line 7)
4230 * device: device. (line 7)
4231 * devread: Filesystem interface. (line 71)
4232 * dhcp: dhcp. (line 7)
4233 * disk_read_func: Filesystem interface. (line 62)
4234 * displayapm: displayapm. (line 7)
4235 * displaymem: displaymem. (line 7)
4236 * embed: embed. (line 7)
4237 * fallback: fallback. (line 7)
4238 * filemax: Filesystem interface. (line 59)
4239 * filepos: Filesystem interface. (line 52)
4240 * find: find. (line 7)
4241 * fstest: fstest. (line 7)
4242 * FSYS_BUF: Filesystem interface. (line 46)
4243 * geometry: geometry. (line 7)
4244 * grub_read: Filesystem interface. (line 75)
4245 * halt: halt. (line 7)
4246 * help: help. (line 7)
4247 * hiddenmenu: hiddenmenu. (line 7)
4248 * hide: hide. (line 7)
4249 * ifconfig: ifconfig. (line 8)
4250 * impsprobe: impsprobe. (line 7)
4251 * initrd: initrd. (line 7)
4252 * install: install. (line 9)
4253 * ioprobe: ioprobe. (line 7)
4254 * kernel: kernel. (line 7)
4255 * lock: lock. (line 7)
4256 * makeactive: makeactive. (line 7)
4257 * map: map. (line 7)
4258 * md5crypt: md5crypt. (line 7)
4259 * module: module. (line 7)
4260 * modulenounzip: modulenounzip. (line 7)
4261 * pager: pager. (line 7)
4262 * part_length: Filesystem interface. (line 38)
4263 * part_start: Filesystem interface. (line 35)
4264 * partnew: partnew. (line 7)
4265 * parttype: parttype. (line 7)
4266 * password: password. (line 7)
4267 * pause: pause. (line 7)
4268 * print_a_completion: Filesystem interface. (line 79)
4269 * print_possibilities: Filesystem interface. (line 41)
4270 * quit: quit. (line 7)
4271 * rarp: rarp. (line 7)
4272 * read: read. (line 7)
4273 * reboot: reboot. (line 7)
4274 * root: root. (line 7)
4275 * rootnoverify: rootnoverify. (line 7)
4276 * saved_drive: Filesystem interface. (line 29)
4277 * saved_partition: Filesystem interface. (line 32)
4278 * savedefault: savedefault. (line 7)
4279 * serial: serial. (line 9)
4280 * setkey: setkey. (line 7)
4281 * setup: setup. (line 8)
4282 * terminal: terminal. (line 9)
4283 * terminfo: terminfo. (line 9)
4284 * testload: testload. (line 7)
4285 * testvbe: testvbe. (line 7)
4286 * tftpserver: tftpserver. (line 7)
4287 * timeout: timeout. (line 7)
4288 * title: title. (line 7)
4289 * unhide: unhide. (line 7)
4290 * uppermem: uppermem. (line 7)
4291 * vbeprobe: vbeprobe. (line 7)
4297 Node: Introduction
\x7f3266
4298 Node: Overview
\x7f3643
4299 Node: Overview-Footnotes
\x7f5865
4300 Ref: Overview-Footnote-1
\x7f5926
4301 Node: History
\x7f6087
4302 Node: Features
\x7f7208
4303 Node: Features-Footnotes
\x7f12976
4304 Ref: Features-Footnote-1
\x7f13037
4305 Node: Role of a boot loader
\x7f13182
4306 Node: Role of a boot loader-Footnotes
\x7f14520
4307 Ref: Role of a boot loader-Footnote-1
\x7f14607
4308 Node: Naming convention
\x7f14686
4309 Node: Installation
\x7f17621
4310 Node: Creating a GRUB boot floppy
\x7f19363
4311 Node: Installing GRUB natively
\x7f20181
4312 Node: Installing GRUB natively-Footnotes
\x7f22461
4313 Ref: Installing GRUB natively-Footnote-1
\x7f22554
4314 Node: Installing GRUB using grub-install
\x7f22739
4315 Node: Making a GRUB bootable CD-ROM
\x7f25685
4316 Node: Making a GRUB bootable CD-ROM-Footnotes
\x7f27730
4317 Ref: Making a GRUB bootable CD-ROM-Footnote-1
\x7f27833
4318 Node: Booting
\x7f27908
4319 Node: General boot methods
\x7f28363
4320 Node: Loading an operating system directly
\x7f29104
4321 Node: Chain-loading
\x7f30408
4322 Node: Chain-loading-Footnotes
\x7f31718
4323 Ref: Chain-loading-Footnote-1
\x7f31789
4324 Node: OS-specific notes
\x7f31861
4325 Node: GNU/Hurd
\x7f32237
4326 Node: GNU/Linux
\x7f32856
4327 Node: FreeBSD
\x7f34104
4328 Node: NetBSD
\x7f34617
4329 Node: OpenBSD
\x7f35275
4330 Node: DOS/Windows
\x7f35475
4331 Node: SCO UnixWare
\x7f37301
4333 Node: Making your system robust
\x7f37969
4334 Node: Booting once-only
\x7f39294
4335 Node: Booting fallback systems
\x7f41219
4336 Node: Configuration
\x7f44066
4337 Node: Network
\x7f48495
4338 Node: General usage of network support
\x7f48989
4339 Node: General usage of network support-Footnotes
\x7f50850
4340 Ref: General usage of network support-Footnote-1
\x7f50959
4341 Node: Diskless
\x7f51027
4342 Node: Serial terminal
\x7f53211
4343 Node: Preset Menu
\x7f55444
4344 Node: Security
\x7f57812
4345 Node: Images
\x7f60620
4346 Node: Filesystem
\x7f63131
4347 Node: Device syntax
\x7f63814
4348 Node: File name syntax
\x7f65308
4349 Node: Block list syntax
\x7f66051
4350 Node: Interface
\x7f66784
4351 Node: Command-line interface
\x7f67661
4352 Node: Command-line interface-Footnotes
\x7f69602
4353 Ref: Command-line interface-Footnote-1
\x7f69691
4354 Node: Menu interface
\x7f69786
4355 Node: Menu entry editor
\x7f70796
4356 Node: Hidden menu interface
\x7f71875
4357 Node: Commands
\x7f72452
4358 Node: Menu-specific commands
\x7f73029
4359 Node: default
\x7f74200
4360 Node: fallback
\x7f74678
4361 Node: hiddenmenu
\x7f75229
4362 Node: timeout
\x7f75717
4363 Node: title
\x7f75995
4364 Node: General commands
\x7f76266
4365 Node: bootp
\x7f77579
4366 Node: color
\x7f78058
4367 Node: device
\x7f79532
4370 Node: ifconfig
\x7f81066
4371 Node: pager
\x7f81642
4372 Node: partnew
\x7f81976
4373 Node: parttype
\x7f82412
4374 Node: password
\x7f82779
4376 Node: serial
\x7f83899
4377 Node: setkey
\x7f85172
4378 Node: terminal
\x7f87341
4379 Node: terminfo
\x7f88878
4380 Node: tftpserver
\x7f89565
4381 Node: unhide
\x7f90111
4382 Node: Command-line and menu entry commands
\x7f90486
4383 Node: blocklist
\x7f93017
4386 Node: chainloader
\x7f93884
4388 Node: configfile
\x7f95051
4389 Node: debug
\x7f95265
4390 Node: displayapm
\x7f95649
4391 Node: displaymem
\x7f95860
4392 Node: embed
\x7f96562
4393 Node: embed-Footnotes
\x7f97096
4394 Ref: embed-Footnote-1
\x7f97151
4396 Node: fstest
\x7f97588
4397 Node: geometry
\x7f98273
4400 Node: impsprobe
\x7f99833
4401 Node: initrd
\x7f100232
4402 Node: install
\x7f100571
4403 Node: install-Footnotes
\x7f103415
4404 Ref: install-Footnote-1
\x7f103474
4405 Node: ioprobe
\x7f103571
4406 Node: kernel
\x7f103896
4407 Node: lock
\x7f105016
4408 Node: makeactive
\x7f105591
4410 Node: md5crypt
\x7f106470
4411 Node: module
\x7f106817
4412 Node: modulenounzip
\x7f107394
4413 Node: pause
\x7f107687
4414 Node: quit
\x7f108101
4415 Node: reboot
\x7f108377
4416 Node: read
\x7f108558
4417 Node: root
\x7f108800
4418 Node: rootnoverify
\x7f109677
4419 Node: savedefault
\x7f110232
4420 Node: setup
\x7f111208
4421 Node: testload
\x7f112274
4422 Node: testvbe
\x7f112884
4423 Node: uppermem
\x7f113255
4424 Node: vbeprobe
\x7f113837
4425 Node: Troubleshooting
\x7f114220
4426 Node: Stage1 errors
\x7f114758
4427 Node: Stage1.5 errors
\x7f116135
4428 Node: Stage2 errors
\x7f116573
4429 Node: Invoking the grub shell
\x7f124033
4430 Node: Basic usage
\x7f124786
4431 Node: Installation under UNIX
\x7f127073
4432 Node: Device map
\x7f128748
4433 Node: Invoking grub-install
\x7f129896
4434 Node: Invoking grub-md5-crypt
\x7f131484
4435 Node: Invoking grub-terminfo
\x7f132133
4436 Node: Invoking grub-set-default
\x7f132899
4437 Node: Invoking mbchk
\x7f134700
4438 Node: Obtaining and Building GRUB
\x7f135214
4439 Node: Reporting bugs
\x7f136631
4440 Node: Future
\x7f139435
4441 Node: Internals
\x7f139926
4442 Node: Memory map
\x7f141149
4443 Node: Embedded data
\x7f142627
4444 Node: Filesystem interface
\x7f144644
4445 Node: Command interface
\x7f148077
4446 Node: Bootstrap tricks
\x7f149392
4447 Node: I/O ports detection
\x7f151541
4448 Node: Memory detection
\x7f151813
4449 Node: Low-level disk I/O
\x7f152105
4451 Node: Partition table
\x7f152571
4452 Node: Submitting patches
\x7f152844
4453 Node: Index
\x7f154332