1 This is grub.info, produced by makeinfo version 4.0 from grub.texi.
3 INFO-DIR-SECTION Kernel
5 * GRUB: (grub). The GRand Unified Bootloader
6 * grub-install: (grub)Invoking grub-install. Install GRUB on your drive
7 * grub-md5-crypt: (grub)Invoking grub-md5-crypt. Encrypt a password
9 * grub-terminfo: (grub)Invoking grub-terminfo. Generate a terminfo
12 * grub-set-default: (grub)Invoking grub-set-default. Set a default boot
14 * mbchk: (grub)Invoking mbchk. Check for the format of a Multiboot kernel
17 Copyright (C) 1999,2000,2001,2002,2004 Free Software Foundation, Inc.
19 Permission is granted to make and distribute verbatim copies of this
20 manual provided the copyright notice and this permission notice are
21 preserved on all copies.
23 Permission is granted to copy and distribute modified versions of
24 this manual under the conditions for verbatim copying, provided also
25 that the entire resulting derived work is distributed under the terms
26 of a permission notice identical to this one.
28 Permission is granted to copy and distribute translations of this
29 manual into another language, under the above conditions for modified
33 File: grub.info, Node: Top, Next: Introduction, Up: (dir)
38 This is the documentation of GNU GRUB, the GRand Unified Bootloader,
39 a flexible and powerful boot loader program for PCs.
41 This edition documents version 0.95.
45 * Introduction:: Capturing the spirit of GRUB
46 * Naming convention:: Names of your drives in GRUB
47 * Installation:: Installing GRUB on your drive
48 * Booting:: How to boot different operating systems
49 * Configuration:: Writing your own configuration file
50 * Network:: Downloading OS images from a network
51 * Serial terminal:: Using GRUB via a serial line
52 * Preset Menu:: Embedding a configuration file into GRUB
53 * Security:: Improving the security
54 * Images:: GRUB image files
55 * Filesystem:: Filesystem syntax and semantics
56 * Interface:: The menu and the command-line
57 * Commands:: The list of available builtin commands
58 * Troubleshooting:: Error messages produced by GRUB
59 * Invoking the grub shell:: How to use the grub shell
60 * Invoking grub-install:: How to use the GRUB installer
61 * Invoking grub-md5-crypt:: How to generate a cryptic password
62 * Invoking grub-terminfo:: How to generate a terminfo command
63 * Invoking grub-set-default:: How to set a default boot entry
64 * Invoking mbchk:: How to use the Multiboot checker
65 * Obtaining and Building GRUB:: How to obtain and build GRUB
66 * Reporting bugs:: Where you should send a bug report
67 * Future:: Some future plans on GRUB
68 * Internals:: Hacking GRUB
72 File: grub.info, Node: Introduction, Next: Naming convention, Prev: Top, Up: Top
79 * Overview:: What exactly GRUB is and how to use it
80 * History:: From maggot to house fly
81 * Features:: GRUB features
82 * Role of a boot loader:: The role of a boot loader
85 File: grub.info, Node: Overview, Next: History, Up: Introduction
90 Briefly, a "boot loader" is the first software program that runs when
91 a computer starts. It is responsible for loading and transferring
92 control to an operating system "kernel" software (such as Linux or GNU
93 Mach). The kernel, in turn, initializes the rest of the operating
94 system (e.g. a GNU system).
96 GNU GRUB is a very powerful boot loader, which can load a wide
97 variety of free operating systems, as well as proprietary operating
98 systems with chain-loading(1) (*note Overview-Footnote-1::). GRUB is
99 designed to address the complexity of booting a personal computer; both
100 the program and this manual are tightly bound to that computer platform,
101 although porting to other platforms may be addressed in the future.
103 One of the important features in GRUB is flexibility; GRUB
104 understands filesystems and kernel executable formats, so you can load
105 an arbitrary operating system the way you like, without recording the
106 physical position of your kernel on the disk. Thus you can load the
107 kernel just by specifying its file name and the drive and partition
108 where the kernel resides.
110 When booting with GRUB, you can use either a command-line interface
111 (*note Command-line interface::), or a menu interface (*note Menu
112 interface::). Using the command-line interface, you type the drive
113 specification and file name of the kernel manually. In the menu
114 interface, you just select an OS using the arrow keys. The menu is
115 based on a configuration file which you prepare beforehand (*note
116 Configuration::). While in the menu, you can switch to the command-line
117 mode, and vice-versa. You can even edit menu entries before using them.
119 In the following chapters, you will learn how to specify a drive, a
120 partition, and a file name (*note Naming convention::) to GRUB, how to
121 install GRUB on your drive (*note Installation::), and how to boot your
122 OSes (*note Booting::), step by step.
124 Besides the GRUB boot loader itself, there is a "grub shell" `grub'
125 (*note Invoking the grub shell::) which can be run when you are in your
126 operating system. It emulates the boot loader and can be used for
127 installing the boot loader.
130 File: grub.info, Node: Overview-Footnotes, Up: Overview
132 (1) "chain-load" is the mechanism for loading unsupported operating
133 systems by loading another boot loader. It is typically used for
134 loading DOS or Windows.
137 File: grub.info, Node: History, Next: Features, Prev: Overview, Up: Introduction
142 GRUB originated in 1995 when Erich Boleyn was trying to boot the GNU
143 Hurd with the University of Utah's Mach 4 microkernel (now known as GNU
144 Mach). Erich and Brian Ford designed the Multiboot Specification
145 (*note Multiboot Specification: (multiboot)Top.), because they were
146 determined not to add to the large number of mutually-incompatible PC
149 Erich then began modifying the FreeBSD boot loader so that it would
150 understand Multiboot. He soon realized that it would be a lot easier to
151 write his own boot loader from scratch than to keep working on the
152 FreeBSD boot loader, and so GRUB was born.
154 Erich added many features to GRUB, but other priorities prevented him
155 from keeping up with the demands of its quickly-expanding user base. In
156 1999, Gordon Matzigkeit and Yoshinori K. Okuji adopted GRUB as an
157 official GNU package, and opened its development by making the latest
158 sources available via anonymous CVS. *Note Obtaining and Building
159 GRUB::, for more information.
162 File: grub.info, Node: Features, Next: Role of a boot loader, Prev: History, Up: Introduction
167 The primary requirement for GRUB is that it be compliant with the
168 "Multiboot Specification", which is described in *Note Multiboot
169 Specification: (multiboot)Top.
171 The other goals, listed in approximate order of importance, are:
173 * Basic functions must be straightforward for end-users.
175 * Rich functionality to support kernel experts and designers.
177 * Backward compatibility for booting FreeBSD, NetBSD, OpenBSD, and
178 Linux. Proprietary kernels (such as DOS, Windows NT, and OS/2) are
179 supported via a chain-loading function.
181 Except for specific compatibility modes (chain-loading and the Linux
182 "piggyback" format), all kernels will be started in much the same state
183 as in the Multiboot Specification. Only kernels loaded at 1 megabyte or
184 above are presently supported. Any attempt to load below that boundary
185 will simply result in immediate failure and an error message reporting
188 In addition to the requirements above, GRUB has the following
189 features (note that the Multiboot Specification doesn't require all the
190 features that GRUB supports):
192 Recognize multiple executable formats
193 Support many of the "a.out" variants plus "ELF". Symbol tables are
196 Support non-Multiboot kernels
197 Support many of the various free 32-bit kernels that lack Multiboot
198 compliance (primarily FreeBSD, NetBSD, OpenBSD, and Linux).
199 Chain-loading of other boot loaders is also supported.
201 Load multiples modules
202 Fully support the Multiboot feature of loading multiple modules.
204 Load a configuration file
205 Support a human-readable text configuration file with preset boot
206 commands. You can also load another configuration file dynamically
207 and embed a preset configuration file in a GRUB image file. The
208 list of commands (*note Commands::) are a superset of those
209 supported on the command-line. An example configuration file is
210 provided in *Note Configuration::.
212 Provide a menu interface
213 A menu interface listing preset boot commands, with a programmable
214 timeout, is available. There is no fixed limit on the number of
215 boot entries, and the current implementation has space for several
218 Have a flexible command-line interface
219 A fairly flexible command-line interface, accessible from the menu,
220 is available to edit any preset commands, or write a new boot
221 command set from scratch. If no configuration file is present,
222 GRUB drops to the command-line.
224 The list of commands (*note Commands::) are a subset of those
225 supported for configuration files. Editing commands closely
226 resembles the Bash command-line (*note Bash: (features)Command
227 Line Editing.), with <TAB>-completion of commands, devices,
228 partitions, and files in a directory depending on context.
230 Support multiple filesystem types
231 Support multiple filesystem types transparently, plus a useful
232 explicit blocklist notation. The currently supported filesystem
233 types are "BSD FFS", "DOS FAT16 and FAT32", "Minix fs", "Linux
234 ext2fs", "ReiserFS", "JFS", "XFS", and "VSTa fs". *Note
235 Filesystem::, for more information.
237 Support automatic decompression
238 Can decompress files which were compressed by `gzip'. This
239 function is both automatic and transparent to the user (i.e. all
240 functions operate upon the uncompressed contents of the specified
241 files). This greatly reduces a file size and loading time, a
242 particularly great benefit for floppies.(1) (*note
243 Features-Footnote-1::)
245 It is conceivable that some kernel modules should be loaded in a
246 compressed state, so a different module-loading command can be
247 specified to avoid uncompressing the modules.
249 Access data on any installed device
250 Support reading data from any or all floppies or hard disk(s)
251 recognized by the BIOS, independent of the setting of the root
254 Be independent of drive geometry translations
255 Unlike many other boot loaders, GRUB makes the particular drive
256 translation irrelevant. A drive installed and running with one
257 translation may be converted to another translation without any
258 adverse effects or changes in GRUB's configuration.
260 Detect all installed RAM
261 GRUB can generally find all the installed RAM on a PC-compatible
262 machine. It uses an advanced BIOS query technique for finding all
263 memory regions. As described on the Multiboot Specification (*note
264 Multiboot Specification: (multiboot)Top.), not all kernels make
265 use of this information, but GRUB provides it for those who do.
267 Support Logical Block Address mode
268 In traditional disk calls (called "CHS mode"), there is a geometry
269 translation problem, that is, the BIOS cannot access over 1024
270 cylinders, so the accessible space is limited to at least 508 MB
271 and to at most 8GB. GRUB can't universally solve this problem, as
272 there is no standard interface used in all machines. However,
273 several newer machines have the new interface, Logical Block
274 Address ("LBA") mode. GRUB automatically detects if LBA mode is
275 available and uses it if available. In LBA mode, GRUB can access
278 Support network booting
279 GRUB is basically a disk-based boot loader but also has network
280 support. You can load OS images from a network by using the "TFTP"
283 Support remote terminals
284 To support computers with no console, GRUB provides remote terminal
285 support, so that you can control GRUB from a remote host. Only
286 serial terminal support is implemented at the moment.
289 File: grub.info, Node: Features-Footnotes, Up: Features
291 (1) There are a few pathological cases where loading a very badly
292 organized ELF kernel might take longer, but in practice this never
296 File: grub.info, Node: Role of a boot loader, Prev: Features, Up: Introduction
298 The role of a boot loader
299 =========================
301 The following is a quotation from Gordon Matzigkeit, a GRUB fanatic:
303 Some people like to acknowledge both the operating system and
304 kernel when they talk about their computers, so they might say
305 they use "GNU/Linux" or "GNU/Hurd". Other people seem to think
306 that the kernel is the most important part of the system, so they
307 like to call their GNU operating systems "Linux systems."
309 I, personally, believe that this is a grave injustice, because the
310 _boot loader_ is the most important software of all. I used to
311 refer to the above systems as either "LILO"(1) (*note Role of a
312 boot loader-Footnote-1::) or "GRUB" systems.
314 Unfortunately, nobody ever understood what I was talking about;
315 now I just use the word "GNU" as a pseudonym for GRUB.
317 So, if you ever hear people talking about their alleged "GNU"
318 systems, remember that they are actually paying homage to the best
319 boot loader around... GRUB!
321 We, the GRUB maintainers, do not (usually) encourage Gordon's level
322 of fanaticism, but it helps to remember that boot loaders deserve
323 recognition. We hope that you enjoy using GNU GRUB as much as we did
327 File: grub.info, Node: Role of a boot loader-Footnotes, Up: Role of a boot loader
329 (1) The LInux LOader, a boot loader that everybody uses, but nobody
333 File: grub.info, Node: Naming convention, Next: Installation, Prev: Introduction, Up: Top
338 The device syntax used in GRUB is a wee bit different from what you
339 may have seen before in your operating system(s), and you need to know
340 it so that you can specify a drive/partition.
342 Look at the following examples and explanations:
346 First of all, GRUB requires that the device name be enclosed with
347 `(' and `)'. The `fd' part means that it is a floppy disk. The number
348 `0' is the drive number, which is counted from _zero_. This expression
349 means that GRUB will use the whole floppy disk.
353 Here, `hd' means it is a hard disk drive. The first integer `0'
354 indicates the drive number, that is, the first hard disk, while the
355 second integer, `1', indicates the partition number (or the PC slice
356 number in the BSD terminology). Once again, please note that the
357 partition numbers are counted from _zero_, not from one. This
358 expression means the second partition of the first hard disk drive. In
359 this case, GRUB uses one partition of the disk, instead of the whole
364 This specifies the first "extended partition" of the first hard disk
365 drive. Note that the partition numbers for extended partitions are
366 counted from `4', regardless of the actual number of primary partitions
371 This means the BSD `a' partition of the second hard disk. If you
372 need to specify which PC slice number should be used, use something
373 like this: `(hd1,0,a)'. If the PC slice number is omitted, GRUB
374 searches for the first PC slice which has a BSD `a' partition.
376 Of course, to actually access the disks or partitions with GRUB, you
377 need to use the device specification in a command, like `root (fd0)' or
378 `unhide (hd0,2)'. To help you find out which number specifies a
379 partition you want, the GRUB command-line (*note Command-line
380 interface::) options have argument completion. This means that, for
381 example, you only need to type
385 followed by a <TAB>, and GRUB will display the list of drives,
386 partitions, or file names. So it should be quite easy to determine the
387 name of your target partition, even with minimal knowledge of the
390 Note that GRUB does _not_ distinguish IDE from SCSI - it simply
391 counts the drive numbers from zero, regardless of their type. Normally,
392 any IDE drive number is less than any SCSI drive number, although that
393 is not true if you change the boot sequence by swapping IDE and SCSI
396 Now the question is, how to specify a file? Again, consider an
401 This specifies the file named `vmlinuz', found on the first
402 partition of the first hard disk drive. Note that the argument
403 completion works with file names, too.
405 That was easy, admit it. Now read the next chapter, to find out how
406 to actually install GRUB on your drive.
409 File: grub.info, Node: Installation, Next: Booting, Prev: Naming convention, Up: Top
414 In order to install GRUB as your boot loader, you need to first
415 install the GRUB system and utilities under your UNIX-like operating
416 system (*note Obtaining and Building GRUB::). You can do this either
417 from the source tarball, or as a package for your OS.
419 After you have done that, you need to install the boot loader on a
420 drive (floppy or hard disk). There are two ways of doing that - either
421 using the utility `grub-install' (*note Invoking grub-install::) on a
422 UNIX-like OS, or by running GRUB itself from a floppy. These are quite
423 similar, however the utility might probe a wrong BIOS drive, so you
426 Also, if you install GRUB on a UNIX-like OS, please make sure that
427 you have an emergency boot disk ready, so that you can rescue your
428 computer if, by any chance, your hard drive becomes unusable
431 GRUB comes with boot images, which are normally put in the directory
432 `/usr/lib/grub/i386-pc'. If you do not use grub-install, then you need
433 to copy the files `stage1', `stage2', and `*stage1_5' to the directory
434 `/boot/grub', and run the `grub-set-default' (*note Invoking
435 grub-set-default::) if you intend to use `default saved' (*note
436 default::) in your configuration file. Hereafter, the directory where
437 GRUB images are initially placed (normally `/usr/lib/grub/i386-pc')
438 will be called the "image directory", and the directory where the boot
439 loader needs to find them (usually `/boot/grub') will be called the
444 * Creating a GRUB boot floppy::
445 * Installing GRUB natively::
446 * Installing GRUB using grub-install::
447 * Making a GRUB bootable CD-ROM::
450 File: grub.info, Node: Creating a GRUB boot floppy, Next: Installing GRUB natively, Up: Installation
452 Creating a GRUB boot floppy
453 ===========================
455 To create a GRUB boot floppy, you need to take the files `stage1'
456 and `stage2' from the image directory, and write them to the first and
457 the second block of the floppy disk, respectively.
459 *Caution:* This procedure will destroy any data currently stored on
462 On a UNIX-like operating system, that is done with the following
465 # cd /usr/lib/grub/i386-pc
466 # dd if=stage1 of=/dev/fd0 bs=512 count=1
469 # dd if=stage2 of=/dev/fd0 bs=512 seek=1
474 The device file name may be different. Consult the manual for your
478 File: grub.info, Node: Installing GRUB natively, Next: Installing GRUB using grub-install, Prev: Creating a GRUB boot floppy, Up: Installation
480 Installing GRUB natively
481 ========================
483 *Caution:* Installing GRUB's stage1 in this manner will erase the
484 normal boot-sector used by an OS.
486 GRUB can currently boot GNU Mach, Linux, FreeBSD, NetBSD, and OpenBSD
487 directly, so using it on a boot sector (the first sector of a
488 partition) should be okay. But generally, it would be a good idea to
489 back up the first sector of the partition on which you are installing
490 GRUB's stage1. This isn't as important if you are installing GRUB on
491 the first sector of a hard disk, since it's easy to reinitialize it
492 (e.g. by running `FDISK /MBR' from DOS).
494 If you decide to install GRUB in the native environment, which is
495 definitely desirable, you'll need to create a GRUB boot disk, and
496 reboot your computer with it. Otherwise, see *Note Installing GRUB
497 using grub-install::.
499 Once started, GRUB will show the command-line interface (*note
500 Command-line interface::). First, set the GRUB's "root device"(1)
501 (*note Installing GRUB natively-Footnote-1::) to the partition
502 containing the boot directory, like this:
506 If you are not sure which partition actually holds this directory,
507 use the command `find' (*note find::), like this:
509 grub> find /boot/grub/stage1
511 This will search for the file name `/boot/grub/stage1' and show the
512 devices which contain the file.
514 Once you've set the root device correctly, run the command `setup'
519 This command will install the GRUB boot loader on the Master Boot
520 Record (MBR) of the first drive. If you want to put GRUB into the boot
521 sector of a partition instead of putting it in the MBR, specify the
522 partition into which you want to install GRUB:
526 If you install GRUB into a partition or a drive other than the first
527 one, you must chain-load GRUB from another boot loader. Refer to the
528 manual for the boot loader to know how to chain-load GRUB.
530 After using the setup command, you will boot into GRUB without the
531 GRUB floppy. See the chapter *Note Booting:: to find out how to boot
532 your operating systems from GRUB.
535 File: grub.info, Node: Installing GRUB natively-Footnotes, Up: Installing GRUB natively
537 (1) Note that GRUB's root device doesn't necessarily mean your OS's
538 root partition; if you need to specify a root partition for your OS,
539 add the argument into the command `kernel'.
542 File: grub.info, Node: Installing GRUB using grub-install, Next: Making a GRUB bootable CD-ROM, Prev: Installing GRUB natively, Up: Installation
544 Installing GRUB using grub-install
545 ==================================
547 *Caution:* This procedure is definitely less safe, because there are
548 several ways in which your computer can become unbootable. For example,
549 most operating systems don't tell GRUB how to map BIOS drives to OS
550 devices correctly--GRUB merely "guesses" the mapping. This will succeed
551 in most cases, but not always. Therefore, GRUB provides you with a map
552 file called the "device map", which you must fix if it is wrong. *Note
553 Device map::, for more details.
555 If you still do want to install GRUB under a UNIX-like OS (such as
556 GNU), invoke the program `grub-install' (*note Invoking grub-install::)
557 as the superuser ("root").
559 The usage is basically very simple. You only need to specify one
560 argument to the program, namely, where to install the boot loader. The
561 argument can be either a device file (like `/dev/hda') or a partition
562 specified in GRUB's notation. For example, under Linux the following
563 will install GRUB into the MBR of the first IDE disk:
565 # grub-install /dev/hda
567 Likewise, under GNU/Hurd, this has the same effect:
569 # grub-install /dev/hd0
571 If it is the first BIOS drive, this is the same as well:
573 # grub-install '(hd0)'
575 Or you can omit the parentheses:
579 But all the above examples assume that GRUB should use images under
580 the root directory. If you want GRUB to use images under a directory
581 other than the root directory, you need to specify the option
582 `--root-directory'. The typical usage is that you create a GRUB boot
583 floppy with a filesystem. Here is an example:
586 # mount -t ext2 /dev/fd0 /mnt
587 # grub-install --root-directory=/mnt fd0
590 Another example is when you have a separate boot partition which is
591 mounted at `/boot'. Since GRUB is a boot loader, it doesn't know
592 anything about mountpoints at all. Thus, you need to run `grub-install'
595 # grub-install --root-directory=/boot /dev/hda
597 By the way, as noted above, it is quite difficult to guess BIOS
598 drives correctly under a UNIX-like OS. Thus, `grub-install' will prompt
599 you to check if it could really guess the correct mappings, after the
600 installation. The format is defined in *Note Device map::. Please be
601 quite careful. If the output is wrong, it is unlikely that your
602 computer will be able to boot with no problem.
604 Note that `grub-install' is actually just a shell script and the
605 real task is done by the grub shell `grub' (*note Invoking the grub
606 shell::). Therefore, you may run `grub' directly to install GRUB,
607 without using `grub-install'. Don't do that, however, unless you are
608 very familiar with the internals of GRUB. Installing a boot loader on a
609 running OS may be extremely dangerous.
612 File: grub.info, Node: Making a GRUB bootable CD-ROM, Prev: Installing GRUB using grub-install, Up: Installation
614 Making a GRUB bootable CD-ROM
615 =============================
617 GRUB supports the "no emulation mode" in the El Torito
618 specification(1) (*note Making a GRUB bootable CD-ROM-Footnote-1::).
619 This means that you can use the whole CD-ROM from GRUB and you don't
620 have to make a floppy or hard disk image file, which can cause
621 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
675 for 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 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 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 Load another boot loader to boot unsupported operating systems
739 --------------------------------------------------------------
741 If you want to boot an unsupported operating system (e.g. Windows
742 95), chain-load a boot loader for the operating system. Normally, the
743 boot loader is embedded in the "boot sector" of the partition on which
744 the 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 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
803 is nothing special about it. But do not forget that you have to specify
804 a 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
824 somewhat 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,
973 grub> rootnoverify (hd1,1)
978 File: grub.info, Node: Making your system robust, Prev: OS-specific notes, Up: Booting
980 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
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 Booting fallback systems
1069 ------------------------
1071 GRUB supports a fallback mechanism of booting one or more other
1072 entries if a default boot entry fails. You can specify multiple
1073 fallback 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
1146 boot your OS. There's a solution to that - GRUB provides a menu
1147 interface (*note Menu interface::) from which you can select an item
1148 (using arrow 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 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 How to set up your network
1291 ==========================
1293 GRUB requires a file server and optionally a server that will assign
1294 an IP address to the machine on which GRUB is running. For the former,
1295 only TFTP is supported at the moment. The latter is either BOOTP, DHCP
1296 or a RARP server(1) (*note General usage of network
1297 support-Footnote-1::). It is not necessary to run both the servers on
1298 one computer. How to configure these servers is beyond the scope of this
1299 document, so please refer to the manuals specific to those
1302 If you decided to use a server to assign an IP address, set up the
1303 server and run `bootp' (*note bootp::), `dhcp' (*note dhcp::) or `rarp'
1304 (*note rarp::) for BOOTP, DHCP or RARP, respectively. Each command will
1305 show an assigned IP address, a netmask, an IP address for your TFTP
1306 server and a gateway. If any of the addresses is wrong or it causes an
1307 error, probably the configuration of your servers isn't set up properly.
1309 Otherwise, run `ifconfig', like this:
1311 grub> ifconfig --address=192.168.110.23 --server=192.168.110.14
1313 You can also use `ifconfig' in conjuction with `bootp', `dhcp' or
1314 `rarp' (e.g. to reassign the server address manually). *Note
1315 ifconfig::, for more details.
1317 Finally, download your OS images from your network. The network can
1318 be accessed using the network drive `(nd)'. Everything else is very
1319 similar to the normal instructions (*note Booting::).
1326 Address: 192.168.110.23 Netmask: 255.255.255.0
1327 Server: 192.168.110.14 Gateway: 192.168.110.1
1330 grub> kernel /tftproot/gnumach.gz root=sd0s1
1331 grub> module /tftproot/serverboot.gz
1335 File: grub.info, Node: General usage of network support-Footnotes, Up: General usage of network support
1337 (1) RARP is not advised, since it cannot serve much information