17c478bd9Sstevel@tonic-gate\input texinfo
27c478bd9Sstevel@tonic-gate@c -*-texinfo-*-
37c478bd9Sstevel@tonic-gate@c %**start of header
47c478bd9Sstevel@tonic-gate@setfilename grub.info
57c478bd9Sstevel@tonic-gate@settitle GRUB Manual
67c478bd9Sstevel@tonic-gate@c %**end of header
77c478bd9Sstevel@tonic-gate
87c478bd9Sstevel@tonic-gate@include version.texi
97c478bd9Sstevel@tonic-gate
107c478bd9Sstevel@tonic-gate@c Unify all our little indices for now.
117c478bd9Sstevel@tonic-gate@syncodeindex fn cp
127c478bd9Sstevel@tonic-gate@syncodeindex vr cp
137c478bd9Sstevel@tonic-gate@syncodeindex ky cp
147c478bd9Sstevel@tonic-gate@syncodeindex pg cp
157c478bd9Sstevel@tonic-gate@syncodeindex tp cp
167c478bd9Sstevel@tonic-gate
177c478bd9Sstevel@tonic-gate@footnotestyle separate
187c478bd9Sstevel@tonic-gate@paragraphindent 3
197c478bd9Sstevel@tonic-gate@finalout
207c478bd9Sstevel@tonic-gate
217c478bd9Sstevel@tonic-gate@dircategory Kernel
227c478bd9Sstevel@tonic-gate@direntry
237c478bd9Sstevel@tonic-gate* GRUB: (grub).                 The GRand Unified Bootloader
247c478bd9Sstevel@tonic-gate* grub-install: (grub)Invoking grub-install.    Install GRUB on your drive
257c478bd9Sstevel@tonic-gate* grub-md5-crypt: (grub)Invoking grub-md5-crypt.        Encrypt a password
267c478bd9Sstevel@tonic-gate                                                        in MD5 format
277c478bd9Sstevel@tonic-gate* grub-terminfo: (grub)Invoking grub-terminfo.  Generate a terminfo
287c478bd9Sstevel@tonic-gate                                                command from a
297c478bd9Sstevel@tonic-gate                                                terminfo name
307c478bd9Sstevel@tonic-gate* grub-set-default: (grub)Invoking grub-set-default.    Set a default boot
317c478bd9Sstevel@tonic-gate                                                        entry
327c478bd9Sstevel@tonic-gate* mbchk: (grub)Invoking mbchk.  Check for the format of a Multiboot kernel
337c478bd9Sstevel@tonic-gate@end direntry
347c478bd9Sstevel@tonic-gate
357c478bd9Sstevel@tonic-gate@setchapternewpage odd
367c478bd9Sstevel@tonic-gate
377c478bd9Sstevel@tonic-gate@ifinfo
387c478bd9Sstevel@tonic-gateCopyright @copyright{} 1999,2000,2001,2002,2004 Free Software Foundation, Inc.
397c478bd9Sstevel@tonic-gate
407c478bd9Sstevel@tonic-gatePermission is granted to make and distribute verbatim copies of
417c478bd9Sstevel@tonic-gatethis manual provided the copyright notice and this permission notice
427c478bd9Sstevel@tonic-gateare preserved on all copies.
437c478bd9Sstevel@tonic-gate
447c478bd9Sstevel@tonic-gate@ignore
457c478bd9Sstevel@tonic-gatePermission is granted to process this file through TeX and print the
467c478bd9Sstevel@tonic-gateresults, provided the printed document carries a copying permission
477c478bd9Sstevel@tonic-gatenotice identical to this one except for the removal of this paragraph
487c478bd9Sstevel@tonic-gate(this paragraph not being relevant to the printed manual).
497c478bd9Sstevel@tonic-gate
507c478bd9Sstevel@tonic-gate@end ignore
517c478bd9Sstevel@tonic-gate
527c478bd9Sstevel@tonic-gatePermission is granted to copy and distribute modified versions of this
537c478bd9Sstevel@tonic-gatemanual under the conditions for verbatim copying, provided also that
547c478bd9Sstevel@tonic-gatethe entire resulting derived work is distributed under the terms of a
557c478bd9Sstevel@tonic-gatepermission notice identical to this one.
567c478bd9Sstevel@tonic-gate
577c478bd9Sstevel@tonic-gatePermission is granted to copy and distribute translations of this manual
587c478bd9Sstevel@tonic-gateinto another language, under the above conditions for modified versions.
597c478bd9Sstevel@tonic-gate@end ifinfo
607c478bd9Sstevel@tonic-gate
617c478bd9Sstevel@tonic-gate@titlepage
627c478bd9Sstevel@tonic-gate@sp 10
637c478bd9Sstevel@tonic-gate@title the GRUB manual
647c478bd9Sstevel@tonic-gate@subtitle The GRand Unified Bootloader, version @value{VERSION}, @value{UPDATED}.
657c478bd9Sstevel@tonic-gate@author Gordon Matzigkeit
667c478bd9Sstevel@tonic-gate@author Yoshinori K. Okuji
677c478bd9Sstevel@tonic-gate@c The following two commands start the copyright page.
687c478bd9Sstevel@tonic-gate@page
697c478bd9Sstevel@tonic-gate@vskip 0pt plus 1filll
707c478bd9Sstevel@tonic-gateCopyright @copyright{} 1999,2000,2001,2002,2004 Free Software Foundation, Inc.
717c478bd9Sstevel@tonic-gate
727c478bd9Sstevel@tonic-gatePermission is granted to make and distribute verbatim copies of
737c478bd9Sstevel@tonic-gatethis manual provided the copyright notice and this permission notice
747c478bd9Sstevel@tonic-gateare preserved on all copies.
757c478bd9Sstevel@tonic-gatePermission is granted to copy and distribute modified versions of this
767c478bd9Sstevel@tonic-gatemanual under the conditions for verbatim copying, provided that the entire
777c478bd9Sstevel@tonic-gateresulting derived work is distributed under the terms of a permission
787c478bd9Sstevel@tonic-gatenotice identical to this one.
797c478bd9Sstevel@tonic-gate
807c478bd9Sstevel@tonic-gatePermission is granted to copy and distribute translations of this manual
817c478bd9Sstevel@tonic-gateinto another language, under the above conditions for modified versions,
827c478bd9Sstevel@tonic-gateexcept that this permission notice may be stated in a translation approved
837c478bd9Sstevel@tonic-gateby Free Software Foundation.
847c478bd9Sstevel@tonic-gate@end titlepage
857c478bd9Sstevel@tonic-gate
867c478bd9Sstevel@tonic-gate@c Output the table of contents at the beginning.
877c478bd9Sstevel@tonic-gate@contents
887c478bd9Sstevel@tonic-gate
897c478bd9Sstevel@tonic-gate@finalout
907c478bd9Sstevel@tonic-gate@headings double
917c478bd9Sstevel@tonic-gate
927c478bd9Sstevel@tonic-gate@ifnottex
937c478bd9Sstevel@tonic-gate@node Top
947c478bd9Sstevel@tonic-gate@top GRUB manual
957c478bd9Sstevel@tonic-gate
967c478bd9Sstevel@tonic-gateThis is the documentation of GNU GRUB, the GRand Unified Bootloader,
977c478bd9Sstevel@tonic-gatea flexible and powerful boot loader program for @sc{pc}s.
987c478bd9Sstevel@tonic-gate
997c478bd9Sstevel@tonic-gateThis edition documents version @value{VERSION}.
1007c478bd9Sstevel@tonic-gate@end ifnottex
1017c478bd9Sstevel@tonic-gate
1027c478bd9Sstevel@tonic-gate@menu
1037c478bd9Sstevel@tonic-gate* Introduction::                Capturing the spirit of GRUB
1047c478bd9Sstevel@tonic-gate* Naming convention::           Names of your drives in GRUB
1057c478bd9Sstevel@tonic-gate* Installation::                Installing GRUB on your drive
1067c478bd9Sstevel@tonic-gate* Booting::                     How to boot different operating systems
1077c478bd9Sstevel@tonic-gate* Configuration::               Writing your own configuration file
1087c478bd9Sstevel@tonic-gate* Network::                     Downloading OS images from a network
1097c478bd9Sstevel@tonic-gate* Serial terminal::             Using GRUB via a serial line
1107c478bd9Sstevel@tonic-gate* Preset Menu::                 Embedding a configuration file into GRUB
1117c478bd9Sstevel@tonic-gate* Security::                    Improving the security
1127c478bd9Sstevel@tonic-gate* Images::                      GRUB image files
1137c478bd9Sstevel@tonic-gate* Filesystem::                  Filesystem syntax and semantics
1147c478bd9Sstevel@tonic-gate* Interface::                   The menu and the command-line
1157c478bd9Sstevel@tonic-gate* Commands::                    The list of available builtin commands
1167c478bd9Sstevel@tonic-gate* Troubleshooting::             Error messages produced by GRUB
1177c478bd9Sstevel@tonic-gate* Invoking the grub shell::     How to use the grub shell
1187c478bd9Sstevel@tonic-gate* Invoking grub-install::       How to use the GRUB installer
1197c478bd9Sstevel@tonic-gate* Invoking grub-md5-crypt::     How to generate a cryptic password
1207c478bd9Sstevel@tonic-gate* Invoking grub-terminfo::      How to generate a terminfo command
1217c478bd9Sstevel@tonic-gate* Invoking grub-set-default::   How to set a default boot entry
1227c478bd9Sstevel@tonic-gate* Invoking mbchk::              How to use the Multiboot checker
1237c478bd9Sstevel@tonic-gate* Obtaining and Building GRUB:: How to obtain and build GRUB
1247c478bd9Sstevel@tonic-gate* Reporting bugs::              Where you should send a bug report
1257c478bd9Sstevel@tonic-gate* Future::                      Some future plans on GRUB
1267c478bd9Sstevel@tonic-gate* Internals::                   Hacking GRUB
1277c478bd9Sstevel@tonic-gate* Index::
1287c478bd9Sstevel@tonic-gate@end menu
1297c478bd9Sstevel@tonic-gate
1307c478bd9Sstevel@tonic-gate
1317c478bd9Sstevel@tonic-gate@node Introduction
1327c478bd9Sstevel@tonic-gate@chapter Introduction to GRUB
1337c478bd9Sstevel@tonic-gate
1347c478bd9Sstevel@tonic-gate@menu
1357c478bd9Sstevel@tonic-gate* Overview::                    What exactly GRUB is and how to use it
1367c478bd9Sstevel@tonic-gate* History::                     From maggot to house fly
1377c478bd9Sstevel@tonic-gate* Features::                    GRUB features
1387c478bd9Sstevel@tonic-gate* Role of a boot loader::       The role of a boot loader
1397c478bd9Sstevel@tonic-gate@end menu
1407c478bd9Sstevel@tonic-gate
1417c478bd9Sstevel@tonic-gate
1427c478bd9Sstevel@tonic-gate@node Overview
1437c478bd9Sstevel@tonic-gate@section Overview
1447c478bd9Sstevel@tonic-gate
1457c478bd9Sstevel@tonic-gateBriefly, a @dfn{boot loader} is the first software program that runs when
1467c478bd9Sstevel@tonic-gatea computer starts.  It is responsible for loading and transferring
1477c478bd9Sstevel@tonic-gatecontrol to an operating system @dfn{kernel} software (such as Linux or
1487c478bd9Sstevel@tonic-gateGNU Mach).  The kernel, in turn, initializes the rest of the operating
1497c478bd9Sstevel@tonic-gatesystem (e.g. a GNU system).
1507c478bd9Sstevel@tonic-gate
1517c478bd9Sstevel@tonic-gateGNU GRUB is a very powerful boot loader, which can load a wide variety
1527c478bd9Sstevel@tonic-gateof free operating systems, as well as proprietary operating systems with
1537c478bd9Sstevel@tonic-gatechain-loading@footnote{@dfn{chain-load} is the mechanism for loading
1547c478bd9Sstevel@tonic-gateunsupported operating systems by loading another boot loader. It is
1557c478bd9Sstevel@tonic-gatetypically used for loading DOS or Windows.}. GRUB is designed to
1567c478bd9Sstevel@tonic-gateaddress the complexity of booting a personal computer; both the
1577c478bd9Sstevel@tonic-gateprogram and this manual are tightly bound to that computer platform,
1587c478bd9Sstevel@tonic-gatealthough porting to other platforms may be addressed in the future.
1597c478bd9Sstevel@tonic-gate
1607c478bd9Sstevel@tonic-gateOne of the important features in GRUB is flexibility; GRUB understands
1617c478bd9Sstevel@tonic-gatefilesystems and kernel executable formats, so you can load an arbitrary
1627c478bd9Sstevel@tonic-gateoperating system the way you like, without recording the physical
1637c478bd9Sstevel@tonic-gateposition of your kernel on the disk. Thus you can load the kernel
1647c478bd9Sstevel@tonic-gatejust by specifying its file name and the drive and partition where the
1657c478bd9Sstevel@tonic-gatekernel resides.
1667c478bd9Sstevel@tonic-gate
1677c478bd9Sstevel@tonic-gateWhen booting with GRUB, you can use either a command-line interface
1687c478bd9Sstevel@tonic-gate(@pxref{Command-line interface}), or a menu interface (@pxref{Menu
1697c478bd9Sstevel@tonic-gateinterface}). Using the command-line interface, you type the drive
1707c478bd9Sstevel@tonic-gatespecification and file name of the kernel manually. In the menu
1717c478bd9Sstevel@tonic-gateinterface, you just select an OS using the arrow keys. The menu is
1727c478bd9Sstevel@tonic-gatebased on a configuration file which you prepare beforehand
1737c478bd9Sstevel@tonic-gate(@pxref{Configuration}). While in the menu, you can switch to the
1747c478bd9Sstevel@tonic-gatecommand-line mode, and vice-versa. You can even edit menu entries
1757c478bd9Sstevel@tonic-gatebefore using them.
1767c478bd9Sstevel@tonic-gate
1777c478bd9Sstevel@tonic-gateIn the following chapters, you will learn how to specify a drive, a
1787c478bd9Sstevel@tonic-gatepartition, and a file name (@pxref{Naming convention}) to GRUB, how to
1797c478bd9Sstevel@tonic-gateinstall GRUB on your drive (@pxref{Installation}), and how to boot your
1807c478bd9Sstevel@tonic-gateOSes (@pxref{Booting}), step by step.
1817c478bd9Sstevel@tonic-gate
1827c478bd9Sstevel@tonic-gateBesides the GRUB boot loader itself, there is a @dfn{grub shell}
1837c478bd9Sstevel@tonic-gate@command{grub} (@pxref{Invoking the grub shell}) which can be run when
1847c478bd9Sstevel@tonic-gateyou are in your operating system. It emulates the boot loader and can
1857c478bd9Sstevel@tonic-gatebe used for installing the boot loader.
1867c478bd9Sstevel@tonic-gate
1877c478bd9Sstevel@tonic-gate
1887c478bd9Sstevel@tonic-gate@node History
1897c478bd9Sstevel@tonic-gate@section History of GRUB
1907c478bd9Sstevel@tonic-gate
1917c478bd9Sstevel@tonic-gateGRUB originated in 1995 when Erich Boleyn was trying to boot the GNU
1927c478bd9Sstevel@tonic-gateHurd with the University of Utah's Mach 4 microkernel (now known as GNU
1937c478bd9Sstevel@tonic-gateMach).  Erich and Brian Ford designed the Multiboot Specification
1947c478bd9Sstevel@tonic-gate(@pxref{Top, Multiboot Specification, Motivation, multiboot, The Multiboot
1957c478bd9Sstevel@tonic-gateSpecification}), because they were determined not to add to the large
1967c478bd9Sstevel@tonic-gatenumber of mutually-incompatible PC boot methods.
1977c478bd9Sstevel@tonic-gate
1987c478bd9Sstevel@tonic-gateErich then began modifying the FreeBSD boot loader so that it would
1997c478bd9Sstevel@tonic-gateunderstand Multiboot. He soon realized that it would be a lot easier
2007c478bd9Sstevel@tonic-gateto write his own boot loader from scratch than to keep working on the
2017c478bd9Sstevel@tonic-gateFreeBSD boot loader, and so GRUB was born.
2027c478bd9Sstevel@tonic-gate
2037c478bd9Sstevel@tonic-gateErich added many features to GRUB, but other priorities prevented him
2047c478bd9Sstevel@tonic-gatefrom keeping up with the demands of its quickly-expanding user base. In
2057c478bd9Sstevel@tonic-gate1999, Gordon Matzigkeit and Yoshinori K. Okuji adopted GRUB as an
2067c478bd9Sstevel@tonic-gateofficial GNU package, and opened its development by making the latest
2077c478bd9Sstevel@tonic-gatesources available via anonymous CVS. @xref{Obtaining and Building
2087c478bd9Sstevel@tonic-gateGRUB}, for more information.
2097c478bd9Sstevel@tonic-gate
2107c478bd9Sstevel@tonic-gate
2117c478bd9Sstevel@tonic-gate@node Features
2127c478bd9Sstevel@tonic-gate@section GRUB features
2137c478bd9Sstevel@tonic-gate
2147c478bd9Sstevel@tonic-gateThe primary requirement for GRUB is that it be compliant with the
2157c478bd9Sstevel@tonic-gate@dfn{Multiboot Specification}, which is described in @ref{Top, Multiboot
2167c478bd9Sstevel@tonic-gateSpecification, Motivation, multiboot, The Multiboot Specification}.
2177c478bd9Sstevel@tonic-gate
2187c478bd9Sstevel@tonic-gateThe other goals, listed in approximate order of importance, are:
2197c478bd9Sstevel@tonic-gate
2207c478bd9Sstevel@tonic-gate@itemize @bullet{}
2217c478bd9Sstevel@tonic-gate@item
2227c478bd9Sstevel@tonic-gateBasic functions must be straightforward for end-users.
2237c478bd9Sstevel@tonic-gate
2247c478bd9Sstevel@tonic-gate@item
2257c478bd9Sstevel@tonic-gateRich functionality to support kernel experts and designers.
2267c478bd9Sstevel@tonic-gate
2277c478bd9Sstevel@tonic-gate@item
2287c478bd9Sstevel@tonic-gateBackward compatibility for booting FreeBSD, NetBSD, OpenBSD, and
2297c478bd9Sstevel@tonic-gateLinux. Proprietary kernels (such as DOS, Windows NT, and OS/2) are
2307c478bd9Sstevel@tonic-gatesupported via a chain-loading function.
2317c478bd9Sstevel@tonic-gate@end itemize
2327c478bd9Sstevel@tonic-gate
2337c478bd9Sstevel@tonic-gateExcept for specific compatibility modes (chain-loading and the Linux
2347c478bd9Sstevel@tonic-gate@dfn{piggyback} format), all kernels will be started in much the same
2357c478bd9Sstevel@tonic-gatestate as in the Multiboot Specification. Only kernels loaded at 1 megabyte
2367c478bd9Sstevel@tonic-gateor above are presently supported. Any attempt to load below that
2377c478bd9Sstevel@tonic-gateboundary will simply result in immediate failure and an error message
2387c478bd9Sstevel@tonic-gatereporting the problem.
2397c478bd9Sstevel@tonic-gate
2407c478bd9Sstevel@tonic-gateIn addition to the requirements above, GRUB has the following features
2417c478bd9Sstevel@tonic-gate(note that the Multiboot Specification doesn't require all the features
2427c478bd9Sstevel@tonic-gatethat GRUB supports):
2437c478bd9Sstevel@tonic-gate
2447c478bd9Sstevel@tonic-gate@table @asis
2457c478bd9Sstevel@tonic-gate@item Recognize multiple executable formats
2467c478bd9Sstevel@tonic-gateSupport many of the @dfn{a.out} variants plus @dfn{ELF}. Symbol
2477c478bd9Sstevel@tonic-gatetables are also loaded.
2487c478bd9Sstevel@tonic-gate
2497c478bd9Sstevel@tonic-gate@item Support non-Multiboot kernels
2507c478bd9Sstevel@tonic-gateSupport many of the various free 32-bit kernels that lack Multiboot
2517c478bd9Sstevel@tonic-gatecompliance (primarily FreeBSD, NetBSD, OpenBSD, and
2527c478bd9Sstevel@tonic-gateLinux). Chain-loading of other boot loaders is also supported.
2537c478bd9Sstevel@tonic-gate
2547c478bd9Sstevel@tonic-gate@item Load multiples modules
2557c478bd9Sstevel@tonic-gateFully support the Multiboot feature of loading multiple modules.
2567c478bd9Sstevel@tonic-gate
2577c478bd9Sstevel@tonic-gate@item Load a configuration file
2587c478bd9Sstevel@tonic-gateSupport a human-readable text configuration file with preset boot
2597c478bd9Sstevel@tonic-gatecommands. You can also load another configuration file dynamically and
2607c478bd9Sstevel@tonic-gateembed a preset configuration file in a GRUB image file. The list of
2617c478bd9Sstevel@tonic-gatecommands (@pxref{Commands}) are a superset of those supported on the
2627c478bd9Sstevel@tonic-gatecommand-line. An example configuration file is provided in
2637c478bd9Sstevel@tonic-gate@ref{Configuration}.
2647c478bd9Sstevel@tonic-gate
2657c478bd9Sstevel@tonic-gate@item Provide a menu interface
2667c478bd9Sstevel@tonic-gateA menu interface listing preset boot commands, with a programmable
2677c478bd9Sstevel@tonic-gatetimeout, is available. There is no fixed limit on the number of boot
2687c478bd9Sstevel@tonic-gateentries, and the current implementation has space for several hundred.
2697c478bd9Sstevel@tonic-gate
2707c478bd9Sstevel@tonic-gate@item Have a flexible command-line interface
2717c478bd9Sstevel@tonic-gateA fairly flexible command-line interface, accessible from the menu,
2727c478bd9Sstevel@tonic-gateis available to edit any preset commands, or write a new boot command
2737c478bd9Sstevel@tonic-gateset from scratch. If no configuration file is present, GRUB drops to
2747c478bd9Sstevel@tonic-gatethe command-line.
2757c478bd9Sstevel@tonic-gate
2767c478bd9Sstevel@tonic-gateThe list of commands (@pxref{Commands}) are a subset of those supported
2777c478bd9Sstevel@tonic-gatefor configuration files. Editing commands closely resembles the Bash
2787c478bd9Sstevel@tonic-gatecommand-line (@pxref{Command Line Editing, Bash, Command Line Editing,
2797c478bd9Sstevel@tonic-gatefeatures, Bash Features}), with @key{TAB}-completion of commands,
2807c478bd9Sstevel@tonic-gatedevices, partitions, and files in a directory depending on context.
2817c478bd9Sstevel@tonic-gate
2827c478bd9Sstevel@tonic-gate@item Support multiple filesystem types
2837c478bd9Sstevel@tonic-gateSupport multiple filesystem types transparently, plus a useful explicit
2847c478bd9Sstevel@tonic-gateblocklist notation. The currently supported filesystem types are
2857c478bd9Sstevel@tonic-gate@dfn{BSD FFS}, @dfn{DOS FAT16 and FAT32}, @dfn{Minix fs}, @dfn{Linux
2867c478bd9Sstevel@tonic-gateext2fs}, @dfn{ReiserFS}, @dfn{JFS}, @dfn{XFS}, and @dfn{VSTa
2877c478bd9Sstevel@tonic-gatefs}. @xref{Filesystem}, for more information.
2887c478bd9Sstevel@tonic-gate
2897c478bd9Sstevel@tonic-gate@item Support automatic decompression
2907c478bd9Sstevel@tonic-gateCan decompress files which were compressed by @command{gzip}. This
2917c478bd9Sstevel@tonic-gatefunction is both automatic and transparent to the user (i.e. all
2927c478bd9Sstevel@tonic-gatefunctions operate upon the uncompressed contents of the specified
2937c478bd9Sstevel@tonic-gatefiles). This greatly reduces a file size and loading time, a
2947c478bd9Sstevel@tonic-gateparticularly great benefit for floppies.@footnote{There are a few
2957c478bd9Sstevel@tonic-gatepathological cases where loading a very badly organized ELF kernel might
2967c478bd9Sstevel@tonic-gatetake longer, but in practice this never happen.}
2977c478bd9Sstevel@tonic-gate
2987c478bd9Sstevel@tonic-gateIt is conceivable that some kernel modules should be loaded in a
2997c478bd9Sstevel@tonic-gatecompressed state, so a different module-loading command can be specified
3007c478bd9Sstevel@tonic-gateto avoid uncompressing the modules.
3017c478bd9Sstevel@tonic-gate
3027c478bd9Sstevel@tonic-gate@item Access data on any installed device
3037c478bd9Sstevel@tonic-gateSupport reading data from any or all floppies or hard disk(s) recognized
3047c478bd9Sstevel@tonic-gateby the BIOS, independent of the setting of the root device.
3057c478bd9Sstevel@tonic-gate
3067c478bd9Sstevel@tonic-gate@item Be independent of drive geometry translations
3077c478bd9Sstevel@tonic-gateUnlike many other boot loaders, GRUB makes the particular drive
3087c478bd9Sstevel@tonic-gatetranslation irrelevant. A drive installed and running with one
3097c478bd9Sstevel@tonic-gatetranslation may be converted to another translation without any adverse
3107c478bd9Sstevel@tonic-gateeffects or changes in GRUB's configuration.
3117c478bd9Sstevel@tonic-gate
3127c478bd9Sstevel@tonic-gate@item Detect all installed @sc{ram}
3137c478bd9Sstevel@tonic-gateGRUB can generally find all the installed @sc{ram} on a PC-compatible
3147c478bd9Sstevel@tonic-gatemachine. It uses an advanced BIOS query technique for finding all
3157c478bd9Sstevel@tonic-gatememory regions. As described on the Multiboot Specification (@pxref{Top,
3167c478bd9Sstevel@tonic-gateMultiboot Specification, Motivation, multiboot, The Multiboot
3177c478bd9Sstevel@tonic-gateSpecification}), not all kernels make use of this information, but GRUB
3187c478bd9Sstevel@tonic-gateprovides it for those who do.
3197c478bd9Sstevel@tonic-gate
3207c478bd9Sstevel@tonic-gate@item Support Logical Block Address mode
3217c478bd9Sstevel@tonic-gateIn traditional disk calls (called @dfn{CHS mode}), there is a geometry
3227c478bd9Sstevel@tonic-gatetranslation problem, that is, the BIOS cannot access over 1024
3237c478bd9Sstevel@tonic-gatecylinders, so the accessible space is limited to at least 508 MB and to
3247c478bd9Sstevel@tonic-gateat most 8GB. GRUB can't universally solve this problem, as there is no
3257c478bd9Sstevel@tonic-gatestandard interface used in all machines. However, several newer machines
3267c478bd9Sstevel@tonic-gatehave the new interface, Logical Block Address (@dfn{LBA}) mode. GRUB
3277c478bd9Sstevel@tonic-gateautomatically detects if LBA mode is available and uses it if
3287c478bd9Sstevel@tonic-gateavailable. In LBA mode, GRUB can access the entire disk.
3297c478bd9Sstevel@tonic-gate
3307c478bd9Sstevel@tonic-gate@item Support network booting
3317c478bd9Sstevel@tonic-gateGRUB is basically a disk-based boot loader but also has network
3327c478bd9Sstevel@tonic-gatesupport. You can load OS images from a network by using the @dfn{TFTP}
3337c478bd9Sstevel@tonic-gateprotocol.
3347c478bd9Sstevel@tonic-gate
3357c478bd9Sstevel@tonic-gate@item Support remote terminals
3367c478bd9Sstevel@tonic-gateTo support computers with no console, GRUB provides remote terminal
3377c478bd9Sstevel@tonic-gatesupport, so that you can control GRUB from a remote host. Only serial
3387c478bd9Sstevel@tonic-gateterminal support is implemented at the moment.
3397c478bd9Sstevel@tonic-gate@end table
3407c478bd9Sstevel@tonic-gate
3417c478bd9Sstevel@tonic-gate
3427c478bd9Sstevel@tonic-gate@node Role of a boot loader
3437c478bd9Sstevel@tonic-gate@section The role of a boot loader
3447c478bd9Sstevel@tonic-gate
3457c478bd9Sstevel@tonic-gateThe following is a quotation from Gordon Matzigkeit, a GRUB fanatic:
3467c478bd9Sstevel@tonic-gate
3477c478bd9Sstevel@tonic-gate@quotation
3487c478bd9Sstevel@tonic-gateSome people like to acknowledge both the operating system and kernel when
3497c478bd9Sstevel@tonic-gatethey talk about their computers, so they might say they use
3507c478bd9Sstevel@tonic-gate``GNU/Linux'' or ``GNU/Hurd''.  Other people seem to think that the
3517c478bd9Sstevel@tonic-gatekernel is the most important part of the system, so they like to call
3527c478bd9Sstevel@tonic-gatetheir GNU operating systems ``Linux systems.''
3537c478bd9Sstevel@tonic-gate
3547c478bd9Sstevel@tonic-gateI, personally, believe that this is a grave injustice, because the
3557c478bd9Sstevel@tonic-gate@emph{boot loader} is the most important software of all. I used to
3567c478bd9Sstevel@tonic-gaterefer to the above systems as either ``LILO''@footnote{The LInux LOader,
3577c478bd9Sstevel@tonic-gatea boot loader that everybody uses, but nobody likes.} or ``GRUB''
3587c478bd9Sstevel@tonic-gatesystems.
3597c478bd9Sstevel@tonic-gate
3607c478bd9Sstevel@tonic-gateUnfortunately, nobody ever understood what I was talking about; now I
3617c478bd9Sstevel@tonic-gatejust use the word ``GNU'' as a pseudonym for GRUB.
3627c478bd9Sstevel@tonic-gate
3637c478bd9Sstevel@tonic-gateSo, if you ever hear people talking about their alleged ``GNU'' systems,
3647c478bd9Sstevel@tonic-gateremember that they are actually paying homage to the best boot loader
3657c478bd9Sstevel@tonic-gatearound@dots{} GRUB!
3667c478bd9Sstevel@tonic-gate@end quotation
3677c478bd9Sstevel@tonic-gate
3687c478bd9Sstevel@tonic-gateWe, the GRUB maintainers, do not (usually) encourage Gordon's level of
3697c478bd9Sstevel@tonic-gatefanaticism, but it helps to remember that boot loaders deserve
3707c478bd9Sstevel@tonic-gaterecognition.  We hope that you enjoy using GNU GRUB as much as we did
3717c478bd9Sstevel@tonic-gatewriting it.
3727c478bd9Sstevel@tonic-gate
3737c478bd9Sstevel@tonic-gate
3747c478bd9Sstevel@tonic-gate@node Naming convention
3757c478bd9Sstevel@tonic-gate@chapter Naming convention
3767c478bd9Sstevel@tonic-gate
3777c478bd9Sstevel@tonic-gateThe device syntax used in GRUB is a wee bit different from what you may
3787c478bd9Sstevel@tonic-gatehave seen before in your operating system(s), and you need to know it so
3797c478bd9Sstevel@tonic-gatethat you can specify a drive/partition.
3807c478bd9Sstevel@tonic-gate
3817c478bd9Sstevel@tonic-gateLook at the following examples and explanations:
3827c478bd9Sstevel@tonic-gate
3837c478bd9Sstevel@tonic-gate@example
3847c478bd9Sstevel@tonic-gate(fd0)
3857c478bd9Sstevel@tonic-gate@end example
3867c478bd9Sstevel@tonic-gate
3877c478bd9Sstevel@tonic-gateFirst of all, GRUB requires that the device name be enclosed with
3887c478bd9Sstevel@tonic-gate@samp{(} and @samp{)}. The @samp{fd} part means that it is a floppy
3897c478bd9Sstevel@tonic-gatedisk. The number @samp{0} is the drive number, which is counted from
3907c478bd9Sstevel@tonic-gate@emph{zero}. This expression means that GRUB will use the whole floppy
3917c478bd9Sstevel@tonic-gatedisk.
3927c478bd9Sstevel@tonic-gate
3937c478bd9Sstevel@tonic-gate@example
3947c478bd9Sstevel@tonic-gate(hd0,1)
3957c478bd9Sstevel@tonic-gate@end example
3967c478bd9Sstevel@tonic-gate
3977c478bd9Sstevel@tonic-gateHere, @samp{hd} means it is a hard disk drive. The first integer
3987c478bd9Sstevel@tonic-gate@samp{0} indicates the drive number, that is, the first hard disk, while
3997c478bd9Sstevel@tonic-gatethe second integer, @samp{1}, indicates the partition number (or the
4007c478bd9Sstevel@tonic-gate@sc{pc} slice number in the BSD terminology). Once again, please note
4017c478bd9Sstevel@tonic-gatethat the partition numbers are counted from @emph{zero}, not from
4027c478bd9Sstevel@tonic-gateone. This expression means the second partition of the first hard disk
4037c478bd9Sstevel@tonic-gatedrive. In this case, GRUB uses one partition of the disk, instead of the
4047c478bd9Sstevel@tonic-gatewhole disk.
4057c478bd9Sstevel@tonic-gate
4067c478bd9Sstevel@tonic-gate@example
4077c478bd9Sstevel@tonic-gate(hd0,4)
4087c478bd9Sstevel@tonic-gate@end example
4097c478bd9Sstevel@tonic-gate
4107c478bd9Sstevel@tonic-gateThis specifies the first @dfn{extended partition} of the first hard disk
4117c478bd9Sstevel@tonic-gatedrive. Note that the partition numbers for extended partitions are
4127c478bd9Sstevel@tonic-gatecounted from @samp{4}, regardless of the actual number of primary
4137c478bd9Sstevel@tonic-gatepartitions on your hard disk.
4147c478bd9Sstevel@tonic-gate
4157c478bd9Sstevel@tonic-gate@example
4167c478bd9Sstevel@tonic-gate(hd1,a)
4177c478bd9Sstevel@tonic-gate@end example
4187c478bd9Sstevel@tonic-gate
4197c478bd9Sstevel@tonic-gateThis means the BSD @samp{a} partition of the second hard disk. If you
4207c478bd9Sstevel@tonic-gateneed to specify which @sc{pc} slice number should be used, use something
4217c478bd9Sstevel@tonic-gatelike this: @samp{(hd1,0,a)}. If the @sc{pc} slice number is omitted,
4227c478bd9Sstevel@tonic-gateGRUB searches for the first @sc{pc} slice which has a BSD @samp{a}
4237c478bd9Sstevel@tonic-gatepartition.
4247c478bd9Sstevel@tonic-gate
4257c478bd9Sstevel@tonic-gateOf course, to actually access the disks or partitions with GRUB, you
4267c478bd9Sstevel@tonic-gateneed to use the device specification in a command, like @samp{root
4277c478bd9Sstevel@tonic-gate(fd0)} or @samp{unhide (hd0,2)}. To help you find out which number
4287c478bd9Sstevel@tonic-gatespecifies a partition you want, the GRUB command-line
4297c478bd9Sstevel@tonic-gate(@pxref{Command-line interface}) options have argument
4307c478bd9Sstevel@tonic-gatecompletion. This means that, for example, you only need to type
4317c478bd9Sstevel@tonic-gate
4327c478bd9Sstevel@tonic-gate@example
4337c478bd9Sstevel@tonic-gateroot (
4347c478bd9Sstevel@tonic-gate@end example
4357c478bd9Sstevel@tonic-gate
4367c478bd9Sstevel@tonic-gatefollowed by a @key{TAB}, and GRUB will display the list of drives,
4377c478bd9Sstevel@tonic-gatepartitions, or file names. So it should be quite easy to determine the
4387c478bd9Sstevel@tonic-gatename of your target partition, even with minimal knowledge of the
4397c478bd9Sstevel@tonic-gatesyntax.
4407c478bd9Sstevel@tonic-gate
4417c478bd9Sstevel@tonic-gateNote that GRUB does @emph{not} distinguish IDE from SCSI - it simply
4427c478bd9Sstevel@tonic-gatecounts the drive numbers from zero, regardless of their type. Normally,
4437c478bd9Sstevel@tonic-gateany IDE drive number is less than any SCSI drive number, although that
4447c478bd9Sstevel@tonic-gateis not true if you change the boot sequence by swapping IDE and SCSI
4457c478bd9Sstevel@tonic-gatedrives in your BIOS.
4467c478bd9Sstevel@tonic-gate
4477c478bd9Sstevel@tonic-gateNow the question is, how to specify a file? Again, consider an
4487c478bd9Sstevel@tonic-gateexample:
4497c478bd9Sstevel@tonic-gate
4507c478bd9Sstevel@tonic-gate@example
4517c478bd9Sstevel@tonic-gate(hd0,0)/vmlinuz
4527c478bd9Sstevel@tonic-gate@end example
4537c478bd9Sstevel@tonic-gate
4547c478bd9Sstevel@tonic-gateThis specifies the file named @samp{vmlinuz}, found on the first
4557c478bd9Sstevel@tonic-gatepartition of the first hard disk drive. Note that the argument
4567c478bd9Sstevel@tonic-gatecompletion works with file names, too.
4577c478bd9Sstevel@tonic-gate
4587c478bd9Sstevel@tonic-gateThat was easy, admit it. Now read the next chapter, to find out how to
4597c478bd9Sstevel@tonic-gateactually install GRUB on your drive.
4607c478bd9Sstevel@tonic-gate
4617c478bd9Sstevel@tonic-gate
4627c478bd9Sstevel@tonic-gate@node Installation
4637c478bd9Sstevel@tonic-gate@chapter Installation
4647c478bd9Sstevel@tonic-gate
4657c478bd9Sstevel@tonic-gateIn order to install GRUB as your boot loader, you need to first
4667c478bd9Sstevel@tonic-gateinstall the GRUB system and utilities under your UNIX-like operating
4677c478bd9Sstevel@tonic-gatesystem (@pxref{Obtaining and Building GRUB}). You can do this either
4687c478bd9Sstevel@tonic-gatefrom the source tarball, or as a package for your OS.
4697c478bd9Sstevel@tonic-gate
4707c478bd9Sstevel@tonic-gateAfter you have done that, you need to install the boot loader on a
4717c478bd9Sstevel@tonic-gatedrive (floppy or hard disk). There are two ways of doing that - either
4727c478bd9Sstevel@tonic-gateusing the utility @command{grub-install} (@pxref{Invoking
4737c478bd9Sstevel@tonic-gategrub-install}) on a UNIX-like OS, or by running GRUB itself from a
4747c478bd9Sstevel@tonic-gatefloppy. These are quite similar, however the utility might probe a
4757c478bd9Sstevel@tonic-gatewrong BIOS drive, so you should be careful.
4767c478bd9Sstevel@tonic-gate
4777c478bd9Sstevel@tonic-gateAlso, if you install GRUB on a UNIX-like OS, please make sure that you
4787c478bd9Sstevel@tonic-gatehave an emergency boot disk ready, so that you can rescue your computer
4797c478bd9Sstevel@tonic-gateif, by any chance, your hard drive becomes unusable (unbootable).
4807c478bd9Sstevel@tonic-gate
4817c478bd9Sstevel@tonic-gateGRUB comes with boot images, which are normally put in the directory
4827c478bd9Sstevel@tonic-gate@file{/usr/lib/grub/i386-pc}. If you do not use grub-install, then
4837c478bd9Sstevel@tonic-gateyou need to copy the files @file{stage1}, @file{stage2}, and
4847c478bd9Sstevel@tonic-gate@file{*stage1_5} to the directory @file{/boot/grub}, and run the
4857c478bd9Sstevel@tonic-gate@command{grub-set-default} (@pxref{Invoking grub-set-default}) if you
4867c478bd9Sstevel@tonic-gateintend to use @samp{default saved} (@pxref{default}) in your
4877c478bd9Sstevel@tonic-gateconfiguration file. Hereafter, the directory where GRUB images are
4887c478bd9Sstevel@tonic-gateinitially placed (normally @file{/usr/lib/grub/i386-pc}) will be
4897c478bd9Sstevel@tonic-gatecalled the @dfn{image directory}, and the directory where the boot
4907c478bd9Sstevel@tonic-gateloader needs to find them (usually @file{/boot/grub}) will be called
4917c478bd9Sstevel@tonic-gatethe @dfn{boot directory}.
4927c478bd9Sstevel@tonic-gate
4937c478bd9Sstevel@tonic-gate@menu
4947c478bd9Sstevel@tonic-gate* Creating a GRUB boot floppy::
4957c478bd9Sstevel@tonic-gate* Installing GRUB natively::
4967c478bd9Sstevel@tonic-gate* Installing GRUB using grub-install::
4977c478bd9Sstevel@tonic-gate* Making a GRUB bootable CD-ROM::
4987c478bd9Sstevel@tonic-gate@end menu
4997c478bd9Sstevel@tonic-gate
5007c478bd9Sstevel@tonic-gate
5017c478bd9Sstevel@tonic-gate@node Creating a GRUB boot floppy
5027c478bd9Sstevel@tonic-gate@section Creating a GRUB boot floppy
5037c478bd9Sstevel@tonic-gate
5047c478bd9Sstevel@tonic-gateTo create a GRUB boot floppy, you need to take the files @file{stage1}
5057c478bd9Sstevel@tonic-gateand @file{stage2} from the image directory, and write them to the first
5067c478bd9Sstevel@tonic-gateand the second block of the floppy disk, respectively.
5077c478bd9Sstevel@tonic-gate
5087c478bd9Sstevel@tonic-gate@strong{Caution:} This procedure will destroy any data currently stored
5097c478bd9Sstevel@tonic-gateon the floppy.
5107c478bd9Sstevel@tonic-gate
5117c478bd9Sstevel@tonic-gateOn a UNIX-like operating system, that is done with the following
5127c478bd9Sstevel@tonic-gatecommands:
5137c478bd9Sstevel@tonic-gate
5147c478bd9Sstevel@tonic-gate@example
5157c478bd9Sstevel@tonic-gate@group
5167c478bd9Sstevel@tonic-gate# @kbd{cd /usr/lib/grub/i386-pc}
5177c478bd9Sstevel@tonic-gate# @kbd{dd if=stage1 of=/dev/fd0 bs=512 count=1}
5187c478bd9Sstevel@tonic-gate1+0 records in
5197c478bd9Sstevel@tonic-gate1+0 records out
5207c478bd9Sstevel@tonic-gate# @kbd{dd if=stage2 of=/dev/fd0 bs=512 seek=1}
5217c478bd9Sstevel@tonic-gate153+1 records in
5227c478bd9Sstevel@tonic-gate153+1 records out
5237c478bd9Sstevel@tonic-gate#
5247c478bd9Sstevel@tonic-gate@end group
5257c478bd9Sstevel@tonic-gate@end example
5267c478bd9Sstevel@tonic-gate
5277c478bd9Sstevel@tonic-gateThe device file name may be different. Consult the manual for your OS.
5287c478bd9Sstevel@tonic-gate
5297c478bd9Sstevel@tonic-gate
5307c478bd9Sstevel@tonic-gate@node Installing GRUB natively
5317c478bd9Sstevel@tonic-gate@section Installing GRUB natively
5327c478bd9Sstevel@tonic-gate
5337c478bd9Sstevel@tonic-gate@strong{Caution:} Installing GRUB's stage1 in this manner will erase the
5347c478bd9Sstevel@tonic-gatenormal boot-sector used by an OS.
5357c478bd9Sstevel@tonic-gate
5367c478bd9Sstevel@tonic-gateGRUB can currently boot GNU Mach, Linux, FreeBSD, NetBSD, and OpenBSD
5377c478bd9Sstevel@tonic-gatedirectly, so using it on a boot sector (the first sector of a
5387c478bd9Sstevel@tonic-gatepartition) should be okay. But generally, it would be a good idea to
5397c478bd9Sstevel@tonic-gateback up the first sector of the partition on which you are installing
5407c478bd9Sstevel@tonic-gateGRUB's stage1. This isn't as important if you are installing GRUB on
5417c478bd9Sstevel@tonic-gatethe first sector of a hard disk, since it's easy to reinitialize it
5427c478bd9Sstevel@tonic-gate(e.g. by running @samp{FDISK /MBR} from DOS).
5437c478bd9Sstevel@tonic-gate
5447c478bd9Sstevel@tonic-gateIf you decide to install GRUB in the native environment, which is
5457c478bd9Sstevel@tonic-gatedefinitely desirable, you'll need to create a GRUB boot disk, and
5467c478bd9Sstevel@tonic-gatereboot your computer with it. Otherwise, see @ref{Installing GRUB using
5477c478bd9Sstevel@tonic-gategrub-install}.
5487c478bd9Sstevel@tonic-gate
5497c478bd9Sstevel@tonic-gateOnce started, GRUB will show the command-line interface
5507c478bd9Sstevel@tonic-gate(@pxref{Command-line interface}). First, set the GRUB's @dfn{root
5517c478bd9Sstevel@tonic-gatedevice}@footnote{Note that GRUB's root device doesn't necessarily mean
5527c478bd9Sstevel@tonic-gateyour OS's root partition; if you need to specify a root partition for
5537c478bd9Sstevel@tonic-gateyour OS, add the argument into the command @command{kernel}.} to the
5547c478bd9Sstevel@tonic-gatepartition containing the boot directory, like this:
5557c478bd9Sstevel@tonic-gate
5567c478bd9Sstevel@tonic-gate@example
5577c478bd9Sstevel@tonic-gategrub> @kbd{root (hd0,0)}
5587c478bd9Sstevel@tonic-gate@end example
5597c478bd9Sstevel@tonic-gate
5607c478bd9Sstevel@tonic-gateIf you are not sure which partition actually holds this directory, use the
5617c478bd9Sstevel@tonic-gatecommand @command{find} (@pxref{find}), like this:
5627c478bd9Sstevel@tonic-gate
5637c478bd9Sstevel@tonic-gate@example
5647c478bd9Sstevel@tonic-gategrub> @kbd{find /boot/grub/stage1}
5657c478bd9Sstevel@tonic-gate@end example
5667c478bd9Sstevel@tonic-gate
5677c478bd9Sstevel@tonic-gateThis will search for the file name @file{/boot/grub/stage1} and show the
5687c478bd9Sstevel@tonic-gatedevices which contain the file.
5697c478bd9Sstevel@tonic-gate
5707c478bd9Sstevel@tonic-gateOnce you've set the root device correctly, run the command
5717c478bd9Sstevel@tonic-gate@command{setup} (@pxref{setup}):
5727c478bd9Sstevel@tonic-gate
5737c478bd9Sstevel@tonic-gate@example
5747c478bd9Sstevel@tonic-gategrub> @kbd{setup (hd0)}
5757c478bd9Sstevel@tonic-gate@end example
5767c478bd9Sstevel@tonic-gate
5777c478bd9Sstevel@tonic-gateThis command will install the GRUB boot loader on the Master Boot
5787c478bd9Sstevel@tonic-gateRecord (MBR) of the first drive. If you want to put GRUB into the boot
5797c478bd9Sstevel@tonic-gatesector of a partition instead of putting it in the MBR, specify the
5807c478bd9Sstevel@tonic-gatepartition into which you want to install GRUB:
5817c478bd9Sstevel@tonic-gate
5827c478bd9Sstevel@tonic-gate@example
5837c478bd9Sstevel@tonic-gategrub> @kbd{setup (hd0,0)}
5847c478bd9Sstevel@tonic-gate@end example
5857c478bd9Sstevel@tonic-gate
5867c478bd9Sstevel@tonic-gateIf you install GRUB into a partition or a drive other than the first
5877c478bd9Sstevel@tonic-gateone, you must chain-load GRUB from another boot loader. Refer to the
5887c478bd9Sstevel@tonic-gatemanual for the boot loader to know how to chain-load GRUB.
5897c478bd9Sstevel@tonic-gate
5907c478bd9Sstevel@tonic-gateAfter using the setup command, you will boot into GRUB without the
5917c478bd9Sstevel@tonic-gateGRUB floppy. See the chapter @ref{Booting} to find out how to boot
5927c478bd9Sstevel@tonic-gateyour operating systems from GRUB.
5937c478bd9Sstevel@tonic-gate
5947c478bd9Sstevel@tonic-gate
5957c478bd9Sstevel@tonic-gate@node Installing GRUB using grub-install
5967c478bd9Sstevel@tonic-gate@section Installing GRUB using grub-install
5977c478bd9Sstevel@tonic-gate
5987c478bd9Sstevel@tonic-gate@strong{Caution:} This procedure is definitely less safe, because
5997c478bd9Sstevel@tonic-gatethere are several ways in which your computer can become
6007c478bd9Sstevel@tonic-gateunbootable. For example, most operating systems don't tell GRUB how to
6017c478bd9Sstevel@tonic-gatemap BIOS drives to OS devices correctly---GRUB merely @dfn{guesses}
6027c478bd9Sstevel@tonic-gatethe mapping. This will succeed in most cases, but not
6037c478bd9Sstevel@tonic-gatealways. Therefore, GRUB provides you with a map file called the
6047c478bd9Sstevel@tonic-gate@dfn{device map}, which you must fix if it is wrong. @xref{Device
6057c478bd9Sstevel@tonic-gatemap}, for more details.
6067c478bd9Sstevel@tonic-gate
6077c478bd9Sstevel@tonic-gateIf you still do want to install GRUB under a UNIX-like OS (such
6087c478bd9Sstevel@tonic-gateas @sc{gnu}), invoke the program @command{grub-install} (@pxref{Invoking
6097c478bd9Sstevel@tonic-gategrub-install}) as the superuser (@dfn{root}).
6107c478bd9Sstevel@tonic-gate
6117c478bd9Sstevel@tonic-gateThe usage is basically very simple. You only need to specify one
6127c478bd9Sstevel@tonic-gateargument to the program, namely, where to install the boot loader. The
6137c478bd9Sstevel@tonic-gateargument can be either a device file (like @samp{/dev/hda}) or a
6147c478bd9Sstevel@tonic-gatepartition specified in GRUB's notation. For example, under Linux the
6157c478bd9Sstevel@tonic-gatefollowing will install GRUB into the MBR of the first IDE disk:
6167c478bd9Sstevel@tonic-gate
6177c478bd9Sstevel@tonic-gate@example
6187c478bd9Sstevel@tonic-gate# @kbd{grub-install /dev/hda}
6197c478bd9Sstevel@tonic-gate@end example
6207c478bd9Sstevel@tonic-gate
6217c478bd9Sstevel@tonic-gateLikewise, under GNU/Hurd, this has the same effect:
6227c478bd9Sstevel@tonic-gate
6237c478bd9Sstevel@tonic-gate@example
6247c478bd9Sstevel@tonic-gate# @kbd{grub-install /dev/hd0}
6257c478bd9Sstevel@tonic-gate@end example
6267c478bd9Sstevel@tonic-gate
6277c478bd9Sstevel@tonic-gateIf it is the first BIOS drive, this is the same as well:
6287c478bd9Sstevel@tonic-gate
6297c478bd9Sstevel@tonic-gate@example
6307c478bd9Sstevel@tonic-gate# @kbd{grub-install '(hd0)'}
6317c478bd9Sstevel@tonic-gate@end example
6327c478bd9Sstevel@tonic-gate
6337c478bd9Sstevel@tonic-gateOr you can omit the parentheses:
6347c478bd9Sstevel@tonic-gate
6357c478bd9Sstevel@tonic-gate@example
6367c478bd9Sstevel@tonic-gate# @kbd{grub-install hd0}
6377c478bd9Sstevel@tonic-gate@end example
6387c478bd9Sstevel@tonic-gate
6397c478bd9Sstevel@tonic-gateBut all the above examples assume that GRUB should use images under
6407c478bd9Sstevel@tonic-gatethe root directory. If you want GRUB to use images under a directory
6417c478bd9Sstevel@tonic-gateother than the root directory, you need to specify the option
6427c478bd9Sstevel@tonic-gate@option{--root-directory}. The typical usage is that you create a GRUB
6437c478bd9Sstevel@tonic-gateboot floppy with a filesystem. Here is an example:
6447c478bd9Sstevel@tonic-gate
6457c478bd9Sstevel@tonic-gate@example
6467c478bd9Sstevel@tonic-gate@group
6477c478bd9Sstevel@tonic-gate# @kbd{mke2fs /dev/fd0}
6487c478bd9Sstevel@tonic-gate# @kbd{mount -t ext2 /dev/fd0 /mnt}
6497c478bd9Sstevel@tonic-gate# @kbd{grub-install --root-directory=/mnt fd0}
6507c478bd9Sstevel@tonic-gate# @kbd{umount /mnt}
6517c478bd9Sstevel@tonic-gate@end group
6527c478bd9Sstevel@tonic-gate@end example
6537c478bd9Sstevel@tonic-gate
6547c478bd9Sstevel@tonic-gateAnother example is when you have a separate boot partition
6557c478bd9Sstevel@tonic-gatewhich is mounted at @file{/boot}. Since GRUB is a boot loader, it
6567c478bd9Sstevel@tonic-gatedoesn't know anything about mountpoints at all. Thus, you need to run
6577c478bd9Sstevel@tonic-gate@command{grub-install} like this:
6587c478bd9Sstevel@tonic-gate
6597c478bd9Sstevel@tonic-gate@example
6607c478bd9Sstevel@tonic-gate# @kbd{grub-install --root-directory=/boot /dev/hda}
6617c478bd9Sstevel@tonic-gate@end example
6627c478bd9Sstevel@tonic-gate
6637c478bd9Sstevel@tonic-gateBy the way, as noted above, it is quite difficult to guess BIOS drives
6647c478bd9Sstevel@tonic-gatecorrectly under a UNIX-like OS. Thus, @command{grub-install} will prompt
6657c478bd9Sstevel@tonic-gateyou to check if it could really guess the correct mappings, after the
6667c478bd9Sstevel@tonic-gateinstallation. The format is defined in @ref{Device map}. Please be
6677c478bd9Sstevel@tonic-gatequite careful. If the output is wrong, it is unlikely that your
6687c478bd9Sstevel@tonic-gatecomputer will be able to boot with no problem.
6697c478bd9Sstevel@tonic-gate
6707c478bd9Sstevel@tonic-gateNote that @command{grub-install} is actually just a shell script and the
6717c478bd9Sstevel@tonic-gatereal task is done by the grub shell @command{grub} (@pxref{Invoking the
6727c478bd9Sstevel@tonic-gategrub shell}). Therefore, you may run @command{grub} directly to install
6737c478bd9Sstevel@tonic-gateGRUB, without using @command{grub-install}. Don't do that, however,
6747c478bd9Sstevel@tonic-gateunless you are very familiar with the internals of GRUB. Installing a
6757c478bd9Sstevel@tonic-gateboot loader on a running OS may be extremely dangerous.
6767c478bd9Sstevel@tonic-gate
6777c478bd9Sstevel@tonic-gate
6787c478bd9Sstevel@tonic-gate@node Making a GRUB bootable CD-ROM
6797c478bd9Sstevel@tonic-gate@section Making a GRUB bootable CD-ROM
6807c478bd9Sstevel@tonic-gate
6817c478bd9Sstevel@tonic-gateGRUB supports the @dfn{no emulation mode} in the El Torito
6827c478bd9Sstevel@tonic-gatespecification@footnote{El Torito is a specification for bootable CD
6837c478bd9Sstevel@tonic-gateusing BIOS functions.}. This means that you can use the whole CD-ROM
6847c478bd9Sstevel@tonic-gatefrom GRUB and you don't have to make a floppy or hard disk image file,
6857c478bd9Sstevel@tonic-gatewhich can cause compatibility problems.
6867c478bd9Sstevel@tonic-gate
6877c478bd9Sstevel@tonic-gateFor booting from a CD-ROM, GRUB uses a special Stage 2 called
6887c478bd9Sstevel@tonic-gate@file{stage2_eltorito}. The only GRUB files you need to have in your
6897c478bd9Sstevel@tonic-gatebootable CD-ROM are this @file{stage2_eltorito} and optionally a config file
6907c478bd9Sstevel@tonic-gate@file{menu.lst}. You don't need to use @file{stage1} or @file{stage2},
6917c478bd9Sstevel@tonic-gatebecause El Torito is quite different from the standard boot process.
6927c478bd9Sstevel@tonic-gate
6937c478bd9Sstevel@tonic-gateHere is an example of procedures to make a bootable CD-ROM
6947c478bd9Sstevel@tonic-gateimage. First, make a top directory for the bootable image, say,
6957c478bd9Sstevel@tonic-gate@samp{iso}:
6967c478bd9Sstevel@tonic-gate
6977c478bd9Sstevel@tonic-gate@example
6987c478bd9Sstevel@tonic-gate$ @kbd{mkdir iso}
6997c478bd9Sstevel@tonic-gate@end example
7007c478bd9Sstevel@tonic-gate
7017c478bd9Sstevel@tonic-gateMake a directory for GRUB:
7027c478bd9Sstevel@tonic-gate
7037c478bd9Sstevel@tonic-gate@example
7047c478bd9Sstevel@tonic-gate$ @kbd{mkdir -p iso/boot/grub}
7057c478bd9Sstevel@tonic-gate@end example
7067c478bd9Sstevel@tonic-gate
7077c478bd9Sstevel@tonic-gateCopy the file @file{stage2_eltorito}:
7087c478bd9Sstevel@tonic-gate
7097c478bd9Sstevel@tonic-gate@example
7107c478bd9Sstevel@tonic-gate$ @kbd{cp /usr/lib/grub/i386-pc/stage2_eltorito iso/boot/grub}
7117c478bd9Sstevel@tonic-gate@end example
7127c478bd9Sstevel@tonic-gate
7137c478bd9Sstevel@tonic-gateIf desired, make the config file @file{menu.lst} under @file{iso/boot/grub}
7147c478bd9Sstevel@tonic-gate(@pxref{Configuration}), and copy any files and directories for the disc to the
7157c478bd9Sstevel@tonic-gatedirectory @file{iso/}.
7167c478bd9Sstevel@tonic-gate
7177c478bd9Sstevel@tonic-gateFinally, make a ISO9660 image file like this:
7187c478bd9Sstevel@tonic-gate
7197c478bd9Sstevel@tonic-gate@example
7207c478bd9Sstevel@tonic-gate$ @kbd{mkisofs -R -b boot/grub/stage2_eltorito -no-emul-boot \
7217c478bd9Sstevel@tonic-gate    -boot-load-size 4 -boot-info-table -o grub.iso iso}
7227c478bd9Sstevel@tonic-gate@end example
7237c478bd9Sstevel@tonic-gate
7247c478bd9Sstevel@tonic-gateThis produces a file named @file{grub.iso}, which then can be burned
7257c478bd9Sstevel@tonic-gateinto a CD (or a DVD).  @kbd{mkisofs} has already set up the disc to boot
7267c478bd9Sstevel@tonic-gatefrom the @kbd{boot/grub/stage2_eltorito} file, so there is no need to
7277c478bd9Sstevel@tonic-gatesetup GRUB on the disc.  (Note that the @kbd{-boot-load-size 4} bit is
7287c478bd9Sstevel@tonic-gaterequired for compatibility with the BIOS on many older machines.)
7297c478bd9Sstevel@tonic-gate
7307c478bd9Sstevel@tonic-gateYou can use the device @samp{(cd)} to access a CD-ROM in your
7317c478bd9Sstevel@tonic-gateconfig file. This is not required; GRUB automatically sets the root device
7327c478bd9Sstevel@tonic-gateto @samp{(cd)} when booted from a CD-ROM. It is only necessary to refer to
7337c478bd9Sstevel@tonic-gate@samp{(cd)} if you want to access other drives as well.
7347c478bd9Sstevel@tonic-gate
7357c478bd9Sstevel@tonic-gate
7367c478bd9Sstevel@tonic-gate@node Booting
7377c478bd9Sstevel@tonic-gate@chapter Booting
7387c478bd9Sstevel@tonic-gate
7397c478bd9Sstevel@tonic-gateGRUB can load Multiboot-compliant kernels in a consistent way,
7407c478bd9Sstevel@tonic-gatebut for some free operating systems you need to use some OS-specific
7417c478bd9Sstevel@tonic-gatemagic.
7427c478bd9Sstevel@tonic-gate
7437c478bd9Sstevel@tonic-gate@menu
7447c478bd9Sstevel@tonic-gate* General boot methods::        How to boot OSes with GRUB generally
7457c478bd9Sstevel@tonic-gate* OS-specific notes::           Notes on some operating systems
7467c478bd9Sstevel@tonic-gate* Making your system robust::   How to make your system robust
7477c478bd9Sstevel@tonic-gate@end menu
7487c478bd9Sstevel@tonic-gate
7497c478bd9Sstevel@tonic-gate
7507c478bd9Sstevel@tonic-gate@node General boot methods
7517c478bd9Sstevel@tonic-gate@section How to boot operating systems
7527c478bd9Sstevel@tonic-gate
7537c478bd9Sstevel@tonic-gateGRUB has two distinct boot methods. One of the two is to load an
7547c478bd9Sstevel@tonic-gateoperating system directly, and the other is to chain-load another boot
7557c478bd9Sstevel@tonic-gateloader which then will load an operating system actually. Generally
7567c478bd9Sstevel@tonic-gatespeaking, the former is more desirable, because you don't need to
7577c478bd9Sstevel@tonic-gateinstall or maintain other boot loaders and GRUB is flexible enough to
7587c478bd9Sstevel@tonic-gateload an operating system from an arbitrary disk/partition. However,
7597c478bd9Sstevel@tonic-gatethe latter is sometimes required, since GRUB doesn't support all the
7607c478bd9Sstevel@tonic-gateexisting operating systems natively.
7617c478bd9Sstevel@tonic-gate
7627c478bd9Sstevel@tonic-gate@menu
7637c478bd9Sstevel@tonic-gate* Loading an operating system directly::
7647c478bd9Sstevel@tonic-gate* Chain-loading::
7657c478bd9Sstevel@tonic-gate@end menu
7667c478bd9Sstevel@tonic-gate
7677c478bd9Sstevel@tonic-gate
7687c478bd9Sstevel@tonic-gate@node Loading an operating system directly
7697c478bd9Sstevel@tonic-gate@subsection How to boot an OS directly with GRUB
7707c478bd9Sstevel@tonic-gate
7717c478bd9Sstevel@tonic-gateMultiboot (@pxref{Top, Multiboot Specification, Motivation, multiboot,
7727c478bd9Sstevel@tonic-gateThe Multiboot Specification}) is the native format supported by GRUB.
7737c478bd9Sstevel@tonic-gateFor the sake of convenience, there is also support for Linux, FreeBSD,
7747c478bd9Sstevel@tonic-gateNetBSD and OpenBSD. If you want to boot other operating systems, you
7757c478bd9Sstevel@tonic-gatewill have to chain-load them (@pxref{Chain-loading}).
7767c478bd9Sstevel@tonic-gate
7777c478bd9Sstevel@tonic-gateGenerally, GRUB can boot any Multiboot-compliant OS in the following
7787c478bd9Sstevel@tonic-gatesteps:
7797c478bd9Sstevel@tonic-gate
7807c478bd9Sstevel@tonic-gate@enumerate
7817c478bd9Sstevel@tonic-gate@item
7827c478bd9Sstevel@tonic-gateSet GRUB's root device to the drive where the OS images are stored with
7837c478bd9Sstevel@tonic-gatethe command @command{root} (@pxref{root}).
7847c478bd9Sstevel@tonic-gate
7857c478bd9Sstevel@tonic-gate@item
7867c478bd9Sstevel@tonic-gateLoad the kernel image with the command @command{kernel} (@pxref{kernel}).
7877c478bd9Sstevel@tonic-gate
7887c478bd9Sstevel@tonic-gate@item
7897c478bd9Sstevel@tonic-gateIf you need modules, load them with the command @command{module}
7907c478bd9Sstevel@tonic-gate(@pxref{module}) or @command{modulenounzip} (@pxref{modulenounzip}).
7917c478bd9Sstevel@tonic-gate
7927c478bd9Sstevel@tonic-gate@item
7937c478bd9Sstevel@tonic-gateRun the command @command{boot} (@pxref{boot}).
7947c478bd9Sstevel@tonic-gate@end enumerate
7957c478bd9Sstevel@tonic-gate
7967c478bd9Sstevel@tonic-gateLinux, FreeBSD, NetBSD and OpenBSD can be booted in a similar
7977c478bd9Sstevel@tonic-gatemanner. You load a kernel image with the command @command{kernel} and
7987c478bd9Sstevel@tonic-gatethen run the command @command{boot}. If the kernel requires some
7997c478bd9Sstevel@tonic-gateparameters, just append the parameters to @command{kernel}, after the
8007c478bd9Sstevel@tonic-gatefile name of the kernel. Also, please refer to @ref{OS-specific notes},
8017c478bd9Sstevel@tonic-gatefor information on your OS-specific issues.
8027c478bd9Sstevel@tonic-gate
8037c478bd9Sstevel@tonic-gate
8047c478bd9Sstevel@tonic-gate@node Chain-loading
8057c478bd9Sstevel@tonic-gate@subsection Load another boot loader to boot unsupported operating systems
8067c478bd9Sstevel@tonic-gate
8077c478bd9Sstevel@tonic-gateIf you want to boot an unsupported operating system (e.g. Windows 95),
8087c478bd9Sstevel@tonic-gatechain-load a boot loader for the operating system. Normally, the boot
8097c478bd9Sstevel@tonic-gateloader is embedded in the @dfn{boot sector} of the partition on which
8107c478bd9Sstevel@tonic-gatethe operating system is installed.
8117c478bd9Sstevel@tonic-gate
8127c478bd9Sstevel@tonic-gate@enumerate
8137c478bd9Sstevel@tonic-gate@item
8147c478bd9Sstevel@tonic-gateSet GRUB's root device to the partition by the command
8157c478bd9Sstevel@tonic-gate@command{rootnoverify} (@pxref{rootnoverify}):
8167c478bd9Sstevel@tonic-gate
8177c478bd9Sstevel@tonic-gate@example
8187c478bd9Sstevel@tonic-gategrub> @kbd{rootnoverify (hd0,0)}
8197c478bd9Sstevel@tonic-gate@end example
8207c478bd9Sstevel@tonic-gate
8217c478bd9Sstevel@tonic-gate@item
8227c478bd9Sstevel@tonic-gateSet the @dfn{active} flag in the partition using the command
8237c478bd9Sstevel@tonic-gate@command{makeactive}@footnote{This is not necessary for most of the
8247c478bd9Sstevel@tonic-gatemodern operating systems.} (@pxref{makeactive}):
8257c478bd9Sstevel@tonic-gate
8267c478bd9Sstevel@tonic-gate@example
8277c478bd9Sstevel@tonic-gategrub> @kbd{makeactive}
8287c478bd9Sstevel@tonic-gate@end example
8297c478bd9Sstevel@tonic-gate
8307c478bd9Sstevel@tonic-gate@item
8317c478bd9Sstevel@tonic-gateLoad the boot loader with the command @command{chainloader}
8327c478bd9Sstevel@tonic-gate(@pxref{chainloader}):
8337c478bd9Sstevel@tonic-gate
8347c478bd9Sstevel@tonic-gate@example
8357c478bd9Sstevel@tonic-gategrub> @kbd{chainloader +1}
8367c478bd9Sstevel@tonic-gate@end example
8377c478bd9Sstevel@tonic-gate
8387c478bd9Sstevel@tonic-gate@samp{+1} indicates that GRUB should read one sector from the start of
8397c478bd9Sstevel@tonic-gatethe partition. The complete description about this syntax can be found
8407c478bd9Sstevel@tonic-gatein @ref{Block list syntax}.
8417c478bd9Sstevel@tonic-gate
8427c478bd9Sstevel@tonic-gate@item
8437c478bd9Sstevel@tonic-gateRun the command @command{boot} (@pxref{boot}).
8447c478bd9Sstevel@tonic-gate@end enumerate
8457c478bd9Sstevel@tonic-gate
8467c478bd9Sstevel@tonic-gateHowever, DOS and Windows have some deficiencies, so you might have to
8477c478bd9Sstevel@tonic-gateuse more complicated instructions. @xref{DOS/Windows}, for more
8487c478bd9Sstevel@tonic-gateinformation.
8497c478bd9Sstevel@tonic-gate
8507c478bd9Sstevel@tonic-gate
8517c478bd9Sstevel@tonic-gate@node OS-specific notes
8527c478bd9Sstevel@tonic-gate@section Some caveats on OS-specific issues
8537c478bd9Sstevel@tonic-gate
8547c478bd9Sstevel@tonic-gateHere, we describe some caveats on several operating systems.
8557c478bd9Sstevel@tonic-gate
8567c478bd9Sstevel@tonic-gate@menu
8577c478bd9Sstevel@tonic-gate* GNU/Hurd::
8587c478bd9Sstevel@tonic-gate* GNU/Linux::
8597c478bd9Sstevel@tonic-gate* FreeBSD::
8607c478bd9Sstevel@tonic-gate* NetBSD::
8617c478bd9Sstevel@tonic-gate* OpenBSD::
8627c478bd9Sstevel@tonic-gate* DOS/Windows::
8637c478bd9Sstevel@tonic-gate* SCO UnixWare::
8647c478bd9Sstevel@tonic-gate* QNX::
8657c478bd9Sstevel@tonic-gate@end menu
8667c478bd9Sstevel@tonic-gate
8677c478bd9Sstevel@tonic-gate
8687c478bd9Sstevel@tonic-gate@node GNU/Hurd
8697c478bd9Sstevel@tonic-gate@subsection GNU/Hurd
8707c478bd9Sstevel@tonic-gate
8717c478bd9Sstevel@tonic-gateSince GNU/Hurd is Multiboot-compliant, it is easy to boot it; there is
8727c478bd9Sstevel@tonic-gatenothing special about it. But do not forget that you have to specify a
8737c478bd9Sstevel@tonic-gateroot partition to the kernel.
8747c478bd9Sstevel@tonic-gate
8757c478bd9Sstevel@tonic-gate@enumerate
8767c478bd9Sstevel@tonic-gate@item
8777c478bd9Sstevel@tonic-gateSet GRUB's root device to the same drive as GNU/Hurd's. Probably the
8787c478bd9Sstevel@tonic-gatecommand @code{find /boot/gnumach} or similar can help you
8797c478bd9Sstevel@tonic-gate(@pxref{find}).
8807c478bd9Sstevel@tonic-gate
8817c478bd9Sstevel@tonic-gate@item
8827c478bd9Sstevel@tonic-gateLoad the kernel and the module, like this:
8837c478bd9Sstevel@tonic-gate
8847c478bd9Sstevel@tonic-gate@example
8857c478bd9Sstevel@tonic-gate@group
8867c478bd9Sstevel@tonic-gategrub> @kbd{kernel /boot/gnumach root=hd0s1}
8877c478bd9Sstevel@tonic-gategrub> @kbd{module /boot/serverboot}
8887c478bd9Sstevel@tonic-gate@end group
8897c478bd9Sstevel@tonic-gate@end example
8907c478bd9Sstevel@tonic-gate
8917c478bd9Sstevel@tonic-gate@item
8927c478bd9Sstevel@tonic-gateRun the command @command{boot} (@pxref{boot}).
8937c478bd9Sstevel@tonic-gate@end enumerate
8947c478bd9Sstevel@tonic-gate
8957c478bd9Sstevel@tonic-gate
8967c478bd9Sstevel@tonic-gate@node GNU/Linux
8977c478bd9Sstevel@tonic-gate@subsection GNU/Linux
8987c478bd9Sstevel@tonic-gate
8997c478bd9Sstevel@tonic-gateIt is relatively easy to boot GNU/Linux from GRUB, because it somewhat
9007c478bd9Sstevel@tonic-gateresembles to boot a Multiboot-compliant OS.
9017c478bd9Sstevel@tonic-gate
9027c478bd9Sstevel@tonic-gate@enumerate
9037c478bd9Sstevel@tonic-gate@item
9047c478bd9Sstevel@tonic-gateSet GRUB's root device to the same drive as GNU/Linux's. Probably the
9057c478bd9Sstevel@tonic-gatecommand @code{find /vmlinuz} or similar can help you (@pxref{find}).
9067c478bd9Sstevel@tonic-gate
9077c478bd9Sstevel@tonic-gate@item
9087c478bd9Sstevel@tonic-gateLoad the kernel:
9097c478bd9Sstevel@tonic-gate
9107c478bd9Sstevel@tonic-gate@example
9117c478bd9Sstevel@tonic-gategrub> @kbd{kernel /vmlinuz root=/dev/hda1}
9127c478bd9Sstevel@tonic-gate@end example
9137c478bd9Sstevel@tonic-gate
9147c478bd9Sstevel@tonic-gateIf you need to specify some kernel parameters, just append them to the
9157c478bd9Sstevel@tonic-gatecommand. For example, to set @option{vga} to @samp{ext}, do this:
9167c478bd9Sstevel@tonic-gate
9177c478bd9Sstevel@tonic-gate@example
9187c478bd9Sstevel@tonic-gategrub> @kbd{kernel /vmlinuz root=/dev/hda1 vga=ext}
9197c478bd9Sstevel@tonic-gate@end example
9207c478bd9Sstevel@tonic-gate
9217c478bd9Sstevel@tonic-gateSee the documentation in the Linux source tree for complete
9227c478bd9Sstevel@tonic-gateinformation on the available options.
9237c478bd9Sstevel@tonic-gate
9247c478bd9Sstevel@tonic-gate@item
9257c478bd9Sstevel@tonic-gateIf you use an initrd, execute the command @command{initrd}
9267c478bd9Sstevel@tonic-gate(@pxref{initrd}) after @command{kernel}:
9277c478bd9Sstevel@tonic-gate
9287c478bd9Sstevel@tonic-gate@example
9297c478bd9Sstevel@tonic-gategrub> @kbd{initrd /initrd}
9307c478bd9Sstevel@tonic-gate@end example
9317c478bd9Sstevel@tonic-gate
9327c478bd9Sstevel@tonic-gate@item
9337c478bd9Sstevel@tonic-gateFinally, run the command @command{boot} (@pxref{boot}).
9347c478bd9Sstevel@tonic-gate@end enumerate
9357c478bd9Sstevel@tonic-gate
9367c478bd9Sstevel@tonic-gate@strong{Caution:} If you use an initrd and specify the @samp{mem=}
9377c478bd9Sstevel@tonic-gateoption to the kernel to let it use less than actual memory size, you
9387c478bd9Sstevel@tonic-gatewill also have to specify the same memory size to GRUB. To let GRUB know
9397c478bd9Sstevel@tonic-gatethe size, run the command @command{uppermem} @emph{before} loading the
9407c478bd9Sstevel@tonic-gatekernel. @xref{uppermem}, for more information.
9417c478bd9Sstevel@tonic-gate
9427c478bd9Sstevel@tonic-gate
9437c478bd9Sstevel@tonic-gate@node FreeBSD
9447c478bd9Sstevel@tonic-gate@subsection FreeBSD
9457c478bd9Sstevel@tonic-gate
9467c478bd9Sstevel@tonic-gateGRUB can load the kernel directly, either in ELF or a.out format. But
9477c478bd9Sstevel@tonic-gatethis is not recommended, since FreeBSD's bootstrap interface sometimes
9487c478bd9Sstevel@tonic-gatechanges heavily, so GRUB can't guarantee to pass kernel parameters
9497c478bd9Sstevel@tonic-gatecorrectly.
9507c478bd9Sstevel@tonic-gate
9517c478bd9Sstevel@tonic-gateThus, we'd recommend loading the very flexible loader
9527c478bd9Sstevel@tonic-gate@file{/boot/loader} instead. See this example:
9537c478bd9Sstevel@tonic-gate
9547c478bd9Sstevel@tonic-gate@example
9557c478bd9Sstevel@tonic-gate@group
9567c478bd9Sstevel@tonic-gategrub> @kbd{root (hd0,a)}
9577c478bd9Sstevel@tonic-gategrub> @kbd{kernel /boot/loader}
9587c478bd9Sstevel@tonic-gategrub> @kbd{boot}
9597c478bd9Sstevel@tonic-gate@end group
9607c478bd9Sstevel@tonic-gate@end example
9617c478bd9Sstevel@tonic-gate
9627c478bd9Sstevel@tonic-gate
9637c478bd9Sstevel@tonic-gate@node NetBSD
9647c478bd9Sstevel@tonic-gate@subsection NetBSD
9657c478bd9Sstevel@tonic-gate
9667c478bd9Sstevel@tonic-gateGRUB can load NetBSD a.out and ELF directly, follow these steps:
9677c478bd9Sstevel@tonic-gate
9687c478bd9Sstevel@tonic-gate@enumerate
9697c478bd9Sstevel@tonic-gate@item
9707c478bd9Sstevel@tonic-gateSet GRUB's root device with @command{root} (@pxref{root}).
9717c478bd9Sstevel@tonic-gate
9727c478bd9Sstevel@tonic-gate@item
9737c478bd9Sstevel@tonic-gateLoad the kernel with @command{kernel} (@pxref{kernel}). You should
9747c478bd9Sstevel@tonic-gateappend the ugly option @option{--type=netbsd}, if you want to load an
9757c478bd9Sstevel@tonic-gateELF kernel, like this:
9767c478bd9Sstevel@tonic-gate
9777c478bd9Sstevel@tonic-gate@example
9787c478bd9Sstevel@tonic-gategrub> @kbd{kernel --type=netbsd /netbsd-elf}
9797c478bd9Sstevel@tonic-gate@end example
9807c478bd9Sstevel@tonic-gate
9817c478bd9Sstevel@tonic-gate@item
9827c478bd9Sstevel@tonic-gateRun @command{boot} (@pxref{boot}).
9837c478bd9Sstevel@tonic-gate@end enumerate
9847c478bd9Sstevel@tonic-gate
9857c478bd9Sstevel@tonic-gateFor now, however, GRUB doesn't allow you to pass kernel parameters, so
9867c478bd9Sstevel@tonic-gateit may be better to chain-load it instead. For more information, please
9877c478bd9Sstevel@tonic-gatesee @ref{Chain-loading}.
9887c478bd9Sstevel@tonic-gate
9897c478bd9Sstevel@tonic-gate
9907c478bd9Sstevel@tonic-gate@node OpenBSD
9917c478bd9Sstevel@tonic-gate@subsection OpenBSD
9927c478bd9Sstevel@tonic-gate
9937c478bd9Sstevel@tonic-gateThe booting instruction is exactly the same as for NetBSD
9947c478bd9Sstevel@tonic-gate(@pxref{NetBSD}).
9957c478bd9Sstevel@tonic-gate
9967c478bd9Sstevel@tonic-gate
9977c478bd9Sstevel@tonic-gate@node DOS/Windows
9987c478bd9Sstevel@tonic-gate@subsection DOS/Windows
9997c478bd9Sstevel@tonic-gate
10007c478bd9Sstevel@tonic-gateGRUB cannot boot DOS or Windows directly, so you must chain-load them
10017c478bd9Sstevel@tonic-gate(@pxref{Chain-loading}). However, their boot loaders have some critical
10027c478bd9Sstevel@tonic-gatedeficiencies, so it may not work to just chain-load them. To overcome
10037c478bd9Sstevel@tonic-gatethe problems, GRUB provides you with two helper functions.
10047c478bd9Sstevel@tonic-gate
10057c478bd9Sstevel@tonic-gateIf you have installed DOS (or Windows) on a non-first hard disk, you
10067c478bd9Sstevel@tonic-gatehave to use the disk swapping technique, because that OS cannot boot
10077c478bd9Sstevel@tonic-gatefrom any disks but the first one. The workaround used in GRUB is the
10087c478bd9Sstevel@tonic-gatecommand @command{map} (@pxref{map}), like this:
10097c478bd9Sstevel@tonic-gate
10107c478bd9Sstevel@tonic-gate@example
10117c478bd9Sstevel@tonic-gate@group
10127c478bd9Sstevel@tonic-gategrub> @kbd{map (hd0) (hd1)}
10137c478bd9Sstevel@tonic-gategrub> @kbd{map (hd1) (hd0)}
10147c478bd9Sstevel@tonic-gate@end group
10157c478bd9Sstevel@tonic-gate@end example
10167c478bd9Sstevel@tonic-gate
10177c478bd9Sstevel@tonic-gateThis performs a @dfn{virtual} swap between your first and second hard
10187c478bd9Sstevel@tonic-gatedrive.
10197c478bd9Sstevel@tonic-gate
10207c478bd9Sstevel@tonic-gate@strong{Caution:} This is effective only if DOS (or Windows) uses BIOS
10217c478bd9Sstevel@tonic-gateto access the swapped disks. If that OS uses a special driver for the
10227c478bd9Sstevel@tonic-gatedisks, this probably won't work.
10237c478bd9Sstevel@tonic-gate
10247c478bd9Sstevel@tonic-gateAnother problem arises if you installed more than one set of DOS/Windows
10257c478bd9Sstevel@tonic-gateonto one disk, because they could be confused if there are more than one
10267c478bd9Sstevel@tonic-gateprimary partitions for DOS/Windows. Certainly you should avoid doing
10277c478bd9Sstevel@tonic-gatethis, but there is a solution if you do want to do so. Use the partition
10287c478bd9Sstevel@tonic-gatehiding/unhiding technique.
10297c478bd9Sstevel@tonic-gate
10307c478bd9Sstevel@tonic-gateIf GRUB @dfn{hide}s a DOS (or Windows) partition (@pxref{hide}), DOS (or
10317c478bd9Sstevel@tonic-gateWindows) will ignore the partition. If GRUB @dfn{unhide}s a DOS (or
10327c478bd9Sstevel@tonic-gateWindows) partition (@pxref{unhide}), DOS (or Windows) will detect the
10337c478bd9Sstevel@tonic-gatepartition. Thus, if you have installed DOS (or Windows) on the first
10347c478bd9Sstevel@tonic-gateand the second partition of the first hard disk, and you want to boot
10357c478bd9Sstevel@tonic-gatethe copy on the first partition, do the following:
10367c478bd9Sstevel@tonic-gate
10377c478bd9Sstevel@tonic-gate@example
10387c478bd9Sstevel@tonic-gate@group
10397c478bd9Sstevel@tonic-gategrub> @kbd{unhide (hd0,0)}
10407c478bd9Sstevel@tonic-gategrub> @kbd{hide (hd0,1)}
10417c478bd9Sstevel@tonic-gategrub> @kbd{rootnoverify (hd0,0)}
10427c478bd9Sstevel@tonic-gategrub> @kbd{chainloader +1}
10437c478bd9Sstevel@tonic-gategrub> @kbd{makeactive}
10447c478bd9Sstevel@tonic-gategrub> @kbd{boot}
10457c478bd9Sstevel@tonic-gate@end group
10467c478bd9Sstevel@tonic-gate@end example
10477c478bd9Sstevel@tonic-gate
10487c478bd9Sstevel@tonic-gate
10497c478bd9Sstevel@tonic-gate@node SCO UnixWare
10507c478bd9Sstevel@tonic-gate@subsection SCO UnixWare
10517c478bd9Sstevel@tonic-gate
10527c478bd9Sstevel@tonic-gateIt is known that the signature in the boot loader for SCO UnixWare is
10537c478bd9Sstevel@tonic-gatewrong, so you will have to specify the option @option{--force} to
10547c478bd9Sstevel@tonic-gate@command{chainloader} (@pxref{chainloader}), like this:
10557c478bd9Sstevel@tonic-gate
10567c478bd9Sstevel@tonic-gate@example
10577c478bd9Sstevel@tonic-gate@group
10587c478bd9Sstevel@tonic-gategrub> @kbd{rootnoverify (hd1,0)}
10597c478bd9Sstevel@tonic-gategrub> @kbd{chainloader --force +1}
10607c478bd9Sstevel@tonic-gategrub> @kbd{makeactive}
10617c478bd9Sstevel@tonic-gategrub> @kbd{boot}
10627c478bd9Sstevel@tonic-gate@end group
10637c478bd9Sstevel@tonic-gate@end example
10647c478bd9Sstevel@tonic-gate
10657c478bd9Sstevel@tonic-gate
10667c478bd9Sstevel@tonic-gate@node QNX
10677c478bd9Sstevel@tonic-gate@subsection QNX
10687c478bd9Sstevel@tonic-gate
10697c478bd9Sstevel@tonic-gateQNX seems to use a bigger boot loader, so you need to boot it up, like
10707c478bd9Sstevel@tonic-gatethis:
10717c478bd9Sstevel@tonic-gate
10727c478bd9Sstevel@tonic-gate@example
10737c478bd9Sstevel@tonic-gate@group
10747c478bd9Sstevel@tonic-gategrub> @kbd{rootnoverify (hd1,1)}
10757c478bd9Sstevel@tonic-gategrub> @kbd{chainloader +4}
10767c478bd9Sstevel@tonic-gategrub> @kbd{boot}
10777c478bd9Sstevel@tonic-gate@end group
10787c478bd9Sstevel@tonic-gate@end example
10797c478bd9Sstevel@tonic-gate
10807c478bd9Sstevel@tonic-gate
10817c478bd9Sstevel@tonic-gate@node Making your system robust
10827c478bd9Sstevel@tonic-gate@section How to make your system robust
10837c478bd9Sstevel@tonic-gate
10847c478bd9Sstevel@tonic-gateWhen you test a new kernel or a new OS, it is important to make sure
10857c478bd9Sstevel@tonic-gatethat your computer can boot even if the new system is unbootable. This
10867c478bd9Sstevel@tonic-gateis crucial especially if you maintain servers or remote systems. To
10877c478bd9Sstevel@tonic-gateaccomplish this goal, you need to set up two things:
10887c478bd9Sstevel@tonic-gate
10897c478bd9Sstevel@tonic-gate@enumerate
10907c478bd9Sstevel@tonic-gate@item
10917c478bd9Sstevel@tonic-gateYou must maintain a system which is always bootable. For instance, if
10927c478bd9Sstevel@tonic-gateyou test a new kernel, you need to keep a working kernel in a
10937c478bd9Sstevel@tonic-gatedifferent place. And, it would sometimes be very nice to even have a
10947c478bd9Sstevel@tonic-gatecomplete copy of a working system in a different partition or disk.
10957c478bd9Sstevel@tonic-gate
10967c478bd9Sstevel@tonic-gate@item
10977c478bd9Sstevel@tonic-gateYou must direct GRUB to boot a working system when the new system
10987c478bd9Sstevel@tonic-gatefails. This is possible with the @dfn{fallback} system in GRUB.
10997c478bd9Sstevel@tonic-gate@end enumerate
11007c478bd9Sstevel@tonic-gate
11017c478bd9Sstevel@tonic-gateThe former requirement is very specific to each OS, so this
11027c478bd9Sstevel@tonic-gatedocumentation does not cover that topic. It is better to consult some
11037c478bd9Sstevel@tonic-gatebackup tools.
11047c478bd9Sstevel@tonic-gate
11057c478bd9Sstevel@tonic-gateSo let's see the GRUB part. There are two possibilities: one of them
11067c478bd9Sstevel@tonic-gateis quite simple but not very robust, and the other is a bit complex to
11077c478bd9Sstevel@tonic-gateset up but probably the best solution to make sure that your system
11087c478bd9Sstevel@tonic-gatecan start as long as GRUB itself is bootable.
11097c478bd9Sstevel@tonic-gate
11107c478bd9Sstevel@tonic-gate@menu
11117c478bd9Sstevel@tonic-gate* Booting once-only::
11127c478bd9Sstevel@tonic-gate* Booting fallback systems::
11137c478bd9Sstevel@tonic-gate@end menu
11147c478bd9Sstevel@tonic-gate
11157c478bd9Sstevel@tonic-gate
11167c478bd9Sstevel@tonic-gate@node Booting once-only
11177c478bd9Sstevel@tonic-gate@subsection Booting once-only
11187c478bd9Sstevel@tonic-gate
11197c478bd9Sstevel@tonic-gateYou can teach GRUB to boot an entry only at next boot time. Suppose
11207c478bd9Sstevel@tonic-gatethat your have an old kernel @file{old_kernel} and a new kernel
11217c478bd9Sstevel@tonic-gate@file{new_kernel}. You know that @file{old_kernel} can boot
11227c478bd9Sstevel@tonic-gateyour system correctly, and you want to test @file{new_kernel}.
11237c478bd9Sstevel@tonic-gate
11247c478bd9Sstevel@tonic-gateTo ensure that your system will go back to the old kernel even if the
11257c478bd9Sstevel@tonic-gatenew kernel fails (e.g. it panics), you can specify that GRUB should
11267c478bd9Sstevel@tonic-gatetry the new kernel only once and boot the old kernel after that.
11277c478bd9Sstevel@tonic-gate
11287c478bd9Sstevel@tonic-gateFirst, modify your configuration file. Here is an example:
11297c478bd9Sstevel@tonic-gate
11307c478bd9Sstevel@tonic-gate@example
11317c478bd9Sstevel@tonic-gate@group
11327c478bd9Sstevel@tonic-gatedefault saved        # This is important!!!
11337c478bd9Sstevel@tonic-gatetimeout 10
11347c478bd9Sstevel@tonic-gate
11357c478bd9Sstevel@tonic-gatetitle the old kernel
11367c478bd9Sstevel@tonic-gateroot (hd0,0)
11377c478bd9Sstevel@tonic-gatekernel /old_kernel
11387c478bd9Sstevel@tonic-gatesavedefault
11397c478bd9Sstevel@tonic-gate
11407c478bd9Sstevel@tonic-gatetitle the new kernel
11417c478bd9Sstevel@tonic-gateroot (hd0,0)
11427c478bd9Sstevel@tonic-gatekernel /new_kernel
11437c478bd9Sstevel@tonic-gatesavedefault 0         # This is important!!!
11447c478bd9Sstevel@tonic-gate@end group
11457c478bd9Sstevel@tonic-gate@end example
11467c478bd9Sstevel@tonic-gate
11477c478bd9Sstevel@tonic-gateNote that this configuration file uses @samp{default saved}
11487c478bd9Sstevel@tonic-gate(@pxref{default}) at the head and @samp{savedefault 0}
11497c478bd9Sstevel@tonic-gate(@pxref{savedefault}) in the entry for the new kernel. This means
11507c478bd9Sstevel@tonic-gatethat GRUB boots a saved entry by default, and booting the entry for the
11517c478bd9Sstevel@tonic-gatenew kernel saves @samp{0} as the saved entry.
11527c478bd9Sstevel@tonic-gate
11537c478bd9Sstevel@tonic-gateWith this configuration file, after all, GRUB always tries to boot the
11547c478bd9Sstevel@tonic-gateold kernel after it booted the new one, because @samp{0} is the entry
11557c478bd9Sstevel@tonic-gateof @code{the old kernel}.
11567c478bd9Sstevel@tonic-gate
11577c478bd9Sstevel@tonic-gateThe next step is to tell GRUB to boot the new kernel at next boot
11587c478bd9Sstevel@tonic-gatetime. For this, execute @command{grub-set-default} (@pxref{Invoking
11597c478bd9Sstevel@tonic-gategrub-set-default}):
11607c478bd9Sstevel@tonic-gate
11617c478bd9Sstevel@tonic-gate@example
11627c478bd9Sstevel@tonic-gate# @kbd{grub-set-default 1}
11637c478bd9Sstevel@tonic-gate@end example
11647c478bd9Sstevel@tonic-gate
11657c478bd9Sstevel@tonic-gateThis command sets the saved entry to @samp{1}, that is, to the new
11667c478bd9Sstevel@tonic-gatekernel.
11677c478bd9Sstevel@tonic-gate
11687c478bd9Sstevel@tonic-gateThis method is useful, but still not very robust, because GRUB stops
11697c478bd9Sstevel@tonic-gatebooting, if there is any error in the boot entry, such that the new
11707c478bd9Sstevel@tonic-gatekernel has an invalid executable format. Thus, it it even better to
11717c478bd9Sstevel@tonic-gateuse the @dfn{fallback} mechanism of GRUB. Look at next subsection for
11727c478bd9Sstevel@tonic-gatethis feature.
11737c478bd9Sstevel@tonic-gate
11747c478bd9Sstevel@tonic-gate
11757c478bd9Sstevel@tonic-gate@node Booting fallback systems
11767c478bd9Sstevel@tonic-gate@subsection Booting fallback systems
11777c478bd9Sstevel@tonic-gate
11787c478bd9Sstevel@tonic-gateGRUB supports a fallback mechanism of booting one or more other
11797c478bd9Sstevel@tonic-gateentries if a default boot entry fails. You can specify multiple
11807c478bd9Sstevel@tonic-gatefallback entries if you wish.
11817c478bd9Sstevel@tonic-gate
11827c478bd9Sstevel@tonic-gateSuppose that you have three systems, @samp{A}, @samp{B} and
11837c478bd9Sstevel@tonic-gate@samp{C}. @samp{A} is a system which you want to boot by
11847c478bd9Sstevel@tonic-gatedefault. @samp{B} is a backup system which is supposed to boot
11857c478bd9Sstevel@tonic-gatesafely. @samp{C} is another backup system which is used in case where
11867c478bd9Sstevel@tonic-gate@samp{B} is broken.
11877c478bd9Sstevel@tonic-gate
11887c478bd9Sstevel@tonic-gateThen you may want GRUB to boot the first system which is bootable
11897c478bd9Sstevel@tonic-gateamong @samp{A}, @samp{B} and @samp{C}. A configuration file can be
11907c478bd9Sstevel@tonic-gatewritten in this way:
11917c478bd9Sstevel@tonic-gate
11927c478bd9Sstevel@tonic-gate@example
11937c478bd9Sstevel@tonic-gate@group
11947c478bd9Sstevel@tonic-gatedefault saved        # This is important!!!
11957c478bd9Sstevel@tonic-gatetimeout 10
11967c478bd9Sstevel@tonic-gatefallback 1 2         # This is important!!!
11977c478bd9Sstevel@tonic-gate
11987c478bd9Sstevel@tonic-gatetitle A
11997c478bd9Sstevel@tonic-gateroot (hd0,0)
12007c478bd9Sstevel@tonic-gatekernel /kernel
12017c478bd9Sstevel@tonic-gatesavedefault fallback # This is important!!!
12027c478bd9Sstevel@tonic-gate
12037c478bd9Sstevel@tonic-gatetitle B
12047c478bd9Sstevel@tonic-gateroot (hd1,0)
12057c478bd9Sstevel@tonic-gatekernel /kernel
12067c478bd9Sstevel@tonic-gatesavedefault fallback # This is important!!!
12077c478bd9Sstevel@tonic-gate
12087c478bd9Sstevel@tonic-gatetitle C
12097c478bd9Sstevel@tonic-gateroot (hd2,0)
12107c478bd9Sstevel@tonic-gatekernel /kernel
12117c478bd9Sstevel@tonic-gatesavedefault
12127c478bd9Sstevel@tonic-gate@end group
12137c478bd9Sstevel@tonic-gate@end example
12147c478bd9Sstevel@tonic-gate
12157c478bd9Sstevel@tonic-gateNote that @samp{default saved} (@pxref{default}), @samp{fallback 1 2}
12167c478bd9Sstevel@tonic-gateand @samp{savedefault fallback} are used. GRUB will boot a saved entry
12177c478bd9Sstevel@tonic-gateby default and save a fallback entry as next boot entry with this
12187c478bd9Sstevel@tonic-gateconfiguration.
12197c478bd9Sstevel@tonic-gate
12207c478bd9Sstevel@tonic-gateWhen GRUB tries to boot @samp{A}, GRUB saves @samp{1} as next boot
12217c478bd9Sstevel@tonic-gateentry, because the command @command{fallback} specifies that @samp{1}
12227c478bd9Sstevel@tonic-gateis the first fallback entry. The entry @samp{1} is @samp{B}, so GRUB
12237c478bd9Sstevel@tonic-gatewill try to boot @samp{B} at next boot time.
12247c478bd9Sstevel@tonic-gate
12257c478bd9Sstevel@tonic-gateLikewise, when GRUB tries to boot @samp{B}, GRUB saves @samp{2} as
12267c478bd9Sstevel@tonic-gatenext boot entry, because @command{fallback} specifies @samp{2} as next
12277c478bd9Sstevel@tonic-gatefallback entry. This makes sure that GRUB will boot @samp{C} after
12287c478bd9Sstevel@tonic-gatebooting @samp{B}.
12297c478bd9Sstevel@tonic-gate
12307c478bd9Sstevel@tonic-gateIt is noteworthy that GRUB uses fallback entries both when GRUB
12317c478bd9Sstevel@tonic-gateitself fails in booting an entry and when @samp{A} or @samp{B} fails
12327c478bd9Sstevel@tonic-gatein starting up your system. So this solution ensures that your system
12337c478bd9Sstevel@tonic-gateis started even if GRUB cannot find your kernel or if your kernel
12347c478bd9Sstevel@tonic-gatepanics.
12357c478bd9Sstevel@tonic-gate
12367c478bd9Sstevel@tonic-gateHowever, you need to run @command{grub-set-default} (@pxref{Invoking
12377c478bd9Sstevel@tonic-gategrub-set-default}) when @samp{A} starts correctly or you fix @samp{A}
12387c478bd9Sstevel@tonic-gateafter it crashes, since GRUB always sets next boot entry to a fallback
12397c478bd9Sstevel@tonic-gateentry. You should run this command in a startup script such as
12407c478bd9Sstevel@tonic-gate@file{rc.local} to boot @samp{A} by default:
12417c478bd9Sstevel@tonic-gate
12427c478bd9Sstevel@tonic-gate@example
12437c478bd9Sstevel@tonic-gate# @kbd{grub-set-default 0}
12447c478bd9Sstevel@tonic-gate@end example
12457c478bd9Sstevel@tonic-gate
12467c478bd9Sstevel@tonic-gatewhere @samp{0} is the number of the boot entry for the system
12477c478bd9Sstevel@tonic-gate@samp{A}.
12487c478bd9Sstevel@tonic-gate
12497c478bd9Sstevel@tonic-gateIf you want to see what is current default entry, you can look at the
12507c478bd9Sstevel@tonic-gatefile @file{/boot/grub/default} (or @file{/grub/default} in
12517c478bd9Sstevel@tonic-gatesome systems). Because this file is plain-text, you can just
12527c478bd9Sstevel@tonic-gate@command{cat} this file. But it is strongly recommended @strong{not to
12537c478bd9Sstevel@tonic-gatemodify this file directly}, because GRUB may fail in saving a default
12547c478bd9Sstevel@tonic-gateentry in this file, if you change this file in an unintended
12557c478bd9Sstevel@tonic-gatemanner. Therefore, you should use @command{grub-set-default} when you
12567c478bd9Sstevel@tonic-gateneed to change the default entry.
12577c478bd9Sstevel@tonic-gate
12587c478bd9Sstevel@tonic-gate
12597c478bd9Sstevel@tonic-gate@node Configuration
12607c478bd9Sstevel@tonic-gate@chapter Configuration
12617c478bd9Sstevel@tonic-gate
12627c478bd9Sstevel@tonic-gateYou've probably noticed that you need to type several commands to boot your
12637c478bd9Sstevel@tonic-gateOS. There's a solution to that - GRUB provides a menu interface
12647c478bd9Sstevel@tonic-gate(@pxref{Menu interface}) from which you can select an item (using arrow
12657c478bd9Sstevel@tonic-gatekeys) that will do everything to boot an OS.
12667c478bd9Sstevel@tonic-gate
12677c478bd9Sstevel@tonic-gateTo enable the menu, you need a configuration file,
12687c478bd9Sstevel@tonic-gate@file{menu.lst} under the boot directory. We'll analyze an example
12697c478bd9Sstevel@tonic-gatefile.
12707c478bd9Sstevel@tonic-gate
12717c478bd9Sstevel@tonic-gateThe file first contains some general settings, the menu interface
12727c478bd9Sstevel@tonic-gaterelated options. You can put these commands (@pxref{Menu-specific
12737c478bd9Sstevel@tonic-gatecommands}) before any of the items (starting with @command{title}
12747c478bd9Sstevel@tonic-gate(@pxref{title})).
12757c478bd9Sstevel@tonic-gate
12767c478bd9Sstevel@tonic-gate@example
12777c478bd9Sstevel@tonic-gate@group
12787c478bd9Sstevel@tonic-gate#
12797c478bd9Sstevel@tonic-gate# Sample boot menu configuration file
12807c478bd9Sstevel@tonic-gate#
12817c478bd9Sstevel@tonic-gate@end group
12827c478bd9Sstevel@tonic-gate@end example
12837c478bd9Sstevel@tonic-gate
12847c478bd9Sstevel@tonic-gateAs you may have guessed, these lines are comments. Lines starting with a
12857c478bd9Sstevel@tonic-gatehash character (@samp{#}), and blank lines, are ignored by GRUB.
12867c478bd9Sstevel@tonic-gate
12877c478bd9Sstevel@tonic-gate@example
12887c478bd9Sstevel@tonic-gate@group
12897c478bd9Sstevel@tonic-gate# By default, boot the first entry.
12907c478bd9Sstevel@tonic-gatedefault 0
12917c478bd9Sstevel@tonic-gate@end group
12927c478bd9Sstevel@tonic-gate@end example
12937c478bd9Sstevel@tonic-gate
12947c478bd9Sstevel@tonic-gateThe first entry (here, counting starts with number zero, not one!) will
12957c478bd9Sstevel@tonic-gatebe the default choice.
12967c478bd9Sstevel@tonic-gate
12977c478bd9Sstevel@tonic-gate@example
12987c478bd9Sstevel@tonic-gate@group
12997c478bd9Sstevel@tonic-gate# Boot automatically after 30 secs.
13007c478bd9Sstevel@tonic-gatetimeout 30
13017c478bd9Sstevel@tonic-gate@end group
13027c478bd9Sstevel@tonic-gate@end example
13037c478bd9Sstevel@tonic-gate
13047c478bd9Sstevel@tonic-gateAs the comment says, GRUB will boot automatically in 30 seconds, unless
13057c478bd9Sstevel@tonic-gateinterrupted with a keypress.
13067c478bd9Sstevel@tonic-gate
13077c478bd9Sstevel@tonic-gate@example
13087c478bd9Sstevel@tonic-gate@group
13097c478bd9Sstevel@tonic-gate# Fallback to the second entry.
13107c478bd9Sstevel@tonic-gatefallback 1
13117c478bd9Sstevel@tonic-gate@end group
13127c478bd9Sstevel@tonic-gate@end example
13137c478bd9Sstevel@tonic-gate
13147c478bd9Sstevel@tonic-gateIf, for any reason, the default entry doesn't work, fall back to the
13157c478bd9Sstevel@tonic-gatesecond one (this is rarely used, for obvious reasons).
13167c478bd9Sstevel@tonic-gate
13177c478bd9Sstevel@tonic-gateNote that the complete descriptions of these commands, which are menu
13187c478bd9Sstevel@tonic-gateinterface specific, can be found in @ref{Menu-specific
13197c478bd9Sstevel@tonic-gatecommands}. Other descriptions can be found in @ref{Commands}.
13207c478bd9Sstevel@tonic-gate
13217c478bd9Sstevel@tonic-gateNow, on to the actual OS definitions. You will see that each entry
13227c478bd9Sstevel@tonic-gatebegins with a special command, @command{title} (@pxref{title}), and the
13237c478bd9Sstevel@tonic-gateaction is described after it. Note that there is no command
13247c478bd9Sstevel@tonic-gate@command{boot} (@pxref{boot}) at the  end of each item. That is because
13257c478bd9Sstevel@tonic-gateGRUB automatically executes @command{boot} if it loads other commands
13267c478bd9Sstevel@tonic-gatesuccessfully.
13277c478bd9Sstevel@tonic-gate
13287c478bd9Sstevel@tonic-gateThe argument for the command @command{title} is used to display a short
13297c478bd9Sstevel@tonic-gatetitle/description of the entry in the menu. Since @command{title}
13307c478bd9Sstevel@tonic-gatedisplays the argument as is, you can write basically anything there.
13317c478bd9Sstevel@tonic-gate
13327c478bd9Sstevel@tonic-gate@example
13337c478bd9Sstevel@tonic-gate@group
13347c478bd9Sstevel@tonic-gate# For booting GNU/Hurd
13357c478bd9Sstevel@tonic-gatetitle  GNU/Hurd
13367c478bd9Sstevel@tonic-gateroot   (hd0,0)
13377c478bd9Sstevel@tonic-gatekernel /boot/gnumach.gz root=hd0s1
13387c478bd9Sstevel@tonic-gatemodule /boot/serverboot.gz
13397c478bd9Sstevel@tonic-gate@end group
13407c478bd9Sstevel@tonic-gate@end example
13417c478bd9Sstevel@tonic-gate
13427c478bd9Sstevel@tonic-gateThis boots GNU/Hurd from the first hard disk.
13437c478bd9Sstevel@tonic-gate
13447c478bd9Sstevel@tonic-gate@example
13457c478bd9Sstevel@tonic-gate@group
13467c478bd9Sstevel@tonic-gate# For booting GNU/Linux
13477c478bd9Sstevel@tonic-gatetitle  GNU/Linux
13487c478bd9Sstevel@tonic-gatekernel (hd1,0)/vmlinuz root=/dev/hdb1
13497c478bd9Sstevel@tonic-gate@end group
13507c478bd9Sstevel@tonic-gate@end example
13517c478bd9Sstevel@tonic-gate
13527c478bd9Sstevel@tonic-gateThis boots GNU/Linux, but from the second hard disk.
13537c478bd9Sstevel@tonic-gate
13547c478bd9Sstevel@tonic-gate@example
13557c478bd9Sstevel@tonic-gate@group
13567c478bd9Sstevel@tonic-gate# For booting Mach (getting kernel from floppy)
13577c478bd9Sstevel@tonic-gatetitle  Utah Mach4 multiboot
13587c478bd9Sstevel@tonic-gateroot   (hd0,2)
13597c478bd9Sstevel@tonic-gatepause  Insert the diskette now^G!!
13607c478bd9Sstevel@tonic-gatekernel (fd0)/boot/kernel root=hd0s3
13617c478bd9Sstevel@tonic-gatemodule (fd0)/boot/bootstrap
13627c478bd9Sstevel@tonic-gate@end group
13637c478bd9Sstevel@tonic-gate@end example
13647c478bd9Sstevel@tonic-gate
13657c478bd9Sstevel@tonic-gateThis boots Mach with a kernel on a floppy, but the root filesystem at
13667c478bd9Sstevel@tonic-gatehd0s3. It also contains a @command{pause} line (@pxref{pause}), which
13677c478bd9Sstevel@tonic-gatewill cause GRUB to display a prompt and delay, before actually executing
13687c478bd9Sstevel@tonic-gatethe rest of the commands and booting.
13697c478bd9Sstevel@tonic-gate
13707c478bd9Sstevel@tonic-gate@example
13717c478bd9Sstevel@tonic-gate@group
13727c478bd9Sstevel@tonic-gate# For booting FreeBSD
13737c478bd9Sstevel@tonic-gatetitle  FreeBSD
13747c478bd9Sstevel@tonic-gateroot   (hd0,2,a)
13757c478bd9Sstevel@tonic-gatekernel /boot/loader
13767c478bd9Sstevel@tonic-gate@end group
13777c478bd9Sstevel@tonic-gate@end example
13787c478bd9Sstevel@tonic-gate
13797c478bd9Sstevel@tonic-gateThis item will boot FreeBSD kernel loaded from the @samp{a} partition of
13807c478bd9Sstevel@tonic-gatethe third @sc{pc} slice of the first hard disk.
13817c478bd9Sstevel@tonic-gate
13827c478bd9Sstevel@tonic-gate@example
13837c478bd9Sstevel@tonic-gate@group
13847c478bd9Sstevel@tonic-gate# For booting OS/2
13857c478bd9Sstevel@tonic-gatetitle OS/2
13867c478bd9Sstevel@tonic-gateroot  (hd0,1)
13877c478bd9Sstevel@tonic-gatemakeactive
13887c478bd9Sstevel@tonic-gate# chainload OS/2 bootloader from the first sector
13897c478bd9Sstevel@tonic-gatechainloader +1
13907c478bd9Sstevel@tonic-gate# This is similar to "chainload", but loads a specific file
13917c478bd9Sstevel@tonic-gate#chainloader /boot/chain.os2
13927c478bd9Sstevel@tonic-gate@end group
13937c478bd9Sstevel@tonic-gate@end example
13947c478bd9Sstevel@tonic-gate
13957c478bd9Sstevel@tonic-gateThis will boot OS/2, using a chain-loader (@pxref{Chain-loading}).
13967c478bd9Sstevel@tonic-gate
13977c478bd9Sstevel@tonic-gate@example
13987c478bd9Sstevel@tonic-gate@group
13997c478bd9Sstevel@tonic-gate# For booting Windows NT or Windows95
14007c478bd9Sstevel@tonic-gatetitle Windows NT / Windows 95 boot menu
14017c478bd9Sstevel@tonic-gateroot        (hd0,0)
14027c478bd9Sstevel@tonic-gatemakeactive
14037c478bd9Sstevel@tonic-gatechainloader +1
14047c478bd9Sstevel@tonic-gate# For loading DOS if Windows NT is installed
14057c478bd9Sstevel@tonic-gate# chainload /bootsect.dos
14067c478bd9Sstevel@tonic-gate@end group
14077c478bd9Sstevel@tonic-gate@end example
14087c478bd9Sstevel@tonic-gate
14097c478bd9Sstevel@tonic-gateThe same as the above, but for Windows.
14107c478bd9Sstevel@tonic-gate
14117c478bd9Sstevel@tonic-gate@example
14127c478bd9Sstevel@tonic-gate@group
14137c478bd9Sstevel@tonic-gate# For installing GRUB into the hard disk
14147c478bd9Sstevel@tonic-gatetitle Install GRUB into the hard disk
14157c478bd9Sstevel@tonic-gateroot    (hd0,0)
14167c478bd9Sstevel@tonic-gatesetup   (hd0)
14177c478bd9Sstevel@tonic-gate@end group
14187c478bd9Sstevel@tonic-gate@end example
14197c478bd9Sstevel@tonic-gate
14207c478bd9Sstevel@tonic-gateThis will just (re)install GRUB onto the hard disk.
14217c478bd9Sstevel@tonic-gate
14227c478bd9Sstevel@tonic-gate@example
14237c478bd9Sstevel@tonic-gate# Change the colors.
14247c478bd9Sstevel@tonic-gatetitle Change the colors
14257c478bd9Sstevel@tonic-gatecolor light-green/brown blink-red/blue
14267c478bd9Sstevel@tonic-gate@end example
14277c478bd9Sstevel@tonic-gate
14287c478bd9Sstevel@tonic-gateIn the last entry, the command @command{color} is used (@pxref{color}),
14297c478bd9Sstevel@tonic-gateto change the menu colors (try it!). This command is somewhat special,
14307c478bd9Sstevel@tonic-gatebecause it can be used both in the command-line and in the menu. GRUB
14317c478bd9Sstevel@tonic-gatehas several such commands, see @ref{General commands}.
14327c478bd9Sstevel@tonic-gate
14337c478bd9Sstevel@tonic-gateWe hope that you now understand how to use the basic features of
14347c478bd9Sstevel@tonic-gateGRUB. To learn more about GRUB, see the following chapters.
14357c478bd9Sstevel@tonic-gate
14367c478bd9Sstevel@tonic-gate
14377c478bd9Sstevel@tonic-gate@node Network
14387c478bd9Sstevel@tonic-gate@chapter Downloading OS images from a network
14397c478bd9Sstevel@tonic-gate
14407c478bd9Sstevel@tonic-gateAlthough GRUB is a disk-based boot loader, it does provide network
14417c478bd9Sstevel@tonic-gatesupport. To use the network support, you need to enable at least one
14427c478bd9Sstevel@tonic-gatenetwork driver in the GRUB build process. For more information please
14437c478bd9Sstevel@tonic-gatesee @file{netboot/README.netboot} in the source distribution.
14447c478bd9Sstevel@tonic-gate
14457c478bd9Sstevel@tonic-gate@menu
14467c478bd9Sstevel@tonic-gate* General usage of network support::
14477c478bd9Sstevel@tonic-gate* Diskless::
14487c478bd9Sstevel@tonic-gate@end menu
14497c478bd9Sstevel@tonic-gate
14507c478bd9Sstevel@tonic-gate
14517c478bd9Sstevel@tonic-gate@node General usage of network support
14527c478bd9Sstevel@tonic-gate@section How to set up your network
14537c478bd9Sstevel@tonic-gate
14547c478bd9Sstevel@tonic-gateGRUB requires a file server and optionally a server that will assign an
14557c478bd9Sstevel@tonic-gateIP address to the machine on which GRUB is running. For the former, only
14567c478bd9Sstevel@tonic-gateTFTP is supported at the moment. The latter is either BOOTP, DHCP or a
14577c478bd9Sstevel@tonic-gateRARP server@footnote{RARP is not advised, since it cannot serve much
14587c478bd9Sstevel@tonic-gateinformation}. It is not necessary to run both the servers on one
14597c478bd9Sstevel@tonic-gatecomputer. How to configure these servers is beyond the scope of this
14607c478bd9Sstevel@tonic-gatedocument, so please refer to the manuals specific to those
14617c478bd9Sstevel@tonic-gateprotocols/servers.
14627c478bd9Sstevel@tonic-gate
14637c478bd9Sstevel@tonic-gateIf you decided to use a server to assign an IP address, set up the
14647c478bd9Sstevel@tonic-gateserver and run @command{bootp} (@pxref{bootp}), @command{dhcp}
14657c478bd9Sstevel@tonic-gate(@pxref{dhcp}) or @command{rarp} (@pxref{rarp}) for BOOTP, DHCP or RARP,
14667c478bd9Sstevel@tonic-gaterespectively. Each command will show an assigned IP address, a netmask,
14677c478bd9Sstevel@tonic-gatean IP address for your TFTP server and a gateway. If any of the
14687c478bd9Sstevel@tonic-gateaddresses is wrong or it causes an error, probably the configuration of
14697c478bd9Sstevel@tonic-gateyour servers isn't set up properly.
14707c478bd9Sstevel@tonic-gate
14717c478bd9Sstevel@tonic-gateOtherwise, run @command{ifconfig}, like this:
14727c478bd9Sstevel@tonic-gate
14737c478bd9Sstevel@tonic-gate@example
14747c478bd9Sstevel@tonic-gategrub> @kbd{ifconfig --address=192.168.110.23 --server=192.168.110.14}
14757c478bd9Sstevel@tonic-gate@end example
14767c478bd9Sstevel@tonic-gate
14777c478bd9Sstevel@tonic-gateYou can also use @command{ifconfig} in conjuction with @command{bootp},
14787c478bd9Sstevel@tonic-gate@command{dhcp} or @command{rarp} (e.g. to reassign the server address
14797c478bd9Sstevel@tonic-gatemanually). @xref{ifconfig}, for more details.
14807c478bd9Sstevel@tonic-gate
14817c478bd9Sstevel@tonic-gateFinally, download your OS images from your network. The network can be
14827c478bd9Sstevel@tonic-gateaccessed using the network drive @samp{(nd)}. Everything else is very
14837c478bd9Sstevel@tonic-gatesimilar to the normal instructions (@pxref{Booting}).
14847c478bd9Sstevel@tonic-gate
14857c478bd9Sstevel@tonic-gateHere is an example:
14867c478bd9Sstevel@tonic-gate
14877c478bd9Sstevel@tonic-gate@example
14887c478bd9Sstevel@tonic-gate@group
14897c478bd9Sstevel@tonic-gategrub> @kbd{bootp}
14907c478bd9Sstevel@tonic-gateProbing... [NE*000]
14917c478bd9Sstevel@tonic-gateNE2000 base ...
14927c478bd9Sstevel@tonic-gateAddress: 192.168.110.23    Netmask: 255.255.255.0
14937c478bd9Sstevel@tonic-gateServer: 192.168.110.14     Gateway: 192.168.110.1
14947c478bd9Sstevel@tonic-gate
14957c478bd9Sstevel@tonic-gategrub> @kbd{root (nd)}
14967c478bd9Sstevel@tonic-gategrub> @kbd{kernel /tftproot/gnumach.gz root=sd0s1}
14977c478bd9Sstevel@tonic-gategrub> @kbd{module /tftproot/serverboot.gz}
14987c478bd9Sstevel@tonic-gategrub> @kbd{boot}
14997c478bd9Sstevel@tonic-gate@end group
15007c478bd9Sstevel@tonic-gate@end example
15017c478bd9Sstevel@tonic-gate
15027c478bd9Sstevel@tonic-gate
15037c478bd9Sstevel@tonic-gate@node Diskless
15047c478bd9Sstevel@tonic-gate@section Booting from a network
15057c478bd9Sstevel@tonic-gate
15067c478bd9Sstevel@tonic-gateIt is sometimes very useful to boot from a network, especially when you
15077c478bd9Sstevel@tonic-gateuse a machine which has no local disk. In this case, you need to obtain
15087c478bd9Sstevel@tonic-gatea kind of Net Boot @sc{rom}, such as a PXE @sc{rom} or a free software
15097c478bd9Sstevel@tonic-gatepackage like Etherboot. Such a Boot @sc{rom} first boots the machine,
15107c478bd9Sstevel@tonic-gatesets up the network card installed into the machine, and downloads a
15117c478bd9Sstevel@tonic-gatesecond stage boot image from the network. Then, the second image will
15127c478bd9Sstevel@tonic-gatetry to boot an operating system actually from the network.
15137c478bd9Sstevel@tonic-gate
15147c478bd9Sstevel@tonic-gateGRUB provides two second stage images, @file{nbgrub} and
15157c478bd9Sstevel@tonic-gate@file{pxegrub} (@pxref{Images}). These images are the same as the
15167c478bd9Sstevel@tonic-gatenormal Stage 2, except that they set up a network automatically, and try
15177c478bd9Sstevel@tonic-gateto load a configuration file from the network, if specified. The usage
15187c478bd9Sstevel@tonic-gateis very simple: If the machine has a PXE @sc{rom}, use
15197c478bd9Sstevel@tonic-gate@file{pxegrub}. If the machine has an NBI loader such as Etherboot, use
15207c478bd9Sstevel@tonic-gate@file{nbgrub}. There is no difference between them except their
15217c478bd9Sstevel@tonic-gateformats. Since the way to load a second stage image you want to use
15227c478bd9Sstevel@tonic-gateshould be described in the manual on your Net Boot @sc{rom}, please
15237c478bd9Sstevel@tonic-gaterefer to the manual, for more information.
15247c478bd9Sstevel@tonic-gate
15257c478bd9Sstevel@tonic-gateHowever, there is one thing specific to GRUB. Namely, how to specify a
15267c478bd9Sstevel@tonic-gateconfiguration file in a BOOTP/DHCP server. For now, GRUB uses the tag
15277c478bd9Sstevel@tonic-gate@samp{150}, to get the name of a configuration file. The following is an
15287c478bd9Sstevel@tonic-gateexample with a BOOTP configuration:
15297c478bd9Sstevel@tonic-gate
15307c478bd9Sstevel@tonic-gate@example
15317c478bd9Sstevel@tonic-gate@group
15327c478bd9Sstevel@tonic-gate.allhost:hd=/tmp:bf=null:\
15337c478bd9Sstevel@tonic-gate        :ds=145.71.35.1 145.71.32.1:\
15347c478bd9Sstevel@tonic-gate        :sm=255.255.254.0:\
15357c478bd9Sstevel@tonic-gate        :gw=145.71.35.1:\
15367c478bd9Sstevel@tonic-gate        :sa=145.71.35.5:
15377c478bd9Sstevel@tonic-gate
15387c478bd9Sstevel@tonic-gatefoo:ht=1:ha=63655d0334a7:ip=145.71.35.127:\
15397c478bd9Sstevel@tonic-gate        :bf=/nbgrub:\
15407c478bd9Sstevel@tonic-gate        :tc=.allhost:\
15417c478bd9Sstevel@tonic-gate        :T150="(nd)/tftpboot/menu.lst.foo":
15427c478bd9Sstevel@tonic-gate@end group
15437c478bd9Sstevel@tonic-gate@end example
15447c478bd9Sstevel@tonic-gate
15457c478bd9Sstevel@tonic-gateNote that you should specify the drive name @code{(nd)} in the name of
15467c478bd9Sstevel@tonic-gatethe configuration file. This is because you might change the root drive
15477c478bd9Sstevel@tonic-gatebefore downloading the configuration from the TFTP server when the
15487c478bd9Sstevel@tonic-gatepreset menu feature is used (@pxref{Preset Menu}).
15497c478bd9Sstevel@tonic-gate
15507c478bd9Sstevel@tonic-gateGRUB sends the string "GRUBClient" as its vendor class identifier to
15517c478bd9Sstevel@tonic-gatethe BOOTP/DHCP server. This can be used to generate answers specific
15527c478bd9Sstevel@tonic-gateto GRUB clients on your network.
15537c478bd9Sstevel@tonic-gate
15547c478bd9Sstevel@tonic-gateSee the manual of your BOOTP/DHCP server for more information. The
15557c478bd9Sstevel@tonic-gateexact syntax should differ a little from the example.
15567c478bd9Sstevel@tonic-gate
15577c478bd9Sstevel@tonic-gate@node Serial terminal
15587c478bd9Sstevel@tonic-gate@chapter Using GRUB via a serial line
15597c478bd9Sstevel@tonic-gate
15607c478bd9Sstevel@tonic-gateThis chapter describes how to use the serial terminal support in GRUB.
15617c478bd9Sstevel@tonic-gate
15627c478bd9Sstevel@tonic-gateIf you have many computers or computers with no display/keyboard, it
15637c478bd9Sstevel@tonic-gatecould be very useful to control the computers through serial
15647c478bd9Sstevel@tonic-gatecommunications. To connect one computer with another via a serial line,
15657c478bd9Sstevel@tonic-gateyou need to prepare a null-modem (cross) serial cable, and you may need
15667c478bd9Sstevel@tonic-gateto have multiport serial boards, if your computer doesn't have extra
15677c478bd9Sstevel@tonic-gateserial ports. In addition, a terminal emulator is also required, such as
15687c478bd9Sstevel@tonic-gateminicom. Refer to a manual of your operating system, for more
15697c478bd9Sstevel@tonic-gateinformation.
15707c478bd9Sstevel@tonic-gate
15717c478bd9Sstevel@tonic-gateAs for GRUB, the instruction to set up a serial terminal is quite
15727c478bd9Sstevel@tonic-gatesimple. First of all, make sure that you haven't specified the option
15737c478bd9Sstevel@tonic-gate@option{--disable-serial} to the configure script when you built your
15747c478bd9Sstevel@tonic-gateGRUB images. If you get them in binary form, probably they have serial
15757c478bd9Sstevel@tonic-gateterminal support already.
15767c478bd9Sstevel@tonic-gate
15777c478bd9Sstevel@tonic-gateThen, initialize your serial terminal after GRUB starts up. Here is an
15787c478bd9Sstevel@tonic-gateexample:
15797c478bd9Sstevel@tonic-gate
15807c478bd9Sstevel@tonic-gate@example
15817c478bd9Sstevel@tonic-gate@group
15827c478bd9Sstevel@tonic-gategrub> @kbd{serial --unit=0 --speed=9600}
15837c478bd9Sstevel@tonic-gategrub> @kbd{terminal serial}
15847c478bd9Sstevel@tonic-gate@end group
15857c478bd9Sstevel@tonic-gate@end example
15867c478bd9Sstevel@tonic-gate
15877c478bd9Sstevel@tonic-gateThe command @command{serial} initializes the serial unit 0 with the
15887c478bd9Sstevel@tonic-gatespeed 9600bps. The serial unit 0 is usually called @samp{COM1}, so, if
15897c478bd9Sstevel@tonic-gateyou want to use COM2, you must specify @samp{--unit=1} instead. This
15907c478bd9Sstevel@tonic-gatecommand accepts many other options, so please refer to @ref{serial},
15917c478bd9Sstevel@tonic-gatefor more details.
15927c478bd9Sstevel@tonic-gate
15937c478bd9Sstevel@tonic-gateThe command @command{terminal} (@pxref{terminal}) chooses which type of
15947c478bd9Sstevel@tonic-gateterminal you want to use. In the case above, the terminal will be a
15957c478bd9Sstevel@tonic-gateserial terminal, but you can also pass @code{console} to the command,
15967c478bd9Sstevel@tonic-gateas @samp{terminal serial console}. In this case, a terminal in which
15977c478bd9Sstevel@tonic-gateyou press any key will be selected as a GRUB terminal.
15987c478bd9Sstevel@tonic-gate
15997c478bd9Sstevel@tonic-gateHowever, note that GRUB assumes that your terminal emulator is
16007c478bd9Sstevel@tonic-gatecompatible with VT100 by default. This is true for most terminal
16017c478bd9Sstevel@tonic-gateemulators nowadays, but you should pass the option @option{--dumb} to
16027c478bd9Sstevel@tonic-gatethe command if your terminal emulator is not VT100-compatible or
16037c478bd9Sstevel@tonic-gateimplements few VT100 escape sequences. If you specify this option then
16047c478bd9Sstevel@tonic-gateGRUB provides you with an alternative menu interface, because the normal
16057c478bd9Sstevel@tonic-gatemenu requires several fancy features of your terminal.
16067c478bd9Sstevel@tonic-gate
16077c478bd9Sstevel@tonic-gate
16087c478bd9Sstevel@tonic-gate@node Preset Menu
16097c478bd9Sstevel@tonic-gate@chapter Embedding a configuration file into GRUB
16107c478bd9Sstevel@tonic-gate
16117c478bd9Sstevel@tonic-gateGRUB supports a @dfn{preset menu} which is to be always loaded before
16127c478bd9Sstevel@tonic-gatestarting. The preset menu feature is useful, for example, when your
16137c478bd9Sstevel@tonic-gatecomputer has no console but a serial cable. In this case, it is
16147c478bd9Sstevel@tonic-gatecritical to set up the serial terminal as soon as possible, since you
16157c478bd9Sstevel@tonic-gatecannot see any message until the serial terminal begins to work. So it
16167c478bd9Sstevel@tonic-gateis good to run the commands @command{serial} (@pxref{serial}) and
16177c478bd9Sstevel@tonic-gate@command{terminal} (@pxref{terminal}) before anything else at the
16187c478bd9Sstevel@tonic-gatestart-up time.
16197c478bd9Sstevel@tonic-gate
16207c478bd9Sstevel@tonic-gateHow the preset menu works is slightly complicated:
16217c478bd9Sstevel@tonic-gate
16227c478bd9Sstevel@tonic-gate@enumerate
16237c478bd9Sstevel@tonic-gate@item
16247c478bd9Sstevel@tonic-gateGRUB checks if the preset menu feature is used, and loads the preset
16257c478bd9Sstevel@tonic-gatemenu, if available. This includes running commands and reading boot
16267c478bd9Sstevel@tonic-gateentries, like an ordinary configuration file.
16277c478bd9Sstevel@tonic-gate
16287c478bd9Sstevel@tonic-gate@item
16297c478bd9Sstevel@tonic-gateGRUB checks if the configuration file is available. Note that this check
16307c478bd9Sstevel@tonic-gateis performed @strong{regardless of the existence of the preset
16317c478bd9Sstevel@tonic-gatemenu}. The configuration file is loaded even if the preset menu was
16327c478bd9Sstevel@tonic-gateloaded.
16337c478bd9Sstevel@tonic-gate
16347c478bd9Sstevel@tonic-gate@item
16357c478bd9Sstevel@tonic-gateIf the preset menu includes any boot entries, they are cleared when
16367c478bd9Sstevel@tonic-gatethe configuration file is loaded. It doesn't matter whether the
16377c478bd9Sstevel@tonic-gateconfiguration file has any entries or no entry. The boot entries in the
16387c478bd9Sstevel@tonic-gatepreset menu are used only when GRUB fails in loading the configuration
16397c478bd9Sstevel@tonic-gatefile.
16407c478bd9Sstevel@tonic-gate@end enumerate
16417c478bd9Sstevel@tonic-gate
16427c478bd9Sstevel@tonic-gateTo enable the preset menu feature, you must rebuild GRUB specifying a
16437c478bd9Sstevel@tonic-gatefile to the configure script with the option
16447c478bd9Sstevel@tonic-gate@option{--enable-preset-menu}. The file has the same semantics as
16457c478bd9Sstevel@tonic-gatenormal configuration files (@pxref{Configuration}).
16467c478bd9Sstevel@tonic-gate
16477c478bd9Sstevel@tonic-gateAnother point you should take care is that the diskless support
16487c478bd9Sstevel@tonic-gate(@pxref{Diskless}) diverts the preset menu. Diskless images embed a
16497c478bd9Sstevel@tonic-gatepreset menu to execute the command @command{bootp} (@pxref{bootp})
16507c478bd9Sstevel@tonic-gateautomatically, unless you specify your own preset menu to the configure
16517c478bd9Sstevel@tonic-gatescript. This means that you must put commands to initialize a network in
16527c478bd9Sstevel@tonic-gatethe preset menu yourself, because diskless images don't set it up
16537c478bd9Sstevel@tonic-gateimplicitly, when you use the preset menu explicitly.
16547c478bd9Sstevel@tonic-gate
16557c478bd9Sstevel@tonic-gateTherefore, a typical preset menu used with diskless support would be
16567c478bd9Sstevel@tonic-gatelike this:
16577c478bd9Sstevel@tonic-gate
16587c478bd9Sstevel@tonic-gate@example
16597c478bd9Sstevel@tonic-gate@group
16607c478bd9Sstevel@tonic-gate# Set up the serial terminal, first of all.
16617c478bd9Sstevel@tonic-gateserial --unit=0 --speed=19200
16627c478bd9Sstevel@tonic-gateterminal --timeout=0 serial
16637c478bd9Sstevel@tonic-gate
16647c478bd9Sstevel@tonic-gate# Initialize the network.
16657c478bd9Sstevel@tonic-gatedhcp
16667c478bd9Sstevel@tonic-gate@end group
16677c478bd9Sstevel@tonic-gate@end example
16687c478bd9Sstevel@tonic-gate
16697c478bd9Sstevel@tonic-gate
16707c478bd9Sstevel@tonic-gate@node Security
16717c478bd9Sstevel@tonic-gate@chapter Protecting your computer from cracking
16727c478bd9Sstevel@tonic-gate
16737c478bd9Sstevel@tonic-gateYou may be interested in how to prevent ordinary users from doing
16747c478bd9Sstevel@tonic-gatewhatever they like, if you share your computer with other people. So
16757c478bd9Sstevel@tonic-gatethis chapter describes how to improve the security of GRUB.
16767c478bd9Sstevel@tonic-gate
16777c478bd9Sstevel@tonic-gateOne thing which could be a security hole is that the user can do too
16787c478bd9Sstevel@tonic-gatemany things with GRUB, because GRUB allows one to modify its configuration
16797c478bd9Sstevel@tonic-gateand run arbitrary commands at run-time. For example, the user can even
16807c478bd9Sstevel@tonic-gateread @file{/etc/passwd} in the command-line interface by the command
16817c478bd9Sstevel@tonic-gate@command{cat} (@pxref{cat}). So it is necessary to disable all the
16827c478bd9Sstevel@tonic-gateinteractive operations.
16837c478bd9Sstevel@tonic-gate
16847c478bd9Sstevel@tonic-gateThus, GRUB provides a @dfn{password} feature, so that only administrators
16857c478bd9Sstevel@tonic-gatecan start the interactive operations (i.e. editing menu entries and
16867c478bd9Sstevel@tonic-gateentering the command-line interface). To use this feature, you need to
16877c478bd9Sstevel@tonic-gaterun the command @command{password} in your configuration file
16887c478bd9Sstevel@tonic-gate(@pxref{password}), like this:
16897c478bd9Sstevel@tonic-gate
16907c478bd9Sstevel@tonic-gate@example
16917c478bd9Sstevel@tonic-gatepassword --md5 PASSWORD
16927c478bd9Sstevel@tonic-gate@end example
16937c478bd9Sstevel@tonic-gate
16947c478bd9Sstevel@tonic-gateIf this is specified, GRUB disallows any interactive control, until you
16957c478bd9Sstevel@tonic-gatepress the key @key{p} and enter a correct password.  The option
16967c478bd9Sstevel@tonic-gate@option{--md5} tells GRUB that @samp{PASSWORD} is in MD5 format.  If it
16977c478bd9Sstevel@tonic-gateis omitted, GRUB assumes the @samp{PASSWORD} is in clear text.
16987c478bd9Sstevel@tonic-gate
16997c478bd9Sstevel@tonic-gateYou can encrypt your password with the command @command{md5crypt}
17007c478bd9Sstevel@tonic-gate(@pxref{md5crypt}). For example, run the grub shell (@pxref{Invoking the
17017c478bd9Sstevel@tonic-gategrub shell}), and enter your password:
17027c478bd9Sstevel@tonic-gate
17037c478bd9Sstevel@tonic-gate@example
17047c478bd9Sstevel@tonic-gate@group
17057c478bd9Sstevel@tonic-gategrub> md5crypt
17067c478bd9Sstevel@tonic-gatePassword: **********
17077c478bd9Sstevel@tonic-gateEncrypted: $1$U$JK7xFegdxWH6VuppCUSIb.
17087c478bd9Sstevel@tonic-gate@end group
17097c478bd9Sstevel@tonic-gate@end example
17107c478bd9Sstevel@tonic-gate
17117c478bd9Sstevel@tonic-gateThen, cut and paste the encrypted password to your configuration file.
17127c478bd9Sstevel@tonic-gate
17137c478bd9Sstevel@tonic-gateAlso, you can specify an optional argument to @command{password}. See
17147c478bd9Sstevel@tonic-gatethis example:
17157c478bd9Sstevel@tonic-gate
17167c478bd9Sstevel@tonic-gate@example
17177c478bd9Sstevel@tonic-gatepassword PASSWORD /boot/grub/menu-admin.lst
17187c478bd9Sstevel@tonic-gate@end example
17197c478bd9Sstevel@tonic-gate
17207c478bd9Sstevel@tonic-gateIn this case, GRUB will load @file{/boot/grub/menu-admin.lst} as a
17217c478bd9Sstevel@tonic-gateconfiguration file when you enter the valid password.
17227c478bd9Sstevel@tonic-gate
17237c478bd9Sstevel@tonic-gateAnother thing which may be dangerous is that any user can choose any
17247c478bd9Sstevel@tonic-gatemenu entry. Usually, this wouldn't be problematic, but you might want to
17257c478bd9Sstevel@tonic-gatepermit only administrators to run some of your menu entries, such as an
17267c478bd9Sstevel@tonic-gateentry for booting an insecure OS like DOS.
17277c478bd9Sstevel@tonic-gate
17287c478bd9Sstevel@tonic-gateGRUB provides the command @command{lock} (@pxref{lock}). This command
17297c478bd9Sstevel@tonic-gatealways fails until you enter the valid password, so you can use it, like
17307c478bd9Sstevel@tonic-gatethis:
17317c478bd9Sstevel@tonic-gate
17327c478bd9Sstevel@tonic-gate@example
17337c478bd9Sstevel@tonic-gate@group
17347c478bd9Sstevel@tonic-gatetitle Boot DOS
17357c478bd9Sstevel@tonic-gatelock
17367c478bd9Sstevel@tonic-gaterootnoverify (hd0,1)
17377c478bd9Sstevel@tonic-gatemakeactive
17387c478bd9Sstevel@tonic-gatechainload +1
17397c478bd9Sstevel@tonic-gate@end group
17407c478bd9Sstevel@tonic-gate@end example
17417c478bd9Sstevel@tonic-gate
17427c478bd9Sstevel@tonic-gateYou should insert @command{lock} right after @command{title}, because
17437c478bd9Sstevel@tonic-gateany user can execute commands in an entry until GRUB encounters
17447c478bd9Sstevel@tonic-gate@command{lock}.
17457c478bd9Sstevel@tonic-gate
17467c478bd9Sstevel@tonic-gateYou can also use the command @command{password} instead of
17477c478bd9Sstevel@tonic-gate@command{lock}. In this case the boot process will ask for the password
17487c478bd9Sstevel@tonic-gateand stop if it was entered incorrectly.  Since the @command{password}
17497c478bd9Sstevel@tonic-gatetakes its own @var{PASSWORD} argument this is useful if you want
17507c478bd9Sstevel@tonic-gatedifferent passwords for different entries.
17517c478bd9Sstevel@tonic-gate
17527c478bd9Sstevel@tonic-gate
17537c478bd9Sstevel@tonic-gate@node Images
17547c478bd9Sstevel@tonic-gate@chapter GRUB image files
17557c478bd9Sstevel@tonic-gate
17567c478bd9Sstevel@tonic-gateGRUB consists of several images: two essential stages, optional stages
17577c478bd9Sstevel@tonic-gatecalled @dfn{Stage 1.5}, one image for bootable CD-ROM, and two network
17587c478bd9Sstevel@tonic-gateboot images. Here is a short overview of them. @xref{Internals}, for
17597c478bd9Sstevel@tonic-gatemore details.
17607c478bd9Sstevel@tonic-gate
17617c478bd9Sstevel@tonic-gate@table @file
17627c478bd9Sstevel@tonic-gate@item stage1
17637c478bd9Sstevel@tonic-gateThis is an essential image used for booting up GRUB. Usually, this is
17647c478bd9Sstevel@tonic-gateembedded in an MBR or the boot sector of a partition. Because a PC boot
17657c478bd9Sstevel@tonic-gatesector is 512 bytes, the size of this image is exactly 512 bytes.
17667c478bd9Sstevel@tonic-gate
17677c478bd9Sstevel@tonic-gateAll @file{stage1} must do is to load Stage 2 or Stage 1.5 from a local
17687c478bd9Sstevel@tonic-gatedisk. Because of the size restriction, @file{stage1} encodes the
17697c478bd9Sstevel@tonic-gatelocation of Stage 2 (or Stage 1.5) in a block list format, so it never
17707c478bd9Sstevel@tonic-gateunderstand any filesystem structure.
17717c478bd9Sstevel@tonic-gate
17727c478bd9Sstevel@tonic-gate@item stage2
17737c478bd9Sstevel@tonic-gateThis is the core image of GRUB. It does everything but booting up
17747c478bd9Sstevel@tonic-gateitself. Usually, this is put in a filesystem, but that is not required.
17757c478bd9Sstevel@tonic-gate
17767c478bd9Sstevel@tonic-gate@item e2fs_stage1_5
17777c478bd9Sstevel@tonic-gate@itemx fat_stage1_5
17787c478bd9Sstevel@tonic-gate@itemx ffs_stage1_5
17797c478bd9Sstevel@tonic-gate@itemx jfs_stage1_5
17807c478bd9Sstevel@tonic-gate@itemx minix_stage1_5
17817c478bd9Sstevel@tonic-gate@itemx reiserfs_stage1_5
17827c478bd9Sstevel@tonic-gate@itemx vstafs_stage1_5
17837c478bd9Sstevel@tonic-gate@itemx xfs_stage1_5
17847c478bd9Sstevel@tonic-gate
17857c478bd9Sstevel@tonic-gateThese are called @dfn{Stage 1.5}, because they serve as a bridge
17867c478bd9Sstevel@tonic-gatebetween @file{stage1} and @file{stage2}, that is to say, Stage 1.5 is
17877c478bd9Sstevel@tonic-gateloaded by Stage 1 and Stage 1.5 loads Stage 2. The difference between
17887c478bd9Sstevel@tonic-gate@file{stage1} and @file{*_stage1_5} is that the former doesn't
17897c478bd9Sstevel@tonic-gateunderstand any filesystem while the latter understands one filesystem
17907c478bd9Sstevel@tonic-gate(e.g. @file{e2fs_stage1_5} understands ext2fs). So you can move the
17917c478bd9Sstevel@tonic-gateStage 2 image to another location safely, even after GRUB has been
17927c478bd9Sstevel@tonic-gateinstalled.
17937c478bd9Sstevel@tonic-gate
17947c478bd9Sstevel@tonic-gateWhile Stage 2 cannot generally be embedded in a fixed area as the size
17957c478bd9Sstevel@tonic-gateis so large, Stage 1.5 can be installed into the area right after an MBR,
17967c478bd9Sstevel@tonic-gateor the boot loader area of a ReiserFS or a FFS.
17977c478bd9Sstevel@tonic-gate
17987c478bd9Sstevel@tonic-gate@item stage2_eltorito
17997c478bd9Sstevel@tonic-gateThis is a boot image for CD-ROMs using the @dfn{no emulation mode} in
18007c478bd9Sstevel@tonic-gateEl Torito specification. This is identical to Stage 2, except that
18017c478bd9Sstevel@tonic-gatethis boots up without Stage 1 and sets up a special drive @samp{(cd)}.
18027c478bd9Sstevel@tonic-gate
18037c478bd9Sstevel@tonic-gate@item nbgrub
18047c478bd9Sstevel@tonic-gateThis is a network boot image for the Network Image Proposal used by some
18057c478bd9Sstevel@tonic-gatenetwork boot loaders, such as Etherboot. This is mostly the same as
18067c478bd9Sstevel@tonic-gateStage 2, but it also sets up a network and loads a configuration file
18077c478bd9Sstevel@tonic-gatefrom the network.
18087c478bd9Sstevel@tonic-gate
18097c478bd9Sstevel@tonic-gate@item pxegrub
18107c478bd9Sstevel@tonic-gateThis is another network boot image for the Preboot Execution Environment
18117c478bd9Sstevel@tonic-gateused by several Netboot ROMs. This is identical to @file{nbgrub}, except
18127c478bd9Sstevel@tonic-gatefor the format.
18137c478bd9Sstevel@tonic-gate@end table
18147c478bd9Sstevel@tonic-gate
18157c478bd9Sstevel@tonic-gate
18167c478bd9Sstevel@tonic-gate@node Filesystem
18177c478bd9Sstevel@tonic-gate@chapter Filesystem syntax and semantics
18187c478bd9Sstevel@tonic-gate
18197c478bd9Sstevel@tonic-gateGRUB uses a special syntax for specifying disk drives which can be
18207c478bd9Sstevel@tonic-gateaccessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish
18217c478bd9Sstevel@tonic-gatebetween IDE, ESDI, SCSI, or others. You must know yourself which BIOS
18227c478bd9Sstevel@tonic-gatedevice is equivalent to which OS device. Normally, that will be clear if
18237c478bd9Sstevel@tonic-gateyou see the files in a device or use the command @command{find}
18247c478bd9Sstevel@tonic-gate(@pxref{find}).
18257c478bd9Sstevel@tonic-gate
18267c478bd9Sstevel@tonic-gate@menu
18277c478bd9Sstevel@tonic-gate* Device syntax::               How to specify devices
18287c478bd9Sstevel@tonic-gate* File name syntax::            How to specify files
18297c478bd9Sstevel@tonic-gate* Block list syntax::           How to specify block lists
18307c478bd9Sstevel@tonic-gate@end menu
18317c478bd9Sstevel@tonic-gate
18327c478bd9Sstevel@tonic-gate
18337c478bd9Sstevel@tonic-gate@node Device syntax
18347c478bd9Sstevel@tonic-gate@section How to specify devices
18357c478bd9Sstevel@tonic-gate
18367c478bd9Sstevel@tonic-gateThe device syntax is like this:
18377c478bd9Sstevel@tonic-gate
18387c478bd9Sstevel@tonic-gate@example
18397c478bd9Sstevel@tonic-gate@code{(@var{device}[,@var{part-num}][,@var{bsd-subpart-letter}])}
18407c478bd9Sstevel@tonic-gate@end example
18417c478bd9Sstevel@tonic-gate
18427c478bd9Sstevel@tonic-gate@samp{[]} means the parameter is optional. @var{device} should be
18437c478bd9Sstevel@tonic-gateeither @samp{fd} or @samp{hd} followed by a digit, like @samp{fd0}.
18447c478bd9Sstevel@tonic-gateBut you can also set @var{device} to a hexadecimal or a decimal number
18457c478bd9Sstevel@tonic-gatewhich is a BIOS drive number, so the following are equivalent:
18467c478bd9Sstevel@tonic-gate
18477c478bd9Sstevel@tonic-gate@example
18487c478bd9Sstevel@tonic-gate(hd0)
18497c478bd9Sstevel@tonic-gate(0x80)
18507c478bd9Sstevel@tonic-gate(128)
18517c478bd9Sstevel@tonic-gate@end example
18527c478bd9Sstevel@tonic-gate
18537c478bd9Sstevel@tonic-gate@var{part-num} represents the partition number of @var{device}, starting
18547c478bd9Sstevel@tonic-gatefrom zero for primary partitions and from four for extended partitions,
18557c478bd9Sstevel@tonic-gateand @var{bsd-subpart-letter} represents the BSD disklabel subpartition,
18567c478bd9Sstevel@tonic-gatesuch as @samp{a} or @samp{e}.
18577c478bd9Sstevel@tonic-gate
18587c478bd9Sstevel@tonic-gateA shortcut for specifying BSD subpartitions is
18597c478bd9Sstevel@tonic-gate@code{(@var{device},@var{bsd-subpart-letter})}, in this case, GRUB
18607c478bd9Sstevel@tonic-gatesearches for the first PC partition containing a BSD disklabel, then
18617c478bd9Sstevel@tonic-gatefinds the subpartition @var{bsd-subpart-letter}. Here is an example:
18627c478bd9Sstevel@tonic-gate
18637c478bd9Sstevel@tonic-gate@example
18647c478bd9Sstevel@tonic-gate(hd0,a)
18657c478bd9Sstevel@tonic-gate@end example
18667c478bd9Sstevel@tonic-gate
18677c478bd9Sstevel@tonic-gateThe syntax @samp{(hd0)} represents using the entire disk (or the
18687c478bd9Sstevel@tonic-gateMBR when installing GRUB), while the syntax @samp{(hd0,0)}
18697c478bd9Sstevel@tonic-gaterepresents using the first partition of the disk (or the boot sector
18707c478bd9Sstevel@tonic-gateof the partition when installing GRUB).
18717c478bd9Sstevel@tonic-gate
18727c478bd9Sstevel@tonic-gateIf you enabled the network support, the special drive, @samp{(nd)}, is
18737c478bd9Sstevel@tonic-gatealso available. Before using the network drive, you must initialize the
18747c478bd9Sstevel@tonic-gatenetwork. @xref{Network}, for more information.
18757c478bd9Sstevel@tonic-gate
18767c478bd9Sstevel@tonic-gateIf you boot GRUB from a CD-ROM, @samp{(cd)} is available. @xref{Making
18777c478bd9Sstevel@tonic-gatea GRUB bootable CD-ROM}, for details.
18787c478bd9Sstevel@tonic-gate
18797c478bd9Sstevel@tonic-gate
18807c478bd9Sstevel@tonic-gate@node File name syntax
18817c478bd9Sstevel@tonic-gate@section How to specify files
18827c478bd9Sstevel@tonic-gate
18837c478bd9Sstevel@tonic-gateThere are two ways to specify files, by @dfn{absolute file name} and by
18847c478bd9Sstevel@tonic-gate@dfn{block list}.
18857c478bd9Sstevel@tonic-gate
18867c478bd9Sstevel@tonic-gateAn absolute file name resembles a Unix absolute file name, using
18877c478bd9Sstevel@tonic-gate@samp{/} for the directory separator (not @samp{\} as in DOS). One
18887c478bd9Sstevel@tonic-gateexample is @samp{(hd0,0)/boot/grub/menu.lst}. This means the file
18897c478bd9Sstevel@tonic-gate@file{/boot/grub/menu.lst} in the first partition of the first hard
18907c478bd9Sstevel@tonic-gatedisk. If you omit the device name in an absolute file name, GRUB uses
18917c478bd9Sstevel@tonic-gateGRUB's @dfn{root device} implicitly. So if you set the root device to,
18927c478bd9Sstevel@tonic-gatesay, @samp{(hd1,0)} by the command @command{root} (@pxref{root}), then
18937c478bd9Sstevel@tonic-gate@code{/boot/kernel} is the same as @code{(hd1,0)/boot/kernel}.
18947c478bd9Sstevel@tonic-gate
18957c478bd9Sstevel@tonic-gate
18967c478bd9Sstevel@tonic-gate@node Block list syntax
18977c478bd9Sstevel@tonic-gate@section How to specify block lists
18987c478bd9Sstevel@tonic-gate
18997c478bd9Sstevel@tonic-gateA block list is used for specifying a file that doesn't appear in the
19007c478bd9Sstevel@tonic-gatefilesystem, like a chainloader. The syntax is
19017c478bd9Sstevel@tonic-gate@code{[@var{offset}]+@var{length}[,[@var{offset}]+@var{length}]@dots{}}.
19027c478bd9Sstevel@tonic-gateHere is an example:
19037c478bd9Sstevel@tonic-gate
19047c478bd9Sstevel@tonic-gate@example
19057c478bd9Sstevel@tonic-gate@code{0+100,200+1,300+300}
19067c478bd9Sstevel@tonic-gate@end example
19077c478bd9Sstevel@tonic-gate
19087c478bd9Sstevel@tonic-gateThis represents that GRUB should read blocks 0 through 99, block 200,
19097c478bd9Sstevel@tonic-gateand blocks 300 through 599. If you omit an offset, then GRUB assumes
19107c478bd9Sstevel@tonic-gatethe offset is zero.
19117c478bd9Sstevel@tonic-gate
19127c478bd9Sstevel@tonic-gateLike the file name syntax (@pxref{File name syntax}), if a blocklist
19137c478bd9Sstevel@tonic-gatedoes not contain a device name, then GRUB uses GRUB's @dfn{root
19147c478bd9Sstevel@tonic-gatedevice}. So @code{(hd0,1)+1} is the same as @code{+1} when the root
19157c478bd9Sstevel@tonic-gatedevice is @samp{(hd0,1)}.
19167c478bd9Sstevel@tonic-gate
19177c478bd9Sstevel@tonic-gate
19187c478bd9Sstevel@tonic-gate@node Interface
19197c478bd9Sstevel@tonic-gate@chapter GRUB's user interface
19207c478bd9Sstevel@tonic-gate
19217c478bd9Sstevel@tonic-gateGRUB has both a simple menu interface for choosing preset entries from a
19227c478bd9Sstevel@tonic-gateconfiguration file, and a highly flexible command-line for performing
19237c478bd9Sstevel@tonic-gateany desired combination of boot commands.
19247c478bd9Sstevel@tonic-gate
19257c478bd9Sstevel@tonic-gateGRUB looks for its configuration file as soon as it is loaded. If one
19267c478bd9Sstevel@tonic-gateis found, then the full menu interface is activated using whatever
19277c478bd9Sstevel@tonic-gateentries were found in the file. If you choose the @dfn{command-line} menu
19287c478bd9Sstevel@tonic-gateoption, or if the configuration file was not found, then GRUB drops to
19297c478bd9Sstevel@tonic-gatethe command-line interface.
19307c478bd9Sstevel@tonic-gate
19317c478bd9Sstevel@tonic-gate@menu
19327c478bd9Sstevel@tonic-gate* Command-line interface::      The flexible command-line interface
19337c478bd9Sstevel@tonic-gate* Menu interface::              The simple menu interface
19347c478bd9Sstevel@tonic-gate* Menu entry editor::           Editing a menu entry
19357c478bd9Sstevel@tonic-gate* Hidden menu interface::       The hidden menu interface
19367c478bd9Sstevel@tonic-gate@end menu
19377c478bd9Sstevel@tonic-gate
19387c478bd9Sstevel@tonic-gate
19397c478bd9Sstevel@tonic-gate@node Command-line interface
19407c478bd9Sstevel@tonic-gate@section The flexible command-line interface
19417c478bd9Sstevel@tonic-gate
19427c478bd9Sstevel@tonic-gateThe command-line interface provides a prompt and after it an editable
19437c478bd9Sstevel@tonic-gatetext area much like a command-line in Unix or DOS. Each command is
19447c478bd9Sstevel@tonic-gateimmediately executed after it is entered@footnote{However, this
19457c478bd9Sstevel@tonic-gatebehavior will be changed in the future version, in a user-invisible
19467c478bd9Sstevel@tonic-gateway.}. The commands (@pxref{Command-line and menu entry commands}) are a
19477c478bd9Sstevel@tonic-gatesubset of those available in the configuration file, used with exactly
19487c478bd9Sstevel@tonic-gatethe same syntax.
19497c478bd9Sstevel@tonic-gate
19507c478bd9Sstevel@tonic-gateCursor movement and editing of the text on the line can be done via a
19517c478bd9Sstevel@tonic-gatesubset of the functions available in the Bash shell:
19527c478bd9Sstevel@tonic-gate
19537c478bd9Sstevel@tonic-gate@table @key
19547c478bd9Sstevel@tonic-gate@item C-f
19557c478bd9Sstevel@tonic-gate@itemx PC right key
19567c478bd9Sstevel@tonic-gateMove forward one character.
19577c478bd9Sstevel@tonic-gate
19587c478bd9Sstevel@tonic-gate@item C-b
19597c478bd9Sstevel@tonic-gate@itemx PC left key
19607c478bd9Sstevel@tonic-gateMove back one character.
19617c478bd9Sstevel@tonic-gate
19627c478bd9Sstevel@tonic-gate@item C-a
19637c478bd9Sstevel@tonic-gate@itemx HOME
19647c478bd9Sstevel@tonic-gateMove to the start of the line.
19657c478bd9Sstevel@tonic-gate
19667c478bd9Sstevel@tonic-gate@item C-e
19677c478bd9Sstevel@tonic-gate@itemx END
19687c478bd9Sstevel@tonic-gateMove the the end of the line.
19697c478bd9Sstevel@tonic-gate
19707c478bd9Sstevel@tonic-gate@item C-d
19717c478bd9Sstevel@tonic-gate@itemx DEL
19727c478bd9Sstevel@tonic-gateDelete the character underneath the cursor.
19737c478bd9Sstevel@tonic-gate
19747c478bd9Sstevel@tonic-gate@item C-h
19757c478bd9Sstevel@tonic-gate@itemx BS
19767c478bd9Sstevel@tonic-gateDelete the character to the left of the cursor.
19777c478bd9Sstevel@tonic-gate
19787c478bd9Sstevel@tonic-gate@item C-k
19797c478bd9Sstevel@tonic-gateKill the text from the current cursor position to the end of the line.
19807c478bd9Sstevel@tonic-gate
19817c478bd9Sstevel@tonic-gate@item C-u
19827c478bd9Sstevel@tonic-gateKill backward from the cursor to the beginning of the line.
19837c478bd9Sstevel@tonic-gate
19847c478bd9Sstevel@tonic-gate@item C-y
19857c478bd9Sstevel@tonic-gateYank the killed text back into the buffer at the cursor.
19867c478bd9Sstevel@tonic-gate
19877c478bd9Sstevel@tonic-gate@item C-p
19887c478bd9Sstevel@tonic-gate@itemx PC up key
19897c478bd9Sstevel@tonic-gateMove up through the history list.
19907c478bd9Sstevel@tonic-gate
19917c478bd9Sstevel@tonic-gate@item C-n
19927c478bd9Sstevel@tonic-gate@itemx PC down key
19937c478bd9Sstevel@tonic-gateMove down through the history list.
19947c478bd9Sstevel@tonic-gate@end table
19957c478bd9Sstevel@tonic-gate
19967c478bd9Sstevel@tonic-gateWhen typing commands interactively, if the cursor is within or before
19977c478bd9Sstevel@tonic-gatethe first word in the command-line, pressing the @key{TAB} key (or
19987c478bd9Sstevel@tonic-gate@key{C-i}) will display a listing of the available commands, and if the
19997c478bd9Sstevel@tonic-gatecursor is after the first word, the @kbd{@key{TAB}} will provide a
20007c478bd9Sstevel@tonic-gatecompletion listing of disks, partitions, and file names depending on the
20017c478bd9Sstevel@tonic-gatecontext. Note that to obtain a list of drives, one must open a
20027c478bd9Sstevel@tonic-gateparenthesis, as @command{root (}.
20037c478bd9Sstevel@tonic-gate
20047c478bd9Sstevel@tonic-gateNote that you cannot use the completion functionality in the TFTP
20057c478bd9Sstevel@tonic-gatefilesystem. This is because TFTP doesn't support file name listing for
20067c478bd9Sstevel@tonic-gatethe security.
20077c478bd9Sstevel@tonic-gate
20087c478bd9Sstevel@tonic-gate
20097c478bd9Sstevel@tonic-gate@node Menu interface
20107c478bd9Sstevel@tonic-gate@section The simple menu interface
20117c478bd9Sstevel@tonic-gate
20127c478bd9Sstevel@tonic-gateThe menu interface is quite easy to use. Its commands are both
20137c478bd9Sstevel@tonic-gatereasonably intuitive and described on screen.
20147c478bd9Sstevel@tonic-gate
20157c478bd9Sstevel@tonic-gateBasically, the menu interface provides a list of @dfn{boot entries} to
20167c478bd9Sstevel@tonic-gatethe user to choose from. Use the arrow keys to select the entry of
20177c478bd9Sstevel@tonic-gatechoice, then press @key{RET} to run it.  An optional timeout is
20187c478bd9Sstevel@tonic-gateavailable to boot the default entry (the first one if not set), which is
20197c478bd9Sstevel@tonic-gateaborted by pressing any key.
20207c478bd9Sstevel@tonic-gate
20217c478bd9Sstevel@tonic-gateCommands are available to enter a bare command-line by pressing @key{c}
20227c478bd9Sstevel@tonic-gate(which operates exactly like the non-config-file version of GRUB, but
20237c478bd9Sstevel@tonic-gateallows one to return to the menu if desired by pressing @key{ESC}) or to
20247c478bd9Sstevel@tonic-gateedit any of the @dfn{boot entries} by pressing @key{e}.
20257c478bd9Sstevel@tonic-gate
20267c478bd9Sstevel@tonic-gateIf you protect the menu interface with a password (@pxref{Security}),
20277c478bd9Sstevel@tonic-gateall you can do is choose an entry by pressing @key{RET}, or press
20287c478bd9Sstevel@tonic-gate@key{p} to enter the password.
20297c478bd9Sstevel@tonic-gate
20307c478bd9Sstevel@tonic-gate
20317c478bd9Sstevel@tonic-gate@node Menu entry editor
20327c478bd9Sstevel@tonic-gate@section Editing a menu entry
20337c478bd9Sstevel@tonic-gate
20347c478bd9Sstevel@tonic-gateThe menu entry editor looks much like the main menu interface, but the
20357c478bd9Sstevel@tonic-gatelines in the menu are individual commands in the selected entry instead
20367c478bd9Sstevel@tonic-gateof entry names.
20377c478bd9Sstevel@tonic-gate
20387c478bd9Sstevel@tonic-gateIf an @key{ESC} is pressed in the editor, it aborts all the changes made
20397c478bd9Sstevel@tonic-gateto the configuration entry and returns to the main menu interface.
20407c478bd9Sstevel@tonic-gate
20417c478bd9Sstevel@tonic-gateWhen a particular line is selected, the editor places the user in a
20427c478bd9Sstevel@tonic-gatespecial version of the GRUB command-line to edit that line.  When the
20437c478bd9Sstevel@tonic-gateuser hits @key{RET}, GRUB replaces the line in question in the boot
20447c478bd9Sstevel@tonic-gateentry with the changes (unless it was aborted via @key{ESC},
20457c478bd9Sstevel@tonic-gatein which case the changes are thrown away).
20467c478bd9Sstevel@tonic-gate
20477c478bd9Sstevel@tonic-gateIf you want to add a new line to the menu entry, press @key{o} if adding
20487c478bd9Sstevel@tonic-gatea line after the current line or press @key{O} if before the current
20497c478bd9Sstevel@tonic-gateline.
20507c478bd9Sstevel@tonic-gate
20517c478bd9Sstevel@tonic-gateTo delete a line, hit the key @key{d}. Although GRUB unfortunately
20527c478bd9Sstevel@tonic-gatedoes not support @dfn{undo}, you can do almost the same thing by just
20537c478bd9Sstevel@tonic-gatereturning to the main menu.
20547c478bd9Sstevel@tonic-gate
20557c478bd9Sstevel@tonic-gate
20567c478bd9Sstevel@tonic-gate@node Hidden menu interface
20577c478bd9Sstevel@tonic-gate@section The hidden menu interface
20587c478bd9Sstevel@tonic-gate
20597c478bd9Sstevel@tonic-gateWhen your terminal is dumb or you request GRUB to hide the menu
20607c478bd9Sstevel@tonic-gateinterface explicitly with the command @command{hiddenmenu}
20617c478bd9Sstevel@tonic-gate(@pxref{hiddenmenu}), GRUB doesn't show the menu interface (@pxref{Menu
20627c478bd9Sstevel@tonic-gateinterface}) and automatically boots the default entry, unless
20637c478bd9Sstevel@tonic-gateinterrupted by pressing @key{ESC}.
20647c478bd9Sstevel@tonic-gate
20657c478bd9Sstevel@tonic-gateWhen you interrupt the timeout and your terminal is dumb, GRUB falls
20667c478bd9Sstevel@tonic-gateback to the command-line interface (@pxref{Command-line interface}).
20677c478bd9Sstevel@tonic-gate
20687c478bd9Sstevel@tonic-gate
20697c478bd9Sstevel@tonic-gate@node Commands
20707c478bd9Sstevel@tonic-gate@chapter The list of available commands
20717c478bd9Sstevel@tonic-gate
20727c478bd9Sstevel@tonic-gateIn this chapter, we list all commands that are available in GRUB.
20737c478bd9Sstevel@tonic-gate
20747c478bd9Sstevel@tonic-gateCommands belong to different groups. A few can only be used in
20757c478bd9Sstevel@tonic-gatethe global section of the configuration file (or ``menu''); most
20767c478bd9Sstevel@tonic-gateof them can be entered on the command-line and can be used either
20777c478bd9Sstevel@tonic-gateanywhere in the menu or specifically in the menu entries.
20787c478bd9Sstevel@tonic-gate
20797c478bd9Sstevel@tonic-gate@menu
20807c478bd9Sstevel@tonic-gate* Menu-specific commands::
20817c478bd9Sstevel@tonic-gate* General commands::
20827c478bd9Sstevel@tonic-gate* Command-line and menu entry commands::
20837c478bd9Sstevel@tonic-gate@end menu
20847c478bd9Sstevel@tonic-gate
20857c478bd9Sstevel@tonic-gate
20867c478bd9Sstevel@tonic-gate@node Menu-specific commands
20877c478bd9Sstevel@tonic-gate@section The list of commands for the menu only
20887c478bd9Sstevel@tonic-gate
20897c478bd9Sstevel@tonic-gateThe semantics used in parsing the configuration file are the following:
20907c478bd9Sstevel@tonic-gate
20917c478bd9Sstevel@tonic-gate@itemize @bullet
20927c478bd9Sstevel@tonic-gate@item
20937c478bd9Sstevel@tonic-gateThe menu-specific commands have to be used before any others.
20947c478bd9Sstevel@tonic-gate
20957c478bd9Sstevel@tonic-gate@item
20967c478bd9Sstevel@tonic-gateThe files @emph{must} be in plain-text format.
20977c478bd9Sstevel@tonic-gate
20987c478bd9Sstevel@tonic-gate@item
20997c478bd9Sstevel@tonic-gate@samp{#} at the beginning of a line in a configuration file means it is
21007c478bd9Sstevel@tonic-gateonly a comment.
21017c478bd9Sstevel@tonic-gate
21027c478bd9Sstevel@tonic-gate@item
21037c478bd9Sstevel@tonic-gateOptions are separated by spaces.
21047c478bd9Sstevel@tonic-gate
21057c478bd9Sstevel@tonic-gate@item
21067c478bd9Sstevel@tonic-gateAll numbers can be either decimal or hexadecimal. A hexadecimal number
21077c478bd9Sstevel@tonic-gatemust be preceded by @samp{0x}, and is case-insensitive.
21087c478bd9Sstevel@tonic-gate
21097c478bd9Sstevel@tonic-gate@item
21107c478bd9Sstevel@tonic-gateExtra options or text at the end of the line are ignored unless otherwise
21117c478bd9Sstevel@tonic-gatespecified.
21127c478bd9Sstevel@tonic-gate
21137c478bd9Sstevel@tonic-gate@item
21147c478bd9Sstevel@tonic-gateUnrecognized commands are added to the current entry, except before entries
21157c478bd9Sstevel@tonic-gatestart, where they are ignored.
21167c478bd9Sstevel@tonic-gate@end itemize
21177c478bd9Sstevel@tonic-gate
21187c478bd9Sstevel@tonic-gateThese commands can only be used in the menu:
21197c478bd9Sstevel@tonic-gate
21207c478bd9Sstevel@tonic-gate@menu
21217c478bd9Sstevel@tonic-gate* default::                     Set the default entry
21227c478bd9Sstevel@tonic-gate* fallback::                    Set the fallback entry
21237c478bd9Sstevel@tonic-gate* hiddenmenu::                  Hide the menu interface
21247c478bd9Sstevel@tonic-gate* timeout::                     Set the timeout
21257c478bd9Sstevel@tonic-gate* title::                       Start a menu entry
21267c478bd9Sstevel@tonic-gate@end menu
21277c478bd9Sstevel@tonic-gate
21287c478bd9Sstevel@tonic-gate
21297c478bd9Sstevel@tonic-gate@node default
21307c478bd9Sstevel@tonic-gate@subsection default
21317c478bd9Sstevel@tonic-gate
21327c478bd9Sstevel@tonic-gate@deffn Command default num
21337c478bd9Sstevel@tonic-gateSet the default entry to the entry number @var{num}. Numbering starts
21347c478bd9Sstevel@tonic-gatefrom 0, and the entry number 0 is the default if the command is not
21357c478bd9Sstevel@tonic-gateused.
21367c478bd9Sstevel@tonic-gate
21377c478bd9Sstevel@tonic-gateYou can specify @samp{saved} instead of a number. In this case, the
21387c478bd9Sstevel@tonic-gatedefault entry is the entry saved with the command
21397c478bd9Sstevel@tonic-gate@command{savedefault}. @xref{savedefault}, for more information.
21407c478bd9Sstevel@tonic-gate@end deffn
21417c478bd9Sstevel@tonic-gate
21427c478bd9Sstevel@tonic-gate
21437c478bd9Sstevel@tonic-gate@node fallback
21447c478bd9Sstevel@tonic-gate@subsection fallback
21457c478bd9Sstevel@tonic-gate
21467c478bd9Sstevel@tonic-gate@deffn Command fallback num...
21477c478bd9Sstevel@tonic-gateGo into unattended boot mode: if the default boot entry has any errors,
21487c478bd9Sstevel@tonic-gateinstead of waiting for the user to do something, immediately start
21497c478bd9Sstevel@tonic-gateover using the @var{num} entry (same numbering as the @code{default}
21507c478bd9Sstevel@tonic-gatecommand (@pxref{default})). This obviously won't help if the machine was
21517c478bd9Sstevel@tonic-gaterebooted by a kernel that GRUB loaded. You can specify multiple
21527c478bd9Sstevel@tonic-gatefallback entry numbers.
21537c478bd9Sstevel@tonic-gate@end deffn
21547c478bd9Sstevel@tonic-gate
21557c478bd9Sstevel@tonic-gate
21567c478bd9Sstevel@tonic-gate@node hiddenmenu
21577c478bd9Sstevel@tonic-gate@subsection hiddenmenu
21587c478bd9Sstevel@tonic-gate
21597c478bd9Sstevel@tonic-gate@deffn Command hiddenmenu
21607c478bd9Sstevel@tonic-gateDon't display the menu. If the command is used, no menu will be
21617c478bd9Sstevel@tonic-gatedisplayed on the control terminal, and the default entry will be
21627c478bd9Sstevel@tonic-gatebooted after the timeout expired. The user can still request the
21637c478bd9Sstevel@tonic-gatemenu to be displayed by pressing @key{ESC} before the timeout
21647c478bd9Sstevel@tonic-gateexpires. See also @ref{Hidden menu interface}.
21657c478bd9Sstevel@tonic-gate@end deffn
21667c478bd9Sstevel@tonic-gate
21677c478bd9Sstevel@tonic-gate
21687c478bd9Sstevel@tonic-gate@node timeout
21697c478bd9Sstevel@tonic-gate@subsection timeout
21707c478bd9Sstevel@tonic-gate
21717c478bd9Sstevel@tonic-gate@deffn Command timeout sec
21727c478bd9Sstevel@tonic-gateSet a timeout, in @var{sec} seconds, before automatically booting the
21737c478bd9Sstevel@tonic-gatedefault entry (normally the first entry defined).
21747c478bd9Sstevel@tonic-gate@end deffn
21757c478bd9Sstevel@tonic-gate
21767c478bd9Sstevel@tonic-gate
21777c478bd9Sstevel@tonic-gate@node title
21787c478bd9Sstevel@tonic-gate@subsection title
21797c478bd9Sstevel@tonic-gate
21807c478bd9Sstevel@tonic-gate@deffn Command title name @dots{}
21817c478bd9Sstevel@tonic-gateStart a new boot entry, and set its name to the contents of the rest of
21827c478bd9Sstevel@tonic-gatethe line, starting with the first non-space character.
21837c478bd9Sstevel@tonic-gate@end deffn
21847c478bd9Sstevel@tonic-gate
21857c478bd9Sstevel@tonic-gate
21867c478bd9Sstevel@tonic-gate@node General commands
21877c478bd9Sstevel@tonic-gate@section The list of general commands
21887c478bd9Sstevel@tonic-gate
21897c478bd9Sstevel@tonic-gateCommands usable anywhere in the menu and in the command-line.
21907c478bd9Sstevel@tonic-gate
21917c478bd9Sstevel@tonic-gate@menu
21927c478bd9Sstevel@tonic-gate* bootp::                       Initialize a network device via BOOTP
21937c478bd9Sstevel@tonic-gate* color::                       Color the menu interface
21947c478bd9Sstevel@tonic-gate* device::                      Specify a file as a drive
21957c478bd9Sstevel@tonic-gate* dhcp::                        Initialize a network device via DHCP
21967c478bd9Sstevel@tonic-gate* hide::                        Hide a partition
21977c478bd9Sstevel@tonic-gate* ifconfig::                    Configure a network device manually
21987c478bd9Sstevel@tonic-gate* pager::                       Change the state of the internal pager
21997c478bd9Sstevel@tonic-gate* partnew::                     Make a primary partition
22007c478bd9Sstevel@tonic-gate* parttype::                    Change the type of a partition
22017c478bd9Sstevel@tonic-gate* password::                    Set a password for the menu interface
22027c478bd9Sstevel@tonic-gate* rarp::                        Initialize a network device via RARP
22037c478bd9Sstevel@tonic-gate* serial::                      Set up a serial device
22047c478bd9Sstevel@tonic-gate* setkey::                      Configure the key map
22057c478bd9Sstevel@tonic-gate* terminal::                    Choose a terminal
22067c478bd9Sstevel@tonic-gate* terminfo::                    Define escape sequences for a terminal
22077c478bd9Sstevel@tonic-gate* tftpserver::                  Specify a TFTP server
22087c478bd9Sstevel@tonic-gate* unhide::                      Unhide a partition
22097c478bd9Sstevel@tonic-gate@end menu
22107c478bd9Sstevel@tonic-gate
22117c478bd9Sstevel@tonic-gate
22127c478bd9Sstevel@tonic-gate@node bootp
22137c478bd9Sstevel@tonic-gate@subsection bootp
22147c478bd9Sstevel@tonic-gate
22157c478bd9Sstevel@tonic-gate@deffn Command bootp [@option{--with-configfile}]
22167c478bd9Sstevel@tonic-gateInitialize a network device via the @dfn{BOOTP} protocol. This command
22177c478bd9Sstevel@tonic-gateis only available if GRUB is compiled with netboot support. See also
22187c478bd9Sstevel@tonic-gate@ref{Network}.
22197c478bd9Sstevel@tonic-gate
22207c478bd9Sstevel@tonic-gateIf you specify @option{--with-configfile} to this command, GRUB will
22217c478bd9Sstevel@tonic-gatefetch and load a configuration file specified by your BOOTP server
22227c478bd9Sstevel@tonic-gatewith the vendor tag @samp{150}.
22237c478bd9Sstevel@tonic-gate@end deffn
22247c478bd9Sstevel@tonic-gate
22257c478bd9Sstevel@tonic-gate
22267c478bd9Sstevel@tonic-gate@node color
22277c478bd9Sstevel@tonic-gate@subsection color
22287c478bd9Sstevel@tonic-gate
22297c478bd9Sstevel@tonic-gate@deffn Command color normal [highlight]
22307c478bd9Sstevel@tonic-gateChange the menu colors. The color @var{normal} is used for most
22317c478bd9Sstevel@tonic-gatelines in the menu (@pxref{Menu interface}), and the color
22327c478bd9Sstevel@tonic-gate@var{highlight} is used to highlight the line where the cursor
22337c478bd9Sstevel@tonic-gatepoints. If you omit @var{highlight}, then the inverted color of
22347c478bd9Sstevel@tonic-gate@var{normal} is used for the highlighted line. The format of a color is
22357c478bd9Sstevel@tonic-gate@code{@var{foreground}/@var{background}}. @var{foreground} and
22367c478bd9Sstevel@tonic-gate@var{background} are symbolic color names. A symbolic color name must be
22377c478bd9Sstevel@tonic-gateone of these:
22387c478bd9Sstevel@tonic-gate
22397c478bd9Sstevel@tonic-gate@itemize @bullet
22407c478bd9Sstevel@tonic-gate@item
22417c478bd9Sstevel@tonic-gateblack
22427c478bd9Sstevel@tonic-gate
22437c478bd9Sstevel@tonic-gate@item
22447c478bd9Sstevel@tonic-gateblue
22457c478bd9Sstevel@tonic-gate
22467c478bd9Sstevel@tonic-gate@item
22477c478bd9Sstevel@tonic-gategreen
22487c478bd9Sstevel@tonic-gate
22497c478bd9Sstevel@tonic-gate@item
22507c478bd9Sstevel@tonic-gatecyan
22517c478bd9Sstevel@tonic-gate
22527c478bd9Sstevel@tonic-gate@item
22537c478bd9Sstevel@tonic-gatered
22547c478bd9Sstevel@tonic-gate
22557c478bd9Sstevel@tonic-gate@item
22567c478bd9Sstevel@tonic-gatemagenta
22577c478bd9Sstevel@tonic-gate
22587c478bd9Sstevel@tonic-gate@item
22597c478bd9Sstevel@tonic-gatebrown
22607c478bd9Sstevel@tonic-gate
22617c478bd9Sstevel@tonic-gate@item
22627c478bd9Sstevel@tonic-gatelight-gray
22637c478bd9Sstevel@tonic-gate
22647c478bd9Sstevel@tonic-gate@strong{These below can be specified only for the foreground.}
22657c478bd9Sstevel@tonic-gate
22667c478bd9Sstevel@tonic-gate@item
22677c478bd9Sstevel@tonic-gatedark-gray
22687c478bd9Sstevel@tonic-gate
22697c478bd9Sstevel@tonic-gate@item
22707c478bd9Sstevel@tonic-gatelight-blue
22717c478bd9Sstevel@tonic-gate
22727c478bd9Sstevel@tonic-gate@item
22737c478bd9Sstevel@tonic-gatelight-green
22747c478bd9Sstevel@tonic-gate
22757c478bd9Sstevel@tonic-gate@item
22767c478bd9Sstevel@tonic-gatelight-cyan
22777c478bd9Sstevel@tonic-gate
22787c478bd9Sstevel@tonic-gate@item
22797c478bd9Sstevel@tonic-gatelight-red
22807c478bd9Sstevel@tonic-gate
22817c478bd9Sstevel@tonic-gate@item
22827c478bd9Sstevel@tonic-gatelight-magenta
22837c478bd9Sstevel@tonic-gate
22847c478bd9Sstevel@tonic-gate@item
22857c478bd9Sstevel@tonic-gateyellow
22867c478bd9Sstevel@tonic-gate
22877c478bd9Sstevel@tonic-gate@item
22887c478bd9Sstevel@tonic-gatewhite
22897c478bd9Sstevel@tonic-gate@end itemize
22907c478bd9Sstevel@tonic-gate
22917c478bd9Sstevel@tonic-gateBut only the first eight names can be used for @var{background}. You can
22927c478bd9Sstevel@tonic-gateprefix @code{blink-} to @var{foreground} if you want a blinking
22937c478bd9Sstevel@tonic-gateforeground color.
22947c478bd9Sstevel@tonic-gate
22957c478bd9Sstevel@tonic-gateThis command can be used in the configuration file and on the command
22967c478bd9Sstevel@tonic-gateline, so you may write something like this in your configuration file:
22977c478bd9Sstevel@tonic-gate
22987c478bd9Sstevel@tonic-gate@example
22997c478bd9Sstevel@tonic-gate@group
23007c478bd9Sstevel@tonic-gate# Set default colors.
23017c478bd9Sstevel@tonic-gatecolor light-gray/blue black/light-gray
23027c478bd9Sstevel@tonic-gate
23037c478bd9Sstevel@tonic-gate# Change the colors.
23047c478bd9Sstevel@tonic-gatetitle OS-BS like
23057c478bd9Sstevel@tonic-gatecolor magenta/blue black/magenta
23067c478bd9Sstevel@tonic-gate@end group
23077c478bd9Sstevel@tonic-gate@end example
23087c478bd9Sstevel@tonic-gate@end deffn
23097c478bd9Sstevel@tonic-gate
23107c478bd9Sstevel@tonic-gate
23117c478bd9Sstevel@tonic-gate@node device
23127c478bd9Sstevel@tonic-gate@subsection device
23137c478bd9Sstevel@tonic-gate
23147c478bd9Sstevel@tonic-gate@deffn Command device drive file
23157c478bd9Sstevel@tonic-gateIn the grub shell, specify the file @var{file} as the actual drive for a
23167c478bd9Sstevel@tonic-gate@sc{bios} drive @var{drive}. You can use this command to create a disk
23177c478bd9Sstevel@tonic-gateimage, and/or to fix the drives guessed by GRUB when GRUB fails to
23187c478bd9Sstevel@tonic-gatedetermine them correctly, like this:
23197c478bd9Sstevel@tonic-gate
23207c478bd9Sstevel@tonic-gate@example
23217c478bd9Sstevel@tonic-gate@group
23227c478bd9Sstevel@tonic-gategrub> @kbd{device (fd0) /floppy-image}
23237c478bd9Sstevel@tonic-gategrub> @kbd{device (hd0) /dev/sd0}
23247c478bd9Sstevel@tonic-gate@end group
23257c478bd9Sstevel@tonic-gate@end example
23267c478bd9Sstevel@tonic-gate
23277c478bd9Sstevel@tonic-gateThis command can be used only in the grub shell (@pxref{Invoking the
23287c478bd9Sstevel@tonic-gategrub shell}).
23297c478bd9Sstevel@tonic-gate@end deffn
23307c478bd9Sstevel@tonic-gate
23317c478bd9Sstevel@tonic-gate
23327c478bd9Sstevel@tonic-gate@node dhcp
23337c478bd9Sstevel@tonic-gate@subsection dhcp
23347c478bd9Sstevel@tonic-gate
23357c478bd9Sstevel@tonic-gate@deffn Command dhcp [--with-configfile]
23367c478bd9Sstevel@tonic-gateInitialize a network device via the @dfn{DHCP} protocol. Currently,
23377c478bd9Sstevel@tonic-gatethis command is just an alias for @command{bootp}, since the two
23387c478bd9Sstevel@tonic-gateprotocols are very similar. This command is only available if GRUB is
23397c478bd9Sstevel@tonic-gatecompiled with netboot support. See also @ref{Network}.
23407c478bd9Sstevel@tonic-gate
23417c478bd9Sstevel@tonic-gateIf you specify @option{--with-configfile} to this command, GRUB will
23427c478bd9Sstevel@tonic-gatefetch and load a configuration file specified by your DHCP server
23437c478bd9Sstevel@tonic-gatewith the vendor tag @samp{150}.
23447c478bd9Sstevel@tonic-gate@end deffn
23457c478bd9Sstevel@tonic-gate
23467c478bd9Sstevel@tonic-gate
23477c478bd9Sstevel@tonic-gate@node hide
23487c478bd9Sstevel@tonic-gate@subsection hide
23497c478bd9Sstevel@tonic-gate
23507c478bd9Sstevel@tonic-gate@deffn Command hide partition
23517c478bd9Sstevel@tonic-gateHide the partition @var{partition} by setting the @dfn{hidden} bit in
23527c478bd9Sstevel@tonic-gateits partition type code. This is useful only when booting DOS or Windows
23537c478bd9Sstevel@tonic-gateand multiple primary FAT partitions exist in one disk. See also
23547c478bd9Sstevel@tonic-gate@ref{DOS/Windows}.
23557c478bd9Sstevel@tonic-gate@end deffn
23567c478bd9Sstevel@tonic-gate
23577c478bd9Sstevel@tonic-gate
23587c478bd9Sstevel@tonic-gate@node ifconfig
23597c478bd9Sstevel@tonic-gate@subsection ifconfig
23607c478bd9Sstevel@tonic-gate
23617c478bd9Sstevel@tonic-gate@deffn Command ifconfig [@option{--server=server}] [@option{--gateway=gateway}] [@option{--mask=mask}] [@option{--address=address}]
23627c478bd9Sstevel@tonic-gateConfigure the IP address, the netmask, the gateway, and the server
23637c478bd9Sstevel@tonic-gateaddress of a network device manually. The values must be in dotted
23647c478bd9Sstevel@tonic-gatedecimal format, like @samp{192.168.11.178}. The order of the options is
23657c478bd9Sstevel@tonic-gatenot important. This command shows current network configuration, if no
23667c478bd9Sstevel@tonic-gateoption is specified. See also @ref{Network}.
23677c478bd9Sstevel@tonic-gate@end deffn
23687c478bd9Sstevel@tonic-gate
23697c478bd9Sstevel@tonic-gate
23707c478bd9Sstevel@tonic-gate@node pager
23717c478bd9Sstevel@tonic-gate@subsection pager
23727c478bd9Sstevel@tonic-gate
23737c478bd9Sstevel@tonic-gate@deffn Command pager [flag]
23747c478bd9Sstevel@tonic-gateToggle or set the state of the internal pager. If @var{flag} is
23757c478bd9Sstevel@tonic-gate@samp{on}, the internal pager is enabled. If @var{flag} is @samp{off},
23767c478bd9Sstevel@tonic-gateit is disabled. If no argument is given, the state is toggled.
23777c478bd9Sstevel@tonic-gate@end deffn
23787c478bd9Sstevel@tonic-gate
23797c478bd9Sstevel@tonic-gate
23807c478bd9Sstevel@tonic-gate@node partnew
23817c478bd9Sstevel@tonic-gate@subsection partnew
23827c478bd9Sstevel@tonic-gate
23837c478bd9Sstevel@tonic-gate@deffn Command partnew part type from len
23847c478bd9Sstevel@tonic-gateCreate a new primary partition. @var{part} is a partition specification
23857c478bd9Sstevel@tonic-gatein GRUB syntax (@pxref{Naming convention}); @var{type} is the partition
23867c478bd9Sstevel@tonic-gatetype and must be a number in the range @code{0-0xff}; @var{from} is
23877c478bd9Sstevel@tonic-gatethe starting address and @var{len} is the length, both in sector units.
23887c478bd9Sstevel@tonic-gate@end deffn
23897c478bd9Sstevel@tonic-gate
23907c478bd9Sstevel@tonic-gate
23917c478bd9Sstevel@tonic-gate@node parttype
23927c478bd9Sstevel@tonic-gate@subsection parttype
23937c478bd9Sstevel@tonic-gate
23947c478bd9Sstevel@tonic-gate@deffn Command parttype part type
23957c478bd9Sstevel@tonic-gateChange the type of an existing partition.  @var{part} is a partition
23967c478bd9Sstevel@tonic-gatespecification in GRUB syntax (@pxref{Naming convention}); @var{type}
23977c478bd9Sstevel@tonic-gateis the new partition type and must be a number in the range 0-0xff.
23987c478bd9Sstevel@tonic-gate@end deffn
23997c478bd9Sstevel@tonic-gate
24007c478bd9Sstevel@tonic-gate
24017c478bd9Sstevel@tonic-gate@node password
24027c478bd9Sstevel@tonic-gate@subsection password
24037c478bd9Sstevel@tonic-gate
24047c478bd9Sstevel@tonic-gate@deffn Command password [@option{--md5}] passwd [new-config-file]
24057c478bd9Sstevel@tonic-gateIf used in the first section of a menu file, disable all interactive
24067c478bd9Sstevel@tonic-gateediting control (menu entry editor and command-line) and entries
24077c478bd9Sstevel@tonic-gateprotected by the command @command{lock}. If the password @var{passwd} is
24087c478bd9Sstevel@tonic-gateentered, it loads the @var{new-config-file} as a new config file and
24097c478bd9Sstevel@tonic-gaterestarts the GRUB Stage 2, if @var{new-config-file} is
24107c478bd9Sstevel@tonic-gatespecified. Otherwise, GRUB will just unlock the privileged instructions.
24117c478bd9Sstevel@tonic-gateYou can also use this command in the script section, in which case it
24127c478bd9Sstevel@tonic-gatewill ask for the password, before continuing.  The option
24137c478bd9Sstevel@tonic-gate@option{--md5} tells GRUB that @var{passwd} is encrypted with
24147c478bd9Sstevel@tonic-gate@command{md5crypt} (@pxref{md5crypt}).
24157c478bd9Sstevel@tonic-gate@end deffn
24167c478bd9Sstevel@tonic-gate
24177c478bd9Sstevel@tonic-gate
24187c478bd9Sstevel@tonic-gate@node rarp
24197c478bd9Sstevel@tonic-gate@subsection rarp
24207c478bd9Sstevel@tonic-gate
24217c478bd9Sstevel@tonic-gate@deffn Command rarp
24227c478bd9Sstevel@tonic-gateInitialize a network device via the @dfn{RARP} protocol.  This command
24237c478bd9Sstevel@tonic-gateis only available if GRUB is compiled with netboot support. See also
24247c478bd9Sstevel@tonic-gate@ref{Network}.
24257c478bd9Sstevel@tonic-gate@end deffn
24267c478bd9Sstevel@tonic-gate
24277c478bd9Sstevel@tonic-gate
24287c478bd9Sstevel@tonic-gate@node serial
24297c478bd9Sstevel@tonic-gate@subsection serial
24307c478bd9Sstevel@tonic-gate
24317c478bd9Sstevel@tonic-gate@deffn Command serial [@option{--unit=unit}] [@option{--port=port}] [@option{--speed=speed}] [@option{--word=word}] [@option{--parity=parity}] [@option{--stop=stop}] [@option{--device=dev}]
24327c478bd9Sstevel@tonic-gateInitialize a serial device. @var{unit} is a number in the range 0-3
24337c478bd9Sstevel@tonic-gatespecifying which serial port to use; default is 0, which corresponds to
24347c478bd9Sstevel@tonic-gatethe port often called COM1. @var{port} is the I/O port where the UART
24357c478bd9Sstevel@tonic-gateis to be found; if specified it takes precedence over @var{unit}.
24367c478bd9Sstevel@tonic-gate@var{speed} is the transmission speed; default is 9600. @var{word} and
24377c478bd9Sstevel@tonic-gate@var{stop} are the number of data bits and stop bits. Data bits must
24387c478bd9Sstevel@tonic-gatebe in the range 5-8 and stop bits must be 1 or 2. Default is 8 data
24397c478bd9Sstevel@tonic-gatebits and one stop bit. @var{parity} is one of @samp{no}, @samp{odd},
24407c478bd9Sstevel@tonic-gate@samp{even} and defaults to @samp{no}. The option @option{--device}
24417c478bd9Sstevel@tonic-gatecan only be used in the grub shell and is used to specify the
24427c478bd9Sstevel@tonic-gatetty device to be used in the host operating system (@pxref{Invoking the
24437c478bd9Sstevel@tonic-gategrub shell}).
24447c478bd9Sstevel@tonic-gate
24457c478bd9Sstevel@tonic-gateThe serial port is not used as a communication channel unless the
24467c478bd9Sstevel@tonic-gate@command{terminal} command is used (@pxref{terminal}).
24477c478bd9Sstevel@tonic-gate
24487c478bd9Sstevel@tonic-gateThis command is only available if GRUB is compiled with serial
24497c478bd9Sstevel@tonic-gatesupport. See also @ref{Serial terminal}.
24507c478bd9Sstevel@tonic-gate@end deffn
24517c478bd9Sstevel@tonic-gate
24527c478bd9Sstevel@tonic-gate
24537c478bd9Sstevel@tonic-gate@node setkey
24547c478bd9Sstevel@tonic-gate@subsection setkey
24557c478bd9Sstevel@tonic-gate
24567c478bd9Sstevel@tonic-gate@deffn Command setkey [to_key from_key]
24577c478bd9Sstevel@tonic-gateChange the keyboard map. The key @var{from_key} is mapped to the key
24587c478bd9Sstevel@tonic-gate@var{to_key}. If no argument is specified, reset key mappings. Note that
24597c478bd9Sstevel@tonic-gatethis command @emph{does not} exchange the keys. If you want to exchange
24607c478bd9Sstevel@tonic-gatethe keys, run this command again with the arguments exchanged, like this:
24617c478bd9Sstevel@tonic-gate
24627c478bd9Sstevel@tonic-gate@example
24637c478bd9Sstevel@tonic-gategrub> @kbd{setkey capslock control}
24647c478bd9Sstevel@tonic-gategrub> @kbd{setkey control capslock}
24657c478bd9Sstevel@tonic-gate@end example
24667c478bd9Sstevel@tonic-gate
24677c478bd9Sstevel@tonic-gateA key must be an alphabet letter, a digit, or one of these symbols:
24687c478bd9Sstevel@tonic-gate@samp{escape}, @samp{exclam}, @samp{at}, @samp{numbersign},
24697c478bd9Sstevel@tonic-gate@samp{dollar}, @samp{percent}, @samp{caret}, @samp{ampersand},
24707c478bd9Sstevel@tonic-gate@samp{asterisk}, @samp{parenleft}, @samp{parenright}, @samp{minus},
24717c478bd9Sstevel@tonic-gate@samp{underscore}, @samp{equal}, @samp{plus}, @samp{backspace},
24727c478bd9Sstevel@tonic-gate@samp{tab}, @samp{bracketleft}, @samp{braceleft}, @samp{bracketright},
24737c478bd9Sstevel@tonic-gate@samp{braceright}, @samp{enter}, @samp{control}, @samp{semicolon},
24747c478bd9Sstevel@tonic-gate@samp{colon}, @samp{quote}, @samp{doublequote}, @samp{backquote},
24757c478bd9Sstevel@tonic-gate@samp{tilde}, @samp{shift}, @samp{backslash}, @samp{bar}, @samp{comma},
24767c478bd9Sstevel@tonic-gate@samp{less}, @samp{period}, @samp{greater}, @samp{slash},
24777c478bd9Sstevel@tonic-gate@samp{question}, @samp{alt}, @samp{space}, @samp{capslock}, @samp{FX}
24787c478bd9Sstevel@tonic-gate(@samp{X} is a digit), and @samp{delete}. This table describes to which
24797c478bd9Sstevel@tonic-gatecharacter each of the symbols corresponds:
24807c478bd9Sstevel@tonic-gate
24817c478bd9Sstevel@tonic-gate@table @samp
24827c478bd9Sstevel@tonic-gate@item exclam
24837c478bd9Sstevel@tonic-gate@samp{!}
24847c478bd9Sstevel@tonic-gate
24857c478bd9Sstevel@tonic-gate@item at
24867c478bd9Sstevel@tonic-gate@samp{@@}
24877c478bd9Sstevel@tonic-gate
24887c478bd9Sstevel@tonic-gate@item numbersign
24897c478bd9Sstevel@tonic-gate@samp{#}
24907c478bd9Sstevel@tonic-gate
24917c478bd9Sstevel@tonic-gate@item dollar
24927c478bd9Sstevel@tonic-gate@samp{$}
24937c478bd9Sstevel@tonic-gate
24947c478bd9Sstevel@tonic-gate@item percent
24957c478bd9Sstevel@tonic-gate@samp{%}
24967c478bd9Sstevel@tonic-gate
24977c478bd9Sstevel@tonic-gate@item caret
24987c478bd9Sstevel@tonic-gate@samp{^}
24997c478bd9Sstevel@tonic-gate
25007c478bd9Sstevel@tonic-gate@item ampersand
25017c478bd9Sstevel@tonic-gate@samp{&}
25027c478bd9Sstevel@tonic-gate
25037c478bd9Sstevel@tonic-gate@item asterisk
25047c478bd9Sstevel@tonic-gate@samp{*}
25057c478bd9Sstevel@tonic-gate
25067c478bd9Sstevel@tonic-gate@item parenleft
25077c478bd9Sstevel@tonic-gate@samp{(}
25087c478bd9Sstevel@tonic-gate
25097c478bd9Sstevel@tonic-gate@item parenright
25107c478bd9Sstevel@tonic-gate@samp{)}
25117c478bd9Sstevel@tonic-gate
25127c478bd9Sstevel@tonic-gate@item minus
25137c478bd9Sstevel@tonic-gate@samp{-}
25147c478bd9Sstevel@tonic-gate
25157c478bd9Sstevel@tonic-gate@item underscore
25167c478bd9Sstevel@tonic-gate@samp{_}
25177c478bd9Sstevel@tonic-gate
25187c478bd9Sstevel@tonic-gate@item equal
25197c478bd9Sstevel@tonic-gate@samp{=}
25207c478bd9Sstevel@tonic-gate
25217c478bd9Sstevel@tonic-gate@item plus
25227c478bd9Sstevel@tonic-gate@samp{+}
25237c478bd9Sstevel@tonic-gate
25247c478bd9Sstevel@tonic-gate@item bracketleft
25257c478bd9Sstevel@tonic-gate@samp{[}
25267c478bd9Sstevel@tonic-gate
25277c478bd9Sstevel@tonic-gate@item braceleft
25287c478bd9Sstevel@tonic-gate@samp{@{}
25297c478bd9Sstevel@tonic-gate
25307c478bd9Sstevel@tonic-gate@item bracketright
25317c478bd9Sstevel@tonic-gate@samp{]}
25327c478bd9Sstevel@tonic-gate
25337c478bd9Sstevel@tonic-gate@item braceright
25347c478bd9Sstevel@tonic-gate@samp{@}}
25357c478bd9Sstevel@tonic-gate
25367c478bd9Sstevel@tonic-gate@item semicolon
25377c478bd9Sstevel@tonic-gate@samp{;}
25387c478bd9Sstevel@tonic-gate
25397c478bd9Sstevel@tonic-gate@item colon
25407c478bd9Sstevel@tonic-gate@samp{:}
25417c478bd9Sstevel@tonic-gate
25427c478bd9Sstevel@tonic-gate@item quote
25437c478bd9Sstevel@tonic-gate@samp{'}
25447c478bd9Sstevel@tonic-gate
25457c478bd9Sstevel@tonic-gate@item doublequote
25467c478bd9Sstevel@tonic-gate@samp{"}
25477c478bd9Sstevel@tonic-gate
25487c478bd9Sstevel@tonic-gate@item backquote
25497c478bd9Sstevel@tonic-gate@samp{`}
25507c478bd9Sstevel@tonic-gate
25517c478bd9Sstevel@tonic-gate@item tilde
25527c478bd9Sstevel@tonic-gate@samp{~}
25537c478bd9Sstevel@tonic-gate
25547c478bd9Sstevel@tonic-gate@item backslash
25557c478bd9Sstevel@tonic-gate@samp{\}
25567c478bd9Sstevel@tonic-gate
25577c478bd9Sstevel@tonic-gate@item bar
25587c478bd9Sstevel@tonic-gate@samp{|}
25597c478bd9Sstevel@tonic-gate
25607c478bd9Sstevel@tonic-gate@item comma
25617c478bd9Sstevel@tonic-gate@samp{,}
25627c478bd9Sstevel@tonic-gate
25637c478bd9Sstevel@tonic-gate@item less
25647c478bd9Sstevel@tonic-gate@samp{<}
25657c478bd9Sstevel@tonic-gate
25667c478bd9Sstevel@tonic-gate@item period
25677c478bd9Sstevel@tonic-gate@samp{.}
25687c478bd9Sstevel@tonic-gate
25697c478bd9Sstevel@tonic-gate@item greater
25707c478bd9Sstevel@tonic-gate@samp{>}
25717c478bd9Sstevel@tonic-gate
25727c478bd9Sstevel@tonic-gate@item slash
25737c478bd9Sstevel@tonic-gate@samp{/}
25747c478bd9Sstevel@tonic-gate
25757c478bd9Sstevel@tonic-gate@item question
25767c478bd9Sstevel@tonic-gate@samp{?}
25777c478bd9Sstevel@tonic-gate
25787c478bd9Sstevel@tonic-gate@item space
25797c478bd9Sstevel@tonic-gate@samp{ }
25807c478bd9Sstevel@tonic-gate@end table
25817c478bd9Sstevel@tonic-gate@end deffn
25827c478bd9Sstevel@tonic-gate
25837c478bd9Sstevel@tonic-gate
25847c478bd9Sstevel@tonic-gate@node terminal
25857c478bd9Sstevel@tonic-gate@subsection terminal
25867c478bd9Sstevel@tonic-gate
25877c478bd9Sstevel@tonic-gate@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}]
25887c478bd9Sstevel@tonic-gateSelect a terminal for user interaction. The terminal is assumed to be
25897c478bd9Sstevel@tonic-gateVT100-compatible unless @option{--dumb} is specified. If both
25907c478bd9Sstevel@tonic-gate@option{console} and @option{serial} are specified, then GRUB will use
25917c478bd9Sstevel@tonic-gatethe one where a key is entered first or the first when the timeout
25927c478bd9Sstevel@tonic-gateexpires. If neither are specified, the current setting is
25937c478bd9Sstevel@tonic-gatereported. This command is only available if GRUB is compiled with serial
25947c478bd9Sstevel@tonic-gatesupport. See also @ref{Serial terminal}.
25957c478bd9Sstevel@tonic-gate
25967c478bd9Sstevel@tonic-gateThis may not make sense for most users, but GRUB supports Hercules
25977c478bd9Sstevel@tonic-gateconsole as well. Hercules console is usable like the ordinary console,
25987c478bd9Sstevel@tonic-gateand the usage is quite similar to that for serial terminals: specify
25997c478bd9Sstevel@tonic-gate@option{hercules} as the argument.
26007c478bd9Sstevel@tonic-gate
26017c478bd9Sstevel@tonic-gateThe option @option{--lines} defines the number of lines in your
26027c478bd9Sstevel@tonic-gateterminal, and it is used for the internal pager function. If you don't
26037c478bd9Sstevel@tonic-gatespecify this option, the number is assumed as 24.
26047c478bd9Sstevel@tonic-gate
26057c478bd9Sstevel@tonic-gateThe option @option{--silent} suppresses the message to prompt you to
26067c478bd9Sstevel@tonic-gatehit any key. This might be useful if your system has no terminal
26077c478bd9Sstevel@tonic-gatedevice.
26087c478bd9Sstevel@tonic-gate
26097c478bd9Sstevel@tonic-gateThe option @option{--no-echo} has GRUB not to echo back input
26107c478bd9Sstevel@tonic-gatecharacters. This implies the option @option{--no-edit}.
26117c478bd9Sstevel@tonic-gate
26127c478bd9Sstevel@tonic-gateThe option @option{--no-edit} disables the BASH-like editing feature.
26137c478bd9Sstevel@tonic-gate@end deffn
26147c478bd9Sstevel@tonic-gate
26157c478bd9Sstevel@tonic-gate
26167c478bd9Sstevel@tonic-gate@node terminfo
26177c478bd9Sstevel@tonic-gate@subsection terminfo
26187c478bd9Sstevel@tonic-gate
26197c478bd9Sstevel@tonic-gate@deffn Command terminfo @option{--name=name} @option{--cursor-address=seq} [@option{--clear-screen=seq}] [@option{--enter-standout-mode=seq}] [@option{--exit-standout-mode=seq}]
26207c478bd9Sstevel@tonic-gateDefine the capabilities of your terminal. Use this command to define
26217c478bd9Sstevel@tonic-gateescape sequences, if it is not vt100-compatible. You may use @samp{\e}
26227c478bd9Sstevel@tonic-gatefor @key{ESC} and @samp{^X} for a control character.
26237c478bd9Sstevel@tonic-gate
26247c478bd9Sstevel@tonic-gateYou can use the utility @command{grub-terminfo} to generate
26257c478bd9Sstevel@tonic-gateappropriate arguments to this command. @xref{Invoking grub-terminfo}.
26267c478bd9Sstevel@tonic-gate
26277c478bd9Sstevel@tonic-gateIf no option is specified, the current settings are printed.
26287c478bd9Sstevel@tonic-gate@end deffn
26297c478bd9Sstevel@tonic-gate
26307c478bd9Sstevel@tonic-gate
26317c478bd9Sstevel@tonic-gate@node tftpserver
26327c478bd9Sstevel@tonic-gate@subsection tftpserver
26337c478bd9Sstevel@tonic-gate
26347c478bd9Sstevel@tonic-gate@deffn Command tftpserver ipaddr
26357c478bd9Sstevel@tonic-gate@strong{Caution:} This command exists only for backward
26367c478bd9Sstevel@tonic-gatecompatibility. Use @command{ifconfig} (@pxref{ifconfig}) instead.
26377c478bd9Sstevel@tonic-gate
26387c478bd9Sstevel@tonic-gateOverride a TFTP server address returned by a BOOTP/DHCP/RARP server. The
26397c478bd9Sstevel@tonic-gateargument @var{ipaddr} must be in dotted decimal format, like
26407c478bd9Sstevel@tonic-gate@samp{192.168.0.15}.  This command is only available if GRUB is compiled
26417c478bd9Sstevel@tonic-gatewith netboot support. See also @ref{Network}.
26427c478bd9Sstevel@tonic-gate@end deffn
26437c478bd9Sstevel@tonic-gate
26447c478bd9Sstevel@tonic-gate
26457c478bd9Sstevel@tonic-gate@node unhide
26467c478bd9Sstevel@tonic-gate@subsection unhide
26477c478bd9Sstevel@tonic-gate
26487c478bd9Sstevel@tonic-gate@deffn Command unhide partition
26497c478bd9Sstevel@tonic-gateUnhide the partition @var{partition} by clearing the @dfn{hidden} bit in
26507c478bd9Sstevel@tonic-gateits partition type code. This is useful only when booting DOS or Windows
26517c478bd9Sstevel@tonic-gateand multiple primary partitions exist on one disk. See also
26527c478bd9Sstevel@tonic-gate@ref{DOS/Windows}.
26537c478bd9Sstevel@tonic-gate@end deffn
26547c478bd9Sstevel@tonic-gate
26557c478bd9Sstevel@tonic-gate
26567c478bd9Sstevel@tonic-gate@node Command-line and menu entry commands
26577c478bd9Sstevel@tonic-gate@section The list of command-line and menu entry commands
26587c478bd9Sstevel@tonic-gate
26597c478bd9Sstevel@tonic-gateThese commands are usable in the command-line and in menu entries.  If
26607c478bd9Sstevel@tonic-gateyou forget a command, you can run the command @command{help}
26617c478bd9Sstevel@tonic-gate(@pxref{help}).
26627c478bd9Sstevel@tonic-gate
26637c478bd9Sstevel@tonic-gate@menu
26647c478bd9Sstevel@tonic-gate* blocklist::                   Get the block list notation of a file
26657c478bd9Sstevel@tonic-gate* boot::                        Start up your operating system
26667c478bd9Sstevel@tonic-gate* cat::                         Show the contents of a file
26677c478bd9Sstevel@tonic-gate* chainloader::                 Chain-load another boot loader
26687c478bd9Sstevel@tonic-gate* cmp::                         Compare two files
26697c478bd9Sstevel@tonic-gate* configfile::                  Load a configuration file
26707c478bd9Sstevel@tonic-gate* debug::                       Toggle the debug flag
26717c478bd9Sstevel@tonic-gate* displayapm::                  Display APM information
26727c478bd9Sstevel@tonic-gate* displaymem::                  Display memory configuration
26737c478bd9Sstevel@tonic-gate* embed::                       Embed Stage 1.5
26747c478bd9Sstevel@tonic-gate* find::                        Find a file
26757c478bd9Sstevel@tonic-gate* fstest::                      Test a filesystem
26767c478bd9Sstevel@tonic-gate* geometry::                    Manipulate the geometry of a drive
26777c478bd9Sstevel@tonic-gate* halt::                        Shut down your computer
26787c478bd9Sstevel@tonic-gate* help::                        Show help messages
26797c478bd9Sstevel@tonic-gate* impsprobe::                   Probe SMP
26807c478bd9Sstevel@tonic-gate* initrd::                      Load an initrd
26817c478bd9Sstevel@tonic-gate* install::                     Install GRUB
26827c478bd9Sstevel@tonic-gate* ioprobe::                     Probe I/O ports used for a drive
26837c478bd9Sstevel@tonic-gate* kernel::                      Load a kernel
26847c478bd9Sstevel@tonic-gate* lock::                        Lock a menu entry
26857c478bd9Sstevel@tonic-gate* makeactive::                  Make a partition active
26867c478bd9Sstevel@tonic-gate* map::                         Map a drive to another
26877c478bd9Sstevel@tonic-gate* md5crypt::                    Encrypt a password in MD5 format
26887c478bd9Sstevel@tonic-gate* module::                      Load a module
26897c478bd9Sstevel@tonic-gate* modulenounzip::               Load a module without decompression
26907c478bd9Sstevel@tonic-gate* pause::                       Wait for a key press
26917c478bd9Sstevel@tonic-gate* quit::                        Exit from the grub shell
26927c478bd9Sstevel@tonic-gate* reboot::                      Reboot your computer
26937c478bd9Sstevel@tonic-gate* read::                        Read data from memory
26947c478bd9Sstevel@tonic-gate* root::                        Set GRUB's root device
26957c478bd9Sstevel@tonic-gate* rootnoverify::                Set GRUB's root device without mounting
26967c478bd9Sstevel@tonic-gate* savedefault::                 Save current entry as the default entry
26977c478bd9Sstevel@tonic-gate* setup::                       Set up GRUB's installation automatically
26987c478bd9Sstevel@tonic-gate* testload::                    Load a file for testing a filesystem
26997c478bd9Sstevel@tonic-gate* testvbe::                     Test VESA BIOS EXTENSION
27007c478bd9Sstevel@tonic-gate* uppermem::                    Set the upper memory size
27017c478bd9Sstevel@tonic-gate* vbeprobe::                    Probe VESA BIOS EXTENSION
27027c478bd9Sstevel@tonic-gate@end menu
27037c478bd9Sstevel@tonic-gate
27047c478bd9Sstevel@tonic-gate
27057c478bd9Sstevel@tonic-gate@node blocklist
27067c478bd9Sstevel@tonic-gate@subsection blocklist
27077c478bd9Sstevel@tonic-gate
27087c478bd9Sstevel@tonic-gate@deffn Command blocklist file
27097c478bd9Sstevel@tonic-gatePrint the block list notation of the file @var{file}. @xref{Block list
27107c478bd9Sstevel@tonic-gatesyntax}.
27117c478bd9Sstevel@tonic-gate@end deffn
27127c478bd9Sstevel@tonic-gate
27137c478bd9Sstevel@tonic-gate
27147c478bd9Sstevel@tonic-gate@node boot
27157c478bd9Sstevel@tonic-gate@subsection boot
27167c478bd9Sstevel@tonic-gate
27177c478bd9Sstevel@tonic-gate@deffn Command boot
27187c478bd9Sstevel@tonic-gateBoot the OS or chain-loader which has been loaded. Only necessary if
27197c478bd9Sstevel@tonic-gaterunning the fully interactive command-line (it is implicit at the end of
27207c478bd9Sstevel@tonic-gatea menu entry).
27217c478bd9Sstevel@tonic-gate@end deffn
27227c478bd9Sstevel@tonic-gate
27237c478bd9Sstevel@tonic-gate
27247c478bd9Sstevel@tonic-gate@node cat
27257c478bd9Sstevel@tonic-gate@subsection cat
27267c478bd9Sstevel@tonic-gate
27277c478bd9Sstevel@tonic-gate@deffn Command cat file
27287c478bd9Sstevel@tonic-gateDisplay the contents of the file @var{file}. This command may be useful
27297c478bd9Sstevel@tonic-gateto remind you of your OS's root partition:
27307c478bd9Sstevel@tonic-gate
27317c478bd9Sstevel@tonic-gate@example
27327c478bd9Sstevel@tonic-gategrub> @kbd{cat /etc/fstab}
27337c478bd9Sstevel@tonic-gate@end example
27347c478bd9Sstevel@tonic-gate@end deffn
27357c478bd9Sstevel@tonic-gate
27367c478bd9Sstevel@tonic-gate
27377c478bd9Sstevel@tonic-gate@node chainloader
27387c478bd9Sstevel@tonic-gate@subsection chainloader
27397c478bd9Sstevel@tonic-gate
27407c478bd9Sstevel@tonic-gate@deffn Command chainloader [@option{--force}] file
27417c478bd9Sstevel@tonic-gateLoad @var{file} as a chain-loader. Like any other file loaded by the
27427c478bd9Sstevel@tonic-gatefilesystem code, it can use the blocklist notation to grab the first
27437c478bd9Sstevel@tonic-gatesector of the current partition with @samp{+1}. If you specify the
27447c478bd9Sstevel@tonic-gateoption @option{--force}, then load @var{file} forcibly, whether it has a
27457c478bd9Sstevel@tonic-gatecorrect signature or not. This is required when you want to load a
27467c478bd9Sstevel@tonic-gatedefective boot loader, such as SCO UnixWare 7.1 (@pxref{SCO UnixWare}).
27477c478bd9Sstevel@tonic-gate@end deffn
27487c478bd9Sstevel@tonic-gate
27497c478bd9Sstevel@tonic-gate
27507c478bd9Sstevel@tonic-gate@node cmp
27517c478bd9Sstevel@tonic-gate@subsection cmp
27527c478bd9Sstevel@tonic-gate
27537c478bd9Sstevel@tonic-gate@deffn Command cmp file1 file2
27547c478bd9Sstevel@tonic-gateCompare the file @var{file1} with the file @var{file2}. If they differ
27557c478bd9Sstevel@tonic-gatein size, print the sizes like this:
27567c478bd9Sstevel@tonic-gate
27577c478bd9Sstevel@tonic-gate@example
27587c478bd9Sstevel@tonic-gateDiffer in size: 0x1234 [foo], 0x4321 [bar]
27597c478bd9Sstevel@tonic-gate@end example
27607c478bd9Sstevel@tonic-gate
27617c478bd9Sstevel@tonic-gateIf the sizes are equal but the bytes at an offset differ, then print the
27627c478bd9Sstevel@tonic-gatebytes like this:
27637c478bd9Sstevel@tonic-gate
27647c478bd9Sstevel@tonic-gate@example
27657c478bd9Sstevel@tonic-gateDiffer at the offset 777: 0xbe [foo], 0xef [bar]
27667c478bd9Sstevel@tonic-gate@end example
27677c478bd9Sstevel@tonic-gate
27687c478bd9Sstevel@tonic-gateIf they are completely identical, nothing will be printed.
27697c478bd9Sstevel@tonic-gate@end deffn
27707c478bd9Sstevel@tonic-gate
27717c478bd9Sstevel@tonic-gate
27727c478bd9Sstevel@tonic-gate@node configfile
27737c478bd9Sstevel@tonic-gate@subsection configfile
27747c478bd9Sstevel@tonic-gate
27757c478bd9Sstevel@tonic-gate@deffn Command configfile file
27767c478bd9Sstevel@tonic-gateLoad @var{file} as a configuration file.
27777c478bd9Sstevel@tonic-gate@end deffn
27787c478bd9Sstevel@tonic-gate
27797c478bd9Sstevel@tonic-gate
27807c478bd9Sstevel@tonic-gate@node debug
27817c478bd9Sstevel@tonic-gate@subsection debug
27827c478bd9Sstevel@tonic-gate
27837c478bd9Sstevel@tonic-gate@deffn Command debug
27847c478bd9Sstevel@tonic-gateToggle debug mode (by default it is off). When debug mode is on, some
27857c478bd9Sstevel@tonic-gateextra messages are printed to show disk activity. This global debug flag
27867c478bd9Sstevel@tonic-gateis mainly useful for GRUB developers when testing new code.
27877c478bd9Sstevel@tonic-gate@end deffn
27887c478bd9Sstevel@tonic-gate
27897c478bd9Sstevel@tonic-gate
27907c478bd9Sstevel@tonic-gate@node displayapm
27917c478bd9Sstevel@tonic-gate@subsection displayapm
27927c478bd9Sstevel@tonic-gate
27937c478bd9Sstevel@tonic-gate@deffn Command displayapm
27947c478bd9Sstevel@tonic-gateDisplay APM BIOS information.
27957c478bd9Sstevel@tonic-gate@end deffn
27967c478bd9Sstevel@tonic-gate
27977c478bd9Sstevel@tonic-gate
27987c478bd9Sstevel@tonic-gate@node displaymem
27997c478bd9Sstevel@tonic-gate@subsection displaymem
28007c478bd9Sstevel@tonic-gate
28017c478bd9Sstevel@tonic-gate@deffn Command displaymem
28027c478bd9Sstevel@tonic-gateDisplay what GRUB thinks the system address space map of the machine is,
28037c478bd9Sstevel@tonic-gateincluding all regions of physical @sc{ram} installed. GRUB's
28047c478bd9Sstevel@tonic-gate@dfn{upper/lower memory} display uses the standard BIOS interface for
28057c478bd9Sstevel@tonic-gatethe available memory in the first megabyte, or @dfn{lower memory}, and a
28067c478bd9Sstevel@tonic-gatesynthesized number from various BIOS interfaces of the memory starting
28077c478bd9Sstevel@tonic-gateat 1MB and going up to the first chipset hole for @dfn{upper memory}
28087c478bd9Sstevel@tonic-gate(the standard PC @dfn{upper memory} interface is limited to reporting a
28097c478bd9Sstevel@tonic-gatemaximum of 64MB).
28107c478bd9Sstevel@tonic-gate@end deffn
28117c478bd9Sstevel@tonic-gate
28127c478bd9Sstevel@tonic-gate
28137c478bd9Sstevel@tonic-gate@node embed
28147c478bd9Sstevel@tonic-gate@subsection embed
28157c478bd9Sstevel@tonic-gate
28167c478bd9Sstevel@tonic-gate@deffn Command embed stage1_5 device
28177c478bd9Sstevel@tonic-gateEmbed the Stage 1.5 @var{stage1_5} in the sectors after the MBR if
28187c478bd9Sstevel@tonic-gate@var{device} is a drive, or in the @dfn{boot loader} area if @var{device}
28197c478bd9Sstevel@tonic-gateis a FFS partition or a ReiserFS partition.@footnote{The latter feature
28207c478bd9Sstevel@tonic-gatehas not been implemented yet.} Print the number of sectors which
28217c478bd9Sstevel@tonic-gate@var{stage1_5} occupies, if successful.
28227c478bd9Sstevel@tonic-gate
28237c478bd9Sstevel@tonic-gateUsually, you don't need to run this command directly. @xref{setup}.
28247c478bd9Sstevel@tonic-gate@end deffn
28257c478bd9Sstevel@tonic-gate
28267c478bd9Sstevel@tonic-gate
28277c478bd9Sstevel@tonic-gate@node find
28287c478bd9Sstevel@tonic-gate@subsection find
28297c478bd9Sstevel@tonic-gate
28307c478bd9Sstevel@tonic-gate@deffn Command find filename
28317c478bd9Sstevel@tonic-gateSearch for the file name @var{filename} in all mountable partitions
28327c478bd9Sstevel@tonic-gateand print the list of the devices which contain the file. The file
28337c478bd9Sstevel@tonic-gatename @var{filename} should be an absolute file name like
28347c478bd9Sstevel@tonic-gate@code{/boot/grub/stage1}.
28357c478bd9Sstevel@tonic-gate@end deffn
28367c478bd9Sstevel@tonic-gate
28377c478bd9Sstevel@tonic-gate
28387c478bd9Sstevel@tonic-gate@node fstest
28397c478bd9Sstevel@tonic-gate@subsection fstest
28407c478bd9Sstevel@tonic-gate
28417c478bd9Sstevel@tonic-gate@deffn Command fstest
28427c478bd9Sstevel@tonic-gateToggle filesystem test mode.
28437c478bd9Sstevel@tonic-gateFilesystem test mode, when turned on, prints out data corresponding to
28447c478bd9Sstevel@tonic-gateall the device reads and what values are being sent to the low-level
28457c478bd9Sstevel@tonic-gateroutines. The format is @samp{<@var{partition-offset-sector},
28467c478bd9Sstevel@tonic-gate@var{byte-offset}, @var{byte-length}>} for high-level reads inside a
28477c478bd9Sstevel@tonic-gatepartition, and @samp{[@var{disk-offset-sector}]} for low-level sector
28487c478bd9Sstevel@tonic-gaterequests from the disk.
28497c478bd9Sstevel@tonic-gateFilesystem test mode is turned off by any use of the @command{install}
28507c478bd9Sstevel@tonic-gate(@pxref{install}) or @command{testload} (@pxref{testload}) commands.
28517c478bd9Sstevel@tonic-gate@end deffn
28527c478bd9Sstevel@tonic-gate
28537c478bd9Sstevel@tonic-gate
28547c478bd9Sstevel@tonic-gate@node geometry
28557c478bd9Sstevel@tonic-gate@subsection geometry
28567c478bd9Sstevel@tonic-gate
28577c478bd9Sstevel@tonic-gate@deffn Command geometry drive [cylinder head sector [total_sector]]
28587c478bd9Sstevel@tonic-gatePrint the information for the drive @var{drive}. In the grub shell, you
28597c478bd9Sstevel@tonic-gatecan set the geometry of the drive arbitrarily. The number of
28607c478bd9Sstevel@tonic-gatecylinders, the number of heads, the number of sectors and the number of
28617c478bd9Sstevel@tonic-gatetotal sectors are set to CYLINDER, HEAD, SECTOR and TOTAL_SECTOR,
28627c478bd9Sstevel@tonic-gaterespectively. If you omit TOTAL_SECTOR, then it will be calculated
28637c478bd9Sstevel@tonic-gatebased on the C/H/S values automatically.
28647c478bd9Sstevel@tonic-gate@end deffn
28657c478bd9Sstevel@tonic-gate
28667c478bd9Sstevel@tonic-gate
28677c478bd9Sstevel@tonic-gate@node halt
28687c478bd9Sstevel@tonic-gate@subsection halt
28697c478bd9Sstevel@tonic-gate
28707c478bd9Sstevel@tonic-gate@deffn Command halt @option{--no-apm}
28717c478bd9Sstevel@tonic-gateThe command halts the computer. If the @option{--no-apm} option
28727c478bd9Sstevel@tonic-gateis specified, no APM BIOS call is performed. Otherwise, the computer
28737c478bd9Sstevel@tonic-gateis shut down using APM.
28747c478bd9Sstevel@tonic-gate@end deffn
28757c478bd9Sstevel@tonic-gate
28767c478bd9Sstevel@tonic-gate
28777c478bd9Sstevel@tonic-gate@node help
28787c478bd9Sstevel@tonic-gate@subsection help
28797c478bd9Sstevel@tonic-gate
28807c478bd9Sstevel@tonic-gate@deffn Command help @option{--all} [pattern @dots{}]
28817c478bd9Sstevel@tonic-gateDisplay helpful information about builtin commands. If you do not
28827c478bd9Sstevel@tonic-gatespecify @var{pattern}, this command shows short descriptions of most of
28837c478bd9Sstevel@tonic-gateavailable commands. If you specify the option @option{--all} to this
28847c478bd9Sstevel@tonic-gatecommand, short descriptions of rarely used commands (such as
28857c478bd9Sstevel@tonic-gate@ref{testload}) are displayed as well.
28867c478bd9Sstevel@tonic-gate
28877c478bd9Sstevel@tonic-gateIf you specify any @var{patterns}, it displays longer information
28887c478bd9Sstevel@tonic-gateabout each of the commands which match those @var{patterns}.
28897c478bd9Sstevel@tonic-gate@end deffn
28907c478bd9Sstevel@tonic-gate
28917c478bd9Sstevel@tonic-gate
28927c478bd9Sstevel@tonic-gate@node impsprobe
28937c478bd9Sstevel@tonic-gate@subsection impsprobe
28947c478bd9Sstevel@tonic-gate
28957c478bd9Sstevel@tonic-gate@deffn Command impsprobe
28967c478bd9Sstevel@tonic-gateProbe the Intel Multiprocessor Specification 1.1 or 1.4 configuration
28977c478bd9Sstevel@tonic-gatetable and boot the various CPUs which are found into a tight loop. This
28987c478bd9Sstevel@tonic-gatecommand can be used only in the Stage 2, but not in the grub shell.
28997c478bd9Sstevel@tonic-gate@end deffn
29007c478bd9Sstevel@tonic-gate
29017c478bd9Sstevel@tonic-gate
29027c478bd9Sstevel@tonic-gate@node initrd
29037c478bd9Sstevel@tonic-gate@subsection initrd
29047c478bd9Sstevel@tonic-gate
29057c478bd9Sstevel@tonic-gate@deffn Command initrd file @dots{}
29067c478bd9Sstevel@tonic-gateLoad an initial ramdisk for a Linux format boot image and set the
29077c478bd9Sstevel@tonic-gateappropriate parameters in the Linux setup area in memory. See also
29087c478bd9Sstevel@tonic-gate@ref{GNU/Linux}.
29097c478bd9Sstevel@tonic-gate@end deffn
29107c478bd9Sstevel@tonic-gate
29117c478bd9Sstevel@tonic-gate
29127c478bd9Sstevel@tonic-gate@node install
29137c478bd9Sstevel@tonic-gate@subsection install
29147c478bd9Sstevel@tonic-gate
29157c478bd9Sstevel@tonic-gate@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]
29167c478bd9Sstevel@tonic-gateThis command is fairly complex, and you should not use this command
29177c478bd9Sstevel@tonic-gateunless you are familiar with GRUB. Use @command{setup} (@pxref{setup})
29187c478bd9Sstevel@tonic-gateinstead.
29197c478bd9Sstevel@tonic-gate
29207c478bd9Sstevel@tonic-gateIn short, it will perform a full install presuming the Stage 2 or Stage
29217c478bd9Sstevel@tonic-gate1.5@footnote{They're loaded the same way, so we will refer to the Stage
29227c478bd9Sstevel@tonic-gate1.5 as a Stage 2 from now on.} is in its final install location.
29237c478bd9Sstevel@tonic-gate
29247c478bd9Sstevel@tonic-gateIn slightly more detail, it will load @var{stage1_file}, validate that
29257c478bd9Sstevel@tonic-gateit is a GRUB Stage 1 of the right version number, install in it a
29267c478bd9Sstevel@tonic-gateblocklist for loading @var{stage2_file} as a Stage 2. If the option
29277c478bd9Sstevel@tonic-gate@option{d} is present, the Stage 1 will always look for the actual
29287c478bd9Sstevel@tonic-gatedisk @var{stage2_file} was installed on, rather than using the booting
29297c478bd9Sstevel@tonic-gatedrive. The Stage 2 will be loaded at address @var{addr}, which must be
29307c478bd9Sstevel@tonic-gate@samp{0x8000} for a true Stage 2, and @samp{0x2000} for a Stage 1.5. If
29317c478bd9Sstevel@tonic-gate@var{addr} is not present, GRUB will determine the address
29327c478bd9Sstevel@tonic-gateautomatically. It then writes the completed Stage 1 to the first block
29337c478bd9Sstevel@tonic-gateof the device @var{dest_dev}. If the options @option{p} or
29347c478bd9Sstevel@tonic-gate@var{config_file} are present, then it reads the first block of stage2,
29357c478bd9Sstevel@tonic-gatemodifies it with the values of the partition @var{stage2_file} was found
29367c478bd9Sstevel@tonic-gateon (for @option{p}) or places the string @var{config_file} into the area
29377c478bd9Sstevel@tonic-gatetelling the stage2 where to look for a configuration file at boot
29387c478bd9Sstevel@tonic-gatetime. Likewise, if @var{real_config_file} is present and
29397c478bd9Sstevel@tonic-gate@var{stage2_file} is a Stage 1.5, then the Stage 2 @var{config_file} is
29407c478bd9Sstevel@tonic-gatepatched with the configuration file name @var{real_config_file}. This
29417c478bd9Sstevel@tonic-gatecommand preserves the DOS BPB (and for hard disks, the partition table)
29427c478bd9Sstevel@tonic-gateof the sector the Stage 1 is to be installed into.
29437c478bd9Sstevel@tonic-gate
29447c478bd9Sstevel@tonic-gate@strong{Caution:} Several buggy BIOSes don't pass a booting drive
29457c478bd9Sstevel@tonic-gateproperly when booting from a hard disk drive. Therefore, you will
29467c478bd9Sstevel@tonic-gateunfortunately have to specify the option @option{d}, whether your
29477c478bd9Sstevel@tonic-gateStage2 resides at the booting drive or not, if you have such a
29487c478bd9Sstevel@tonic-gateBIOS. We know these are defective in this way:
29497c478bd9Sstevel@tonic-gate
29507c478bd9Sstevel@tonic-gate@table @asis
29517c478bd9Sstevel@tonic-gate@item
29527c478bd9Sstevel@tonic-gateFujitsu LifeBook 400 BIOS version 31J0103A
29537c478bd9Sstevel@tonic-gate
29547c478bd9Sstevel@tonic-gate@item
29557c478bd9Sstevel@tonic-gateHP Vectra XU 6/200 BIOS version GG.06.11
29567c478bd9Sstevel@tonic-gate@end table
29577c478bd9Sstevel@tonic-gate
29587c478bd9Sstevel@tonic-gate@strong{Caution2:} A number of BIOSes don't return a correct LBA support
29597c478bd9Sstevel@tonic-gatebitmap even if they do have the support. So GRUB provides a solution to
29607c478bd9Sstevel@tonic-gateignore the wrong bitmap, that is, the option @option{--force-lba}. Don't
29617c478bd9Sstevel@tonic-gateuse this option if you know that your BIOS doesn't have LBA support.
29627c478bd9Sstevel@tonic-gate
29637c478bd9Sstevel@tonic-gate@strong{Caution3:} You must specify the option @option{--stage2} in the
29647c478bd9Sstevel@tonic-gategrub shell, if you cannot unmount the filesystem where your stage2 file
29657c478bd9Sstevel@tonic-gateresides. The argument should be the file name in your operating system.
29667c478bd9Sstevel@tonic-gate@end deffn
29677c478bd9Sstevel@tonic-gate
29687c478bd9Sstevel@tonic-gate
29697c478bd9Sstevel@tonic-gate@node ioprobe
29707c478bd9Sstevel@tonic-gate@subsection ioprobe
29717c478bd9Sstevel@tonic-gate
29727c478bd9Sstevel@tonic-gate@deffn Command ioprobe drive
29737c478bd9Sstevel@tonic-gateProbe I/O ports used for the drive @var{drive}. This command will list
29747c478bd9Sstevel@tonic-gatethe I/O ports on the screen. For technical information,
29757c478bd9Sstevel@tonic-gate@xref{Internals}.
29767c478bd9Sstevel@tonic-gate@end deffn
29777c478bd9Sstevel@tonic-gate
29787c478bd9Sstevel@tonic-gate
29797c478bd9Sstevel@tonic-gate@node kernel
29807c478bd9Sstevel@tonic-gate@subsection kernel
29817c478bd9Sstevel@tonic-gate
29827c478bd9Sstevel@tonic-gate@deffn Command kernel [@option{--type=type}] [@option{--no-mem-option}] file @dots{}
29837c478bd9Sstevel@tonic-gateAttempt to load the primary boot image (Multiboot a.out or @sc{elf},
29847c478bd9Sstevel@tonic-gateLinux zImage or bzImage, FreeBSD a.out, NetBSD a.out, etc.) from
29857c478bd9Sstevel@tonic-gate@var{file}. The rest of the line is passed verbatim as the @dfn{kernel
29867c478bd9Sstevel@tonic-gatecommand-line}. Any modules must be reloaded after using this command.
29877c478bd9Sstevel@tonic-gate
29887c478bd9Sstevel@tonic-gateThis command also accepts the option @option{--type} so that you can
29897c478bd9Sstevel@tonic-gatespecify the kernel type of @var{file} explicitly. The argument
29907c478bd9Sstevel@tonic-gate@var{type} must be one of these: @samp{netbsd}, @samp{freebsd},
29917c478bd9Sstevel@tonic-gate@samp{openbsd}, @samp{linux}, @samp{biglinux}, and
29927c478bd9Sstevel@tonic-gate@samp{multiboot}. However, you need to specify it only if you want to
29937c478bd9Sstevel@tonic-gateload a NetBSD @sc{elf} kernel, because GRUB can automatically determine
29947c478bd9Sstevel@tonic-gatea kernel type in the other cases, quite safely.
29957c478bd9Sstevel@tonic-gate
29967c478bd9Sstevel@tonic-gateThe option @option{--no-mem-option} is effective only for Linux. If the
29977c478bd9Sstevel@tonic-gateoption is specified, GRUB doesn't pass the option @option{mem=} to the
29987c478bd9Sstevel@tonic-gatekernel.  This option is implied for Linux kernels 2.4.18 and newer.
29997c478bd9Sstevel@tonic-gate@end deffn
30007c478bd9Sstevel@tonic-gate
30017c478bd9Sstevel@tonic-gate
30027c478bd9Sstevel@tonic-gate@node lock
30037c478bd9Sstevel@tonic-gate@subsection lock
30047c478bd9Sstevel@tonic-gate
30057c478bd9Sstevel@tonic-gate@deffn Command lock
30067c478bd9Sstevel@tonic-gatePrevent normal users from executing arbitrary menu entries. You must use
30077c478bd9Sstevel@tonic-gatethe command @command{password} if you really want this command to be
30087c478bd9Sstevel@tonic-gateuseful (@pxref{password}).
30097c478bd9Sstevel@tonic-gate
30107c478bd9Sstevel@tonic-gateThis command is used in a menu, as shown in this example:
30117c478bd9Sstevel@tonic-gate
30127c478bd9Sstevel@tonic-gate@example
30137c478bd9Sstevel@tonic-gate@group
30147c478bd9Sstevel@tonic-gatetitle This entry is too dangerous to be executed by normal users
30157c478bd9Sstevel@tonic-gatelock
30167c478bd9Sstevel@tonic-gateroot (hd0,a)
30177c478bd9Sstevel@tonic-gatekernel /no-security-os
30187c478bd9Sstevel@tonic-gate@end group
30197c478bd9Sstevel@tonic-gate@end example
30207c478bd9Sstevel@tonic-gate
30217c478bd9Sstevel@tonic-gateSee also @ref{Security}.
30227c478bd9Sstevel@tonic-gate@end deffn
30237c478bd9Sstevel@tonic-gate
30247c478bd9Sstevel@tonic-gate
30257c478bd9Sstevel@tonic-gate@node makeactive
30267c478bd9Sstevel@tonic-gate@subsection makeactive
30277c478bd9Sstevel@tonic-gate
30287c478bd9Sstevel@tonic-gate@deffn Command makeactive
30297c478bd9Sstevel@tonic-gateSet the active partition on the root disk to GRUB's root device.
30307c478bd9Sstevel@tonic-gateThis command is limited to @emph{primary} PC partitions on a hard disk.
30317c478bd9Sstevel@tonic-gate@end deffn
30327c478bd9Sstevel@tonic-gate
30337c478bd9Sstevel@tonic-gate
30347c478bd9Sstevel@tonic-gate@node map
30357c478bd9Sstevel@tonic-gate@subsection map
30367c478bd9Sstevel@tonic-gate
30377c478bd9Sstevel@tonic-gate@deffn Command map to_drive from_drive
30387c478bd9Sstevel@tonic-gateMap the drive @var{from_drive} to the drive @var{to_drive}. This is
30397c478bd9Sstevel@tonic-gatenecessary when you chain-load some operating systems, such as DOS, if
30407c478bd9Sstevel@tonic-gatesuch an OS resides at a non-first drive. Here is an example:
30417c478bd9Sstevel@tonic-gate
30427c478bd9Sstevel@tonic-gate@example
30437c478bd9Sstevel@tonic-gate@group
30447c478bd9Sstevel@tonic-gategrub> @kbd{map (hd0) (hd1)}
30457c478bd9Sstevel@tonic-gategrub> @kbd{map (hd1) (hd0)}
30467c478bd9Sstevel@tonic-gate@end group
30477c478bd9Sstevel@tonic-gate@end example
30487c478bd9Sstevel@tonic-gate
30497c478bd9Sstevel@tonic-gateThe example exchanges the order between the first hard disk and the
30507c478bd9Sstevel@tonic-gatesecond hard disk. See also @ref{DOS/Windows}.
30517c478bd9Sstevel@tonic-gate@end deffn
30527c478bd9Sstevel@tonic-gate
30537c478bd9Sstevel@tonic-gate
30547c478bd9Sstevel@tonic-gate@node md5crypt
30557c478bd9Sstevel@tonic-gate@subsection md5crypt
30567c478bd9Sstevel@tonic-gate
30577c478bd9Sstevel@tonic-gate@deffn Command md5crypt
30587c478bd9Sstevel@tonic-gatePrompt to enter a password, and encrypt it in MD5 format. The encrypted
30597c478bd9Sstevel@tonic-gatepassword can be used with the command @command{password}
30607c478bd9Sstevel@tonic-gate(@pxref{password}). See also @ref{Security}.
30617c478bd9Sstevel@tonic-gate@end deffn
30627c478bd9Sstevel@tonic-gate
30637c478bd9Sstevel@tonic-gate
30647c478bd9Sstevel@tonic-gate@node module
30657c478bd9Sstevel@tonic-gate@subsection module
30667c478bd9Sstevel@tonic-gate
30677c478bd9Sstevel@tonic-gate@deffn Command module file @dots{}
30687c478bd9Sstevel@tonic-gateLoad a boot module @var{file} for a Multiboot format boot image (no
30697c478bd9Sstevel@tonic-gateinterpretation of the file contents are made, so the user of this
30707c478bd9Sstevel@tonic-gatecommand must know what the kernel in question expects). The rest of the
30717c478bd9Sstevel@tonic-gateline is passed as the @dfn{module command-line}, like the
30727c478bd9Sstevel@tonic-gate@command{kernel} command. You must load a Multiboot kernel image before
30737c478bd9Sstevel@tonic-gateloading any module. See also @ref{modulenounzip}.
30747c478bd9Sstevel@tonic-gate@end deffn
30757c478bd9Sstevel@tonic-gate
30767c478bd9Sstevel@tonic-gate
30777c478bd9Sstevel@tonic-gate@node modulenounzip
30787c478bd9Sstevel@tonic-gate@subsection modulenounzip
30797c478bd9Sstevel@tonic-gate
30807c478bd9Sstevel@tonic-gate@deffn Command modulenounzip file @dots{}
30817c478bd9Sstevel@tonic-gateThe same as @command{module} (@pxref{module}), except that automatic
30827c478bd9Sstevel@tonic-gatedecompression is disabled.
30837c478bd9Sstevel@tonic-gate@end deffn
30847c478bd9Sstevel@tonic-gate
30857c478bd9Sstevel@tonic-gate
30867c478bd9Sstevel@tonic-gate@node pause
30877c478bd9Sstevel@tonic-gate@subsection pause
30887c478bd9Sstevel@tonic-gate
30897c478bd9Sstevel@tonic-gate@deffn Command pause message @dots{}
30907c478bd9Sstevel@tonic-gatePrint the @var{message}, then wait until a key is pressed. Note that
30917c478bd9Sstevel@tonic-gateplacing @key{^G} (ASCII code 7) in the message will cause the speaker to
30927c478bd9Sstevel@tonic-gateemit the standard beep sound, which is useful when prompting the user to
30937c478bd9Sstevel@tonic-gatechange floppies.
30947c478bd9Sstevel@tonic-gate@end deffn
30957c478bd9Sstevel@tonic-gate
30967c478bd9Sstevel@tonic-gate
30977c478bd9Sstevel@tonic-gate@node quit
30987c478bd9Sstevel@tonic-gate@subsection quit
30997c478bd9Sstevel@tonic-gate
31007c478bd9Sstevel@tonic-gate@deffn Command quit
31017c478bd9Sstevel@tonic-gateExit from the grub shell @command{grub} (@pxref{Invoking the grub
31027c478bd9Sstevel@tonic-gateshell}). This command can be used only in the grub shell.
31037c478bd9Sstevel@tonic-gate@end deffn
31047c478bd9Sstevel@tonic-gate
31057c478bd9Sstevel@tonic-gate
31067c478bd9Sstevel@tonic-gate@node reboot
31077c478bd9Sstevel@tonic-gate@subsection reboot
31087c478bd9Sstevel@tonic-gate
31097c478bd9Sstevel@tonic-gate@deffn Command reboot
31107c478bd9Sstevel@tonic-gateReboot the computer.
31117c478bd9Sstevel@tonic-gate@end deffn
31127c478bd9Sstevel@tonic-gate
31137c478bd9Sstevel@tonic-gate
31147c478bd9Sstevel@tonic-gate@node read
31157c478bd9Sstevel@tonic-gate@subsection read
31167c478bd9Sstevel@tonic-gate
31177c478bd9Sstevel@tonic-gate@deffn Command read addr
31187c478bd9Sstevel@tonic-gateRead a 32-bit value from memory at address @var{addr} and display it in
31197c478bd9Sstevel@tonic-gatehex format.
31207c478bd9Sstevel@tonic-gate@end deffn
31217c478bd9Sstevel@tonic-gate
31227c478bd9Sstevel@tonic-gate
31237c478bd9Sstevel@tonic-gate@node root
31247c478bd9Sstevel@tonic-gate@subsection root
31257c478bd9Sstevel@tonic-gate
31267c478bd9Sstevel@tonic-gate@deffn Command root device [hdbias]
31277c478bd9Sstevel@tonic-gateSet the current @dfn{root device} to the device @var{device}, then
31287c478bd9Sstevel@tonic-gateattempt to mount it to get the partition size (for passing the partition
31297c478bd9Sstevel@tonic-gatedescriptor in @code{ES:ESI}, used by some chain-loaded boot loaders), the
31307c478bd9Sstevel@tonic-gateBSD drive-type (for booting BSD kernels using their native boot format),
31317c478bd9Sstevel@tonic-gateand correctly determine the PC partition where a BSD sub-partition is
31327c478bd9Sstevel@tonic-gatelocated. The optional @var{hdbias} parameter is a number to tell a BSD
31337c478bd9Sstevel@tonic-gatekernel how many BIOS drive numbers are on controllers before the current
31347c478bd9Sstevel@tonic-gateone. For example, if there is an IDE disk and a SCSI disk, and your
31357c478bd9Sstevel@tonic-gateFreeBSD root partition is on the SCSI disk, then use a @samp{1} for
31367c478bd9Sstevel@tonic-gate@var{hdbias}.
31377c478bd9Sstevel@tonic-gate
31387c478bd9Sstevel@tonic-gateSee also @ref{rootnoverify}.
31397c478bd9Sstevel@tonic-gate@end deffn
31407c478bd9Sstevel@tonic-gate
31417c478bd9Sstevel@tonic-gate
31427c478bd9Sstevel@tonic-gate@node rootnoverify
31437c478bd9Sstevel@tonic-gate@subsection rootnoverify
31447c478bd9Sstevel@tonic-gate
31457c478bd9Sstevel@tonic-gate@deffn Command rootnoverify device [hdbias]
31467c478bd9Sstevel@tonic-gateSimilar to @command{root} (@pxref{root}), but don't attempt to mount the
31477c478bd9Sstevel@tonic-gatepartition. This is useful for when an OS is outside of the area of the
31487c478bd9Sstevel@tonic-gatedisk that GRUB can read, but setting the correct root device is still
31497c478bd9Sstevel@tonic-gatedesired. Note that the items mentioned in @command{root} above which
31507c478bd9Sstevel@tonic-gatederived from attempting the mount will @emph{not} work correctly.
31517c478bd9Sstevel@tonic-gate@end deffn
31527c478bd9Sstevel@tonic-gate
31537c478bd9Sstevel@tonic-gate
31547c478bd9Sstevel@tonic-gate@node savedefault
31557c478bd9Sstevel@tonic-gate@subsection savedefault
31567c478bd9Sstevel@tonic-gate
31577c478bd9Sstevel@tonic-gate@deffn Command savedefault num
31587c478bd9Sstevel@tonic-gateSave the current menu entry or @var{num} if specified as a default
31597c478bd9Sstevel@tonic-gateentry. Here is an example:
31607c478bd9Sstevel@tonic-gate
31617c478bd9Sstevel@tonic-gate@example
31627c478bd9Sstevel@tonic-gate@group
31637c478bd9Sstevel@tonic-gatedefault saved
31647c478bd9Sstevel@tonic-gatetimeout 10
31657c478bd9Sstevel@tonic-gate
31667c478bd9Sstevel@tonic-gatetitle GNU/Linux
31677c478bd9Sstevel@tonic-gateroot (hd0,0)
31687c478bd9Sstevel@tonic-gatekernel /boot/vmlinuz root=/dev/sda1 vga=ext
31697c478bd9Sstevel@tonic-gateinitrd /boot/initrd
31707c478bd9Sstevel@tonic-gatesavedefault
31717c478bd9Sstevel@tonic-gate
31727c478bd9Sstevel@tonic-gatetitle FreeBSD
31737c478bd9Sstevel@tonic-gateroot (hd0,a)
31747c478bd9Sstevel@tonic-gatekernel /boot/loader
31757c478bd9Sstevel@tonic-gatesavedefault
31767c478bd9Sstevel@tonic-gate@end group
31777c478bd9Sstevel@tonic-gate@end example
31787c478bd9Sstevel@tonic-gate
31797c478bd9Sstevel@tonic-gateWith this configuration, GRUB will choose the entry booted previously as
31807c478bd9Sstevel@tonic-gatethe default entry.
31817c478bd9Sstevel@tonic-gate
31827c478bd9Sstevel@tonic-gateYou can specify @samp{fallback} instead of a number. Then, next
31837c478bd9Sstevel@tonic-gatefallback entry is saved. Next fallback entry is chosen from fallback
31847c478bd9Sstevel@tonic-gateentries. Normally, this will be the first entry in fallback ones.
31857c478bd9Sstevel@tonic-gate
31867c478bd9Sstevel@tonic-gateSee also @ref{default} and @ref{Invoking grub-set-default}.
31877c478bd9Sstevel@tonic-gate@end deffn
31887c478bd9Sstevel@tonic-gate
31897c478bd9Sstevel@tonic-gate
31907c478bd9Sstevel@tonic-gate@node setup
31917c478bd9Sstevel@tonic-gate@subsection setup
31927c478bd9Sstevel@tonic-gate
31937c478bd9Sstevel@tonic-gate@deffn Command setup [@option{--force-lba}] [@option{--stage2=os_stage2_file}] [@option{--prefix=dir}] install_device [image_device]
31947c478bd9Sstevel@tonic-gateSet up the installation of GRUB automatically. This command uses the
31957c478bd9Sstevel@tonic-gatemore flexible command @command{install} (@pxref{install}) in the backend
31967c478bd9Sstevel@tonic-gateand installs GRUB into the device @var{install_device}. If
31977c478bd9Sstevel@tonic-gate@var{image_device} is specified, then find the GRUB images
31987c478bd9Sstevel@tonic-gate(@pxref{Images}) in the device @var{image_device}, otherwise use the
31997c478bd9Sstevel@tonic-gatecurrent @dfn{root device}, which can be set by the command
32007c478bd9Sstevel@tonic-gate@command{root}. If @var{install_device} is a hard disk, then embed a
32017c478bd9Sstevel@tonic-gateStage 1.5 in the disk if possible.
32027c478bd9Sstevel@tonic-gate
32037c478bd9Sstevel@tonic-gateThe option @option{--prefix} specifies the directory under which GRUB
32047c478bd9Sstevel@tonic-gateimages are put. If it is not specified, GRUB automatically searches them
32057c478bd9Sstevel@tonic-gatein @file{/boot/grub} and @file{/grub}.
32067c478bd9Sstevel@tonic-gate
32077c478bd9Sstevel@tonic-gateThe options @option{--force-lba} and @option{--stage2} are just passed
32087c478bd9Sstevel@tonic-gateto @command{install} if specified. @xref{install}, for more
32097c478bd9Sstevel@tonic-gateinformation.
32107c478bd9Sstevel@tonic-gate@end deffn
32117c478bd9Sstevel@tonic-gate
32127c478bd9Sstevel@tonic-gate
32137c478bd9Sstevel@tonic-gate@node testload
32147c478bd9Sstevel@tonic-gate@subsection testload
32157c478bd9Sstevel@tonic-gate
32167c478bd9Sstevel@tonic-gate@deffn Command testload file
32177c478bd9Sstevel@tonic-gateRead the entire contents of @var{file} in several different ways and
32187c478bd9Sstevel@tonic-gatecompare them, to test the filesystem code. The output is somewhat
32197c478bd9Sstevel@tonic-gatecryptic, but if no errors are reported and the final @samp{i=@var{X},
32207c478bd9Sstevel@tonic-gatefilepos=@var{Y}} reading has @var{X} and @var{Y} equal, then it is
32217c478bd9Sstevel@tonic-gatedefinitely consistent, and very likely works correctly subject to a
32227c478bd9Sstevel@tonic-gateconsistent offset error. If this test succeeds, then a good next step is
32237c478bd9Sstevel@tonic-gateto try loading a kernel.
32247c478bd9Sstevel@tonic-gate@end deffn
32257c478bd9Sstevel@tonic-gate
32267c478bd9Sstevel@tonic-gate
32277c478bd9Sstevel@tonic-gate@node testvbe
32287c478bd9Sstevel@tonic-gate@subsection testvbe
32297c478bd9Sstevel@tonic-gate
32307c478bd9Sstevel@tonic-gate@deffn Command testvbe mode
32317c478bd9Sstevel@tonic-gateTest the VESA BIOS EXTENSION mode @var{mode}. This command will switch
32327c478bd9Sstevel@tonic-gateyour video card to the graphics mode, and show an endless animation. Hit
32337c478bd9Sstevel@tonic-gateany key to return. See also @ref{vbeprobe}.
32347c478bd9Sstevel@tonic-gate@end deffn
32357c478bd9Sstevel@tonic-gate
32367c478bd9Sstevel@tonic-gate
32377c478bd9Sstevel@tonic-gate@node uppermem
32387c478bd9Sstevel@tonic-gate@subsection uppermem
32397c478bd9Sstevel@tonic-gate
32407c478bd9Sstevel@tonic-gate@deffn Command uppermem kbytes
32417c478bd9Sstevel@tonic-gateForce GRUB to assume that only @var{kbytes} kilobytes of upper memory
32427c478bd9Sstevel@tonic-gateare installed. Any system address range maps are discarded.
32437c478bd9Sstevel@tonic-gate
32447c478bd9Sstevel@tonic-gate@strong{Caution:} This should be used with great caution, and should
32457c478bd9Sstevel@tonic-gateonly be necessary on some old machines. GRUB's BIOS probe can pick up
32467c478bd9Sstevel@tonic-gateall @sc{ram} on all new machines the author has ever heard of. It can
32477c478bd9Sstevel@tonic-gatealso be used for debugging purposes to lie to an OS.
32487c478bd9Sstevel@tonic-gate@end deffn
32497c478bd9Sstevel@tonic-gate
32507c478bd9Sstevel@tonic-gate
32517c478bd9Sstevel@tonic-gate@node vbeprobe
32527c478bd9Sstevel@tonic-gate@subsection vbeprobe
32537c478bd9Sstevel@tonic-gate
32547c478bd9Sstevel@tonic-gate@deffn Command vbeprobe [mode]
32557c478bd9Sstevel@tonic-gateProbe VESA BIOS EXTENSION information. If the mode @var{mode} is
32567c478bd9Sstevel@tonic-gatespecified, show only the information about @var{mode}. Otherwise, this
32577c478bd9Sstevel@tonic-gatecommand lists up available VBE modes on the screen. See also
32587c478bd9Sstevel@tonic-gate@ref{testvbe}.
32597c478bd9Sstevel@tonic-gate@end deffn
32607c478bd9Sstevel@tonic-gate
32617c478bd9Sstevel@tonic-gate
32627c478bd9Sstevel@tonic-gate@node Troubleshooting
32637c478bd9Sstevel@tonic-gate@chapter Error messages reported by GRUB
32647c478bd9Sstevel@tonic-gate
32657c478bd9Sstevel@tonic-gateThis chapter describes error messages reported by GRUB when you
32667c478bd9Sstevel@tonic-gateencounter trouble. @xref{Invoking the grub shell}, if your problem is
32677c478bd9Sstevel@tonic-gatespecific to the grub shell.
32687c478bd9Sstevel@tonic-gate
32697c478bd9Sstevel@tonic-gate@menu
32707c478bd9Sstevel@tonic-gate* Stage1 errors::               Errors reported by the Stage 1
32717c478bd9Sstevel@tonic-gate* Stage1.5 errors::             Errors reported by the Stage 1.5
32727c478bd9Sstevel@tonic-gate* Stage2 errors::               Errors reported by the Stage 2
32737c478bd9Sstevel@tonic-gate@end menu
32747c478bd9Sstevel@tonic-gate
32757c478bd9Sstevel@tonic-gate
32767c478bd9Sstevel@tonic-gate@node Stage1 errors
32777c478bd9Sstevel@tonic-gate@section Errors reported by the Stage 1
32787c478bd9Sstevel@tonic-gate
32797c478bd9Sstevel@tonic-gateThe general way that the Stage 1 handles errors is to print an error
32807c478bd9Sstevel@tonic-gatestring and then halt. Pressing @kbd{@key{CTRL}-@key{ALT}-@key{DEL}} will
32817c478bd9Sstevel@tonic-gatereboot.
32827c478bd9Sstevel@tonic-gate
32837c478bd9Sstevel@tonic-gateThe following is a comprehensive list of error messages for the Stage 1:
32847c478bd9Sstevel@tonic-gate
32857c478bd9Sstevel@tonic-gate@table @asis
32867c478bd9Sstevel@tonic-gate@item Hard Disk Error
32877c478bd9Sstevel@tonic-gateThe stage2 or stage1.5 is being read from a hard disk, and the attempt
32887c478bd9Sstevel@tonic-gateto determine the size and geometry of the hard disk failed.
32897c478bd9Sstevel@tonic-gate
32907c478bd9Sstevel@tonic-gate@item Floppy Error
32917c478bd9Sstevel@tonic-gateThe stage2 or stage1.5 is being read from a floppy disk, and the attempt
32927c478bd9Sstevel@tonic-gateto determine the size and geometry of the floppy disk failed. It's listed
32937c478bd9Sstevel@tonic-gateas a separate error since the probe sequence is different than for hard
32947c478bd9Sstevel@tonic-gatedisks.
32957c478bd9Sstevel@tonic-gate
32967c478bd9Sstevel@tonic-gate@item Read Error
32977c478bd9Sstevel@tonic-gateA disk read error happened while trying to read the stage2 or stage1.5.
32987c478bd9Sstevel@tonic-gate
32997c478bd9Sstevel@tonic-gate@item Geom Error
33007c478bd9Sstevel@tonic-gateThe location of the stage2 or stage1.5 is not in the portion of the disk
33017c478bd9Sstevel@tonic-gatesupported directly by the BIOS read calls.  This could occur because the
33027c478bd9Sstevel@tonic-gateBIOS translated geometry has been changed by the user or the disk is
33037c478bd9Sstevel@tonic-gatemoved to another machine or controller after installation, or GRUB was
33047c478bd9Sstevel@tonic-gatenot installed using itself (if it was, the Stage 2 version of this error
33057c478bd9Sstevel@tonic-gatewould have been seen during that process and it would not have completed
33067c478bd9Sstevel@tonic-gatethe install).
33077c478bd9Sstevel@tonic-gate@end table
33087c478bd9Sstevel@tonic-gate
33097c478bd9Sstevel@tonic-gate
33107c478bd9Sstevel@tonic-gate@node Stage1.5 errors
33117c478bd9Sstevel@tonic-gate@section Errors reported by the Stage 1.5
33127c478bd9Sstevel@tonic-gate
33137c478bd9Sstevel@tonic-gateThe general way that the Stage 1.5 handles errors is to print an error
33147c478bd9Sstevel@tonic-gatenumber in the form @code{Error @var{num}} and then halt. Pressing
33157c478bd9Sstevel@tonic-gate@kbd{@key{CTRL}-@key{ALT}-@key{DEL}} will reboot.
33167c478bd9Sstevel@tonic-gate
33177c478bd9Sstevel@tonic-gateThe error numbers correspond to the errors reported by Stage
33187c478bd9Sstevel@tonic-gate2. @xref{Stage2 errors}.
33197c478bd9Sstevel@tonic-gate
33207c478bd9Sstevel@tonic-gate
33217c478bd9Sstevel@tonic-gate@node Stage2 errors
33227c478bd9Sstevel@tonic-gate@section Errors reported by the Stage 2
33237c478bd9Sstevel@tonic-gate
33247c478bd9Sstevel@tonic-gateThe general way that the Stage 2 handles errors is to abort the
33257c478bd9Sstevel@tonic-gateoperation in question, print an error string, then (if possible) either
33267c478bd9Sstevel@tonic-gatecontinue based on the fact that an error occurred or wait for the user to
33277c478bd9Sstevel@tonic-gatedeal with the error.
33287c478bd9Sstevel@tonic-gate
33297c478bd9Sstevel@tonic-gateThe following is a comprehensive list of error messages for the Stage 2
33307c478bd9Sstevel@tonic-gate(error numbers for the Stage 1.5 are listed before the colon in each
33317c478bd9Sstevel@tonic-gatedescription):
33327c478bd9Sstevel@tonic-gate
33337c478bd9Sstevel@tonic-gate@table @asis
33347c478bd9Sstevel@tonic-gate@item 1 : Filename must be either an absolute filename or blocklist
33357c478bd9Sstevel@tonic-gateThis error is returned if a file name is requested which doesn't fit the
33367c478bd9Sstevel@tonic-gatesyntax/rules listed in the @ref{Filesystem}.
33377c478bd9Sstevel@tonic-gate
33387c478bd9Sstevel@tonic-gate@item 2 : Bad file or directory type
33397c478bd9Sstevel@tonic-gateThis error is returned if a file requested is not a regular file, but
33407c478bd9Sstevel@tonic-gatesomething like a symbolic link, directory, or FIFO.
33417c478bd9Sstevel@tonic-gate
33427c478bd9Sstevel@tonic-gate@item 3 : Bad or corrupt data while decompressing file
33437c478bd9Sstevel@tonic-gateThis error is returned if the run-length decompression code gets an
33447c478bd9Sstevel@tonic-gateinternal error. This is usually from a corrupt file.
33457c478bd9Sstevel@tonic-gate
33467c478bd9Sstevel@tonic-gate@item 4 : Bad or incompatible header in compressed file
33477c478bd9Sstevel@tonic-gateThis error is returned if the file header for a supposedly compressed
33487c478bd9Sstevel@tonic-gatefile is bad.
33497c478bd9Sstevel@tonic-gate
33507c478bd9Sstevel@tonic-gate@item 5 : Partition table invalid or corrupt
33517c478bd9Sstevel@tonic-gateThis error is returned if the sanity checks on the integrity of the
33527c478bd9Sstevel@tonic-gatepartition table fail. This is a bad sign.
33537c478bd9Sstevel@tonic-gate
33547c478bd9Sstevel@tonic-gate@item 6 : Mismatched or corrupt version of stage1/stage2
33557c478bd9Sstevel@tonic-gateThis error is returned if the install command points to incompatible
33567c478bd9Sstevel@tonic-gateor corrupt versions of the stage1 or stage2. It can't detect corruption
33577c478bd9Sstevel@tonic-gatein general, but this is a sanity check on the version numbers, which
33587c478bd9Sstevel@tonic-gateshould be correct.
33597c478bd9Sstevel@tonic-gate
33607c478bd9Sstevel@tonic-gate@item 7 : Loading below 1MB is not supported
33617c478bd9Sstevel@tonic-gateThis error is returned if the lowest address in a kernel is below the
33627c478bd9Sstevel@tonic-gate1MB boundary. The Linux zImage format is a special case and can be
33637c478bd9Sstevel@tonic-gatehandled since it has a fixed loading address and maximum size.
33647c478bd9Sstevel@tonic-gate
33657c478bd9Sstevel@tonic-gate@item 8 : Kernel must be loaded before booting
33667c478bd9Sstevel@tonic-gateThis error is returned if GRUB is told to execute the boot sequence
33677c478bd9Sstevel@tonic-gatewithout having a kernel to start.
33687c478bd9Sstevel@tonic-gate
33697c478bd9Sstevel@tonic-gate@item 9 : Unknown boot failure
33707c478bd9Sstevel@tonic-gateThis error is returned if the boot attempt did not succeed for reasons
33717c478bd9Sstevel@tonic-gatewhich are unknown.
33727c478bd9Sstevel@tonic-gate
33737c478bd9Sstevel@tonic-gate@item 10 : Unsupported Multiboot features requested
33747c478bd9Sstevel@tonic-gateThis error is returned when the Multiboot features word in the Multiboot
33757c478bd9Sstevel@tonic-gateheader requires a feature that is not recognized. The point of this is
33767c478bd9Sstevel@tonic-gatethat the kernel requires special handling which GRUB is probably
33777c478bd9Sstevel@tonic-gateunable to provide.
33787c478bd9Sstevel@tonic-gate
33797c478bd9Sstevel@tonic-gate@item 11 : Unrecognized device string
33807c478bd9Sstevel@tonic-gateThis error is returned if a device string was expected, and the string
33817c478bd9Sstevel@tonic-gateencountered didn't fit the syntax/rules listed in the @ref{Filesystem}.
33827c478bd9Sstevel@tonic-gate
33837c478bd9Sstevel@tonic-gate@item 12 : Invalid device requested
33847c478bd9Sstevel@tonic-gateThis error is returned if a device string is recognizable but does not
33857c478bd9Sstevel@tonic-gatefall under the other device errors.
33867c478bd9Sstevel@tonic-gate
33877c478bd9Sstevel@tonic-gate@item 13 : Invalid or unsupported executable format
33887c478bd9Sstevel@tonic-gateThis error is returned if the kernel image being loaded is not
33897c478bd9Sstevel@tonic-gaterecognized as Multiboot or one of the supported native formats (Linux
33907c478bd9Sstevel@tonic-gatezImage or bzImage, FreeBSD, or NetBSD).
33917c478bd9Sstevel@tonic-gate
33927c478bd9Sstevel@tonic-gate@item 14 : Filesystem compatibility error, cannot read whole file
33937c478bd9Sstevel@tonic-gateSome of the filesystem reading code in GRUB has limits on the length of
33947c478bd9Sstevel@tonic-gatethe files it can read. This error is returned when the user runs into
33957c478bd9Sstevel@tonic-gatesuch a limit.
33967c478bd9Sstevel@tonic-gate
33977c478bd9Sstevel@tonic-gate@item 15 : File not found
33987c478bd9Sstevel@tonic-gateThis error is returned if the specified file name cannot be found, but
33997c478bd9Sstevel@tonic-gateeverything else (like the disk/partition info) is OK.
34007c478bd9Sstevel@tonic-gate
34017c478bd9Sstevel@tonic-gate@item 16 : Inconsistent filesystem structure
34027c478bd9Sstevel@tonic-gateThis error is returned by the filesystem code to denote an internal
34037c478bd9Sstevel@tonic-gateerror caused by the sanity checks of the filesystem structure on disk
34047c478bd9Sstevel@tonic-gatenot matching what it expects. This is usually caused by a corrupt
34057c478bd9Sstevel@tonic-gatefilesystem or bugs in the code handling it in GRUB.
34067c478bd9Sstevel@tonic-gate
34077c478bd9Sstevel@tonic-gate@item 17 : Cannot mount selected partition
34087c478bd9Sstevel@tonic-gateThis error is returned if the partition requested exists, but the
34097c478bd9Sstevel@tonic-gatefilesystem type cannot be recognized by GRUB.
34107c478bd9Sstevel@tonic-gate
34117c478bd9Sstevel@tonic-gate@item 18 : Selected cylinder exceeds maximum supported by BIOS
34127c478bd9Sstevel@tonic-gateThis error is returned when a read is attempted at a linear block
34137c478bd9Sstevel@tonic-gateaddress beyond the end of the BIOS translated area. This generally
34147c478bd9Sstevel@tonic-gatehappens if your disk is larger than the BIOS can handle (512MB for
34157c478bd9Sstevel@tonic-gate(E)IDE disks on older machines or larger than 8GB in general).
34167c478bd9Sstevel@tonic-gate
34177c478bd9Sstevel@tonic-gate@item 19 : Linux kernel must be loaded before initrd
34187c478bd9Sstevel@tonic-gateThis error is returned if the initrd command is used before loading a
34197c478bd9Sstevel@tonic-gateLinux kernel.
34207c478bd9Sstevel@tonic-gate
34217c478bd9Sstevel@tonic-gate@item 20 : Multiboot kernel must be loaded before modules
34227c478bd9Sstevel@tonic-gateThis error is returned if the module load command is used before loading
34237c478bd9Sstevel@tonic-gatea Multiboot kernel. It only makes sense in this case anyway, as GRUB has
34247c478bd9Sstevel@tonic-gateno idea how to communicate the presence of such modules to a
34257c478bd9Sstevel@tonic-gatenon-Multiboot-aware kernel.
34267c478bd9Sstevel@tonic-gate
34277c478bd9Sstevel@tonic-gate@item 21 : Selected disk does not exist
34287c478bd9Sstevel@tonic-gateThis error is returned if the device part of a device- or full file name
34297c478bd9Sstevel@tonic-gaterefers to a disk or BIOS device that is not present or not recognized by
34307c478bd9Sstevel@tonic-gatethe BIOS in the system.
34317c478bd9Sstevel@tonic-gate
34327c478bd9Sstevel@tonic-gate@item 22 : No such partition
34337c478bd9Sstevel@tonic-gateThis error is returned if a partition is requested in the device part of
34347c478bd9Sstevel@tonic-gatea device- or full file name which isn't on the selected disk.
34357c478bd9Sstevel@tonic-gate
34367c478bd9Sstevel@tonic-gate@item 23 : Error while parsing number
34377c478bd9Sstevel@tonic-gateThis error is returned if GRUB was expecting to read a number and
34387c478bd9Sstevel@tonic-gateencountered bad data.
34397c478bd9Sstevel@tonic-gate
34407c478bd9Sstevel@tonic-gate@item 24 : Attempt to access block outside partition
34417c478bd9Sstevel@tonic-gateThis error is returned if a linear block address is outside of the disk
34427c478bd9Sstevel@tonic-gatepartition. This generally happens because of a corrupt filesystem on the
34437c478bd9Sstevel@tonic-gatedisk or a bug in the code handling it in GRUB (it's a great debugging
34447c478bd9Sstevel@tonic-gatetool).
34457c478bd9Sstevel@tonic-gate
34467c478bd9Sstevel@tonic-gate@item 25 : Disk read error
34477c478bd9Sstevel@tonic-gateThis error is returned if there is a disk read error when trying to
34487c478bd9Sstevel@tonic-gateprobe or read data from a particular disk.
34497c478bd9Sstevel@tonic-gate
34507c478bd9Sstevel@tonic-gate@item 26 : Too many symbolic links
34517c478bd9Sstevel@tonic-gateThis error is returned if the link count is beyond the maximum
34527c478bd9Sstevel@tonic-gate(currently 5), possibly the symbolic links are looped.
34537c478bd9Sstevel@tonic-gate
34547c478bd9Sstevel@tonic-gate@item 27 : Unrecognized command
34557c478bd9Sstevel@tonic-gateThis error is returned if an unrecognized command is entered on the
34567c478bd9Sstevel@tonic-gatecommand-line or in a boot sequence section of a configuration file and
34577c478bd9Sstevel@tonic-gatethat entry is selected.
34587c478bd9Sstevel@tonic-gate
34597c478bd9Sstevel@tonic-gate@item 28 : Selected item cannot fit into memory
34607c478bd9Sstevel@tonic-gateThis error is returned if a kernel, module, or raw file load command is
34617c478bd9Sstevel@tonic-gateeither trying to load its data such that it won't fit into memory or it
34627c478bd9Sstevel@tonic-gateis simply too big.
34637c478bd9Sstevel@tonic-gate
34647c478bd9Sstevel@tonic-gate@item 29 : Disk write error
34657c478bd9Sstevel@tonic-gateThis error is returned if there is a disk write error when trying to
34667c478bd9Sstevel@tonic-gatewrite to a particular disk. This would generally only occur during an
34677c478bd9Sstevel@tonic-gateinstall of set active partition command.
34687c478bd9Sstevel@tonic-gate
34697c478bd9Sstevel@tonic-gate@item 30 : Invalid argument
34707c478bd9Sstevel@tonic-gateThis error is returned if an argument specified to a command is invalid.
34717c478bd9Sstevel@tonic-gate
34727c478bd9Sstevel@tonic-gate@item 31 : File is not sector aligned
34737c478bd9Sstevel@tonic-gateThis error may occur only when you access a ReiserFS partition by
34747c478bd9Sstevel@tonic-gateblock-lists (e.g. the command @command{install}). In this case, you
34757c478bd9Sstevel@tonic-gateshould mount the partition with the @samp{-o notail} option.
34767c478bd9Sstevel@tonic-gate
34777c478bd9Sstevel@tonic-gate@item 32 : Must be authenticated
34787c478bd9Sstevel@tonic-gateThis error is returned if you try to run a locked entry. You should
34797c478bd9Sstevel@tonic-gateenter a correct password before running such an entry.
34807c478bd9Sstevel@tonic-gate
34817c478bd9Sstevel@tonic-gate@item 33 : Serial device not configured
34827c478bd9Sstevel@tonic-gateThis error is returned if you try to change your terminal to a serial
34837c478bd9Sstevel@tonic-gateone before initializing any serial device.
34847c478bd9Sstevel@tonic-gate
34857c478bd9Sstevel@tonic-gate@item 34 : No spare sectors on the disk
34867c478bd9Sstevel@tonic-gateThis error is returned if a disk doesn't have enough spare space. This
34877c478bd9Sstevel@tonic-gatehappens when you try to embed Stage 1.5 into the unused sectors after
34887c478bd9Sstevel@tonic-gatethe MBR, but the first partition starts right after the MBR or they are
34897c478bd9Sstevel@tonic-gateused by EZ-BIOS.
34907c478bd9Sstevel@tonic-gate@end table
34917c478bd9Sstevel@tonic-gate
34927c478bd9Sstevel@tonic-gate
34937c478bd9Sstevel@tonic-gate@node Invoking the grub shell
34947c478bd9Sstevel@tonic-gate@chapter Invoking the grub shell
34957c478bd9Sstevel@tonic-gate
34967c478bd9Sstevel@tonic-gateThis chapter documents the grub shell @command{grub}. Note that the grub
34977c478bd9Sstevel@tonic-gateshell is an emulator; it doesn't run under the native environment, so it
34987c478bd9Sstevel@tonic-gatesometimes does something wrong. Therefore, you shouldn't trust it too
34997c478bd9Sstevel@tonic-gatemuch. If there is anything wrong with it, don't hesitate to try the
35007c478bd9Sstevel@tonic-gatenative GRUB environment, especially when it guesses a wrong map between
35017c478bd9Sstevel@tonic-gateBIOS drives and OS devices.
35027c478bd9Sstevel@tonic-gate
35037c478bd9Sstevel@tonic-gate@menu
35047c478bd9Sstevel@tonic-gate* Basic usage::                 How to use the grub shell
35057c478bd9Sstevel@tonic-gate* Installation under UNIX::     How to install GRUB via @command{grub}
35067c478bd9Sstevel@tonic-gate* Device map::                  The map between BIOS drives and OS devices
35077c478bd9Sstevel@tonic-gate@end menu
35087c478bd9Sstevel@tonic-gate
35097c478bd9Sstevel@tonic-gate
35107c478bd9Sstevel@tonic-gate@node Basic usage
35117c478bd9Sstevel@tonic-gate@section Introduction into the grub shell
35127c478bd9Sstevel@tonic-gate
35137c478bd9Sstevel@tonic-gateYou can use the command @command{grub} for installing GRUB under your
35147c478bd9Sstevel@tonic-gateoperating systems and for a testbed when you add a new feature into GRUB
35157c478bd9Sstevel@tonic-gateor when fixing a bug. @command{grub} is almost the same as the Stage 2,
35167c478bd9Sstevel@tonic-gateand, in fact, it shares the source code with the Stage 2 and you can use
35177c478bd9Sstevel@tonic-gatethe same commands (@pxref{Commands}) in @command{grub}. It is emulated by
35187c478bd9Sstevel@tonic-gatereplacing BIOS calls with UNIX system calls and libc functions.
35197c478bd9Sstevel@tonic-gate
35207c478bd9Sstevel@tonic-gateThe command @command{grub} accepts the following options:
35217c478bd9Sstevel@tonic-gate
35227c478bd9Sstevel@tonic-gate@table @option
35237c478bd9Sstevel@tonic-gate@item --help
35247c478bd9Sstevel@tonic-gatePrint a summary of the command-line options and exit.
35257c478bd9Sstevel@tonic-gate
35267c478bd9Sstevel@tonic-gate@item --version
35277c478bd9Sstevel@tonic-gatePrint the version number of GRUB and exit.
35287c478bd9Sstevel@tonic-gate
35297c478bd9Sstevel@tonic-gate@item --verbose
35307c478bd9Sstevel@tonic-gatePrint some verbose messages for debugging purpose.
35317c478bd9Sstevel@tonic-gate
35327c478bd9Sstevel@tonic-gate@item --device-map=@var{file}
35337c478bd9Sstevel@tonic-gateUse the device map file @var{file}. The format is described in
35347c478bd9Sstevel@tonic-gate@ref{Device map}.
35357c478bd9Sstevel@tonic-gate
35367c478bd9Sstevel@tonic-gate@item --no-floppy
35377c478bd9Sstevel@tonic-gateDo not probe any floppy drive. This option has no effect if the option
35387c478bd9Sstevel@tonic-gate@option{--device-map} is specified (@pxref{Device map}).
35397c478bd9Sstevel@tonic-gate
35407c478bd9Sstevel@tonic-gate@item --probe-second-floppy
35417c478bd9Sstevel@tonic-gateProbe the second floppy drive. If this option is not specified, the grub
35427c478bd9Sstevel@tonic-gateshell does not probe it, as that sometimes takes a long time. If you
35437c478bd9Sstevel@tonic-gatespecify the device map file (@pxref{Device map}), the grub shell just
35447c478bd9Sstevel@tonic-gateignores this option.
35457c478bd9Sstevel@tonic-gate
35467c478bd9Sstevel@tonic-gate@item --config-file=@var{file}
35477c478bd9Sstevel@tonic-gateRead the configuration file @var{file} instead of
35487c478bd9Sstevel@tonic-gate@file{/boot/grub/menu.lst}. The format is the same as the normal GRUB
35497c478bd9Sstevel@tonic-gatesyntax. See @ref{Filesystem}, for more information.
35507c478bd9Sstevel@tonic-gate
35517c478bd9Sstevel@tonic-gate@item --boot-drive=@var{drive}
35527c478bd9Sstevel@tonic-gateSet the stage2 @var{boot_drive} to @var{drive}. This argument should be
35537c478bd9Sstevel@tonic-gatean integer (decimal, octal or hexadecimal).
35547c478bd9Sstevel@tonic-gate
35557c478bd9Sstevel@tonic-gate@item --install-partition=@var{par}
35567c478bd9Sstevel@tonic-gateSet the stage2 @var{install_partition} to @var{par}. This argument
35577c478bd9Sstevel@tonic-gateshould be an integer (decimal, octal or hexadecimal).
35587c478bd9Sstevel@tonic-gate
35597c478bd9Sstevel@tonic-gate@item --no-config-file
35607c478bd9Sstevel@tonic-gateDo not use the configuration file even if it can be read.
35617c478bd9Sstevel@tonic-gate
35627c478bd9Sstevel@tonic-gate@item --no-curses
35637c478bd9Sstevel@tonic-gateDo not use the screen handling interface by the curses even if it is
35647c478bd9Sstevel@tonic-gateavailable.
35657c478bd9Sstevel@tonic-gate
35667c478bd9Sstevel@tonic-gate@item --batch
35677c478bd9Sstevel@tonic-gateThis option has the same meaning as @samp{--no-config-file --no-curses}.
35687c478bd9Sstevel@tonic-gate
35697c478bd9Sstevel@tonic-gate@item --read-only
35707c478bd9Sstevel@tonic-gateDisable writing to any disk.
35717c478bd9Sstevel@tonic-gate
35727c478bd9Sstevel@tonic-gate@item --hold
35737c478bd9Sstevel@tonic-gateWait until a debugger will attach. This option is useful when you want
35747c478bd9Sstevel@tonic-gateto debug the startup code.
35757c478bd9Sstevel@tonic-gate@end table
35767c478bd9Sstevel@tonic-gate
35777c478bd9Sstevel@tonic-gate
35787c478bd9Sstevel@tonic-gate@node Installation under UNIX
35797c478bd9Sstevel@tonic-gate@section How to install GRUB via @command{grub}
35807c478bd9Sstevel@tonic-gate
35817c478bd9Sstevel@tonic-gateThe installation procedure is the same as under the @dfn{native} Stage
35827c478bd9Sstevel@tonic-gate2. @xref{Installation}, for more information. The command
35837c478bd9Sstevel@tonic-gate@command{grub}-specific information is described here.
35847c478bd9Sstevel@tonic-gate
35857c478bd9Sstevel@tonic-gateWhat you should be careful about is @dfn{buffer cache}. @command{grub}
35867c478bd9Sstevel@tonic-gatemakes use of raw devices instead of filesystems that your operating
35877c478bd9Sstevel@tonic-gatesystems serve, so there exists a potential problem that some cache
35887c478bd9Sstevel@tonic-gateinconsistency may corrupt your filesystems. What we recommend is:
35897c478bd9Sstevel@tonic-gate
35907c478bd9Sstevel@tonic-gate@itemize @bullet
35917c478bd9Sstevel@tonic-gate@item
35927c478bd9Sstevel@tonic-gateIf you can unmount drives to which GRUB may write any amount of data,
35937c478bd9Sstevel@tonic-gateunmount them before running @command{grub}.
35947c478bd9Sstevel@tonic-gate
35957c478bd9Sstevel@tonic-gate@item
35967c478bd9Sstevel@tonic-gateIf a drive cannot be unmounted but can be mounted with the read-only
35977c478bd9Sstevel@tonic-gateflag, mount it in read-only mode. That should be secure.
35987c478bd9Sstevel@tonic-gate
35997c478bd9Sstevel@tonic-gate@item
36007c478bd9Sstevel@tonic-gateIf a drive must be mounted with the read-write flag, make sure that no
36017c478bd9Sstevel@tonic-gateactivity is being done on it while the command @command{grub} is
36027c478bd9Sstevel@tonic-gaterunning.
36037c478bd9Sstevel@tonic-gate
36047c478bd9Sstevel@tonic-gate@item
36057c478bd9Sstevel@tonic-gateReboot your operating system as soon as possible. This is probably not
36067c478bd9Sstevel@tonic-gaterequired if you follow the rules above, but reboot is the most secure
36077c478bd9Sstevel@tonic-gateway.
36087c478bd9Sstevel@tonic-gate@end itemize
36097c478bd9Sstevel@tonic-gate
36107c478bd9Sstevel@tonic-gateIn addition, enter the command @command{quit} when you finish the
36117c478bd9Sstevel@tonic-gateinstallation. That is @emph{very important} because @command{quit} makes
36127c478bd9Sstevel@tonic-gatethe buffer cache consistent. Do not push @key{C-c}.
36137c478bd9Sstevel@tonic-gate
36147c478bd9Sstevel@tonic-gateIf you want to install GRUB non-interactively, specify @samp{--batch}
36157c478bd9Sstevel@tonic-gateoption in the command-line. This is a simple example:
36167c478bd9Sstevel@tonic-gate
36177c478bd9Sstevel@tonic-gate@example
36187c478bd9Sstevel@tonic-gate@group
36197c478bd9Sstevel@tonic-gate#!/bin/sh
36207c478bd9Sstevel@tonic-gate
36217c478bd9Sstevel@tonic-gate# Use /usr/sbin/grub if you are on an older system.
36227c478bd9Sstevel@tonic-gate/sbin/grub --batch <<EOT 1>/dev/null 2>/dev/null
36237c478bd9Sstevel@tonic-gateroot (hd0,0)
36247c478bd9Sstevel@tonic-gatesetup (hd0)
36257c478bd9Sstevel@tonic-gatequit
36267c478bd9Sstevel@tonic-gateEOT
36277c478bd9Sstevel@tonic-gate@end group
36287c478bd9Sstevel@tonic-gate@end example
36297c478bd9Sstevel@tonic-gate
36307c478bd9Sstevel@tonic-gate
36317c478bd9Sstevel@tonic-gate@node Device map
36327c478bd9Sstevel@tonic-gate@section The map between BIOS drives and OS devices
36337c478bd9Sstevel@tonic-gate
36347c478bd9Sstevel@tonic-gateWhen you specify the option @option{--device-map} (@pxref{Basic usage}),
36357c478bd9Sstevel@tonic-gatethe grub shell creates the @dfn{device map file} automatically unless it
36367c478bd9Sstevel@tonic-gatealready exists. The file name @file{/boot/grub/device.map} is preferred.
36377c478bd9Sstevel@tonic-gate
36387c478bd9Sstevel@tonic-gateIf the device map file exists, the grub shell reads it to map BIOS
36397c478bd9Sstevel@tonic-gatedrives to OS devices. This file consists of lines like this:
36407c478bd9Sstevel@tonic-gate
36417c478bd9Sstevel@tonic-gate@example
36427c478bd9Sstevel@tonic-gate@var{device} @var{file}
36437c478bd9Sstevel@tonic-gate@end example
36447c478bd9Sstevel@tonic-gate
36457c478bd9Sstevel@tonic-gate@var{device} is a drive specified in the GRUB syntax (@pxref{Device
36467c478bd9Sstevel@tonic-gatesyntax}), and @var{file} is an OS file, which is normally a device
36477c478bd9Sstevel@tonic-gatefile.
36487c478bd9Sstevel@tonic-gate
36497c478bd9Sstevel@tonic-gateThe reason why the grub shell gives you the device map file is that it
36507c478bd9Sstevel@tonic-gatecannot guess the map between BIOS drives and OS devices correctly in
36517c478bd9Sstevel@tonic-gatesome environments. For example, if you exchange the boot sequence
36527c478bd9Sstevel@tonic-gatebetween IDE and SCSI in your BIOS, it gets the order wrong.
36537c478bd9Sstevel@tonic-gate
36547c478bd9Sstevel@tonic-gateThus, edit the file if the grub shell makes a mistake. You can put any
36557c478bd9Sstevel@tonic-gatecomments in the file if needed, as the grub shell assumes that a line is
36567c478bd9Sstevel@tonic-gatejust a comment if the first character is @samp{#}.
36577c478bd9Sstevel@tonic-gate
36587c478bd9Sstevel@tonic-gate
36597c478bd9Sstevel@tonic-gate@node Invoking grub-install
36607c478bd9Sstevel@tonic-gate@chapter Invoking grub-install
36617c478bd9Sstevel@tonic-gate
36627c478bd9Sstevel@tonic-gateThe program @command{grub-install} installs GRUB on your drive using the
36637c478bd9Sstevel@tonic-gategrub shell (@pxref{Invoking the grub shell}). You must specify the
36647c478bd9Sstevel@tonic-gatedevice name on which you want to install GRUB, like this:
36657c478bd9Sstevel@tonic-gate
36667c478bd9Sstevel@tonic-gate@example
36677c478bd9Sstevel@tonic-gategrub-install @var{install_device}
36687c478bd9Sstevel@tonic-gate@end example
36697c478bd9Sstevel@tonic-gate
36707c478bd9Sstevel@tonic-gateThe device name @var{install_device} is an OS device name or a GRUB
36717c478bd9Sstevel@tonic-gatedevice name.
36727c478bd9Sstevel@tonic-gate
36737c478bd9Sstevel@tonic-gate@command{grub-install} accepts the following options:
36747c478bd9Sstevel@tonic-gate
36757c478bd9Sstevel@tonic-gate@table @option
36767c478bd9Sstevel@tonic-gate@item --help
36777c478bd9Sstevel@tonic-gatePrint a summary of the command-line options and exit.
36787c478bd9Sstevel@tonic-gate
36797c478bd9Sstevel@tonic-gate@item --version
36807c478bd9Sstevel@tonic-gatePrint the version number of GRUB and exit.
36817c478bd9Sstevel@tonic-gate
36827c478bd9Sstevel@tonic-gate@item --force-lba
36837c478bd9Sstevel@tonic-gateForce GRUB to use LBA mode even for a buggy BIOS. Use this option only
36847c478bd9Sstevel@tonic-gateif your BIOS doesn't work properly in LBA mode even though it supports
36857c478bd9Sstevel@tonic-gateLBA mode.
36867c478bd9Sstevel@tonic-gate
36877c478bd9Sstevel@tonic-gate@item --root-directory=@var{dir}
36887c478bd9Sstevel@tonic-gateInstall GRUB images under the directory @var{dir} instead of the root
36897c478bd9Sstevel@tonic-gatedirectory. This option is useful when you want to install GRUB into a
36907c478bd9Sstevel@tonic-gateseparate partition or a removable disk. Here is an example in which
36917c478bd9Sstevel@tonic-gateyou have a separate @dfn{boot} partition which is mounted on
36927c478bd9Sstevel@tonic-gate@file{/boot}:
36937c478bd9Sstevel@tonic-gate
36947c478bd9Sstevel@tonic-gate@example
36957c478bd9Sstevel@tonic-gate@kbd{grub-install --root-directory=/boot hd0}
36967c478bd9Sstevel@tonic-gate@end example
36977c478bd9Sstevel@tonic-gate
36987c478bd9Sstevel@tonic-gate@item --grub-shell=@var{file}
36997c478bd9Sstevel@tonic-gateUse @var{file} as the grub shell. You can append arbitrary options to
37007c478bd9Sstevel@tonic-gate@var{file} after the file name, like this:
37017c478bd9Sstevel@tonic-gate
37027c478bd9Sstevel@tonic-gate@example
37037c478bd9Sstevel@tonic-gate@kbd{grub-install --grub-shell="grub --read-only" /dev/fd0}
37047c478bd9Sstevel@tonic-gate@end example
37057c478bd9Sstevel@tonic-gate
37067c478bd9Sstevel@tonic-gate@item --recheck
37077c478bd9Sstevel@tonic-gateRecheck the device map, even if @file{/boot/grub/device.map} already
37087c478bd9Sstevel@tonic-gateexists. You should use this option whenever you add/remove a disk
37097c478bd9Sstevel@tonic-gateinto/from your computer.
37107c478bd9Sstevel@tonic-gate@end table
37117c478bd9Sstevel@tonic-gate
37127c478bd9Sstevel@tonic-gate
37137c478bd9Sstevel@tonic-gate@node Invoking grub-md5-crypt
37147c478bd9Sstevel@tonic-gate@chapter Invoking grub-md5-crypt
37157c478bd9Sstevel@tonic-gate
37167c478bd9Sstevel@tonic-gateThe program @command{grub-md5-crypt} encrypts a password in MD5 format.
37177c478bd9Sstevel@tonic-gateThis is just a frontend of the grub shell (@pxref{Invoking the grub
37187c478bd9Sstevel@tonic-gateshell}). Passwords encrypted by this program can be used with the
37197c478bd9Sstevel@tonic-gatecommand @command{password} (@pxref{password}).
37207c478bd9Sstevel@tonic-gate
37217c478bd9Sstevel@tonic-gate@command{grub-md5-crypt} accepts the following options:
37227c478bd9Sstevel@tonic-gate
37237c478bd9Sstevel@tonic-gate@table @option
37247c478bd9Sstevel@tonic-gate@item --help
37257c478bd9Sstevel@tonic-gatePrint a summary of the command-line options and exit.
37267c478bd9Sstevel@tonic-gate
37277c478bd9Sstevel@tonic-gate@item --version
37287c478bd9Sstevel@tonic-gatePrint the version information and exit.
37297c478bd9Sstevel@tonic-gate
37307c478bd9Sstevel@tonic-gate@item --grub-shell=@var{file}
37317c478bd9Sstevel@tonic-gateUse @var{file} as the grub shell.
37327c478bd9Sstevel@tonic-gate@end table
37337c478bd9Sstevel@tonic-gate
37347c478bd9Sstevel@tonic-gate
37357c478bd9Sstevel@tonic-gate@node Invoking grub-terminfo
37367c478bd9Sstevel@tonic-gate@chapter Invoking grub-terminfo
37377c478bd9Sstevel@tonic-gate
37387c478bd9Sstevel@tonic-gateThe program @command{grub-terminfo} generates a terminfo command from
37397c478bd9Sstevel@tonic-gatea terminfo name (@pxref{terminfo}). The result can be used in the
37407c478bd9Sstevel@tonic-gateconfiguration file, to define escape sequences. Because GRUB assumes
37417c478bd9Sstevel@tonic-gatethat your terminal is vt100-compatible by default, this would be
37427c478bd9Sstevel@tonic-gateuseful only if your terminal is uncommon (such as vt52).
37437c478bd9Sstevel@tonic-gate
37447c478bd9Sstevel@tonic-gate@command{grub-terminfo} accepts the following options:
37457c478bd9Sstevel@tonic-gate
37467c478bd9Sstevel@tonic-gate@table @option
37477c478bd9Sstevel@tonic-gate@item --help
37487c478bd9Sstevel@tonic-gatePrint a summary of the command-line options and exit.
37497c478bd9Sstevel@tonic-gate
37507c478bd9Sstevel@tonic-gate@item --version
37517c478bd9Sstevel@tonic-gatePrint the version information and exit.
37527c478bd9Sstevel@tonic-gate@end table
37537c478bd9Sstevel@tonic-gate
37547c478bd9Sstevel@tonic-gateYou must specify one argument to this command. For example:
37557c478bd9Sstevel@tonic-gate
37567c478bd9Sstevel@tonic-gate@example
37577c478bd9Sstevel@tonic-gate@kbd{grub-terminfo vt52}
37587c478bd9Sstevel@tonic-gate@end example
37597c478bd9Sstevel@tonic-gate
37607c478bd9Sstevel@tonic-gate
37617c478bd9Sstevel@tonic-gate@node Invoking grub-set-default
37627c478bd9Sstevel@tonic-gate@chapter Invoking grub-set-default
37637c478bd9Sstevel@tonic-gate
37647c478bd9Sstevel@tonic-gateThe program @command{grub-set-default} sets the default boot entry for
37657c478bd9Sstevel@tonic-gateGRUB. This automatically creates a file named @file{default} under
37667c478bd9Sstevel@tonic-gateyour GRUB directory (i.e. @file{/boot/grub}), if it is not
37677c478bd9Sstevel@tonic-gatepresent. This file is used to determine the default boot entry when
37687c478bd9Sstevel@tonic-gateGRUB boots up your system when you use @samp{default saved} in your
37697c478bd9Sstevel@tonic-gateconfiguration file (@pxref{default}), and to save next default boot
37707c478bd9Sstevel@tonic-gateentry when you use @samp{savedefault} in a boot entry
37717c478bd9Sstevel@tonic-gate(@pxref{savedefault}).
37727c478bd9Sstevel@tonic-gate
37737c478bd9Sstevel@tonic-gate@command{grub-set-default} accepts the following options:
37747c478bd9Sstevel@tonic-gate
37757c478bd9Sstevel@tonic-gate@table @option
37767c478bd9Sstevel@tonic-gate@item --help
37777c478bd9Sstevel@tonic-gatePrint a summary of the command-line options and exit.
37787c478bd9Sstevel@tonic-gate
37797c478bd9Sstevel@tonic-gate@item --version
37807c478bd9Sstevel@tonic-gatePrint the version information and exit.
37817c478bd9Sstevel@tonic-gate
37827c478bd9Sstevel@tonic-gate@item --root-directory=@var{dir}
37837c478bd9Sstevel@tonic-gateUse the directory @var{dir} instead of the root directory
37847c478bd9Sstevel@tonic-gate(i.e. @file{/}) to define the location of the default file. This
37857c478bd9Sstevel@tonic-gateis useful when you mount a disk which is used for another system.
37867c478bd9Sstevel@tonic-gate@end table
37877c478bd9Sstevel@tonic-gate
37887c478bd9Sstevel@tonic-gateYou must specify a single argument to @command{grub-set-default}. This
37897c478bd9Sstevel@tonic-gateargument is normally the number of a default boot entry. For example,
37907c478bd9Sstevel@tonic-gateif you have this configuration file:
37917c478bd9Sstevel@tonic-gate
37927c478bd9Sstevel@tonic-gate@example
37937c478bd9Sstevel@tonic-gate@group
37947c478bd9Sstevel@tonic-gatedefault saved
37957c478bd9Sstevel@tonic-gatetimeout 10
37967c478bd9Sstevel@tonic-gate
37977c478bd9Sstevel@tonic-gatetitle GNU/Hurd
37987c478bd9Sstevel@tonic-gateroot (hd0,0)
37997c478bd9Sstevel@tonic-gate...
38007c478bd9Sstevel@tonic-gate
38017c478bd9Sstevel@tonic-gatetitle GNU/Linux
38027c478bd9Sstevel@tonic-gateroot (hd0,1)
38037c478bd9Sstevel@tonic-gate...
38047c478bd9Sstevel@tonic-gate@end group
38057c478bd9Sstevel@tonic-gate@end example
38067c478bd9Sstevel@tonic-gate
38077c478bd9Sstevel@tonic-gateand if you want to set the next default boot entry to GNU/Linux, you
38087c478bd9Sstevel@tonic-gatemay execute this command:
38097c478bd9Sstevel@tonic-gate
38107c478bd9Sstevel@tonic-gate@example
38117c478bd9Sstevel@tonic-gate@kbd{grub-set-default 1}
38127c478bd9Sstevel@tonic-gate@end example
38137c478bd9Sstevel@tonic-gate
38147c478bd9Sstevel@tonic-gateBecause the entry for GNU/Linux is @samp{1}. Note that entries are
38157c478bd9Sstevel@tonic-gatecounted from zero. So, if you want to specify GNU/Hurd here, then you
38167c478bd9Sstevel@tonic-gateshould specify @samp{0}.
38177c478bd9Sstevel@tonic-gate
38187c478bd9Sstevel@tonic-gateThis feature is very useful if you want to test a new kernel or to
38197c478bd9Sstevel@tonic-gatemake your system quite robust. @xref{Making your system robust}, for
38207c478bd9Sstevel@tonic-gatemore hints about how to set up a robust system.
38217c478bd9Sstevel@tonic-gate
38227c478bd9Sstevel@tonic-gate
38237c478bd9Sstevel@tonic-gate@node Invoking mbchk
38247c478bd9Sstevel@tonic-gate@chapter Invoking mbchk
38257c478bd9Sstevel@tonic-gate
38267c478bd9Sstevel@tonic-gateThe program @command{mbchk} checks for the format of a Multiboot
38277c478bd9Sstevel@tonic-gatekernel. We recommend using this program before booting your own kernel
38287c478bd9Sstevel@tonic-gateby GRUB.
38297c478bd9Sstevel@tonic-gate
38307c478bd9Sstevel@tonic-gate@command{mbchk} accepts the following options:
38317c478bd9Sstevel@tonic-gate
38327c478bd9Sstevel@tonic-gate@table @option
38337c478bd9Sstevel@tonic-gate@item --help
38347c478bd9Sstevel@tonic-gatePrint a summary of the command-line options and exit.
38357c478bd9Sstevel@tonic-gate
38367c478bd9Sstevel@tonic-gate@item --version
38377c478bd9Sstevel@tonic-gatePrint the version number of GRUB and exit.
38387c478bd9Sstevel@tonic-gate
38397c478bd9Sstevel@tonic-gate@item --quiet
38407c478bd9Sstevel@tonic-gateSuppress all normal output.
38417c478bd9Sstevel@tonic-gate@end table
38427c478bd9Sstevel@tonic-gate
38437c478bd9Sstevel@tonic-gate
38447c478bd9Sstevel@tonic-gate@node Obtaining and Building GRUB
38457c478bd9Sstevel@tonic-gate@appendix How to obtain and build GRUB
38467c478bd9Sstevel@tonic-gate
38477c478bd9Sstevel@tonic-gate@quotation
38487c478bd9Sstevel@tonic-gate@strong{Caution:} GRUB requires binutils-2.9.1.0.23 or later because the
38497c478bd9Sstevel@tonic-gateGNU assembler has been changed so that it can produce real 16bits
38507c478bd9Sstevel@tonic-gatemachine code between 2.9.1 and 2.9.1.0.x. See
38517c478bd9Sstevel@tonic-gate@uref{http://sources.redhat.com/binutils/}, to obtain information on
38527c478bd9Sstevel@tonic-gatehow to get the latest version.
38537c478bd9Sstevel@tonic-gate@end quotation
38547c478bd9Sstevel@tonic-gate
38557c478bd9Sstevel@tonic-gateGRUB is available from the GNU alpha archive site
38567c478bd9Sstevel@tonic-gate@uref{ftp://alpha.gnu.org/gnu/grub} or any of its mirrors. The file
38577c478bd9Sstevel@tonic-gatewill be named grub-version.tar.gz. The current version is
38587c478bd9Sstevel@tonic-gate@value{VERSION}, so the file you should grab is:
38597c478bd9Sstevel@tonic-gate
38607c478bd9Sstevel@tonic-gate@uref{ftp://alpha.gnu.org/gnu/grub/grub-@value{VERSION}.tar.gz}
38617c478bd9Sstevel@tonic-gate
38627c478bd9Sstevel@tonic-gateTo unbundle GRUB use the instruction:
38637c478bd9Sstevel@tonic-gate
38647c478bd9Sstevel@tonic-gate@example
38657c478bd9Sstevel@tonic-gate@kbd{zcat grub-@value{VERSION}.tar.gz | tar xvf -}
38667c478bd9Sstevel@tonic-gate@end example
38677c478bd9Sstevel@tonic-gate
38687c478bd9Sstevel@tonic-gatewhich will create a directory called @file{grub-@value{VERSION}} with
38697c478bd9Sstevel@tonic-gateall the sources. You can look at the file @file{INSTALL} for detailed
38707c478bd9Sstevel@tonic-gateinstructions on how to build and install GRUB, but you should be able to
38717c478bd9Sstevel@tonic-gatejust do:
38727c478bd9Sstevel@tonic-gate
38737c478bd9Sstevel@tonic-gate@example
38747c478bd9Sstevel@tonic-gate@group
38757c478bd9Sstevel@tonic-gate@kbd{cd grub-@value{VERSION}}
38767c478bd9Sstevel@tonic-gate@kbd{./configure}
38777c478bd9Sstevel@tonic-gate@kbd{make install}
38787c478bd9Sstevel@tonic-gate@end group
38797c478bd9Sstevel@tonic-gate@end example
38807c478bd9Sstevel@tonic-gate
38817c478bd9Sstevel@tonic-gateThis will install the grub shell @file{grub} (@pxref{Invoking the grub
38827c478bd9Sstevel@tonic-gateshell}), the Multiboot checker @file{mbchk} (@pxref{Invoking mbchk}),
38837c478bd9Sstevel@tonic-gateand the GRUB images. This will also install the GRUB manual.
38847c478bd9Sstevel@tonic-gate
38857c478bd9Sstevel@tonic-gateAlso, the latest version is available from the CVS. See
38867c478bd9Sstevel@tonic-gate@uref{http://savannah.gnu.org/cvs/?group=grub} for more information.
38877c478bd9Sstevel@tonic-gate
38887c478bd9Sstevel@tonic-gate
38897c478bd9Sstevel@tonic-gate@node Reporting bugs
38907c478bd9Sstevel@tonic-gate@appendix Reporting bugs
38917c478bd9Sstevel@tonic-gate
38927c478bd9Sstevel@tonic-gateThese are the guideline for how to report bugs. Take a look at this
38937c478bd9Sstevel@tonic-gatelist below before you submit bugs:
38947c478bd9Sstevel@tonic-gate
38957c478bd9Sstevel@tonic-gate@enumerate
38967c478bd9Sstevel@tonic-gate@item
38977c478bd9Sstevel@tonic-gateBefore getting unsettled, read this manual through and through. Also,
38987c478bd9Sstevel@tonic-gatesee the @uref{http://www.gnu.org/software/grub/grub-faq.html, GNU GRUB FAQ}.
38997c478bd9Sstevel@tonic-gate
39007c478bd9Sstevel@tonic-gate@item
39017c478bd9Sstevel@tonic-gateAlways mention the information on your GRUB. The version number and the
39027c478bd9Sstevel@tonic-gateconfiguration are quite important. If you build it yourself, write the
39037c478bd9Sstevel@tonic-gateoptions specified to the configure script and your operating system,
39047c478bd9Sstevel@tonic-gateincluding the versions of gcc and binutils.
39057c478bd9Sstevel@tonic-gate
39067c478bd9Sstevel@tonic-gate@item
39077c478bd9Sstevel@tonic-gateIf you have trouble with the installation, inform us of how you
39087c478bd9Sstevel@tonic-gateinstalled GRUB. Don't omit error messages, if any. Just @samp{GRUB hangs
39097c478bd9Sstevel@tonic-gateup when it boots} is not enough.
39107c478bd9Sstevel@tonic-gate
39117c478bd9Sstevel@tonic-gateThe information on your hardware is also essential. These are especially
39127c478bd9Sstevel@tonic-gateimportant: the geometries and the partition tables of your hard disk
39137c478bd9Sstevel@tonic-gatedrives and your BIOS.
39147c478bd9Sstevel@tonic-gate
39157c478bd9Sstevel@tonic-gate@item
39167c478bd9Sstevel@tonic-gateIf GRUB cannot boot your operating system, write down
39177c478bd9Sstevel@tonic-gate@emph{everything} you see on the screen. Don't paraphrase them, like
39187c478bd9Sstevel@tonic-gate@samp{The foo OS crashes with GRUB, even though it can boot with the
39197c478bd9Sstevel@tonic-gatebar boot loader just fine}. Mention the commands you executed, the
39207c478bd9Sstevel@tonic-gatemessages printed by them, and information on your operating system
39217c478bd9Sstevel@tonic-gateincluding the version number.
39227c478bd9Sstevel@tonic-gate
39237c478bd9Sstevel@tonic-gate@item
39247c478bd9Sstevel@tonic-gateExplain what you wanted to do. It is very useful to know your purpose
39257c478bd9Sstevel@tonic-gateand your wish, and how GRUB didn't satisfy you.
39267c478bd9Sstevel@tonic-gate
39277c478bd9Sstevel@tonic-gate@item
39287c478bd9Sstevel@tonic-gateIf you can investigate the problem yourself, please do. That will give
39297c478bd9Sstevel@tonic-gateyou and us much more information on the problem. Attaching a patch is
39307c478bd9Sstevel@tonic-gateeven better.
39317c478bd9Sstevel@tonic-gate
39327c478bd9Sstevel@tonic-gateWhen you attach a patch, make the patch in unified diff format, and
39337c478bd9Sstevel@tonic-gatewrite ChangeLog entries. But, even when you make a patch, don't forget
39347c478bd9Sstevel@tonic-gateto explain the problem, so that we can understand what your patch is
39357c478bd9Sstevel@tonic-gatefor.
39367c478bd9Sstevel@tonic-gate
39377c478bd9Sstevel@tonic-gate@item
39387c478bd9Sstevel@tonic-gateWrite down anything that you think might be related. Please understand
39397c478bd9Sstevel@tonic-gatethat we often need to reproduce the same problem you encounterred in our
39407c478bd9Sstevel@tonic-gateenvironment. So your information should be sufficient for us to do the
39417c478bd9Sstevel@tonic-gatesame thing---Don't forget that we cannot see your computer directly. If
39427c478bd9Sstevel@tonic-gateyou are not sure whether to state a fact or leave it out, state it!
39437c478bd9Sstevel@tonic-gateReporting too many things is much better than omitting something
39447c478bd9Sstevel@tonic-gateimportant.
39457c478bd9Sstevel@tonic-gate@end enumerate
39467c478bd9Sstevel@tonic-gate
39477c478bd9Sstevel@tonic-gateIf you follow the guideline above, submit a report to the
39487c478bd9Sstevel@tonic-gate@uref{http://savannah.gnu.org/bugs/?group=grub, Bug Tracking System}.
39497c478bd9Sstevel@tonic-gateAlternatively, you can submit a report via electronic mail to
39507c478bd9Sstevel@tonic-gate@email{bug-grub@@gnu.org}, but we strongly recommend that you use the
39517c478bd9Sstevel@tonic-gateBug Tracking System, because e-mail can be passed over easily.
39527c478bd9Sstevel@tonic-gate
39537c478bd9Sstevel@tonic-gateOnce we get your report, we will try to fix the bugs.
39547c478bd9Sstevel@tonic-gate
39557c478bd9Sstevel@tonic-gate
39567c478bd9Sstevel@tonic-gate@node Future
39577c478bd9Sstevel@tonic-gate@appendix Where GRUB will go
39587c478bd9Sstevel@tonic-gate
39597c478bd9Sstevel@tonic-gateWe started the next generation of GRUB, GRUB 2. This will include
39607c478bd9Sstevel@tonic-gateinternationalization, dynamic module loading, real memory management,
39617c478bd9Sstevel@tonic-gatemultiple architecture support, a scripting language, and many other
39627c478bd9Sstevel@tonic-gatenice feature. If you are interested in the development of GRUB 2, take
39637c478bd9Sstevel@tonic-gatea look at @uref{http://www.gnu.org/software/grub/grub.html, the
39647c478bd9Sstevel@tonic-gatehomepage}.
39657c478bd9Sstevel@tonic-gate
39667c478bd9Sstevel@tonic-gate
39677c478bd9Sstevel@tonic-gate@c Separate the programming guide.
39687c478bd9Sstevel@tonic-gate@include internals.texi
39697c478bd9Sstevel@tonic-gate
39707c478bd9Sstevel@tonic-gate
39717c478bd9Sstevel@tonic-gate@node Index
39727c478bd9Sstevel@tonic-gate@unnumbered Index
39737c478bd9Sstevel@tonic-gate
39747c478bd9Sstevel@tonic-gate@c Currently, we use only the Concept Index.
39757c478bd9Sstevel@tonic-gate@printindex cp
39767c478bd9Sstevel@tonic-gate
39777c478bd9Sstevel@tonic-gate
39787c478bd9Sstevel@tonic-gate@bye
39797c478bd9Sstevel@tonic-gate
39807c478bd9Sstevel@tonic-gateSome notes:
39817c478bd9Sstevel@tonic-gate
39827c478bd9Sstevel@tonic-gate  This is the second attempt to rewrite the manual. The status is
39837c478bd9Sstevel@tonic-gatemostly complete, but I need to check the spelling by ispell, and add
39847c478bd9Sstevel@tonic-gatemore indices. Perhaps I also have to let some English native speakers
39857c478bd9Sstevel@tonic-gateproofread this manual through. My English is syntactically almost
39867c478bd9Sstevel@tonic-gateperfect, but sometimes (often?) awful in the nuance. Hehe, I can't be an
39877c478bd9Sstevel@tonic-gateEnglish poet for now.
3988