xref: /titanic_51/usr/src/grub/grub-0.97/docs/grub.texi (revision c3a9724da5c6e77268b3f725df640f2848b1ebf8)
1\input texinfo
2@c -*-texinfo-*-
3@c %**start of header
4@setfilename grub.info
5@settitle GRUB Manual
6@c %**end of header
7
8@include version.texi
9
10@c Unify all our little indices for now.
11@syncodeindex fn cp
12@syncodeindex vr cp
13@syncodeindex ky cp
14@syncodeindex pg cp
15@syncodeindex tp cp
16
17@footnotestyle separate
18@paragraphindent 3
19@finalout
20
21@dircategory Kernel
22@direntry
23* GRUB: (grub).                 The GRand Unified Bootloader
24* grub-install: (grub)Invoking grub-install.    Install GRUB on your drive
25* grub-md5-crypt: (grub)Invoking grub-md5-crypt.        Encrypt a password
26                                                        in MD5 format
27* grub-terminfo: (grub)Invoking grub-terminfo.  Generate a terminfo
28                                                command from a
29                                                terminfo name
30* grub-set-default: (grub)Invoking grub-set-default.    Set a default boot
31                                                        entry
32* mbchk: (grub)Invoking mbchk.  Check for the format of a Multiboot kernel
33@end direntry
34
35@setchapternewpage odd
36
37@ifinfo
38Copyright @copyright{} 1999,2000,2001,2002,2004 Free Software Foundation, Inc.
39
40Permission is granted to make and distribute verbatim copies of
41this manual provided the copyright notice and this permission notice
42are preserved on all copies.
43
44@ignore
45Permission is granted to process this file through TeX and print the
46results, provided the printed document carries a copying permission
47notice identical to this one except for the removal of this paragraph
48(this paragraph not being relevant to the printed manual).
49
50@end ignore
51
52Permission is granted to copy and distribute modified versions of this
53manual under the conditions for verbatim copying, provided also that
54the entire resulting derived work is distributed under the terms of a
55permission notice identical to this one.
56
57Permission is granted to copy and distribute translations of this manual
58into another language, under the above conditions for modified versions.
59@end ifinfo
60
61@titlepage
62@sp 10
63@title the GRUB manual
64@subtitle The GRand Unified Bootloader, version @value{VERSION}, @value{UPDATED}.
65@author Gordon Matzigkeit
66@author Yoshinori K. Okuji
67@c The following two commands start the copyright page.
68@page
69@vskip 0pt plus 1filll
70Copyright @copyright{} 1999,2000,2001,2002,2004 Free Software Foundation, Inc.
71
72Permission is granted to make and distribute verbatim copies of
73this manual provided the copyright notice and this permission notice
74are preserved on all copies.
75Permission is granted to copy and distribute modified versions of this
76manual under the conditions for verbatim copying, provided that the entire
77resulting derived work is distributed under the terms of a permission
78notice identical to this one.
79
80Permission is granted to copy and distribute translations of this manual
81into another language, under the above conditions for modified versions,
82except that this permission notice may be stated in a translation approved
83by Free Software Foundation.
84@end titlepage
85
86@c Output the table of contents at the beginning.
87@contents
88
89@finalout
90@headings double
91
92@ifnottex
93@node Top
94@top GRUB manual
95
96This is the documentation of GNU GRUB, the GRand Unified Bootloader,
97a flexible and powerful boot loader program for @sc{pc}s.
98
99This edition documents version @value{VERSION}.
100@end ifnottex
101
102@menu
103* Introduction::                Capturing the spirit of GRUB
104* Naming convention::           Names of your drives in GRUB
105* Installation::                Installing GRUB on your drive
106* Booting::                     How to boot different operating systems
107* Configuration::               Writing your own configuration file
108* Network::                     Downloading OS images from a network
109* Serial terminal::             Using GRUB via a serial line
110* Preset Menu::                 Embedding a configuration file into GRUB
111* Security::                    Improving the security
112* Images::                      GRUB image files
113* Filesystem::                  Filesystem syntax and semantics
114* Interface::                   The menu and the command-line
115* Commands::                    The list of available builtin commands
116* Troubleshooting::             Error messages produced by GRUB
117* Invoking the grub shell::     How to use the grub shell
118* Invoking grub-install::       How to use the GRUB installer
119* Invoking grub-md5-crypt::     How to generate a cryptic password
120* Invoking grub-terminfo::      How to generate a terminfo command
121* Invoking grub-set-default::   How to set a default boot entry
122* Invoking mbchk::              How to use the Multiboot checker
123* Obtaining and Building GRUB:: How to obtain and build GRUB
124* Reporting bugs::              Where you should send a bug report
125* Future::                      Some future plans on GRUB
126* Internals::                   Hacking GRUB
127* Index::
128@end menu
129
130
131@node Introduction
132@chapter Introduction to GRUB
133
134@menu
135* Overview::                    What exactly GRUB is and how to use it
136* History::                     From maggot to house fly
137* Features::                    GRUB features
138* Role of a boot loader::       The role of a boot loader
139@end menu
140
141
142@node Overview
143@section Overview
144
145Briefly, a @dfn{boot loader} is the first software program that runs when
146a computer starts.  It is responsible for loading and transferring
147control to an operating system @dfn{kernel} software (such as Linux or
148GNU Mach).  The kernel, in turn, initializes the rest of the operating
149system (e.g. a GNU system).
150
151GNU GRUB is a very powerful boot loader, which can load a wide variety
152of free operating systems, as well as proprietary operating systems with
153chain-loading@footnote{@dfn{chain-load} is the mechanism for loading
154unsupported operating systems by loading another boot loader. It is
155typically used for loading DOS or Windows.}. GRUB is designed to
156address the complexity of booting a personal computer; both the
157program and this manual are tightly bound to that computer platform,
158although porting to other platforms may be addressed in the future.
159
160One of the important features in GRUB is flexibility; GRUB understands
161filesystems and kernel executable formats, so you can load an arbitrary
162operating system the way you like, without recording the physical
163position of your kernel on the disk. Thus you can load the kernel
164just by specifying its file name and the drive and partition where the
165kernel resides.
166
167When booting with GRUB, you can use either a command-line interface
168(@pxref{Command-line interface}), or a menu interface (@pxref{Menu
169interface}). Using the command-line interface, you type the drive
170specification and file name of the kernel manually. In the menu
171interface, you just select an OS using the arrow keys. The menu is
172based on a configuration file which you prepare beforehand
173(@pxref{Configuration}). While in the menu, you can switch to the
174command-line mode, and vice-versa. You can even edit menu entries
175before using them.
176
177In the following chapters, you will learn how to specify a drive, a
178partition, and a file name (@pxref{Naming convention}) to GRUB, how to
179install GRUB on your drive (@pxref{Installation}), and how to boot your
180OSes (@pxref{Booting}), step by step.
181
182Besides the GRUB boot loader itself, there is a @dfn{grub shell}
183@command{grub} (@pxref{Invoking the grub shell}) which can be run when
184you are in your operating system. It emulates the boot loader and can
185be used for installing the boot loader.
186
187
188@node History
189@section History of GRUB
190
191GRUB originated in 1995 when Erich Boleyn was trying to boot the GNU
192Hurd with the University of Utah's Mach 4 microkernel (now known as GNU
193Mach).  Erich and Brian Ford designed the Multiboot Specification
194(@pxref{Top, Multiboot Specification, Motivation, multiboot, The Multiboot
195Specification}), because they were determined not to add to the large
196number of mutually-incompatible PC boot methods.
197
198Erich then began modifying the FreeBSD boot loader so that it would
199understand Multiboot. He soon realized that it would be a lot easier
200to write his own boot loader from scratch than to keep working on the
201FreeBSD boot loader, and so GRUB was born.
202
203Erich added many features to GRUB, but other priorities prevented him
204from keeping up with the demands of its quickly-expanding user base. In
2051999, Gordon Matzigkeit and Yoshinori K. Okuji adopted GRUB as an
206official GNU package, and opened its development by making the latest
207sources available via anonymous CVS. @xref{Obtaining and Building
208GRUB}, for more information.
209
210
211@node Features
212@section GRUB features
213
214The primary requirement for GRUB is that it be compliant with the
215@dfn{Multiboot Specification}, which is described in @ref{Top, Multiboot
216Specification, Motivation, multiboot, The Multiboot Specification}.
217
218The other goals, listed in approximate order of importance, are:
219
220@itemize @bullet{}
221@item
222Basic functions must be straightforward for end-users.
223
224@item
225Rich functionality to support kernel experts and designers.
226
227@item
228Backward compatibility for booting FreeBSD, NetBSD, OpenBSD, and
229Linux. Proprietary kernels (such as DOS, Windows NT, and OS/2) are
230supported via a chain-loading function.
231@end itemize
232
233Except for specific compatibility modes (chain-loading and the Linux
234@dfn{piggyback} format), all kernels will be started in much the same
235state as in the Multiboot Specification. Only kernels loaded at 1 megabyte
236or above are presently supported. Any attempt to load below that
237boundary will simply result in immediate failure and an error message
238reporting the problem.
239
240In addition to the requirements above, GRUB has the following features
241(note that the Multiboot Specification doesn't require all the features
242that GRUB supports):
243
244@table @asis
245@item Recognize multiple executable formats
246Support many of the @dfn{a.out} variants plus @dfn{ELF}. Symbol
247tables are also loaded.
248
249@item Support non-Multiboot kernels
250Support many of the various free 32-bit kernels that lack Multiboot
251compliance (primarily FreeBSD, NetBSD, OpenBSD, and
252Linux). Chain-loading of other boot loaders is also supported.
253
254@item Load multiples modules
255Fully support the Multiboot feature of loading multiple modules.
256
257@item Load a configuration file
258Support a human-readable text configuration file with preset boot
259commands. You can also load another configuration file dynamically and
260embed a preset configuration file in a GRUB image file. The list of
261commands (@pxref{Commands}) are a superset of those supported on the
262command-line. An example configuration file is provided in
263@ref{Configuration}.
264
265@item Provide a menu interface
266A menu interface listing preset boot commands, with a programmable
267timeout, is available. There is no fixed limit on the number of boot
268entries, and the current implementation has space for several hundred.
269
270@item Have a flexible command-line interface
271A fairly flexible command-line interface, accessible from the menu,
272is available to edit any preset commands, or write a new boot command
273set from scratch. If no configuration file is present, GRUB drops to
274the command-line.
275
276The list of commands (@pxref{Commands}) are a subset of those supported
277for configuration files. Editing commands closely resembles the Bash
278command-line (@pxref{Command Line Editing, Bash, Command Line Editing,
279features, Bash Features}), with @key{TAB}-completion of commands,
280devices, partitions, and files in a directory depending on context.
281
282@item Support multiple filesystem types
283Support multiple filesystem types transparently, plus a useful explicit
284blocklist notation. The currently supported filesystem types are
285@dfn{BSD FFS}, @dfn{DOS FAT16 and FAT32}, @dfn{Minix fs}, @dfn{Linux
286ext2fs}, @dfn{ReiserFS}, @dfn{JFS}, @dfn{XFS}, and @dfn{VSTa
287fs}. @xref{Filesystem}, for more information.
288
289@item Support automatic decompression
290Can decompress files which were compressed by @command{gzip}. This
291function is both automatic and transparent to the user (i.e. all
292functions operate upon the uncompressed contents of the specified
293files). This greatly reduces a file size and loading time, a
294particularly great benefit for floppies.@footnote{There are a few
295pathological cases where loading a very badly organized ELF kernel might
296take longer, but in practice this never happen.}
297
298It is conceivable that some kernel modules should be loaded in a
299compressed state, so a different module-loading command can be specified
300to avoid uncompressing the modules.
301
302@item Access data on any installed device
303Support reading data from any or all floppies or hard disk(s) recognized
304by the BIOS, independent of the setting of the root device.
305
306@item Be independent of drive geometry translations
307Unlike many other boot loaders, GRUB makes the particular drive
308translation irrelevant. A drive installed and running with one
309translation may be converted to another translation without any adverse
310effects or changes in GRUB's configuration.
311
312@item Detect all installed @sc{ram}
313GRUB can generally find all the installed @sc{ram} on a PC-compatible
314machine. It uses an advanced BIOS query technique for finding all
315memory regions. As described on the Multiboot Specification (@pxref{Top,
316Multiboot Specification, Motivation, multiboot, The Multiboot
317Specification}), not all kernels make use of this information, but GRUB
318provides it for those who do.
319
320@item Support Logical Block Address mode
321In traditional disk calls (called @dfn{CHS mode}), there is a geometry
322translation problem, that is, the BIOS cannot access over 1024
323cylinders, so the accessible space is limited to at least 508 MB and to
324at most 8GB. GRUB can't universally solve this problem, as there is no
325standard interface used in all machines. However, several newer machines
326have the new interface, Logical Block Address (@dfn{LBA}) mode. GRUB
327automatically detects if LBA mode is available and uses it if
328available. In LBA mode, GRUB can access the entire disk.
329
330@item Support network booting
331GRUB is basically a disk-based boot loader but also has network
332support. You can load OS images from a network by using the @dfn{TFTP}
333protocol.
334
335@item Support remote terminals
336To support computers with no console, GRUB provides remote terminal
337support, so that you can control GRUB from a remote host. Only serial
338terminal support is implemented at the moment.
339@end table
340
341
342@node Role of a boot loader
343@section The role of a boot loader
344
345The following is a quotation from Gordon Matzigkeit, a GRUB fanatic:
346
347@quotation
348Some people like to acknowledge both the operating system and kernel when
349they talk about their computers, so they might say they use
350``GNU/Linux'' or ``GNU/Hurd''.  Other people seem to think that the
351kernel is the most important part of the system, so they like to call
352their GNU operating systems ``Linux systems.''
353
354I, personally, believe that this is a grave injustice, because the
355@emph{boot loader} is the most important software of all. I used to
356refer to the above systems as either ``LILO''@footnote{The LInux LOader,
357a boot loader that everybody uses, but nobody likes.} or ``GRUB''
358systems.
359
360Unfortunately, nobody ever understood what I was talking about; now I
361just use the word ``GNU'' as a pseudonym for GRUB.
362
363So, if you ever hear people talking about their alleged ``GNU'' systems,
364remember that they are actually paying homage to the best boot loader
365around@dots{} GRUB!
366@end quotation
367
368We, the GRUB maintainers, do not (usually) encourage Gordon's level of
369fanaticism, but it helps to remember that boot loaders deserve
370recognition.  We hope that you enjoy using GNU GRUB as much as we did
371writing it.
372
373
374@node Naming convention
375@chapter Naming convention
376
377The device syntax used in GRUB is a wee bit different from what you may
378have seen before in your operating system(s), and you need to know it so
379that you can specify a drive/partition.
380
381Look at the following examples and explanations:
382
383@example
384(fd0)
385@end example
386
387First of all, GRUB requires that the device name be enclosed with
388@samp{(} and @samp{)}. The @samp{fd} part means that it is a floppy
389disk. The number @samp{0} is the drive number, which is counted from
390@emph{zero}. This expression means that GRUB will use the whole floppy
391disk.
392
393@example
394(hd0,1)
395@end example
396
397Here, @samp{hd} means it is a hard disk drive. The first integer
398@samp{0} indicates the drive number, that is, the first hard disk, while
399the second integer, @samp{1}, indicates the partition number (or the
400@sc{pc} slice number in the BSD terminology). Once again, please note
401that the partition numbers are counted from @emph{zero}, not from
402one. This expression means the second partition of the first hard disk
403drive. In this case, GRUB uses one partition of the disk, instead of the
404whole disk.
405
406@example
407(hd0,4)
408@end example
409
410This specifies the first @dfn{extended partition} of the first hard disk
411drive. Note that the partition numbers for extended partitions are
412counted from @samp{4}, regardless of the actual number of primary
413partitions on your hard disk.
414
415@example
416(hd1,a)
417@end example
418
419This means the BSD @samp{a} partition of the second hard disk. If you
420need to specify which @sc{pc} slice number should be used, use something
421like this: @samp{(hd1,0,a)}. If the @sc{pc} slice number is omitted,
422GRUB searches for the first @sc{pc} slice which has a BSD @samp{a}
423partition.
424
425Of course, to actually access the disks or partitions with GRUB, you
426need to use the device specification in a command, like @samp{root
427(fd0)} or @samp{unhide (hd0,2)}. To help you find out which number
428specifies a partition you want, the GRUB command-line
429(@pxref{Command-line interface}) options have argument
430completion. This means that, for example, you only need to type
431
432@example
433root (
434@end example
435
436followed by a @key{TAB}, and GRUB will display the list of drives,
437partitions, or file names. So it should be quite easy to determine the
438name of your target partition, even with minimal knowledge of the
439syntax.
440
441Note that GRUB does @emph{not} distinguish IDE from SCSI - it simply
442counts the drive numbers from zero, regardless of their type. Normally,
443any IDE drive number is less than any SCSI drive number, although that
444is not true if you change the boot sequence by swapping IDE and SCSI
445drives in your BIOS.
446
447Now the question is, how to specify a file? Again, consider an
448example:
449
450@example
451(hd0,0)/vmlinuz
452@end example
453
454This specifies the file named @samp{vmlinuz}, found on the first
455partition of the first hard disk drive. Note that the argument
456completion works with file names, too.
457
458That was easy, admit it. Now read the next chapter, to find out how to
459actually install GRUB on your drive.
460
461
462@node Installation
463@chapter Installation
464
465In order to install GRUB as your boot loader, you need to first
466install the GRUB system and utilities under your UNIX-like operating
467system (@pxref{Obtaining and Building GRUB}). You can do this either
468from the source tarball, or as a package for your OS.
469
470After you have done that, you need to install the boot loader on a
471drive (floppy or hard disk). There are two ways of doing that - either
472using the utility @command{grub-install} (@pxref{Invoking
473grub-install}) on a UNIX-like OS, or by running GRUB itself from a
474floppy. These are quite similar, however the utility might probe a
475wrong BIOS drive, so you should be careful.
476
477Also, if you install GRUB on a UNIX-like OS, please make sure that you
478have an emergency boot disk ready, so that you can rescue your computer
479if, by any chance, your hard drive becomes unusable (unbootable).
480
481GRUB comes with boot images, which are normally put in the directory
482@file{/usr/lib/grub/i386-pc}. If you do not use grub-install, then
483you need to copy the files @file{stage1}, @file{stage2}, and
484@file{*stage1_5} to the directory @file{/boot/grub}, and run the
485@command{grub-set-default} (@pxref{Invoking grub-set-default}) if you
486intend to use @samp{default saved} (@pxref{default}) in your
487configuration file. Hereafter, the directory where GRUB images are
488initially placed (normally @file{/usr/lib/grub/i386-pc}) will be
489called the @dfn{image directory}, and the directory where the boot
490loader needs to find them (usually @file{/boot/grub}) will be called
491the @dfn{boot directory}.
492
493@menu
494* Creating a GRUB boot floppy::
495* Installing GRUB natively::
496* Installing GRUB using grub-install::
497* Making a GRUB bootable CD-ROM::
498@end menu
499
500
501@node Creating a GRUB boot floppy
502@section Creating a GRUB boot floppy
503
504To create a GRUB boot floppy, you need to take the files @file{stage1}
505and @file{stage2} from the image directory, and write them to the first
506and the second block of the floppy disk, respectively.
507
508@strong{Caution:} This procedure will destroy any data currently stored
509on the floppy.
510
511On a UNIX-like operating system, that is done with the following
512commands:
513
514@example
515@group
516# @kbd{cd /usr/lib/grub/i386-pc}
517# @kbd{dd if=stage1 of=/dev/fd0 bs=512 count=1}
5181+0 records in
5191+0 records out
520# @kbd{dd if=stage2 of=/dev/fd0 bs=512 seek=1}
521153+1 records in
522153+1 records out
523#
524@end group
525@end example
526
527The device file name may be different. Consult the manual for your OS.
528
529
530@node Installing GRUB natively
531@section Installing GRUB natively
532
533@strong{Caution:} Installing GRUB's stage1 in this manner will erase the
534normal boot-sector used by an OS.
535
536GRUB can currently boot GNU Mach, Linux, FreeBSD, NetBSD, and OpenBSD
537directly, so using it on a boot sector (the first sector of a
538partition) should be okay. But generally, it would be a good idea to
539back up the first sector of the partition on which you are installing
540GRUB's stage1. This isn't as important if you are installing GRUB on
541the first sector of a hard disk, since it's easy to reinitialize it
542(e.g. by running @samp{FDISK /MBR} from DOS).
543
544If you decide to install GRUB in the native environment, which is
545definitely desirable, you'll need to create a GRUB boot disk, and
546reboot your computer with it. Otherwise, see @ref{Installing GRUB using
547grub-install}.
548
549Once started, GRUB will show the command-line interface
550(@pxref{Command-line interface}). First, set the GRUB's @dfn{root
551device}@footnote{Note that GRUB's root device doesn't necessarily mean
552your OS's root partition; if you need to specify a root partition for
553your OS, add the argument into the command @command{kernel}.} to the
554partition containing the boot directory, like this:
555
556@example
557grub> @kbd{root (hd0,0)}
558@end example
559
560If you are not sure which partition actually holds this directory, use the
561command @command{find} (@pxref{find}), like this:
562
563@example
564grub> @kbd{find /boot/grub/stage1}
565@end example
566
567This will search for the file name @file{/boot/grub/stage1} and show the
568devices which contain the file.
569
570Once you've set the root device correctly, run the command
571@command{setup} (@pxref{setup}):
572
573@example
574grub> @kbd{setup (hd0)}
575@end example
576
577This command will install the GRUB boot loader on the Master Boot
578Record (MBR) of the first drive. If you want to put GRUB into the boot
579sector of a partition instead of putting it in the MBR, specify the
580partition into which you want to install GRUB:
581
582@example
583grub> @kbd{setup (hd0,0)}
584@end example
585
586If you install GRUB into a partition or a drive other than the first
587one, you must chain-load GRUB from another boot loader. Refer to the
588manual for the boot loader to know how to chain-load GRUB.
589
590After using the setup command, you will boot into GRUB without the
591GRUB floppy. See the chapter @ref{Booting} to find out how to boot
592your operating systems from GRUB.
593
594
595@node Installing GRUB using grub-install
596@section Installing GRUB using grub-install
597
598@strong{Caution:} This procedure is definitely less safe, because
599there are several ways in which your computer can become
600unbootable. For example, most operating systems don't tell GRUB how to
601map BIOS drives to OS devices correctly---GRUB merely @dfn{guesses}
602the mapping. This will succeed in most cases, but not
603always. Therefore, GRUB provides you with a map file called the
604@dfn{device map}, which you must fix if it is wrong. @xref{Device
605map}, for more details.
606
607If you still do want to install GRUB under a UNIX-like OS (such
608as @sc{gnu}), invoke the program @command{grub-install} (@pxref{Invoking
609grub-install}) as the superuser (@dfn{root}).
610
611The usage is basically very simple. You only need to specify one
612argument to the program, namely, where to install the boot loader. The
613argument can be either a device file (like @samp{/dev/hda}) or a
614partition specified in GRUB's notation. For example, under Linux the
615following will install GRUB into the MBR of the first IDE disk:
616
617@example
618# @kbd{grub-install /dev/hda}
619@end example
620
621Likewise, under GNU/Hurd, this has the same effect:
622
623@example
624# @kbd{grub-install /dev/hd0}
625@end example
626
627If it is the first BIOS drive, this is the same as well:
628
629@example
630# @kbd{grub-install '(hd0)'}
631@end example
632
633Or you can omit the parentheses:
634
635@example
636# @kbd{grub-install hd0}
637@end example
638
639But all the above examples assume that GRUB should use images under
640the root directory. If you want GRUB to use images under a directory
641other than the root directory, you need to specify the option
642@option{--root-directory}. The typical usage is that you create a GRUB
643boot floppy with a filesystem. Here is an example:
644
645@example
646@group
647# @kbd{mke2fs /dev/fd0}
648# @kbd{mount -t ext2 /dev/fd0 /mnt}
649# @kbd{grub-install --root-directory=/mnt fd0}
650# @kbd{umount /mnt}
651@end group
652@end example
653
654Another example is when you have a separate boot partition
655which is mounted at @file{/boot}. Since GRUB is a boot loader, it
656doesn't know anything about mountpoints at all. Thus, you need to run
657@command{grub-install} like this:
658
659@example
660# @kbd{grub-install --root-directory=/boot /dev/hda}
661@end example
662
663By the way, as noted above, it is quite difficult to guess BIOS drives
664correctly under a UNIX-like OS. Thus, @command{grub-install} will prompt
665you to check if it could really guess the correct mappings, after the
666installation. The format is defined in @ref{Device map}. Please be
667quite careful. If the output is wrong, it is unlikely that your
668computer will be able to boot with no problem.
669
670Note that @command{grub-install} is actually just a shell script and the
671real task is done by the grub shell @command{grub} (@pxref{Invoking the
672grub shell}). Therefore, you may run @command{grub} directly to install
673GRUB, without using @command{grub-install}. Don't do that, however,
674unless you are very familiar with the internals of GRUB. Installing a
675boot loader on a running OS may be extremely dangerous.
676
677
678@node Making a GRUB bootable CD-ROM
679@section Making a GRUB bootable CD-ROM
680
681GRUB supports the @dfn{no emulation mode} in the El Torito
682specification@footnote{El Torito is a specification for bootable CD
683using BIOS functions.}. This means that you can use the whole CD-ROM
684from GRUB and you don't have to make a floppy or hard disk image file,
685which can cause compatibility problems.
686
687For booting from a CD-ROM, GRUB uses a special Stage 2 called
688@file{stage2_eltorito}. The only GRUB files you need to have in your
689bootable CD-ROM are this @file{stage2_eltorito} and optionally a config file
690@file{menu.lst}. You don't need to use @file{stage1} or @file{stage2},
691because El Torito is quite different from the standard boot process.
692
693Here is an example of procedures to make a bootable CD-ROM
694image. First, make a top directory for the bootable image, say,
695@samp{iso}:
696
697@example
698$ @kbd{mkdir iso}
699@end example
700
701Make a directory for GRUB:
702
703@example
704$ @kbd{mkdir -p iso/boot/grub}
705@end example
706
707Copy the file @file{stage2_eltorito}:
708
709@example
710$ @kbd{cp /usr/lib/grub/i386-pc/stage2_eltorito iso/boot/grub}
711@end example
712
713If desired, make the config file @file{menu.lst} under @file{iso/boot/grub}
714(@pxref{Configuration}), and copy any files and directories for the disc to the
715directory @file{iso/}.
716
717Finally, make a ISO9660 image file like this:
718
719@example
720$ @kbd{mkisofs -R -b boot/grub/stage2_eltorito -no-emul-boot \
721    -boot-load-size 4 -boot-info-table -o grub.iso iso}
722@end example
723
724This produces a file named @file{grub.iso}, which then can be burned
725into a CD (or a DVD).  @kbd{mkisofs} has already set up the disc to boot
726from the @kbd{boot/grub/stage2_eltorito} file, so there is no need to
727setup GRUB on the disc.  (Note that the @kbd{-boot-load-size 4} bit is
728required for compatibility with the BIOS on many older machines.)
729
730You can use the device @samp{(cd)} to access a CD-ROM in your
731config file. This is not required; GRUB automatically sets the root device
732to @samp{(cd)} when booted from a CD-ROM. It is only necessary to refer to
733@samp{(cd)} if you want to access other drives as well.
734
735
736@node Booting
737@chapter Booting
738
739GRUB can load Multiboot-compliant kernels in a consistent way,
740but for some free operating systems you need to use some OS-specific
741magic.
742
743@menu
744* General boot methods::        How to boot OSes with GRUB generally
745* OS-specific notes::           Notes on some operating systems
746* Making your system robust::   How to make your system robust
747@end menu
748
749
750@node General boot methods
751@section How to boot operating systems
752
753GRUB has two distinct boot methods. One of the two is to load an
754operating system directly, and the other is to chain-load another boot
755loader which then will load an operating system actually. Generally
756speaking, the former is more desirable, because you don't need to
757install or maintain other boot loaders and GRUB is flexible enough to
758load an operating system from an arbitrary disk/partition. However,
759the latter is sometimes required, since GRUB doesn't support all the
760existing operating systems natively.
761
762@menu
763* Loading an operating system directly::
764* Chain-loading::
765@end menu
766
767
768@node Loading an operating system directly
769@subsection How to boot an OS directly with GRUB
770
771Multiboot (@pxref{Top, Multiboot Specification, Motivation, multiboot,
772The Multiboot Specification}) is the native format supported by GRUB.
773For the sake of convenience, there is also support for Linux, FreeBSD,
774NetBSD and OpenBSD. If you want to boot other operating systems, you
775will have to chain-load them (@pxref{Chain-loading}).
776
777Generally, GRUB can boot any Multiboot-compliant OS in the following
778steps:
779
780@enumerate
781@item
782Set GRUB's root device to the drive where the OS images are stored with
783the command @command{root} (@pxref{root}).
784
785@item
786Load the kernel image with the command @command{kernel} (@pxref{kernel}).
787
788@item
789If you need modules, load them with the command @command{module}
790(@pxref{module}) or @command{modulenounzip} (@pxref{modulenounzip}).
791
792@item
793Run the command @command{boot} (@pxref{boot}).
794@end enumerate
795
796Linux, FreeBSD, NetBSD and OpenBSD can be booted in a similar
797manner. You load a kernel image with the command @command{kernel} and
798then run the command @command{boot}. If the kernel requires some
799parameters, just append the parameters to @command{kernel}, after the
800file name of the kernel. Also, please refer to @ref{OS-specific notes},
801for information on your OS-specific issues.
802
803
804@node Chain-loading
805@subsection Load another boot loader to boot unsupported operating systems
806
807If you want to boot an unsupported operating system (e.g. Windows 95),
808chain-load a boot loader for the operating system. Normally, the boot
809loader is embedded in the @dfn{boot sector} of the partition on which
810the operating system is installed.
811
812@enumerate
813@item
814Set GRUB's root device to the partition by the command
815@command{rootnoverify} (@pxref{rootnoverify}):
816
817@example
818grub> @kbd{rootnoverify (hd0,0)}
819@end example
820
821@item
822Set the @dfn{active} flag in the partition using the command
823@command{makeactive}@footnote{This is not necessary for most of the
824modern operating systems.} (@pxref{makeactive}):
825
826@example
827grub> @kbd{makeactive}
828@end example
829
830@item
831Load the boot loader with the command @command{chainloader}
832(@pxref{chainloader}):
833
834@example
835grub> @kbd{chainloader +1}
836@end example
837
838@samp{+1} indicates that GRUB should read one sector from the start of
839the partition. The complete description about this syntax can be found
840in @ref{Block list syntax}.
841
842@item
843Run the command @command{boot} (@pxref{boot}).
844@end enumerate
845
846However, DOS and Windows have some deficiencies, so you might have to
847use more complicated instructions. @xref{DOS/Windows}, for more
848information.
849
850
851@node OS-specific notes
852@section Some caveats on OS-specific issues
853
854Here, we describe some caveats on several operating systems.
855
856@menu
857* GNU/Hurd::
858* GNU/Linux::
859* FreeBSD::
860* NetBSD::
861* OpenBSD::
862* DOS/Windows::
863* SCO UnixWare::
864* QNX::
865@end menu
866
867
868@node GNU/Hurd
869@subsection GNU/Hurd
870
871Since GNU/Hurd is Multiboot-compliant, it is easy to boot it; there is
872nothing special about it. But do not forget that you have to specify a
873root partition to the kernel.
874
875@enumerate
876@item
877Set GRUB's root device to the same drive as GNU/Hurd's. Probably the
878command @code{find /boot/gnumach} or similar can help you
879(@pxref{find}).
880
881@item
882Load the kernel and the module, like this:
883
884@example
885@group
886grub> @kbd{kernel /boot/gnumach root=hd0s1}
887grub> @kbd{module /boot/serverboot}
888@end group
889@end example
890
891@item
892Run the command @command{boot} (@pxref{boot}).
893@end enumerate
894
895
896@node GNU/Linux
897@subsection GNU/Linux
898
899It is relatively easy to boot GNU/Linux from GRUB, because it somewhat
900resembles to boot a Multiboot-compliant OS.
901
902@enumerate
903@item
904Set GRUB's root device to the same drive as GNU/Linux's. Probably the
905command @code{find /vmlinuz} or similar can help you (@pxref{find}).
906
907@item
908Load the kernel:
909
910@example
911grub> @kbd{kernel /vmlinuz root=/dev/hda1}
912@end example
913
914If you need to specify some kernel parameters, just append them to the
915command. For example, to set @option{vga} to @samp{ext}, do this:
916
917@example
918grub> @kbd{kernel /vmlinuz root=/dev/hda1 vga=ext}
919@end example
920
921See the documentation in the Linux source tree for complete
922information on the available options.
923
924@item
925If you use an initrd, execute the command @command{initrd}
926(@pxref{initrd}) after @command{kernel}:
927
928@example
929grub> @kbd{initrd /initrd}
930@end example
931
932@item
933Finally, run the command @command{boot} (@pxref{boot}).
934@end enumerate
935
936@strong{Caution:} If you use an initrd and specify the @samp{mem=}
937option to the kernel to let it use less than actual memory size, you
938will also have to specify the same memory size to GRUB. To let GRUB know
939the size, run the command @command{uppermem} @emph{before} loading the
940kernel. @xref{uppermem}, for more information.
941
942
943@node FreeBSD
944@subsection FreeBSD
945
946GRUB can load the kernel directly, either in ELF or a.out format. But
947this is not recommended, since FreeBSD's bootstrap interface sometimes
948changes heavily, so GRUB can't guarantee to pass kernel parameters
949correctly.
950
951Thus, we'd recommend loading the very flexible loader
952@file{/boot/loader} instead. See this example:
953
954@example
955@group
956grub> @kbd{root (hd0,a)}
957grub> @kbd{kernel /boot/loader}
958grub> @kbd{boot}
959@end group
960@end example
961
962
963@node NetBSD
964@subsection NetBSD
965
966GRUB can load NetBSD a.out and ELF directly, follow these steps:
967
968@enumerate
969@item
970Set GRUB's root device with @command{root} (@pxref{root}).
971
972@item
973Load the kernel with @command{kernel} (@pxref{kernel}). You should
974append the ugly option @option{--type=netbsd}, if you want to load an
975ELF kernel, like this:
976
977@example
978grub> @kbd{kernel --type=netbsd /netbsd-elf}
979@end example
980
981@item
982Run @command{boot} (@pxref{boot}).
983@end enumerate
984
985For now, however, GRUB doesn't allow you to pass kernel parameters, so
986it may be better to chain-load it instead. For more information, please
987see @ref{Chain-loading}.
988
989
990@node OpenBSD
991@subsection OpenBSD
992
993The booting instruction is exactly the same as for NetBSD
994(@pxref{NetBSD}).
995
996
997@node DOS/Windows
998@subsection DOS/Windows
999
1000GRUB cannot boot DOS or Windows directly, so you must chain-load them
1001(@pxref{Chain-loading}). However, their boot loaders have some critical
1002deficiencies, so it may not work to just chain-load them. To overcome
1003the problems, GRUB provides you with two helper functions.
1004
1005If you have installed DOS (or Windows) on a non-first hard disk, you
1006have to use the disk swapping technique, because that OS cannot boot
1007from any disks but the first one. The workaround used in GRUB is the
1008command @command{map} (@pxref{map}), like this:
1009
1010@example
1011@group
1012grub> @kbd{map (hd0) (hd1)}
1013grub> @kbd{map (hd1) (hd0)}
1014@end group
1015@end example
1016
1017This performs a @dfn{virtual} swap between your first and second hard
1018drive.
1019
1020@strong{Caution:} This is effective only if DOS (or Windows) uses BIOS
1021to access the swapped disks. If that OS uses a special driver for the
1022disks, this probably won't work.
1023
1024Another problem arises if you installed more than one set of DOS/Windows
1025onto one disk, because they could be confused if there are more than one
1026primary partitions for DOS/Windows. Certainly you should avoid doing
1027this, but there is a solution if you do want to do so. Use the partition
1028hiding/unhiding technique.
1029
1030If GRUB @dfn{hide}s a DOS (or Windows) partition (@pxref{hide}), DOS (or
1031Windows) will ignore the partition. If GRUB @dfn{unhide}s a DOS (or
1032Windows) partition (@pxref{unhide}), DOS (or Windows) will detect the
1033partition. Thus, if you have installed DOS (or Windows) on the first
1034and the second partition of the first hard disk, and you want to boot
1035the copy on the first partition, do the following:
1036
1037@example
1038@group
1039grub> @kbd{unhide (hd0,0)}
1040grub> @kbd{hide (hd0,1)}
1041grub> @kbd{rootnoverify (hd0,0)}
1042grub> @kbd{chainloader +1}
1043grub> @kbd{makeactive}
1044grub> @kbd{boot}
1045@end group
1046@end example
1047
1048
1049@node SCO UnixWare
1050@subsection SCO UnixWare
1051
1052It is known that the signature in the boot loader for SCO UnixWare is
1053wrong, so you will have to specify the option @option{--force} to
1054@command{chainloader} (@pxref{chainloader}), like this:
1055
1056@example
1057@group
1058grub> @kbd{rootnoverify (hd1,0)}
1059grub> @kbd{chainloader --force +1}
1060grub> @kbd{makeactive}
1061grub> @kbd{boot}
1062@end group
1063@end example
1064
1065
1066@node QNX
1067@subsection QNX
1068
1069QNX seems to use a bigger boot loader, so you need to boot it up, like
1070this:
1071
1072@example
1073@group
1074grub> @kbd{rootnoverify (hd1,1)}
1075grub> @kbd{chainloader +4}
1076grub> @kbd{boot}
1077@end group
1078@end example
1079
1080
1081@node Making your system robust
1082@section How to make your system robust
1083
1084When you test a new kernel or a new OS, it is important to make sure
1085that your computer can boot even if the new system is unbootable. This
1086is crucial especially if you maintain servers or remote systems. To
1087accomplish this goal, you need to set up two things:
1088
1089@enumerate
1090@item
1091You must maintain a system which is always bootable. For instance, if
1092you test a new kernel, you need to keep a working kernel in a
1093different place. And, it would sometimes be very nice to even have a
1094complete copy of a working system in a different partition or disk.
1095
1096@item
1097You must direct GRUB to boot a working system when the new system
1098fails. This is possible with the @dfn{fallback} system in GRUB.
1099@end enumerate
1100
1101The former requirement is very specific to each OS, so this
1102documentation does not cover that topic. It is better to consult some
1103backup tools.
1104
1105So let's see the GRUB part. There are two possibilities: one of them
1106is quite simple but not very robust, and the other is a bit complex to
1107set up but probably the best solution to make sure that your system
1108can start as long as GRUB itself is bootable.
1109
1110@menu
1111* Booting once-only::
1112* Booting fallback systems::
1113@end menu
1114
1115
1116@node Booting once-only
1117@subsection Booting once-only
1118
1119You can teach GRUB to boot an entry only at next boot time. Suppose
1120that your have an old kernel @file{old_kernel} and a new kernel
1121@file{new_kernel}. You know that @file{old_kernel} can boot
1122your system correctly, and you want to test @file{new_kernel}.
1123
1124To ensure that your system will go back to the old kernel even if the
1125new kernel fails (e.g. it panics), you can specify that GRUB should
1126try the new kernel only once and boot the old kernel after that.
1127
1128First, modify your configuration file. Here is an example:
1129
1130@example
1131@group
1132default saved        # This is important!!!
1133timeout 10
1134
1135title the old kernel
1136root (hd0,0)
1137kernel /old_kernel
1138savedefault
1139
1140title the new kernel
1141root (hd0,0)
1142kernel /new_kernel
1143savedefault 0         # This is important!!!
1144@end group
1145@end example
1146
1147Note that this configuration file uses @samp{default saved}
1148(@pxref{default}) at the head and @samp{savedefault 0}
1149(@pxref{savedefault}) in the entry for the new kernel. This means
1150that GRUB boots a saved entry by default, and booting the entry for the
1151new kernel saves @samp{0} as the saved entry.
1152
1153With this configuration file, after all, GRUB always tries to boot the
1154old kernel after it booted the new one, because @samp{0} is the entry
1155of @code{the old kernel}.
1156
1157The next step is to tell GRUB to boot the new kernel at next boot
1158time. For this, execute @command{grub-set-default} (@pxref{Invoking
1159grub-set-default}):
1160
1161@example
1162# @kbd{grub-set-default 1}
1163@end example
1164
1165This command sets the saved entry to @samp{1}, that is, to the new
1166kernel.
1167
1168This method is useful, but still not very robust, because GRUB stops
1169booting, if there is any error in the boot entry, such that the new
1170kernel has an invalid executable format. Thus, it it even better to
1171use the @dfn{fallback} mechanism of GRUB. Look at next subsection for
1172this feature.
1173
1174
1175@node Booting fallback systems
1176@subsection Booting fallback systems
1177
1178GRUB supports a fallback mechanism of booting one or more other
1179entries if a default boot entry fails. You can specify multiple
1180fallback entries if you wish.
1181
1182Suppose that you have three systems, @samp{A}, @samp{B} and
1183@samp{C}. @samp{A} is a system which you want to boot by
1184default. @samp{B} is a backup system which is supposed to boot
1185safely. @samp{C} is another backup system which is used in case where
1186@samp{B} is broken.
1187
1188Then you may want GRUB to boot the first system which is bootable
1189among @samp{A}, @samp{B} and @samp{C}. A configuration file can be
1190written in this way:
1191
1192@example
1193@group
1194default saved        # This is important!!!
1195timeout 10
1196fallback 1 2         # This is important!!!
1197
1198title A
1199root (hd0,0)
1200kernel /kernel
1201savedefault fallback # This is important!!!
1202
1203title B
1204root (hd1,0)
1205kernel /kernel
1206savedefault fallback # This is important!!!
1207
1208title C
1209root (hd2,0)
1210kernel /kernel
1211savedefault
1212@end group
1213@end example
1214
1215Note that @samp{default saved} (@pxref{default}), @samp{fallback 1 2}
1216and @samp{savedefault fallback} are used. GRUB will boot a saved entry
1217by default and save a fallback entry as next boot entry with this
1218configuration.
1219
1220When GRUB tries to boot @samp{A}, GRUB saves @samp{1} as next boot
1221entry, because the command @command{fallback} specifies that @samp{1}
1222is the first fallback entry. The entry @samp{1} is @samp{B}, so GRUB
1223will try to boot @samp{B} at next boot time.
1224
1225Likewise, when GRUB tries to boot @samp{B}, GRUB saves @samp{2} as
1226next boot entry, because @command{fallback} specifies @samp{2} as next
1227fallback entry. This makes sure that GRUB will boot @samp{C} after
1228booting @samp{B}.
1229
1230It is noteworthy that GRUB uses fallback entries both when GRUB
1231itself fails in booting an entry and when @samp{A} or @samp{B} fails
1232in starting up your system. So this solution ensures that your system
1233is started even if GRUB cannot find your kernel or if your kernel
1234panics.
1235
1236However, you need to run @command{grub-set-default} (@pxref{Invoking
1237grub-set-default}) when @samp{A} starts correctly or you fix @samp{A}
1238after it crashes, since GRUB always sets next boot entry to a fallback
1239entry. You should run this command in a startup script such as
1240@file{rc.local} to boot @samp{A} by default:
1241
1242@example
1243# @kbd{grub-set-default 0}
1244@end example
1245
1246where @samp{0} is the number of the boot entry for the system
1247@samp{A}.
1248
1249If you want to see what is current default entry, you can look at the
1250file @file{/boot/grub/default} (or @file{/grub/default} in
1251some systems). Because this file is plain-text, you can just
1252@command{cat} this file. But it is strongly recommended @strong{not to
1253modify this file directly}, because GRUB may fail in saving a default
1254entry in this file, if you change this file in an unintended
1255manner. Therefore, you should use @command{grub-set-default} when you
1256need to change the default entry.
1257
1258
1259@node Configuration
1260@chapter Configuration
1261
1262You've probably noticed that you need to type several commands to boot your
1263OS. There's a solution to that - GRUB provides a menu interface
1264(@pxref{Menu interface}) from which you can select an item (using arrow
1265keys) that will do everything to boot an OS.
1266
1267To enable the menu, you need a configuration file,
1268@file{menu.lst} under the boot directory. We'll analyze an example
1269file.
1270
1271The file first contains some general settings, the menu interface
1272related options. You can put these commands (@pxref{Menu-specific
1273commands}) before any of the items (starting with @command{title}
1274(@pxref{title})).
1275
1276@example
1277@group
1278#
1279# Sample boot menu configuration file
1280#
1281@end group
1282@end example
1283
1284As you may have guessed, these lines are comments. Lines starting with a
1285hash character (@samp{#}), and blank lines, are ignored by GRUB.
1286
1287@example
1288@group
1289# By default, boot the first entry.
1290default 0
1291@end group
1292@end example
1293
1294The first entry (here, counting starts with number zero, not one!) will
1295be the default choice.
1296
1297@example
1298@group
1299# Boot automatically after 30 secs.
1300timeout 30
1301@end group
1302@end example
1303
1304As the comment says, GRUB will boot automatically in 30 seconds, unless
1305interrupted with a keypress.
1306
1307@example
1308@group
1309# Fallback to the second entry.
1310fallback 1
1311@end group
1312@end example
1313
1314If, for any reason, the default entry doesn't work, fall back to the
1315second one (this is rarely used, for obvious reasons).
1316
1317Note that the complete descriptions of these commands, which are menu
1318interface specific, can be found in @ref{Menu-specific
1319commands}. Other descriptions can be found in @ref{Commands}.
1320
1321Now, on to the actual OS definitions. You will see that each entry
1322begins with a special command, @command{title} (@pxref{title}), and the
1323action is described after it. Note that there is no command
1324@command{boot} (@pxref{boot}) at the  end of each item. That is because
1325GRUB automatically executes @command{boot} if it loads other commands
1326successfully.
1327
1328The argument for the command @command{title} is used to display a short
1329title/description of the entry in the menu. Since @command{title}
1330displays the argument as is, you can write basically anything there.
1331
1332@example
1333@group
1334# For booting GNU/Hurd
1335title  GNU/Hurd
1336root   (hd0,0)
1337kernel /boot/gnumach.gz root=hd0s1
1338module /boot/serverboot.gz
1339@end group
1340@end example
1341
1342This boots GNU/Hurd from the first hard disk.
1343
1344@example
1345@group
1346# For booting GNU/Linux
1347title  GNU/Linux
1348kernel (hd1,0)/vmlinuz root=/dev/hdb1
1349@end group
1350@end example
1351
1352This boots GNU/Linux, but from the second hard disk.
1353
1354@example
1355@group
1356# For booting Mach (getting kernel from floppy)
1357title  Utah Mach4 multiboot
1358root   (hd0,2)
1359pause  Insert the diskette now^G!!
1360kernel (fd0)/boot/kernel root=hd0s3
1361module (fd0)/boot/bootstrap
1362@end group
1363@end example
1364
1365This boots Mach with a kernel on a floppy, but the root filesystem at
1366hd0s3. It also contains a @command{pause} line (@pxref{pause}), which
1367will cause GRUB to display a prompt and delay, before actually executing
1368the rest of the commands and booting.
1369
1370@example
1371@group
1372# For booting FreeBSD
1373title  FreeBSD
1374root   (hd0,2,a)
1375kernel /boot/loader
1376@end group
1377@end example
1378
1379This item will boot FreeBSD kernel loaded from the @samp{a} partition of
1380the third @sc{pc} slice of the first hard disk.
1381
1382@example
1383@group
1384# For booting OS/2
1385title OS/2
1386root  (hd0,1)
1387makeactive
1388# chainload OS/2 bootloader from the first sector
1389chainloader +1
1390# This is similar to "chainload", but loads a specific file
1391#chainloader /boot/chain.os2
1392@end group
1393@end example
1394
1395This will boot OS/2, using a chain-loader (@pxref{Chain-loading}).
1396
1397@example
1398@group
1399# For booting Windows NT or Windows95
1400title Windows NT / Windows 95 boot menu
1401root        (hd0,0)
1402makeactive
1403chainloader +1
1404# For loading DOS if Windows NT is installed
1405# chainload /bootsect.dos
1406@end group
1407@end example
1408
1409The same as the above, but for Windows.
1410
1411@example
1412@group
1413# For installing GRUB into the hard disk
1414title Install GRUB into the hard disk
1415root    (hd0,0)
1416setup   (hd0)
1417@end group
1418@end example
1419
1420This will just (re)install GRUB onto the hard disk.
1421
1422@example
1423# Change the colors.
1424title Change the colors
1425color light-green/brown blink-red/blue
1426@end example
1427
1428In the last entry, the command @command{color} is used (@pxref{color}),
1429to change the menu colors (try it!). This command is somewhat special,
1430because it can be used both in the command-line and in the menu. GRUB
1431has several such commands, see @ref{General commands}.
1432
1433We hope that you now understand how to use the basic features of
1434GRUB. To learn more about GRUB, see the following chapters.
1435
1436
1437@node Network
1438@chapter Downloading OS images from a network
1439
1440Although GRUB is a disk-based boot loader, it does provide network
1441support. To use the network support, you need to enable at least one
1442network driver in the GRUB build process. For more information please
1443see @file{netboot/README.netboot} in the source distribution.
1444
1445@menu
1446* General usage of network support::
1447* Diskless::
1448@end menu
1449
1450
1451@node General usage of network support
1452@section How to set up your network
1453
1454GRUB requires a file server and optionally a server that will assign an
1455IP address to the machine on which GRUB is running. For the former, only
1456TFTP is supported at the moment. The latter is either BOOTP, DHCP or a
1457RARP server@footnote{RARP is not advised, since it cannot serve much
1458information}. It is not necessary to run both the servers on one
1459computer. How to configure these servers is beyond the scope of this
1460document, so please refer to the manuals specific to those
1461protocols/servers.
1462
1463If you decided to use a server to assign an IP address, set up the
1464server and run @command{bootp} (@pxref{bootp}), @command{dhcp}
1465(@pxref{dhcp}) or @command{rarp} (@pxref{rarp}) for BOOTP, DHCP or RARP,
1466respectively. Each command will show an assigned IP address, a netmask,
1467an IP address for your TFTP server and a gateway. If any of the
1468addresses is wrong or it causes an error, probably the configuration of
1469your servers isn't set up properly.
1470
1471Otherwise, run @command{ifconfig}, like this:
1472
1473@example
1474grub> @kbd{ifconfig --address=192.168.110.23 --server=192.168.110.14}
1475@end example
1476
1477You can also use @command{ifconfig} in conjuction with @command{bootp},
1478@command{dhcp} or @command{rarp} (e.g. to reassign the server address
1479manually). @xref{ifconfig}, for more details.
1480
1481Finally, download your OS images from your network. The network can be
1482accessed using the network drive @samp{(nd)}. Everything else is very
1483similar to the normal instructions (@pxref{Booting}).
1484
1485Here is an example:
1486
1487@example
1488@group
1489grub> @kbd{bootp}
1490Probing... [NE*000]
1491NE2000 base ...
1492Address: 192.168.110.23    Netmask: 255.255.255.0
1493Server: 192.168.110.14     Gateway: 192.168.110.1
1494
1495grub> @kbd{root (nd)}
1496grub> @kbd{kernel /tftproot/gnumach.gz root=sd0s1}
1497grub> @kbd{module /tftproot/serverboot.gz}
1498grub> @kbd{boot}
1499@end group
1500@end example
1501
1502
1503@node Diskless
1504@section Booting from a network
1505
1506It is sometimes very useful to boot from a network, especially when you
1507use a machine which has no local disk. In this case, you need to obtain
1508a kind of Net Boot @sc{rom}, such as a PXE @sc{rom} or a free software
1509package like Etherboot. Such a Boot @sc{rom} first boots the machine,
1510sets up the network card installed into the machine, and downloads a
1511second stage boot image from the network. Then, the second image will
1512try to boot an operating system actually from the network.
1513
1514GRUB provides two second stage images, @file{nbgrub} and
1515@file{pxegrub} (@pxref{Images}). These images are the same as the
1516normal Stage 2, except that they set up a network automatically, and try
1517to load a configuration file from the network, if specified. The usage
1518is very simple: If the machine has a PXE @sc{rom}, use
1519@file{pxegrub}. If the machine has an NBI loader such as Etherboot, use
1520@file{nbgrub}. There is no difference between them except their
1521formats. Since the way to load a second stage image you want to use
1522should be described in the manual on your Net Boot @sc{rom}, please
1523refer to the manual, for more information.
1524
1525However, there is one thing specific to GRUB. Namely, how to specify a
1526configuration file in a BOOTP/DHCP server. For now, GRUB uses the tag
1527@samp{150}, to get the name of a configuration file. The following is an
1528example with a BOOTP configuration:
1529
1530@example
1531@group
1532.allhost:hd=/tmp:bf=null:\
1533        :ds=145.71.35.1 145.71.32.1:\
1534        :sm=255.255.254.0:\
1535        :gw=145.71.35.1:\
1536        :sa=145.71.35.5:
1537
1538foo:ht=1:ha=63655d0334a7:ip=145.71.35.127:\
1539        :bf=/nbgrub:\
1540        :tc=.allhost:\
1541        :T150="(nd)/tftpboot/menu.lst.foo":
1542@end group
1543@end example
1544
1545Note that you should specify the drive name @code{(nd)} in the name of
1546the configuration file. This is because you might change the root drive
1547before downloading the configuration from the TFTP server when the
1548preset menu feature is used (@pxref{Preset Menu}).
1549
1550GRUB sends the string "GRUBClient" as its vendor class identifier to
1551the BOOTP/DHCP server. This can be used to generate answers specific
1552to GRUB clients on your network.
1553
1554See the manual of your BOOTP/DHCP server for more information. The
1555exact syntax should differ a little from the example.
1556
1557@node Serial terminal
1558@chapter Using GRUB via a serial line
1559
1560This chapter describes how to use the serial terminal support in GRUB.
1561
1562If you have many computers or computers with no display/keyboard, it
1563could be very useful to control the computers through serial
1564communications. To connect one computer with another via a serial line,
1565you need to prepare a null-modem (cross) serial cable, and you may need
1566to have multiport serial boards, if your computer doesn't have extra
1567serial ports. In addition, a terminal emulator is also required, such as
1568minicom. Refer to a manual of your operating system, for more
1569information.
1570
1571As for GRUB, the instruction to set up a serial terminal is quite
1572simple. First of all, make sure that you haven't specified the option
1573@option{--disable-serial} to the configure script when you built your
1574GRUB images. If you get them in binary form, probably they have serial
1575terminal support already.
1576
1577Then, initialize your serial terminal after GRUB starts up. Here is an
1578example:
1579
1580@example
1581@group
1582grub> @kbd{serial --unit=0 --speed=9600}
1583grub> @kbd{terminal serial}
1584@end group
1585@end example
1586
1587The command @command{serial} initializes the serial unit 0 with the
1588speed 9600bps. The serial unit 0 is usually called @samp{COM1}, so, if
1589you want to use COM2, you must specify @samp{--unit=1} instead. This
1590command accepts many other options, so please refer to @ref{serial},
1591for more details.
1592
1593The command @command{terminal} (@pxref{terminal}) chooses which type of
1594terminal you want to use. In the case above, the terminal will be a
1595serial terminal, but you can also pass @code{console} to the command,
1596as @samp{terminal serial console}. In this case, a terminal in which
1597you press any key will be selected as a GRUB terminal.
1598
1599However, note that GRUB assumes that your terminal emulator is
1600compatible with VT100 by default. This is true for most terminal
1601emulators nowadays, but you should pass the option @option{--dumb} to
1602the command if your terminal emulator is not VT100-compatible or
1603implements few VT100 escape sequences. If you specify this option then
1604GRUB provides you with an alternative menu interface, because the normal
1605menu requires several fancy features of your terminal.
1606
1607
1608@node Preset Menu
1609@chapter Embedding a configuration file into GRUB
1610
1611GRUB supports a @dfn{preset menu} which is to be always loaded before
1612starting. The preset menu feature is useful, for example, when your
1613computer has no console but a serial cable. In this case, it is
1614critical to set up the serial terminal as soon as possible, since you
1615cannot see any message until the serial terminal begins to work. So it
1616is good to run the commands @command{serial} (@pxref{serial}) and
1617@command{terminal} (@pxref{terminal}) before anything else at the
1618start-up time.
1619
1620How the preset menu works is slightly complicated:
1621
1622@enumerate
1623@item
1624GRUB checks if the preset menu feature is used, and loads the preset
1625menu, if available. This includes running commands and reading boot
1626entries, like an ordinary configuration file.
1627
1628@item
1629GRUB checks if the configuration file is available. Note that this check
1630is performed @strong{regardless of the existence of the preset
1631menu}. The configuration file is loaded even if the preset menu was
1632loaded.
1633
1634@item
1635If the preset menu includes any boot entries, they are cleared when
1636the configuration file is loaded. It doesn't matter whether the
1637configuration file has any entries or no entry. The boot entries in the
1638preset menu are used only when GRUB fails in loading the configuration
1639file.
1640@end enumerate
1641
1642To enable the preset menu feature, you must rebuild GRUB specifying a
1643file to the configure script with the option
1644@option{--enable-preset-menu}. The file has the same semantics as
1645normal configuration files (@pxref{Configuration}).
1646
1647Another point you should take care is that the diskless support
1648(@pxref{Diskless}) diverts the preset menu. Diskless images embed a
1649preset menu to execute the command @command{bootp} (@pxref{bootp})
1650automatically, unless you specify your own preset menu to the configure
1651script. This means that you must put commands to initialize a network in
1652the preset menu yourself, because diskless images don't set it up
1653implicitly, when you use the preset menu explicitly.
1654
1655Therefore, a typical preset menu used with diskless support would be
1656like this:
1657
1658@example
1659@group
1660# Set up the serial terminal, first of all.
1661serial --unit=0 --speed=19200
1662terminal --timeout=0 serial
1663
1664# Initialize the network.
1665dhcp
1666@end group
1667@end example
1668
1669
1670@node Security
1671@chapter Protecting your computer from cracking
1672
1673You may be interested in how to prevent ordinary users from doing
1674whatever they like, if you share your computer with other people. So
1675this chapter describes how to improve the security of GRUB.
1676
1677One thing which could be a security hole is that the user can do too
1678many things with GRUB, because GRUB allows one to modify its configuration
1679and run arbitrary commands at run-time. For example, the user can even
1680read @file{/etc/passwd} in the command-line interface by the command
1681@command{cat} (@pxref{cat}). So it is necessary to disable all the
1682interactive operations.
1683
1684Thus, GRUB provides a @dfn{password} feature, so that only administrators
1685can start the interactive operations (i.e. editing menu entries and
1686entering the command-line interface). To use this feature, you need to
1687run the command @command{password} in your configuration file
1688(@pxref{password}), like this:
1689
1690@example
1691password --md5 PASSWORD
1692@end example
1693
1694If this is specified, GRUB disallows any interactive control, until you
1695press the key @key{p} and enter a correct password.  The option
1696@option{--md5} tells GRUB that @samp{PASSWORD} is in MD5 format.  If it
1697is omitted, GRUB assumes the @samp{PASSWORD} is in clear text.
1698
1699You can encrypt your password with the command @command{md5crypt}
1700(@pxref{md5crypt}). For example, run the grub shell (@pxref{Invoking the
1701grub shell}), and enter your password:
1702
1703@example
1704@group
1705grub> md5crypt
1706Password: **********
1707Encrypted: $1$U$JK7xFegdxWH6VuppCUSIb.
1708@end group
1709@end example
1710
1711Then, cut and paste the encrypted password to your configuration file.
1712
1713Also, you can specify an optional argument to @command{password}. See
1714this example:
1715
1716@example
1717password PASSWORD /boot/grub/menu-admin.lst
1718@end example
1719
1720In this case, GRUB will load @file{/boot/grub/menu-admin.lst} as a
1721configuration file when you enter the valid password.
1722
1723Another thing which may be dangerous is that any user can choose any
1724menu entry. Usually, this wouldn't be problematic, but you might want to
1725permit only administrators to run some of your menu entries, such as an
1726entry for booting an insecure OS like DOS.
1727
1728GRUB provides the command @command{lock} (@pxref{lock}). This command
1729always fails until you enter the valid password, so you can use it, like
1730this:
1731
1732@example
1733@group
1734title Boot DOS
1735lock
1736rootnoverify (hd0,1)
1737makeactive
1738chainload +1
1739@end group
1740@end example
1741
1742You should insert @command{lock} right after @command{title}, because
1743any user can execute commands in an entry until GRUB encounters
1744@command{lock}.
1745
1746You can also use the command @command{password} instead of
1747@command{lock}. In this case the boot process will ask for the password
1748and stop if it was entered incorrectly.  Since the @command{password}
1749takes its own @var{PASSWORD} argument this is useful if you want
1750different passwords for different entries.
1751
1752
1753@node Images
1754@chapter GRUB image files
1755
1756GRUB consists of several images: two essential stages, optional stages
1757called @dfn{Stage 1.5}, one image for bootable CD-ROM, and two network
1758boot images. Here is a short overview of them. @xref{Internals}, for
1759more details.
1760
1761@table @file
1762@item stage1
1763This is an essential image used for booting up GRUB. Usually, this is
1764embedded in an MBR or the boot sector of a partition. Because a PC boot
1765sector is 512 bytes, the size of this image is exactly 512 bytes.
1766
1767All @file{stage1} must do is to load Stage 2 or Stage 1.5 from a local
1768disk. Because of the size restriction, @file{stage1} encodes the
1769location of Stage 2 (or Stage 1.5) in a block list format, so it never
1770understand any filesystem structure.
1771
1772@item stage2
1773This is the core image of GRUB. It does everything but booting up
1774itself. Usually, this is put in a filesystem, but that is not required.
1775
1776@item e2fs_stage1_5
1777@itemx fat_stage1_5
1778@itemx ffs_stage1_5
1779@itemx jfs_stage1_5
1780@itemx minix_stage1_5
1781@itemx reiserfs_stage1_5
1782@itemx vstafs_stage1_5
1783@itemx xfs_stage1_5
1784
1785These are called @dfn{Stage 1.5}, because they serve as a bridge
1786between @file{stage1} and @file{stage2}, that is to say, Stage 1.5 is
1787loaded by Stage 1 and Stage 1.5 loads Stage 2. The difference between
1788@file{stage1} and @file{*_stage1_5} is that the former doesn't
1789understand any filesystem while the latter understands one filesystem
1790(e.g. @file{e2fs_stage1_5} understands ext2fs). So you can move the
1791Stage 2 image to another location safely, even after GRUB has been
1792installed.
1793
1794While Stage 2 cannot generally be embedded in a fixed area as the size
1795is so large, Stage 1.5 can be installed into the area right after an MBR,
1796or the boot loader area of a ReiserFS or a FFS.
1797
1798@item stage2_eltorito
1799This is a boot image for CD-ROMs using the @dfn{no emulation mode} in
1800El Torito specification. This is identical to Stage 2, except that
1801this boots up without Stage 1 and sets up a special drive @samp{(cd)}.
1802
1803@item nbgrub
1804This is a network boot image for the Network Image Proposal used by some
1805network boot loaders, such as Etherboot. This is mostly the same as
1806Stage 2, but it also sets up a network and loads a configuration file
1807from the network.
1808
1809@item pxegrub
1810This is another network boot image for the Preboot Execution Environment
1811used by several Netboot ROMs. This is identical to @file{nbgrub}, except
1812for the format.
1813@end table
1814
1815
1816@node Filesystem
1817@chapter Filesystem syntax and semantics
1818
1819GRUB uses a special syntax for specifying disk drives which can be
1820accessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish
1821between IDE, ESDI, SCSI, or others. You must know yourself which BIOS
1822device is equivalent to which OS device. Normally, that will be clear if
1823you see the files in a device or use the command @command{find}
1824(@pxref{find}).
1825
1826@menu
1827* Device syntax::               How to specify devices
1828* File name syntax::            How to specify files
1829* Block list syntax::           How to specify block lists
1830@end menu
1831
1832
1833@node Device syntax
1834@section How to specify devices
1835
1836The device syntax is like this:
1837
1838@example
1839@code{(@var{device}[,@var{part-num}][,@var{bsd-subpart-letter}])}
1840@end example
1841
1842@samp{[]} means the parameter is optional. @var{device} should be
1843either @samp{fd} or @samp{hd} followed by a digit, like @samp{fd0}.
1844But you can also set @var{device} to a hexadecimal or a decimal number
1845which is a BIOS drive number, so the following are equivalent:
1846
1847@example
1848(hd0)
1849(0x80)
1850(128)
1851@end example
1852
1853@var{part-num} represents the partition number of @var{device}, starting
1854from zero for primary partitions and from four for extended partitions,
1855and @var{bsd-subpart-letter} represents the BSD disklabel subpartition,
1856such as @samp{a} or @samp{e}.
1857
1858A shortcut for specifying BSD subpartitions is
1859@code{(@var{device},@var{bsd-subpart-letter})}, in this case, GRUB
1860searches for the first PC partition containing a BSD disklabel, then
1861finds the subpartition @var{bsd-subpart-letter}. Here is an example:
1862
1863@example
1864(hd0,a)
1865@end example
1866
1867The syntax @samp{(hd0)} represents using the entire disk (or the
1868MBR when installing GRUB), while the syntax @samp{(hd0,0)}
1869represents using the first partition of the disk (or the boot sector
1870of the partition when installing GRUB).
1871
1872If you enabled the network support, the special drive, @samp{(nd)}, is
1873also available. Before using the network drive, you must initialize the
1874network. @xref{Network}, for more information.
1875
1876If you boot GRUB from a CD-ROM, @samp{(cd)} is available. @xref{Making
1877a GRUB bootable CD-ROM}, for details.
1878
1879
1880@node File name syntax
1881@section How to specify files
1882
1883There are two ways to specify files, by @dfn{absolute file name} and by
1884@dfn{block list}.
1885
1886An absolute file name resembles a Unix absolute file name, using
1887@samp{/} for the directory separator (not @samp{\} as in DOS). One
1888example is @samp{(hd0,0)/boot/grub/menu.lst}. This means the file
1889@file{/boot/grub/menu.lst} in the first partition of the first hard
1890disk. If you omit the device name in an absolute file name, GRUB uses
1891GRUB's @dfn{root device} implicitly. So if you set the root device to,
1892say, @samp{(hd1,0)} by the command @command{root} (@pxref{root}), then
1893@code{/boot/kernel} is the same as @code{(hd1,0)/boot/kernel}.
1894
1895
1896@node Block list syntax
1897@section How to specify block lists
1898
1899A block list is used for specifying a file that doesn't appear in the
1900filesystem, like a chainloader. The syntax is
1901@code{[@var{offset}]+@var{length}[,[@var{offset}]+@var{length}]@dots{}}.
1902Here is an example:
1903
1904@example
1905@code{0+100,200+1,300+300}
1906@end example
1907
1908This represents that GRUB should read blocks 0 through 99, block 200,
1909and blocks 300 through 599. If you omit an offset, then GRUB assumes
1910the offset is zero.
1911
1912Like the file name syntax (@pxref{File name syntax}), if a blocklist
1913does not contain a device name, then GRUB uses GRUB's @dfn{root
1914device}. So @code{(hd0,1)+1} is the same as @code{+1} when the root
1915device is @samp{(hd0,1)}.
1916
1917
1918@node Interface
1919@chapter GRUB's user interface
1920
1921GRUB has both a simple menu interface for choosing preset entries from a
1922configuration file, and a highly flexible command-line for performing
1923any desired combination of boot commands.
1924
1925GRUB looks for its configuration file as soon as it is loaded. If one
1926is found, then the full menu interface is activated using whatever
1927entries were found in the file. If you choose the @dfn{command-line} menu
1928option, or if the configuration file was not found, then GRUB drops to
1929the command-line interface.
1930
1931@menu
1932* Command-line interface::      The flexible command-line interface
1933* Menu interface::              The simple menu interface
1934* Menu entry editor::           Editing a menu entry
1935* Hidden menu interface::       The hidden menu interface
1936@end menu
1937
1938
1939@node Command-line interface
1940@section The flexible command-line interface
1941
1942The command-line interface provides a prompt and after it an editable
1943text area much like a command-line in Unix or DOS. Each command is
1944immediately executed after it is entered@footnote{However, this
1945behavior will be changed in the future version, in a user-invisible
1946way.}. The commands (@pxref{Command-line and menu entry commands}) are a
1947subset of those available in the configuration file, used with exactly
1948the same syntax.
1949
1950Cursor movement and editing of the text on the line can be done via a
1951subset of the functions available in the Bash shell:
1952
1953@table @key
1954@item C-f
1955@itemx PC right key
1956Move forward one character.
1957
1958@item C-b
1959@itemx PC left key
1960Move back one character.
1961
1962@item C-a
1963@itemx HOME
1964Move to the start of the line.
1965
1966@item C-e
1967@itemx END
1968Move the the end of the line.
1969
1970@item C-d
1971@itemx DEL
1972Delete the character underneath the cursor.
1973
1974@item C-h
1975@itemx BS
1976Delete the character to the left of the cursor.
1977
1978@item C-k
1979Kill the text from the current cursor position to the end of the line.
1980
1981@item C-u
1982Kill backward from the cursor to the beginning of the line.
1983
1984@item C-y
1985Yank the killed text back into the buffer at the cursor.
1986
1987@item C-p
1988@itemx PC up key
1989Move up through the history list.
1990
1991@item C-n
1992@itemx PC down key
1993Move down through the history list.
1994@end table
1995
1996When typing commands interactively, if the cursor is within or before
1997the first word in the command-line, pressing the @key{TAB} key (or
1998@key{C-i}) will display a listing of the available commands, and if the
1999cursor is after the first word, the @kbd{@key{TAB}} will provide a
2000completion listing of disks, partitions, and file names depending on the
2001context. Note that to obtain a list of drives, one must open a
2002parenthesis, as @command{root (}.
2003
2004Note that you cannot use the completion functionality in the TFTP
2005filesystem. This is because TFTP doesn't support file name listing for
2006the security.
2007
2008
2009@node Menu interface
2010@section The simple menu interface
2011
2012The menu interface is quite easy to use. Its commands are both
2013reasonably intuitive and described on screen.
2014
2015Basically, the menu interface provides a list of @dfn{boot entries} to
2016the user to choose from. Use the arrow keys to select the entry of
2017choice, then press @key{RET} to run it.  An optional timeout is
2018available to boot the default entry (the first one if not set), which is
2019aborted by pressing any key.
2020
2021Commands are available to enter a bare command-line by pressing @key{c}
2022(which operates exactly like the non-config-file version of GRUB, but
2023allows one to return to the menu if desired by pressing @key{ESC}) or to
2024edit any of the @dfn{boot entries} by pressing @key{e}.
2025
2026If you protect the menu interface with a password (@pxref{Security}),
2027all you can do is choose an entry by pressing @key{RET}, or press
2028@key{p} to enter the password.
2029
2030
2031@node Menu entry editor
2032@section Editing a menu entry
2033
2034The menu entry editor looks much like the main menu interface, but the
2035lines in the menu are individual commands in the selected entry instead
2036of entry names.
2037
2038If an @key{ESC} is pressed in the editor, it aborts all the changes made
2039to the configuration entry and returns to the main menu interface.
2040
2041When a particular line is selected, the editor places the user in a
2042special version of the GRUB command-line to edit that line.  When the
2043user hits @key{RET}, GRUB replaces the line in question in the boot
2044entry with the changes (unless it was aborted via @key{ESC},
2045in which case the changes are thrown away).
2046
2047If you want to add a new line to the menu entry, press @key{o} if adding
2048a line after the current line or press @key{O} if before the current
2049line.
2050
2051To delete a line, hit the key @key{d}. Although GRUB unfortunately
2052does not support @dfn{undo}, you can do almost the same thing by just
2053returning to the main menu.
2054
2055
2056@node Hidden menu interface
2057@section The hidden menu interface
2058
2059When your terminal is dumb or you request GRUB to hide the menu
2060interface explicitly with the command @command{hiddenmenu}
2061(@pxref{hiddenmenu}), GRUB doesn't show the menu interface (@pxref{Menu
2062interface}) and automatically boots the default entry, unless
2063interrupted by pressing @key{ESC}.
2064
2065When you interrupt the timeout and your terminal is dumb, GRUB falls
2066back to the command-line interface (@pxref{Command-line interface}).
2067
2068
2069@node Commands
2070@chapter The list of available commands
2071
2072In this chapter, we list all commands that are available in GRUB.
2073
2074Commands belong to different groups. A few can only be used in
2075the global section of the configuration file (or ``menu''); most
2076of them can be entered on the command-line and can be used either
2077anywhere in the menu or specifically in the menu entries.
2078
2079@menu
2080* Menu-specific commands::
2081* General commands::
2082* Command-line and menu entry commands::
2083@end menu
2084
2085
2086@node Menu-specific commands
2087@section The list of commands for the menu only
2088
2089The semantics used in parsing the configuration file are the following:
2090
2091@itemize @bullet
2092@item
2093The menu-specific commands have to be used before any others.
2094
2095@item
2096The files @emph{must} be in plain-text format.
2097
2098@item
2099@samp{#} at the beginning of a line in a configuration file means it is
2100only a comment.
2101
2102@item
2103Options are separated by spaces.
2104
2105@item
2106All numbers can be either decimal or hexadecimal. A hexadecimal number
2107must be preceded by @samp{0x}, and is case-insensitive.
2108
2109@item
2110Extra options or text at the end of the line are ignored unless otherwise
2111specified.
2112
2113@item
2114Unrecognized commands are added to the current entry, except before entries
2115start, where they are ignored.
2116@end itemize
2117
2118These commands can only be used in the menu:
2119
2120@menu
2121* default::                     Set the default entry
2122* fallback::                    Set the fallback entry
2123* hiddenmenu::                  Hide the menu interface
2124* timeout::                     Set the timeout
2125* title::                       Start a menu entry
2126@end menu
2127
2128
2129@node default
2130@subsection default
2131
2132@deffn Command default num
2133Set the default entry to the entry number @var{num}. Numbering starts
2134from 0, and the entry number 0 is the default if the command is not
2135used.
2136
2137You can specify @samp{saved} instead of a number. In this case, the
2138default entry is the entry saved with the command
2139@command{savedefault}. @xref{savedefault}, for more information.
2140@end deffn
2141
2142
2143@node fallback
2144@subsection fallback
2145
2146@deffn Command fallback num...
2147Go into unattended boot mode: if the default boot entry has any errors,
2148instead of waiting for the user to do something, immediately start
2149over using the @var{num} entry (same numbering as the @code{default}
2150command (@pxref{default})). This obviously won't help if the machine was
2151rebooted by a kernel that GRUB loaded. You can specify multiple
2152fallback entry numbers.
2153@end deffn
2154
2155
2156@node hiddenmenu
2157@subsection hiddenmenu
2158
2159@deffn Command hiddenmenu
2160Don't display the menu. If the command is used, no menu will be
2161displayed on the control terminal, and the default entry will be
2162booted after the timeout expired. The user can still request the
2163menu to be displayed by pressing @key{ESC} before the timeout
2164expires. See also @ref{Hidden menu interface}.
2165@end deffn
2166
2167
2168@node timeout
2169@subsection timeout
2170
2171@deffn Command timeout sec
2172Set a timeout, in @var{sec} seconds, before automatically booting the
2173default entry (normally the first entry defined).
2174@end deffn
2175
2176
2177@node title
2178@subsection title
2179
2180@deffn Command title name @dots{}
2181Start a new boot entry, and set its name to the contents of the rest of
2182the line, starting with the first non-space character.
2183@end deffn
2184
2185
2186@node General commands
2187@section The list of general commands
2188
2189Commands usable anywhere in the menu and in the command-line.
2190
2191@menu
2192* bootp::                       Initialize a network device via BOOTP
2193* color::                       Color the menu interface
2194* device::                      Specify a file as a drive
2195* dhcp::                        Initialize a network device via DHCP
2196* hide::                        Hide a partition
2197* ifconfig::                    Configure a network device manually
2198* pager::                       Change the state of the internal pager
2199* partnew::                     Make a primary partition
2200* parttype::                    Change the type of a partition
2201* password::                    Set a password for the menu interface
2202* rarp::                        Initialize a network device via RARP
2203* serial::                      Set up a serial device
2204* setkey::                      Configure the key map
2205* terminal::                    Choose a terminal
2206* terminfo::                    Define escape sequences for a terminal
2207* tftpserver::                  Specify a TFTP server
2208* unhide::                      Unhide a partition
2209@end menu
2210
2211
2212@node bootp
2213@subsection bootp
2214
2215@deffn Command bootp [@option{--with-configfile}]
2216Initialize a network device via the @dfn{BOOTP} protocol. This command
2217is only available if GRUB is compiled with netboot support. See also
2218@ref{Network}.
2219
2220If you specify @option{--with-configfile} to this command, GRUB will
2221fetch and load a configuration file specified by your BOOTP server
2222with the vendor tag @samp{150}.
2223@end deffn
2224
2225
2226@node color
2227@subsection color
2228
2229@deffn Command color normal [highlight]
2230Change the menu colors. The color @var{normal} is used for most
2231lines in the menu (@pxref{Menu interface}), and the color
2232@var{highlight} is used to highlight the line where the cursor
2233points. If you omit @var{highlight}, then the inverted color of
2234@var{normal} is used for the highlighted line. The format of a color is
2235@code{@var{foreground}/@var{background}}. @var{foreground} and
2236@var{background} are symbolic color names. A symbolic color name must be
2237one of these:
2238
2239@itemize @bullet
2240@item
2241black
2242
2243@item
2244blue
2245
2246@item
2247green
2248
2249@item
2250cyan
2251
2252@item
2253red
2254
2255@item
2256magenta
2257
2258@item
2259brown
2260
2261@item
2262light-gray
2263
2264@strong{These below can be specified only for the foreground.}
2265
2266@item
2267dark-gray
2268
2269@item
2270light-blue
2271
2272@item
2273light-green
2274
2275@item
2276light-cyan
2277
2278@item
2279light-red
2280
2281@item
2282light-magenta
2283
2284@item
2285yellow
2286
2287@item
2288white
2289@end itemize
2290
2291But only the first eight names can be used for @var{background}. You can
2292prefix @code{blink-} to @var{foreground} if you want a blinking
2293foreground color.
2294
2295This command can be used in the configuration file and on the command
2296line, so you may write something like this in your configuration file:
2297
2298@example
2299@group
2300# Set default colors.
2301color light-gray/blue black/light-gray
2302
2303# Change the colors.
2304title OS-BS like
2305color magenta/blue black/magenta
2306@end group
2307@end example
2308@end deffn
2309
2310
2311@node device
2312@subsection device
2313
2314@deffn Command device drive file
2315In the grub shell, specify the file @var{file} as the actual drive for a
2316@sc{bios} drive @var{drive}. You can use this command to create a disk
2317image, and/or to fix the drives guessed by GRUB when GRUB fails to
2318determine them correctly, like this:
2319
2320@example
2321@group
2322grub> @kbd{device (fd0) /floppy-image}
2323grub> @kbd{device (hd0) /dev/sd0}
2324@end group
2325@end example
2326
2327This command can be used only in the grub shell (@pxref{Invoking the
2328grub shell}).
2329@end deffn
2330
2331
2332@node dhcp
2333@subsection dhcp
2334
2335@deffn Command dhcp [--with-configfile]
2336Initialize a network device via the @dfn{DHCP} protocol. Currently,
2337this command is just an alias for @command{bootp}, since the two
2338protocols are very similar. This command is only available if GRUB is
2339compiled with netboot support. See also @ref{Network}.
2340
2341If you specify @option{--with-configfile} to this command, GRUB will
2342fetch and load a configuration file specified by your DHCP server
2343with the vendor tag @samp{150}.
2344@end deffn
2345
2346
2347@node hide
2348@subsection hide
2349
2350@deffn Command hide partition
2351Hide the partition @var{partition} by setting the @dfn{hidden} bit in
2352its partition type code. This is useful only when booting DOS or Windows
2353and multiple primary FAT partitions exist in one disk. See also
2354@ref{DOS/Windows}.
2355@end deffn
2356
2357
2358@node ifconfig
2359@subsection ifconfig
2360
2361@deffn Command ifconfig [@option{--server=server}] [@option{--gateway=gateway}] [@option{--mask=mask}] [@option{--address=address}]
2362Configure the IP address, the netmask, the gateway, and the server
2363address of a network device manually. The values must be in dotted
2364decimal format, like @samp{192.168.11.178}. The order of the options is
2365not important. This command shows current network configuration, if no
2366option is specified. See also @ref{Network}.
2367@end deffn
2368
2369
2370@node pager
2371@subsection pager
2372
2373@deffn Command pager [flag]
2374Toggle or set the state of the internal pager. If @var{flag} is
2375@samp{on}, the internal pager is enabled. If @var{flag} is @samp{off},
2376it is disabled. If no argument is given, the state is toggled.
2377@end deffn
2378
2379
2380@node partnew
2381@subsection partnew
2382
2383@deffn Command partnew part type from len
2384Create a new primary partition. @var{part} is a partition specification
2385in GRUB syntax (@pxref{Naming convention}); @var{type} is the partition
2386type and must be a number in the range @code{0-0xff}; @var{from} is
2387the starting address and @var{len} is the length, both in sector units.
2388@end deffn
2389
2390
2391@node parttype
2392@subsection parttype
2393
2394@deffn Command parttype part type
2395Change the type of an existing partition.  @var{part} is a partition
2396specification in GRUB syntax (@pxref{Naming convention}); @var{type}
2397is the new partition type and must be a number in the range 0-0xff.
2398@end deffn
2399
2400
2401@node password
2402@subsection password
2403
2404@deffn Command password [@option{--md5}] passwd [new-config-file]
2405If used in the first section of a menu file, disable all interactive
2406editing control (menu entry editor and command-line) and entries
2407protected by the command @command{lock}. If the password @var{passwd} is
2408entered, it loads the @var{new-config-file} as a new config file and
2409restarts the GRUB Stage 2, if @var{new-config-file} is
2410specified. Otherwise, GRUB will just unlock the privileged instructions.
2411You can also use this command in the script section, in which case it
2412will ask for the password, before continuing.  The option
2413@option{--md5} tells GRUB that @var{passwd} is encrypted with
2414@command{md5crypt} (@pxref{md5crypt}).
2415@end deffn
2416
2417
2418@node rarp
2419@subsection rarp
2420
2421@deffn Command rarp
2422Initialize a network device via the @dfn{RARP} protocol.  This command
2423is only available if GRUB is compiled with netboot support. See also
2424@ref{Network}.
2425@end deffn
2426
2427
2428@node serial
2429@subsection serial
2430
2431@deffn Command serial [@option{--unit=unit}] [@option{--port=port}] [@option{--speed=speed}] [@option{--word=word}] [@option{--parity=parity}] [@option{--stop=stop}] [@option{--device=dev}]
2432Initialize a serial device. @var{unit} is a number in the range 0-3
2433specifying which serial port to use; default is 0, which corresponds to
2434the port often called COM1. @var{port} is the I/O port where the UART
2435is to be found; if specified it takes precedence over @var{unit}.
2436@var{speed} is the transmission speed; default is 9600. @var{word} and
2437@var{stop} are the number of data bits and stop bits. Data bits must
2438be in the range 5-8 and stop bits must be 1 or 2. Default is 8 data
2439bits and one stop bit. @var{parity} is one of @samp{no}, @samp{odd},
2440@samp{even} and defaults to @samp{no}. The option @option{--device}
2441can only be used in the grub shell and is used to specify the
2442tty device to be used in the host operating system (@pxref{Invoking the
2443grub shell}).
2444
2445The serial port is not used as a communication channel unless the
2446@command{terminal} command is used (@pxref{terminal}).
2447
2448This command is only available if GRUB is compiled with serial
2449support. See also @ref{Serial terminal}.
2450@end deffn
2451
2452
2453@node setkey
2454@subsection setkey
2455
2456@deffn Command setkey [to_key from_key]
2457Change the keyboard map. The key @var{from_key} is mapped to the key
2458@var{to_key}. If no argument is specified, reset key mappings. Note that
2459this command @emph{does not} exchange the keys. If you want to exchange
2460the keys, run this command again with the arguments exchanged, like this:
2461
2462@example
2463grub> @kbd{setkey capslock control}
2464grub> @kbd{setkey control capslock}
2465@end example
2466
2467A key must be an alphabet letter, a digit, or one of these symbols:
2468@samp{escape}, @samp{exclam}, @samp{at}, @samp{numbersign},
2469@samp{dollar}, @samp{percent}, @samp{caret}, @samp{ampersand},
2470@samp{asterisk}, @samp{parenleft}, @samp{parenright}, @samp{minus},
2471@samp{underscore}, @samp{equal}, @samp{plus}, @samp{backspace},
2472@samp{tab}, @samp{bracketleft}, @samp{braceleft}, @samp{bracketright},
2473@samp{braceright}, @samp{enter}, @samp{control}, @samp{semicolon},
2474@samp{colon}, @samp{quote}, @samp{doublequote}, @samp{backquote},
2475@samp{tilde}, @samp{shift}, @samp{backslash}, @samp{bar}, @samp{comma},
2476@samp{less}, @samp{period}, @samp{greater}, @samp{slash},
2477@samp{question}, @samp{alt}, @samp{space}, @samp{capslock}, @samp{FX}
2478(@samp{X} is a digit), and @samp{delete}. This table describes to which
2479character each of the symbols corresponds:
2480
2481@table @samp
2482@item exclam
2483@samp{!}
2484
2485@item at
2486@samp{@@}
2487
2488@item numbersign
2489@samp{#}
2490
2491@item dollar
2492@samp{$}
2493
2494@item percent
2495@samp{%}
2496
2497@item caret
2498@samp{^}
2499
2500@item ampersand
2501@samp{&}
2502
2503@item asterisk
2504@samp{*}
2505
2506@item parenleft
2507@samp{(}
2508
2509@item parenright
2510@samp{)}
2511
2512@item minus
2513@samp{-}
2514
2515@item underscore
2516@samp{_}
2517
2518@item equal
2519@samp{=}
2520
2521@item plus
2522@samp{+}
2523
2524@item bracketleft
2525@samp{[}
2526
2527@item braceleft
2528@samp{@{}
2529
2530@item bracketright
2531@samp{]}
2532
2533@item braceright
2534@samp{@}}
2535
2536@item semicolon
2537@samp{;}
2538
2539@item colon
2540@samp{:}
2541
2542@item quote
2543@samp{'}
2544
2545@item doublequote
2546@samp{"}
2547
2548@item backquote
2549@samp{`}
2550
2551@item tilde
2552@samp{~}
2553
2554@item backslash
2555@samp{\}
2556
2557@item bar
2558@samp{|}
2559
2560@item comma
2561@samp{,}
2562
2563@item less
2564@samp{<}
2565
2566@item period
2567@samp{.}
2568
2569@item greater
2570@samp{>}
2571
2572@item slash
2573@samp{/}
2574
2575@item question
2576@samp{?}
2577
2578@item space
2579@samp{ }
2580@end table
2581@end deffn
2582
2583
2584@node terminal
2585@subsection terminal
2586
2587@deffn Command terminal [@option{--dumb}] [@option{--no-echo}] [@option{--no-edit}] [@option{--timeout=secs}] [@option{--lines=lines}] [@option{--silent}] [@option{console}] [@option{serial}] [@option{hercules}]
2588Select a terminal for user interaction. The terminal is assumed to be
2589VT100-compatible unless @option{--dumb} is specified. If both
2590@option{console} and @option{serial} are specified, then GRUB will use
2591the one where a key is entered first or the first when the timeout
2592expires. If neither are specified, the current setting is
2593reported. This command is only available if GRUB is compiled with serial
2594support. See also @ref{Serial terminal}.
2595
2596This may not make sense for most users, but GRUB supports Hercules
2597console as well. Hercules console is usable like the ordinary console,
2598and the usage is quite similar to that for serial terminals: specify
2599@option{hercules} as the argument.
2600
2601The option @option{--lines} defines the number of lines in your
2602terminal, and it is used for the internal pager function. If you don't
2603specify this option, the number is assumed as 24.
2604
2605The option @option{--silent} suppresses the message to prompt you to
2606hit any key. This might be useful if your system has no terminal
2607device.
2608
2609The option @option{--no-echo} has GRUB not to echo back input
2610characters. This implies the option @option{--no-edit}.
2611
2612The option @option{--no-edit} disables the BASH-like editing feature.
2613@end deffn
2614
2615
2616@node terminfo
2617@subsection terminfo
2618
2619@deffn Command terminfo @option{--name=name} @option{--cursor-address=seq} [@option{--clear-screen=seq}] [@option{--enter-standout-mode=seq}] [@option{--exit-standout-mode=seq}]
2620Define the capabilities of your terminal. Use this command to define
2621escape sequences, if it is not vt100-compatible. You may use @samp{\e}
2622for @key{ESC} and @samp{^X} for a control character.
2623
2624You can use the utility @command{grub-terminfo} to generate
2625appropriate arguments to this command. @xref{Invoking grub-terminfo}.
2626
2627If no option is specified, the current settings are printed.
2628@end deffn
2629
2630
2631@node tftpserver
2632@subsection tftpserver
2633
2634@deffn Command tftpserver ipaddr
2635@strong{Caution:} This command exists only for backward
2636compatibility. Use @command{ifconfig} (@pxref{ifconfig}) instead.
2637
2638Override a TFTP server address returned by a BOOTP/DHCP/RARP server. The
2639argument @var{ipaddr} must be in dotted decimal format, like
2640@samp{192.168.0.15}.  This command is only available if GRUB is compiled
2641with netboot support. See also @ref{Network}.
2642@end deffn
2643
2644
2645@node unhide
2646@subsection unhide
2647
2648@deffn Command unhide partition
2649Unhide the partition @var{partition} by clearing the @dfn{hidden} bit in
2650its partition type code. This is useful only when booting DOS or Windows
2651and multiple primary partitions exist on one disk. See also
2652@ref{DOS/Windows}.
2653@end deffn
2654
2655
2656@node Command-line and menu entry commands
2657@section The list of command-line and menu entry commands
2658
2659These commands are usable in the command-line and in menu entries.  If
2660you forget a command, you can run the command @command{help}
2661(@pxref{help}).
2662
2663@menu
2664* blocklist::                   Get the block list notation of a file
2665* boot::                        Start up your operating system
2666* cat::                         Show the contents of a file
2667* chainloader::                 Chain-load another boot loader
2668* cmp::                         Compare two files
2669* configfile::                  Load a configuration file
2670* debug::                       Toggle the debug flag
2671* displayapm::                  Display APM information
2672* displaymem::                  Display memory configuration
2673* embed::                       Embed Stage 1.5
2674* find::                        Find a file
2675* fstest::                      Test a filesystem
2676* geometry::                    Manipulate the geometry of a drive
2677* halt::                        Shut down your computer
2678* help::                        Show help messages
2679* impsprobe::                   Probe SMP
2680* initrd::                      Load an initrd
2681* install::                     Install GRUB
2682* ioprobe::                     Probe I/O ports used for a drive
2683* kernel::                      Load a kernel
2684* lock::                        Lock a menu entry
2685* makeactive::                  Make a partition active
2686* map::                         Map a drive to another
2687* md5crypt::                    Encrypt a password in MD5 format
2688* module::                      Load a module
2689* modulenounzip::               Load a module without decompression
2690* pause::                       Wait for a key press
2691* quit::                        Exit from the grub shell
2692* reboot::                      Reboot your computer
2693* read::                        Read data from memory
2694* root::                        Set GRUB's root device
2695* rootnoverify::                Set GRUB's root device without mounting
2696* savedefault::                 Save current entry as the default entry
2697* setup::                       Set up GRUB's installation automatically
2698* testload::                    Load a file for testing a filesystem
2699* testvbe::                     Test VESA BIOS EXTENSION
2700* uppermem::                    Set the upper memory size
2701* vbeprobe::                    Probe VESA BIOS EXTENSION
2702@end menu
2703
2704
2705@node blocklist
2706@subsection blocklist
2707
2708@deffn Command blocklist file
2709Print the block list notation of the file @var{file}. @xref{Block list
2710syntax}.
2711@end deffn
2712
2713
2714@node boot
2715@subsection boot
2716
2717@deffn Command boot
2718Boot the OS or chain-loader which has been loaded. Only necessary if
2719running the fully interactive command-line (it is implicit at the end of
2720a menu entry).
2721@end deffn
2722
2723
2724@node cat
2725@subsection cat
2726
2727@deffn Command cat file
2728Display the contents of the file @var{file}. This command may be useful
2729to remind you of your OS's root partition:
2730
2731@example
2732grub> @kbd{cat /etc/fstab}
2733@end example
2734@end deffn
2735
2736
2737@node chainloader
2738@subsection chainloader
2739
2740@deffn Command chainloader [@option{--force}] file
2741Load @var{file} as a chain-loader. Like any other file loaded by the
2742filesystem code, it can use the blocklist notation to grab the first
2743sector of the current partition with @samp{+1}. If you specify the
2744option @option{--force}, then load @var{file} forcibly, whether it has a
2745correct signature or not. This is required when you want to load a
2746defective boot loader, such as SCO UnixWare 7.1 (@pxref{SCO UnixWare}).
2747@end deffn
2748
2749
2750@node cmp
2751@subsection cmp
2752
2753@deffn Command cmp file1 file2
2754Compare the file @var{file1} with the file @var{file2}. If they differ
2755in size, print the sizes like this:
2756
2757@example
2758Differ in size: 0x1234 [foo], 0x4321 [bar]
2759@end example
2760
2761If the sizes are equal but the bytes at an offset differ, then print the
2762bytes like this:
2763
2764@example
2765Differ at the offset 777: 0xbe [foo], 0xef [bar]
2766@end example
2767
2768If they are completely identical, nothing will be printed.
2769@end deffn
2770
2771
2772@node configfile
2773@subsection configfile
2774
2775@deffn Command configfile file
2776Load @var{file} as a configuration file.
2777@end deffn
2778
2779
2780@node debug
2781@subsection debug
2782
2783@deffn Command debug
2784Toggle debug mode (by default it is off). When debug mode is on, some
2785extra messages are printed to show disk activity. This global debug flag
2786is mainly useful for GRUB developers when testing new code.
2787@end deffn
2788
2789
2790@node displayapm
2791@subsection displayapm
2792
2793@deffn Command displayapm
2794Display APM BIOS information.
2795@end deffn
2796
2797
2798@node displaymem
2799@subsection displaymem
2800
2801@deffn Command displaymem
2802Display what GRUB thinks the system address space map of the machine is,
2803including all regions of physical @sc{ram} installed. GRUB's
2804@dfn{upper/lower memory} display uses the standard BIOS interface for
2805the available memory in the first megabyte, or @dfn{lower memory}, and a
2806synthesized number from various BIOS interfaces of the memory starting
2807at 1MB and going up to the first chipset hole for @dfn{upper memory}
2808(the standard PC @dfn{upper memory} interface is limited to reporting a
2809maximum of 64MB).
2810@end deffn
2811
2812
2813@node embed
2814@subsection embed
2815
2816@deffn Command embed stage1_5 device
2817Embed the Stage 1.5 @var{stage1_5} in the sectors after the MBR if
2818@var{device} is a drive, or in the @dfn{boot loader} area if @var{device}
2819is a FFS partition or a ReiserFS partition.@footnote{The latter feature
2820has not been implemented yet.} Print the number of sectors which
2821@var{stage1_5} occupies, if successful.
2822
2823Usually, you don't need to run this command directly. @xref{setup}.
2824@end deffn
2825
2826
2827@node find
2828@subsection find
2829
2830@deffn Command find filename
2831Search for the file name @var{filename} in all mountable partitions
2832and print the list of the devices which contain the file. The file
2833name @var{filename} should be an absolute file name like
2834@code{/boot/grub/stage1}.
2835@end deffn
2836
2837
2838@node fstest
2839@subsection fstest
2840
2841@deffn Command fstest
2842Toggle filesystem test mode.
2843Filesystem test mode, when turned on, prints out data corresponding to
2844all the device reads and what values are being sent to the low-level
2845routines. The format is @samp{<@var{partition-offset-sector},
2846@var{byte-offset}, @var{byte-length}>} for high-level reads inside a
2847partition, and @samp{[@var{disk-offset-sector}]} for low-level sector
2848requests from the disk.
2849Filesystem test mode is turned off by any use of the @command{install}
2850(@pxref{install}) or @command{testload} (@pxref{testload}) commands.
2851@end deffn
2852
2853
2854@node geometry
2855@subsection geometry
2856
2857@deffn Command geometry drive [cylinder head sector [total_sector]]
2858Print the information for the drive @var{drive}. In the grub shell, you
2859can set the geometry of the drive arbitrarily. The number of
2860cylinders, the number of heads, the number of sectors and the number of
2861total sectors are set to CYLINDER, HEAD, SECTOR and TOTAL_SECTOR,
2862respectively. If you omit TOTAL_SECTOR, then it will be calculated
2863based on the C/H/S values automatically.
2864@end deffn
2865
2866
2867@node halt
2868@subsection halt
2869
2870@deffn Command halt @option{--no-apm}
2871The command halts the computer. If the @option{--no-apm} option
2872is specified, no APM BIOS call is performed. Otherwise, the computer
2873is shut down using APM.
2874@end deffn
2875
2876
2877@node help
2878@subsection help
2879
2880@deffn Command help @option{--all} [pattern @dots{}]
2881Display helpful information about builtin commands. If you do not
2882specify @var{pattern}, this command shows short descriptions of most of
2883available commands. If you specify the option @option{--all} to this
2884command, short descriptions of rarely used commands (such as
2885@ref{testload}) are displayed as well.
2886
2887If you specify any @var{patterns}, it displays longer information
2888about each of the commands which match those @var{patterns}.
2889@end deffn
2890
2891
2892@node impsprobe
2893@subsection impsprobe
2894
2895@deffn Command impsprobe
2896Probe the Intel Multiprocessor Specification 1.1 or 1.4 configuration
2897table and boot the various CPUs which are found into a tight loop. This
2898command can be used only in the Stage 2, but not in the grub shell.
2899@end deffn
2900
2901
2902@node initrd
2903@subsection initrd
2904
2905@deffn Command initrd file @dots{}
2906Load an initial ramdisk for a Linux format boot image and set the
2907appropriate parameters in the Linux setup area in memory. See also
2908@ref{GNU/Linux}.
2909@end deffn
2910
2911
2912@node install
2913@subsection install
2914
2915@deffn Command install [@option{--force-lba}] [@option{--stage2=os_stage2_file}] stage1_file [@option{d}] dest_dev stage2_file [addr] [@option{p}] [config_file] [real_config_file]
2916This command is fairly complex, and you should not use this command
2917unless you are familiar with GRUB. Use @command{setup} (@pxref{setup})
2918instead.
2919
2920In short, it will perform a full install presuming the Stage 2 or Stage
29211.5@footnote{They're loaded the same way, so we will refer to the Stage
29221.5 as a Stage 2 from now on.} is in its final install location.
2923
2924In slightly more detail, it will load @var{stage1_file}, validate that
2925it is a GRUB Stage 1 of the right version number, install in it a
2926blocklist for loading @var{stage2_file} as a Stage 2. If the option
2927@option{d} is present, the Stage 1 will always look for the actual
2928disk @var{stage2_file} was installed on, rather than using the booting
2929drive. The Stage 2 will be loaded at address @var{addr}, which must be
2930@samp{0x8000} for a true Stage 2, and @samp{0x2000} for a Stage 1.5. If
2931@var{addr} is not present, GRUB will determine the address
2932automatically. It then writes the completed Stage 1 to the first block
2933of the device @var{dest_dev}. If the options @option{p} or
2934@var{config_file} are present, then it reads the first block of stage2,
2935modifies it with the values of the partition @var{stage2_file} was found
2936on (for @option{p}) or places the string @var{config_file} into the area
2937telling the stage2 where to look for a configuration file at boot
2938time. Likewise, if @var{real_config_file} is present and
2939@var{stage2_file} is a Stage 1.5, then the Stage 2 @var{config_file} is
2940patched with the configuration file name @var{real_config_file}. This
2941command preserves the DOS BPB (and for hard disks, the partition table)
2942of the sector the Stage 1 is to be installed into.
2943
2944@strong{Caution:} Several buggy BIOSes don't pass a booting drive
2945properly when booting from a hard disk drive. Therefore, you will
2946unfortunately have to specify the option @option{d}, whether your
2947Stage2 resides at the booting drive or not, if you have such a
2948BIOS. We know these are defective in this way:
2949
2950@table @asis
2951@item
2952Fujitsu LifeBook 400 BIOS version 31J0103A
2953
2954@item
2955HP Vectra XU 6/200 BIOS version GG.06.11
2956@end table
2957
2958@strong{Caution2:} A number of BIOSes don't return a correct LBA support
2959bitmap even if they do have the support. So GRUB provides a solution to
2960ignore the wrong bitmap, that is, the option @option{--force-lba}. Don't
2961use this option if you know that your BIOS doesn't have LBA support.
2962
2963@strong{Caution3:} You must specify the option @option{--stage2} in the
2964grub shell, if you cannot unmount the filesystem where your stage2 file
2965resides. The argument should be the file name in your operating system.
2966@end deffn
2967
2968
2969@node ioprobe
2970@subsection ioprobe
2971
2972@deffn Command ioprobe drive
2973Probe I/O ports used for the drive @var{drive}. This command will list
2974the I/O ports on the screen. For technical information,
2975@xref{Internals}.
2976@end deffn
2977
2978
2979@node kernel
2980@subsection kernel
2981
2982@deffn Command kernel [@option{--type=type}] [@option{--no-mem-option}] file @dots{}
2983Attempt to load the primary boot image (Multiboot a.out or @sc{elf},
2984Linux zImage or bzImage, FreeBSD a.out, NetBSD a.out, etc.) from
2985@var{file}. The rest of the line is passed verbatim as the @dfn{kernel
2986command-line}. Any modules must be reloaded after using this command.
2987
2988This command also accepts the option @option{--type} so that you can
2989specify the kernel type of @var{file} explicitly. The argument
2990@var{type} must be one of these: @samp{netbsd}, @samp{freebsd},
2991@samp{openbsd}, @samp{linux}, @samp{biglinux}, and
2992@samp{multiboot}. However, you need to specify it only if you want to
2993load a NetBSD @sc{elf} kernel, because GRUB can automatically determine
2994a kernel type in the other cases, quite safely.
2995
2996The option @option{--no-mem-option} is effective only for Linux. If the
2997option is specified, GRUB doesn't pass the option @option{mem=} to the
2998kernel.  This option is implied for Linux kernels 2.4.18 and newer.
2999@end deffn
3000
3001
3002@node lock
3003@subsection lock
3004
3005@deffn Command lock
3006Prevent normal users from executing arbitrary menu entries. You must use
3007the command @command{password} if you really want this command to be
3008useful (@pxref{password}).
3009
3010This command is used in a menu, as shown in this example:
3011
3012@example
3013@group
3014title This entry is too dangerous to be executed by normal users
3015lock
3016root (hd0,a)
3017kernel /no-security-os
3018@end group
3019@end example
3020
3021See also @ref{Security}.
3022@end deffn
3023
3024
3025@node makeactive
3026@subsection makeactive
3027
3028@deffn Command makeactive
3029Set the active partition on the root disk to GRUB's root device.
3030This command is limited to @emph{primary} PC partitions on a hard disk.
3031@end deffn
3032
3033
3034@node map
3035@subsection map
3036
3037@deffn Command map to_drive from_drive
3038Map the drive @var{from_drive} to the drive @var{to_drive}. This is
3039necessary when you chain-load some operating systems, such as DOS, if
3040such an OS resides at a non-first drive. Here is an example:
3041
3042@example
3043@group
3044grub> @kbd{map (hd0) (hd1)}
3045grub> @kbd{map (hd1) (hd0)}
3046@end group
3047@end example
3048
3049The example exchanges the order between the first hard disk and the
3050second hard disk. See also @ref{DOS/Windows}.
3051@end deffn
3052
3053
3054@node md5crypt
3055@subsection md5crypt
3056
3057@deffn Command md5crypt
3058Prompt to enter a password, and encrypt it in MD5 format. The encrypted
3059password can be used with the command @command{password}
3060(@pxref{password}). See also @ref{Security}.
3061@end deffn
3062
3063
3064@node module
3065@subsection module
3066
3067@deffn Command module file @dots{}
3068Load a boot module @var{file} for a Multiboot format boot image (no
3069interpretation of the file contents are made, so the user of this
3070command must know what the kernel in question expects). The rest of the
3071line is passed as the @dfn{module command-line}, like the
3072@command{kernel} command. You must load a Multiboot kernel image before
3073loading any module. See also @ref{modulenounzip}.
3074@end deffn
3075
3076
3077@node modulenounzip
3078@subsection modulenounzip
3079
3080@deffn Command modulenounzip file @dots{}
3081The same as @command{module} (@pxref{module}), except that automatic
3082decompression is disabled.
3083@end deffn
3084
3085
3086@node pause
3087@subsection pause
3088
3089@deffn Command pause message @dots{}
3090Print the @var{message}, then wait until a key is pressed. Note that
3091placing @key{^G} (ASCII code 7) in the message will cause the speaker to
3092emit the standard beep sound, which is useful when prompting the user to
3093change floppies.
3094@end deffn
3095
3096
3097@node quit
3098@subsection quit
3099
3100@deffn Command quit
3101Exit from the grub shell @command{grub} (@pxref{Invoking the grub
3102shell}). This command can be used only in the grub shell.
3103@end deffn
3104
3105
3106@node reboot
3107@subsection reboot
3108
3109@deffn Command reboot
3110Reboot the computer.
3111@end deffn
3112
3113
3114@node read
3115@subsection read
3116
3117@deffn Command read addr
3118Read a 32-bit value from memory at address @var{addr} and display it in
3119hex format.
3120@end deffn
3121
3122
3123@node root
3124@subsection root
3125
3126@deffn Command root device [hdbias]
3127Set the current @dfn{root device} to the device @var{device}, then
3128attempt to mount it to get the partition size (for passing the partition
3129descriptor in @code{ES:ESI}, used by some chain-loaded boot loaders), the
3130BSD drive-type (for booting BSD kernels using their native boot format),
3131and correctly determine the PC partition where a BSD sub-partition is
3132located. The optional @var{hdbias} parameter is a number to tell a BSD
3133kernel how many BIOS drive numbers are on controllers before the current
3134one. For example, if there is an IDE disk and a SCSI disk, and your
3135FreeBSD root partition is on the SCSI disk, then use a @samp{1} for
3136@var{hdbias}.
3137
3138See also @ref{rootnoverify}.
3139@end deffn
3140
3141
3142@node rootnoverify
3143@subsection rootnoverify
3144
3145@deffn Command rootnoverify device [hdbias]
3146Similar to @command{root} (@pxref{root}), but don't attempt to mount the
3147partition. This is useful for when an OS is outside of the area of the
3148disk that GRUB can read, but setting the correct root device is still
3149desired. Note that the items mentioned in @command{root} above which
3150derived from attempting the mount will @emph{not} work correctly.
3151@end deffn
3152
3153
3154@node savedefault
3155@subsection savedefault
3156
3157@deffn Command savedefault num
3158Save the current menu entry or @var{num} if specified as a default
3159entry. Here is an example:
3160
3161@example
3162@group
3163default saved
3164timeout 10
3165
3166title GNU/Linux
3167root (hd0,0)
3168kernel /boot/vmlinuz root=/dev/sda1 vga=ext
3169initrd /boot/initrd
3170savedefault
3171
3172title FreeBSD
3173root (hd0,a)
3174kernel /boot/loader
3175savedefault
3176@end group
3177@end example
3178
3179With this configuration, GRUB will choose the entry booted previously as
3180the default entry.
3181
3182You can specify @samp{fallback} instead of a number. Then, next
3183fallback entry is saved. Next fallback entry is chosen from fallback
3184entries. Normally, this will be the first entry in fallback ones.
3185
3186See also @ref{default} and @ref{Invoking grub-set-default}.
3187@end deffn
3188
3189
3190@node setup
3191@subsection setup
3192
3193@deffn Command setup [@option{--force-lba}] [@option{--stage2=os_stage2_file}] [@option{--prefix=dir}] install_device [image_device]
3194Set up the installation of GRUB automatically. This command uses the
3195more flexible command @command{install} (@pxref{install}) in the backend
3196and installs GRUB into the device @var{install_device}. If
3197@var{image_device} is specified, then find the GRUB images
3198(@pxref{Images}) in the device @var{image_device}, otherwise use the
3199current @dfn{root device}, which can be set by the command
3200@command{root}. If @var{install_device} is a hard disk, then embed a
3201Stage 1.5 in the disk if possible.
3202
3203The option @option{--prefix} specifies the directory under which GRUB
3204images are put. If it is not specified, GRUB automatically searches them
3205in @file{/boot/grub} and @file{/grub}.
3206
3207The options @option{--force-lba} and @option{--stage2} are just passed
3208to @command{install} if specified. @xref{install}, for more
3209information.
3210@end deffn
3211
3212
3213@node testload
3214@subsection testload
3215
3216@deffn Command testload file
3217Read the entire contents of @var{file} in several different ways and
3218compare them, to test the filesystem code. The output is somewhat
3219cryptic, but if no errors are reported and the final @samp{i=@var{X},
3220filepos=@var{Y}} reading has @var{X} and @var{Y} equal, then it is
3221definitely consistent, and very likely works correctly subject to a
3222consistent offset error. If this test succeeds, then a good next step is
3223to try loading a kernel.
3224@end deffn
3225
3226
3227@node testvbe
3228@subsection testvbe
3229
3230@deffn Command testvbe mode
3231Test the VESA BIOS EXTENSION mode @var{mode}. This command will switch
3232your video card to the graphics mode, and show an endless animation. Hit
3233any key to return. See also @ref{vbeprobe}.
3234@end deffn
3235
3236
3237@node uppermem
3238@subsection uppermem
3239
3240@deffn Command uppermem kbytes
3241Force GRUB to assume that only @var{kbytes} kilobytes of upper memory
3242are installed. Any system address range maps are discarded.
3243
3244@strong{Caution:} This should be used with great caution, and should
3245only be necessary on some old machines. GRUB's BIOS probe can pick up
3246all @sc{ram} on all new machines the author has ever heard of. It can
3247also be used for debugging purposes to lie to an OS.
3248@end deffn
3249
3250
3251@node vbeprobe
3252@subsection vbeprobe
3253
3254@deffn Command vbeprobe [mode]
3255Probe VESA BIOS EXTENSION information. If the mode @var{mode} is
3256specified, show only the information about @var{mode}. Otherwise, this
3257command lists up available VBE modes on the screen. See also
3258@ref{testvbe}.
3259@end deffn
3260
3261
3262@node Troubleshooting
3263@chapter Error messages reported by GRUB
3264
3265This chapter describes error messages reported by GRUB when you
3266encounter trouble. @xref{Invoking the grub shell}, if your problem is
3267specific to the grub shell.
3268
3269@menu
3270* Stage1 errors::               Errors reported by the Stage 1
3271* Stage1.5 errors::             Errors reported by the Stage 1.5
3272* Stage2 errors::               Errors reported by the Stage 2
3273@end menu
3274
3275
3276@node Stage1 errors
3277@section Errors reported by the Stage 1
3278
3279The general way that the Stage 1 handles errors is to print an error
3280string and then halt. Pressing @kbd{@key{CTRL}-@key{ALT}-@key{DEL}} will
3281reboot.
3282
3283The following is a comprehensive list of error messages for the Stage 1:
3284
3285@table @asis
3286@item Hard Disk Error
3287The stage2 or stage1.5 is being read from a hard disk, and the attempt
3288to determine the size and geometry of the hard disk failed.
3289
3290@item Floppy Error
3291The stage2 or stage1.5 is being read from a floppy disk, and the attempt
3292to determine the size and geometry of the floppy disk failed. It's listed
3293as a separate error since the probe sequence is different than for hard
3294disks.
3295
3296@item Read Error
3297A disk read error happened while trying to read the stage2 or stage1.5.
3298
3299@item Geom Error
3300The location of the stage2 or stage1.5 is not in the portion of the disk
3301supported directly by the BIOS read calls.  This could occur because the
3302BIOS translated geometry has been changed by the user or the disk is
3303moved to another machine or controller after installation, or GRUB was
3304not installed using itself (if it was, the Stage 2 version of this error
3305would have been seen during that process and it would not have completed
3306the install).
3307@end table
3308
3309
3310@node Stage1.5 errors
3311@section Errors reported by the Stage 1.5
3312
3313The general way that the Stage 1.5 handles errors is to print an error
3314number in the form @code{Error @var{num}} and then halt. Pressing
3315@kbd{@key{CTRL}-@key{ALT}-@key{DEL}} will reboot.
3316
3317The error numbers correspond to the errors reported by Stage
33182. @xref{Stage2 errors}.
3319
3320
3321@node Stage2 errors
3322@section Errors reported by the Stage 2
3323
3324The general way that the Stage 2 handles errors is to abort the
3325operation in question, print an error string, then (if possible) either
3326continue based on the fact that an error occurred or wait for the user to
3327deal with the error.
3328
3329The following is a comprehensive list of error messages for the Stage 2
3330(error numbers for the Stage 1.5 are listed before the colon in each
3331description):
3332
3333@table @asis
3334@item 1 : Filename must be either an absolute filename or blocklist
3335This error is returned if a file name is requested which doesn't fit the
3336syntax/rules listed in the @ref{Filesystem}.
3337
3338@item 2 : Bad file or directory type
3339This error is returned if a file requested is not a regular file, but
3340something like a symbolic link, directory, or FIFO.
3341
3342@item 3 : Bad or corrupt data while decompressing file
3343This error is returned if the run-length decompression code gets an
3344internal error. This is usually from a corrupt file.
3345
3346@item 4 : Bad or incompatible header in compressed file
3347This error is returned if the file header for a supposedly compressed
3348file is bad.
3349
3350@item 5 : Partition table invalid or corrupt
3351This error is returned if the sanity checks on the integrity of the
3352partition table fail. This is a bad sign.
3353
3354@item 6 : Mismatched or corrupt version of stage1/stage2
3355This error is returned if the install command points to incompatible
3356or corrupt versions of the stage1 or stage2. It can't detect corruption
3357in general, but this is a sanity check on the version numbers, which
3358should be correct.
3359
3360@item 7 : Loading below 1MB is not supported
3361This error is returned if the lowest address in a kernel is below the
33621MB boundary. The Linux zImage format is a special case and can be
3363handled since it has a fixed loading address and maximum size.
3364
3365@item 8 : Kernel must be loaded before booting
3366This error is returned if GRUB is told to execute the boot sequence
3367without having a kernel to start.
3368
3369@item 9 : Unknown boot failure
3370This error is returned if the boot attempt did not succeed for reasons
3371which are unknown.
3372
3373@item 10 : Unsupported Multiboot features requested
3374This error is returned when the Multiboot features word in the Multiboot
3375header requires a feature that is not recognized. The point of this is
3376that the kernel requires special handling which GRUB is probably
3377unable to provide.
3378
3379@item 11 : Unrecognized device string
3380This error is returned if a device string was expected, and the string
3381encountered didn't fit the syntax/rules listed in the @ref{Filesystem}.
3382
3383@item 12 : Invalid device requested
3384This error is returned if a device string is recognizable but does not
3385fall under the other device errors.
3386
3387@item 13 : Invalid or unsupported executable format
3388This error is returned if the kernel image being loaded is not
3389recognized as Multiboot or one of the supported native formats (Linux
3390zImage or bzImage, FreeBSD, or NetBSD).
3391
3392@item 14 : Filesystem compatibility error, cannot read whole file
3393Some of the filesystem reading code in GRUB has limits on the length of
3394the files it can read. This error is returned when the user runs into
3395such a limit.
3396
3397@item 15 : File not found
3398This error is returned if the specified file name cannot be found, but
3399everything else (like the disk/partition info) is OK.
3400
3401@item 16 : Inconsistent filesystem structure
3402This error is returned by the filesystem code to denote an internal
3403error caused by the sanity checks of the filesystem structure on disk
3404not matching what it expects. This is usually caused by a corrupt
3405filesystem or bugs in the code handling it in GRUB.
3406
3407@item 17 : Cannot mount selected partition
3408This error is returned if the partition requested exists, but the
3409filesystem type cannot be recognized by GRUB.
3410
3411@item 18 : Selected cylinder exceeds maximum supported by BIOS
3412This error is returned when a read is attempted at a linear block
3413address beyond the end of the BIOS translated area. This generally
3414happens if your disk is larger than the BIOS can handle (512MB for
3415(E)IDE disks on older machines or larger than 8GB in general).
3416
3417@item 19 : Linux kernel must be loaded before initrd
3418This error is returned if the initrd command is used before loading a
3419Linux kernel.
3420
3421@item 20 : Multiboot kernel must be loaded before modules
3422This error is returned if the module load command is used before loading
3423a Multiboot kernel. It only makes sense in this case anyway, as GRUB has
3424no idea how to communicate the presence of such modules to a
3425non-Multiboot-aware kernel.
3426
3427@item 21 : Selected disk does not exist
3428This error is returned if the device part of a device- or full file name
3429refers to a disk or BIOS device that is not present or not recognized by
3430the BIOS in the system.
3431
3432@item 22 : No such partition
3433This error is returned if a partition is requested in the device part of
3434a device- or full file name which isn't on the selected disk.
3435
3436@item 23 : Error while parsing number
3437This error is returned if GRUB was expecting to read a number and
3438encountered bad data.
3439
3440@item 24 : Attempt to access block outside partition
3441This error is returned if a linear block address is outside of the disk
3442partition. This generally happens because of a corrupt filesystem on the
3443disk or a bug in the code handling it in GRUB (it's a great debugging
3444tool).
3445
3446@item 25 : Disk read error
3447This error is returned if there is a disk read error when trying to
3448probe or read data from a particular disk.
3449
3450@item 26 : Too many symbolic links
3451This error is returned if the link count is beyond the maximum
3452(currently 5), possibly the symbolic links are looped.
3453
3454@item 27 : Unrecognized command
3455This error is returned if an unrecognized command is entered on the
3456command-line or in a boot sequence section of a configuration file and
3457that entry is selected.
3458
3459@item 28 : Selected item cannot fit into memory
3460This error is returned if a kernel, module, or raw file load command is
3461either trying to load its data such that it won't fit into memory or it
3462is simply too big.
3463
3464@item 29 : Disk write error
3465This error is returned if there is a disk write error when trying to
3466write to a particular disk. This would generally only occur during an
3467install of set active partition command.
3468
3469@item 30 : Invalid argument
3470This error is returned if an argument specified to a command is invalid.
3471
3472@item 31 : File is not sector aligned
3473This error may occur only when you access a ReiserFS partition by
3474block-lists (e.g. the command @command{install}). In this case, you
3475should mount the partition with the @samp{-o notail} option.
3476
3477@item 32 : Must be authenticated
3478This error is returned if you try to run a locked entry. You should
3479enter a correct password before running such an entry.
3480
3481@item 33 : Serial device not configured
3482This error is returned if you try to change your terminal to a serial
3483one before initializing any serial device.
3484
3485@item 34 : No spare sectors on the disk
3486This error is returned if a disk doesn't have enough spare space. This
3487happens when you try to embed Stage 1.5 into the unused sectors after
3488the MBR, but the first partition starts right after the MBR or they are
3489used by EZ-BIOS.
3490@end table
3491
3492
3493@node Invoking the grub shell
3494@chapter Invoking the grub shell
3495
3496This chapter documents the grub shell @command{grub}. Note that the grub
3497shell is an emulator; it doesn't run under the native environment, so it
3498sometimes does something wrong. Therefore, you shouldn't trust it too
3499much. If there is anything wrong with it, don't hesitate to try the
3500native GRUB environment, especially when it guesses a wrong map between
3501BIOS drives and OS devices.
3502
3503@menu
3504* Basic usage::                 How to use the grub shell
3505* Installation under UNIX::     How to install GRUB via @command{grub}
3506* Device map::                  The map between BIOS drives and OS devices
3507@end menu
3508
3509
3510@node Basic usage
3511@section Introduction into the grub shell
3512
3513You can use the command @command{grub} for installing GRUB under your
3514operating systems and for a testbed when you add a new feature into GRUB
3515or when fixing a bug. @command{grub} is almost the same as the Stage 2,
3516and, in fact, it shares the source code with the Stage 2 and you can use
3517the same commands (@pxref{Commands}) in @command{grub}. It is emulated by
3518replacing BIOS calls with UNIX system calls and libc functions.
3519
3520The command @command{grub} accepts the following options:
3521
3522@table @option
3523@item --help
3524Print a summary of the command-line options and exit.
3525
3526@item --version
3527Print the version number of GRUB and exit.
3528
3529@item --verbose
3530Print some verbose messages for debugging purpose.
3531
3532@item --device-map=@var{file}
3533Use the device map file @var{file}. The format is described in
3534@ref{Device map}.
3535
3536@item --no-floppy
3537Do not probe any floppy drive. This option has no effect if the option
3538@option{--device-map} is specified (@pxref{Device map}).
3539
3540@item --probe-second-floppy
3541Probe the second floppy drive. If this option is not specified, the grub
3542shell does not probe it, as that sometimes takes a long time. If you
3543specify the device map file (@pxref{Device map}), the grub shell just
3544ignores this option.
3545
3546@item --config-file=@var{file}
3547Read the configuration file @var{file} instead of
3548@file{/boot/grub/menu.lst}. The format is the same as the normal GRUB
3549syntax. See @ref{Filesystem}, for more information.
3550
3551@item --boot-drive=@var{drive}
3552Set the stage2 @var{boot_drive} to @var{drive}. This argument should be
3553an integer (decimal, octal or hexadecimal).
3554
3555@item --install-partition=@var{par}
3556Set the stage2 @var{install_partition} to @var{par}. This argument
3557should be an integer (decimal, octal or hexadecimal).
3558
3559@item --no-config-file
3560Do not use the configuration file even if it can be read.
3561
3562@item --no-curses
3563Do not use the screen handling interface by the curses even if it is
3564available.
3565
3566@item --batch
3567This option has the same meaning as @samp{--no-config-file --no-curses}.
3568
3569@item --read-only
3570Disable writing to any disk.
3571
3572@item --hold
3573Wait until a debugger will attach. This option is useful when you want
3574to debug the startup code.
3575@end table
3576
3577
3578@node Installation under UNIX
3579@section How to install GRUB via @command{grub}
3580
3581The installation procedure is the same as under the @dfn{native} Stage
35822. @xref{Installation}, for more information. The command
3583@command{grub}-specific information is described here.
3584
3585What you should be careful about is @dfn{buffer cache}. @command{grub}
3586makes use of raw devices instead of filesystems that your operating
3587systems serve, so there exists a potential problem that some cache
3588inconsistency may corrupt your filesystems. What we recommend is:
3589
3590@itemize @bullet
3591@item
3592If you can unmount drives to which GRUB may write any amount of data,
3593unmount them before running @command{grub}.
3594
3595@item
3596If a drive cannot be unmounted but can be mounted with the read-only
3597flag, mount it in read-only mode. That should be secure.
3598
3599@item
3600If a drive must be mounted with the read-write flag, make sure that no
3601activity is being done on it while the command @command{grub} is
3602running.
3603
3604@item
3605Reboot your operating system as soon as possible. This is probably not
3606required if you follow the rules above, but reboot is the most secure
3607way.
3608@end itemize
3609
3610In addition, enter the command @command{quit} when you finish the
3611installation. That is @emph{very important} because @command{quit} makes
3612the buffer cache consistent. Do not push @key{C-c}.
3613
3614If you want to install GRUB non-interactively, specify @samp{--batch}
3615option in the command-line. This is a simple example:
3616
3617@example
3618@group
3619#!/bin/sh
3620
3621# Use /usr/sbin/grub if you are on an older system.
3622/sbin/grub --batch <<EOT 1>/dev/null 2>/dev/null
3623root (hd0,0)
3624setup (hd0)
3625quit
3626EOT
3627@end group
3628@end example
3629
3630
3631@node Device map
3632@section The map between BIOS drives and OS devices
3633
3634When you specify the option @option{--device-map} (@pxref{Basic usage}),
3635the grub shell creates the @dfn{device map file} automatically unless it
3636already exists. The file name @file{/boot/grub/device.map} is preferred.
3637
3638If the device map file exists, the grub shell reads it to map BIOS
3639drives to OS devices. This file consists of lines like this:
3640
3641@example
3642@var{device} @var{file}
3643@end example
3644
3645@var{device} is a drive specified in the GRUB syntax (@pxref{Device
3646syntax}), and @var{file} is an OS file, which is normally a device
3647file.
3648
3649The reason why the grub shell gives you the device map file is that it
3650cannot guess the map between BIOS drives and OS devices correctly in
3651some environments. For example, if you exchange the boot sequence
3652between IDE and SCSI in your BIOS, it gets the order wrong.
3653
3654Thus, edit the file if the grub shell makes a mistake. You can put any
3655comments in the file if needed, as the grub shell assumes that a line is
3656just a comment if the first character is @samp{#}.
3657
3658
3659@node Invoking grub-install
3660@chapter Invoking grub-install
3661
3662The program @command{grub-install} installs GRUB on your drive using the
3663grub shell (@pxref{Invoking the grub shell}). You must specify the
3664device name on which you want to install GRUB, like this:
3665
3666@example
3667grub-install @var{install_device}
3668@end example
3669
3670The device name @var{install_device} is an OS device name or a GRUB
3671device name.
3672
3673@command{grub-install} accepts the following options:
3674
3675@table @option
3676@item --help
3677Print a summary of the command-line options and exit.
3678
3679@item --version
3680Print the version number of GRUB and exit.
3681
3682@item --force-lba
3683Force GRUB to use LBA mode even for a buggy BIOS. Use this option only
3684if your BIOS doesn't work properly in LBA mode even though it supports
3685LBA mode.
3686
3687@item --root-directory=@var{dir}
3688Install GRUB images under the directory @var{dir} instead of the root
3689directory. This option is useful when you want to install GRUB into a
3690separate partition or a removable disk. Here is an example in which
3691you have a separate @dfn{boot} partition which is mounted on
3692@file{/boot}:
3693
3694@example
3695@kbd{grub-install --root-directory=/boot hd0}
3696@end example
3697
3698@item --grub-shell=@var{file}
3699Use @var{file} as the grub shell. You can append arbitrary options to
3700@var{file} after the file name, like this:
3701
3702@example
3703@kbd{grub-install --grub-shell="grub --read-only" /dev/fd0}
3704@end example
3705
3706@item --recheck
3707Recheck the device map, even if @file{/boot/grub/device.map} already
3708exists. You should use this option whenever you add/remove a disk
3709into/from your computer.
3710@end table
3711
3712
3713@node Invoking grub-md5-crypt
3714@chapter Invoking grub-md5-crypt
3715
3716The program @command{grub-md5-crypt} encrypts a password in MD5 format.
3717This is just a frontend of the grub shell (@pxref{Invoking the grub
3718shell}). Passwords encrypted by this program can be used with the
3719command @command{password} (@pxref{password}).
3720
3721@command{grub-md5-crypt} accepts the following options:
3722
3723@table @option
3724@item --help
3725Print a summary of the command-line options and exit.
3726
3727@item --version
3728Print the version information and exit.
3729
3730@item --grub-shell=@var{file}
3731Use @var{file} as the grub shell.
3732@end table
3733
3734
3735@node Invoking grub-terminfo
3736@chapter Invoking grub-terminfo
3737
3738The program @command{grub-terminfo} generates a terminfo command from
3739a terminfo name (@pxref{terminfo}). The result can be used in the
3740configuration file, to define escape sequences. Because GRUB assumes
3741that your terminal is vt100-compatible by default, this would be
3742useful only if your terminal is uncommon (such as vt52).
3743
3744@command{grub-terminfo} accepts the following options:
3745
3746@table @option
3747@item --help
3748Print a summary of the command-line options and exit.
3749
3750@item --version
3751Print the version information and exit.
3752@end table
3753
3754You must specify one argument to this command. For example:
3755
3756@example
3757@kbd{grub-terminfo vt52}
3758@end example
3759
3760
3761@node Invoking grub-set-default
3762@chapter Invoking grub-set-default
3763
3764The program @command{grub-set-default} sets the default boot entry for
3765GRUB. This automatically creates a file named @file{default} under
3766your GRUB directory (i.e. @file{/boot/grub}), if it is not
3767present. This file is used to determine the default boot entry when
3768GRUB boots up your system when you use @samp{default saved} in your
3769configuration file (@pxref{default}), and to save next default boot
3770entry when you use @samp{savedefault} in a boot entry
3771(@pxref{savedefault}).
3772
3773@command{grub-set-default} accepts the following options:
3774
3775@table @option
3776@item --help
3777Print a summary of the command-line options and exit.
3778
3779@item --version
3780Print the version information and exit.
3781
3782@item --root-directory=@var{dir}
3783Use the directory @var{dir} instead of the root directory
3784(i.e. @file{/}) to define the location of the default file. This
3785is useful when you mount a disk which is used for another system.
3786@end table
3787
3788You must specify a single argument to @command{grub-set-default}. This
3789argument is normally the number of a default boot entry. For example,
3790if you have this configuration file:
3791
3792@example
3793@group
3794default saved
3795timeout 10
3796
3797title GNU/Hurd
3798root (hd0,0)
3799...
3800
3801title GNU/Linux
3802root (hd0,1)
3803...
3804@end group
3805@end example
3806
3807and if you want to set the next default boot entry to GNU/Linux, you
3808may execute this command:
3809
3810@example
3811@kbd{grub-set-default 1}
3812@end example
3813
3814Because the entry for GNU/Linux is @samp{1}. Note that entries are
3815counted from zero. So, if you want to specify GNU/Hurd here, then you
3816should specify @samp{0}.
3817
3818This feature is very useful if you want to test a new kernel or to
3819make your system quite robust. @xref{Making your system robust}, for
3820more hints about how to set up a robust system.
3821
3822
3823@node Invoking mbchk
3824@chapter Invoking mbchk
3825
3826The program @command{mbchk} checks for the format of a Multiboot
3827kernel. We recommend using this program before booting your own kernel
3828by GRUB.
3829
3830@command{mbchk} accepts the following options:
3831
3832@table @option
3833@item --help
3834Print a summary of the command-line options and exit.
3835
3836@item --version
3837Print the version number of GRUB and exit.
3838
3839@item --quiet
3840Suppress all normal output.
3841@end table
3842
3843
3844@node Obtaining and Building GRUB
3845@appendix How to obtain and build GRUB
3846
3847@quotation
3848@strong{Caution:} GRUB requires binutils-2.9.1.0.23 or later because the
3849GNU assembler has been changed so that it can produce real 16bits
3850machine code between 2.9.1 and 2.9.1.0.x. See
3851@uref{http://sources.redhat.com/binutils/}, to obtain information on
3852how to get the latest version.
3853@end quotation
3854
3855GRUB is available from the GNU alpha archive site
3856@uref{ftp://alpha.gnu.org/gnu/grub} or any of its mirrors. The file
3857will be named grub-version.tar.gz. The current version is
3858@value{VERSION}, so the file you should grab is:
3859
3860@uref{ftp://alpha.gnu.org/gnu/grub/grub-@value{VERSION}.tar.gz}
3861
3862To unbundle GRUB use the instruction:
3863
3864@example
3865@kbd{zcat grub-@value{VERSION}.tar.gz | tar xvf -}
3866@end example
3867
3868which will create a directory called @file{grub-@value{VERSION}} with
3869all the sources. You can look at the file @file{INSTALL} for detailed
3870instructions on how to build and install GRUB, but you should be able to
3871just do:
3872
3873@example
3874@group
3875@kbd{cd grub-@value{VERSION}}
3876@kbd{./configure}
3877@kbd{make install}
3878@end group
3879@end example
3880
3881This will install the grub shell @file{grub} (@pxref{Invoking the grub
3882shell}), the Multiboot checker @file{mbchk} (@pxref{Invoking mbchk}),
3883and the GRUB images. This will also install the GRUB manual.
3884
3885Also, the latest version is available from the CVS. See
3886@uref{http://savannah.gnu.org/cvs/?group=grub} for more information.
3887
3888
3889@node Reporting bugs
3890@appendix Reporting bugs
3891
3892These are the guideline for how to report bugs. Take a look at this
3893list below before you submit bugs:
3894
3895@enumerate
3896@item
3897Before getting unsettled, read this manual through and through. Also,
3898see the @uref{http://www.gnu.org/software/grub/grub-faq.html, GNU GRUB FAQ}.
3899
3900@item
3901Always mention the information on your GRUB. The version number and the
3902configuration are quite important. If you build it yourself, write the
3903options specified to the configure script and your operating system,
3904including the versions of gcc and binutils.
3905
3906@item
3907If you have trouble with the installation, inform us of how you
3908installed GRUB. Don't omit error messages, if any. Just @samp{GRUB hangs
3909up when it boots} is not enough.
3910
3911The information on your hardware is also essential. These are especially
3912important: the geometries and the partition tables of your hard disk
3913drives and your BIOS.
3914
3915@item
3916If GRUB cannot boot your operating system, write down
3917@emph{everything} you see on the screen. Don't paraphrase them, like
3918@samp{The foo OS crashes with GRUB, even though it can boot with the
3919bar boot loader just fine}. Mention the commands you executed, the
3920messages printed by them, and information on your operating system
3921including the version number.
3922
3923@item
3924Explain what you wanted to do. It is very useful to know your purpose
3925and your wish, and how GRUB didn't satisfy you.
3926
3927@item
3928If you can investigate the problem yourself, please do. That will give
3929you and us much more information on the problem. Attaching a patch is
3930even better.
3931
3932When you attach a patch, make the patch in unified diff format, and
3933write ChangeLog entries. But, even when you make a patch, don't forget
3934to explain the problem, so that we can understand what your patch is
3935for.
3936
3937@item
3938Write down anything that you think might be related. Please understand
3939that we often need to reproduce the same problem you encounterred in our
3940environment. So your information should be sufficient for us to do the
3941same thing---Don't forget that we cannot see your computer directly. If
3942you are not sure whether to state a fact or leave it out, state it!
3943Reporting too many things is much better than omitting something
3944important.
3945@end enumerate
3946
3947If you follow the guideline above, submit a report to the
3948@uref{http://savannah.gnu.org/bugs/?group=grub, Bug Tracking System}.
3949Alternatively, you can submit a report via electronic mail to
3950@email{bug-grub@@gnu.org}, but we strongly recommend that you use the
3951Bug Tracking System, because e-mail can be passed over easily.
3952
3953Once we get your report, we will try to fix the bugs.
3954
3955
3956@node Future
3957@appendix Where GRUB will go
3958
3959We started the next generation of GRUB, GRUB 2. This will include
3960internationalization, dynamic module loading, real memory management,
3961multiple architecture support, a scripting language, and many other
3962nice feature. If you are interested in the development of GRUB 2, take
3963a look at @uref{http://www.gnu.org/software/grub/grub.html, the
3964homepage}.
3965
3966
3967@c Separate the programming guide.
3968@include internals.texi
3969
3970
3971@node Index
3972@unnumbered Index
3973
3974@c Currently, we use only the Concept Index.
3975@printindex cp
3976
3977
3978@bye
3979
3980Some notes:
3981
3982  This is the second attempt to rewrite the manual. The status is
3983mostly complete, but I need to check the spelling by ispell, and add
3984more indices. Perhaps I also have to let some English native speakers
3985proofread this manual through. My English is syntactically almost
3986perfect, but sometimes (often?) awful in the nuance. Hehe, I can't be an
3987English poet for now.
3988