2863 lines
99 KiB
Text
2863 lines
99 KiB
Text
\input texinfo
|
|
@c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename grub.info
|
|
@include version.texi
|
|
@settitle GNU GRUB Manual @value{VERSION}
|
|
@c Unify all our little indices for now.
|
|
@syncodeindex fn cp
|
|
@syncodeindex vr cp
|
|
@syncodeindex ky cp
|
|
@syncodeindex pg cp
|
|
@syncodeindex tp cp
|
|
@c %**end of header
|
|
|
|
@footnotestyle separate
|
|
@paragraphindent 3
|
|
@finalout
|
|
|
|
@copying
|
|
This manual is for GNU GRUB (version @value{VERSION},
|
|
@value{UPDATED}).
|
|
|
|
Copyright @copyright{} 1999,2000,2001,2002,2004,2006,2008,2009,2010 Free Software Foundation, Inc.
|
|
|
|
@quotation
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.2 or
|
|
any later version published by the Free Software Foundation; with no
|
|
Invariant Sections.
|
|
@end quotation
|
|
@end copying
|
|
|
|
@dircategory Kernel
|
|
@direntry
|
|
* GRUB: (grub). The GRand Unified Bootloader
|
|
* grub-install: (grub)Invoking grub-install. Install GRUB on your drive
|
|
* grub-mkconfig: (grub)Invoking grub-mkconfig. Generate GRUB configuration
|
|
* grub-mkpasswd-pbkdf2: (grub)Invoking grub-mkpasswd-pbkdf2.
|
|
@end direntry
|
|
|
|
@setchapternewpage odd
|
|
|
|
@titlepage
|
|
@sp 10
|
|
@title the GNU GRUB manual
|
|
@subtitle The GRand Unified Bootloader, version @value{VERSION}, @value{UPDATED}.
|
|
@author Gordon Matzigkeit
|
|
@author Yoshinori K. Okuji
|
|
@c The following two commands start the copyright page.
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
@insertcopying
|
|
@end titlepage
|
|
|
|
@c Output the table of contents at the beginning.
|
|
@contents
|
|
|
|
@finalout
|
|
@headings double
|
|
|
|
@ifnottex
|
|
@node Top
|
|
@top GNU GRUB manual
|
|
|
|
This is the documentation of GNU GRUB, the GRand Unified Bootloader,
|
|
a flexible and powerful boot loader program for a wide range of
|
|
architectures.
|
|
|
|
This edition documents version @value{VERSION}.
|
|
|
|
@insertcopying
|
|
@end ifnottex
|
|
|
|
@menu
|
|
* Introduction:: Capturing the spirit of GRUB
|
|
* Naming convention:: Names of your drives in GRUB
|
|
* Installation:: Installing GRUB on your drive
|
|
* Booting:: How to boot different operating systems
|
|
* Configuration:: Writing your own configuration file
|
|
* Network:: Downloading OS images from a network
|
|
* Serial terminal:: Using GRUB via a serial line
|
|
* Vendor power-on keys:: Changing GRUB behaviour on vendor power-on keys
|
|
* Images:: GRUB image files
|
|
* Filesystem:: Filesystem syntax and semantics
|
|
* Interface:: The menu and the command-line
|
|
* Commands:: The list of available builtin commands
|
|
* Security:: Authentication and authorisation
|
|
* Troubleshooting:: Error messages produced by GRUB
|
|
* Invoking grub-install:: How to use the GRUB installer
|
|
* Invoking grub-mkconfig:: Generate a GRUB configuration file
|
|
* Invoking grub-mkpasswd-pbkdf2::
|
|
Generate GRUB password hashes
|
|
* Obtaining and Building GRUB:: How to obtain and build GRUB
|
|
* Reporting bugs:: Where you should send a bug report
|
|
* Future:: Some future plans on GRUB
|
|
* Internals:: Hacking GRUB
|
|
* Copying This Manual:: Copying This Manual
|
|
* Index::
|
|
@end menu
|
|
|
|
|
|
@node Introduction
|
|
@chapter Introduction to GRUB
|
|
|
|
@menu
|
|
* Overview:: What exactly GRUB is and how to use it
|
|
* History:: From maggot to house fly
|
|
* Features:: GRUB features
|
|
* Changes from GRUB Legacy:: Differences from previous versions
|
|
* Role of a boot loader:: The role of a boot loader
|
|
@end menu
|
|
|
|
|
|
@node Overview
|
|
@section Overview
|
|
|
|
Briefly, a @dfn{boot loader} is the first software program that runs when
|
|
a computer starts. It is responsible for loading and transferring
|
|
control to an operating system @dfn{kernel} software (such as Linux or
|
|
GNU Mach). The kernel, in turn, initializes the rest of the operating
|
|
system (e.g. a GNU system).
|
|
|
|
GNU GRUB is a very powerful boot loader, which can load a wide variety
|
|
of free operating systems, as well as proprietary operating systems with
|
|
chain-loading@footnote{@dfn{chain-load} is the mechanism for loading
|
|
unsupported operating systems by loading another boot loader. It is
|
|
typically used for loading DOS or Windows.}. GRUB is designed to
|
|
address the complexity of booting a personal computer; both the
|
|
program and this manual are tightly bound to that computer platform,
|
|
although porting to other platforms may be addressed in the future.
|
|
|
|
One of the important features in GRUB is flexibility; GRUB understands
|
|
filesystems and kernel executable formats, so you can load an arbitrary
|
|
operating system the way you like, without recording the physical
|
|
position of your kernel on the disk. Thus you can load the kernel
|
|
just by specifying its file name and the drive and partition where the
|
|
kernel resides.
|
|
|
|
When booting with GRUB, you can use either a command-line interface
|
|
(@pxref{Command-line interface}), or a menu interface (@pxref{Menu
|
|
interface}). Using the command-line interface, you type the drive
|
|
specification and file name of the kernel manually. In the menu
|
|
interface, you just select an OS using the arrow keys. The menu is
|
|
based on a configuration file which you prepare beforehand
|
|
(@pxref{Configuration}). While in the menu, you can switch to the
|
|
command-line mode, and vice-versa. You can even edit menu entries
|
|
before using them.
|
|
|
|
In the following chapters, you will learn how to specify a drive, a
|
|
partition, and a file name (@pxref{Naming convention}) to GRUB, how to
|
|
install GRUB on your drive (@pxref{Installation}), and how to boot your
|
|
OSes (@pxref{Booting}), step by step.
|
|
|
|
|
|
@node History
|
|
@section History of GRUB
|
|
|
|
GRUB originated in 1995 when Erich Boleyn was trying to boot the GNU
|
|
Hurd with the University of Utah's Mach 4 microkernel (now known as GNU
|
|
Mach). Erich and Brian Ford designed the Multiboot Specification
|
|
(@pxref{Top, Multiboot Specification, Motivation, multiboot, The Multiboot
|
|
Specification}), because they were determined not to add to the large
|
|
number of mutually-incompatible PC boot methods.
|
|
|
|
Erich then began modifying the FreeBSD boot loader so that it would
|
|
understand Multiboot. He soon realized that it would be a lot easier
|
|
to write his own boot loader from scratch than to keep working on the
|
|
FreeBSD boot loader, and so GRUB was born.
|
|
|
|
Erich added many features to GRUB, but other priorities prevented him
|
|
from keeping up with the demands of its quickly-expanding user base. In
|
|
1999, Gordon Matzigkeit and Yoshinori K. Okuji adopted GRUB as an
|
|
official GNU package, and opened its development by making the latest
|
|
sources available via anonymous CVS. @xref{Obtaining and Building
|
|
GRUB}, for more information.
|
|
|
|
Over the next few years, GRUB was extended to meet many needs, but it
|
|
quickly became clear that its design was not keeping up with the extensions
|
|
being made to it, and we reached the point where it was very difficult to
|
|
make any further changes without breaking existing features. Around 2002,
|
|
Yoshinori K. Okuji started work on PUPA (Preliminary Universal Programming
|
|
Architecture for GNU GRUB), aiming to rewrite the core of GRUB to make it
|
|
cleaner, safer, more robust, and more powerful. PUPA was eventually renamed
|
|
to GRUB 2, and the original version of GRUB was renamed to GRUB Legacy.
|
|
Small amounts of maintenance continued to be done on GRUB Legacy, but the
|
|
last release (0.97) was made in 2005 and at the time of writing it seems
|
|
unlikely that there will be another.
|
|
|
|
By around 2007, GNU/Linux distributions started to use GRUB 2 to limited
|
|
extents, and by the end of 2009 multiple major distributions were installing
|
|
it by default.
|
|
|
|
|
|
@node Changes from GRUB Legacy
|
|
@section Differences from previous versions
|
|
|
|
GRUB 2 is a rewrite of GRUB (@pxref{History}), although it shares many
|
|
characteristics with the previous version, now known as GRUB Legacy. Users
|
|
of GRUB Legacy may need some guidance to find their way around this new
|
|
version.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The configuration file has a new name (@file{grub.cfg} rather than
|
|
@file{menu.lst} or @file{grub.conf}), new syntax (@pxref{Configuration}) and
|
|
many new commands (@pxref{Commands}). Configuration cannot be copied over
|
|
directly, although most GRUB Legacy users should not find the syntax too
|
|
surprising.
|
|
|
|
@item
|
|
@file{grub.cfg} is typically automatically generated by
|
|
@command{grub-mkconfig} (@pxref{Simple configuration}). This makes it
|
|
easier to handle versioned kernel upgrades.
|
|
|
|
@item
|
|
Partition numbers in GRUB device names now start at 1, not 0 (@pxref{Naming
|
|
convention}).
|
|
|
|
@item
|
|
The configuration file is now written in something closer to a full
|
|
scripting language: variables, conditionals, and loops are available.
|
|
|
|
@item
|
|
A small amount of persistent storage is available across reboots, using the
|
|
@command{save_env} and @command{load_env} commands in GRUB and the
|
|
@command{grub-editenv} utility.
|
|
|
|
@item
|
|
GRUB 2 has more reliable ways to find its own files and those of target
|
|
kernels on multiple-disk systems, and has commands (@pxref{search}) to find
|
|
devices using file system labels or Universally Unique Identifiers (UUIDs).
|
|
|
|
@item
|
|
GRUB 2 is available for several other types of system in addition to the PC
|
|
BIOS systems supported by GRUB Legacy: PC EFI, PC coreboot, PowerPC, SPARC,
|
|
and MIPS Lemote Yeeloong are all supported.
|
|
|
|
@item
|
|
Many more file systems are supported, including but not limited to ext4,
|
|
HFS+, and NTFS.
|
|
|
|
@item
|
|
GRUB 2 can read files directly from LVM and RAID devices.
|
|
|
|
@item
|
|
A graphical terminal and a graphical menu system are available.
|
|
|
|
@item
|
|
GRUB 2's interface can be translated, including menu entry names.
|
|
|
|
@item
|
|
The image files (@pxref{Images}) that make up GRUB have been reorganised;
|
|
Stage 1, Stage 1.5, and Stage 2 are no more.
|
|
|
|
@item
|
|
GRUB 2 puts many facilities in dynamically loaded modules, allowing the core
|
|
image to be smaller, and allowing the core image to be built in more
|
|
flexible ways.
|
|
@end itemize
|
|
|
|
|
|
@node Features
|
|
@section GRUB features
|
|
|
|
The primary requirement for GRUB is that it be compliant with the
|
|
@dfn{Multiboot Specification}, which is described in @ref{Top, Multiboot
|
|
Specification, Motivation, multiboot, The Multiboot Specification}.
|
|
|
|
The other goals, listed in approximate order of importance, are:
|
|
|
|
@itemize @bullet{}
|
|
@item
|
|
Basic functions must be straightforward for end-users.
|
|
|
|
@item
|
|
Rich functionality to support kernel experts and designers.
|
|
|
|
@item
|
|
Backward compatibility for booting FreeBSD, NetBSD, OpenBSD, and
|
|
Linux. Proprietary kernels (such as DOS, Windows NT, and OS/2) are
|
|
supported via a chain-loading function.
|
|
@end itemize
|
|
|
|
Except for specific compatibility modes (chain-loading and the Linux
|
|
@dfn{piggyback} format), all kernels will be started in much the same
|
|
state as in the Multiboot Specification. Only kernels loaded at 1 megabyte
|
|
or above are presently supported. Any attempt to load below that
|
|
boundary will simply result in immediate failure and an error message
|
|
reporting the problem.
|
|
|
|
In addition to the requirements above, GRUB has the following features
|
|
(note that the Multiboot Specification doesn't require all the features
|
|
that GRUB supports):
|
|
|
|
@table @asis
|
|
@item Recognize multiple executable formats
|
|
Support many of the @dfn{a.out} variants plus @dfn{ELF}. Symbol
|
|
tables are also loaded.
|
|
|
|
@item Support non-Multiboot kernels
|
|
Support many of the various free 32-bit kernels that lack Multiboot
|
|
compliance (primarily FreeBSD, NetBSD, OpenBSD, and
|
|
Linux). Chain-loading of other boot loaders is also supported.
|
|
|
|
@item Load multiples modules
|
|
Fully support the Multiboot feature of loading multiple modules.
|
|
|
|
@item Load a configuration file
|
|
Support a human-readable text configuration file with preset boot
|
|
commands. You can also load another configuration file dynamically and
|
|
embed a preset configuration file in a GRUB image file. The list of
|
|
commands (@pxref{Commands}) are a superset of those supported on the
|
|
command-line. An example configuration file is provided in
|
|
@ref{Configuration}.
|
|
|
|
@item Provide a menu interface
|
|
A menu interface listing preset boot commands, with a programmable
|
|
timeout, is available. There is no fixed limit on the number of boot
|
|
entries, and the current implementation has space for several hundred.
|
|
|
|
@item Have a flexible command-line interface
|
|
A fairly flexible command-line interface, accessible from the menu,
|
|
is available to edit any preset commands, or write a new boot command
|
|
set from scratch. If no configuration file is present, GRUB drops to
|
|
the command-line.
|
|
|
|
The list of commands (@pxref{Commands}) are a subset of those supported
|
|
for configuration files. Editing commands closely resembles the Bash
|
|
command-line (@pxref{Command Line Editing, Bash, Command Line Editing,
|
|
features, Bash Features}), with @key{TAB}-completion of commands,
|
|
devices, partitions, and files in a directory depending on context.
|
|
|
|
@item Support multiple filesystem types
|
|
Support multiple filesystem types transparently, plus a useful explicit
|
|
blocklist notation. The currently supported filesystem types are
|
|
@dfn{BSD FFS}, @dfn{DOS FAT16 and FAT32}, @dfn{Minix fs}, @dfn{Linux
|
|
ext2fs}, @dfn{ReiserFS}, @dfn{JFS}, @dfn{XFS}, and @dfn{VSTa
|
|
fs}. @xref{Filesystem}, for more information.
|
|
|
|
@item Support automatic decompression
|
|
Can decompress files which were compressed by @command{gzip}. This
|
|
function is both automatic and transparent to the user (i.e. all
|
|
functions operate upon the uncompressed contents of the specified
|
|
files). This greatly reduces a file size and loading time, a
|
|
particularly great benefit for floppies.@footnote{There are a few
|
|
pathological cases where loading a very badly organized ELF kernel might
|
|
take longer, but in practice this never happen.}
|
|
|
|
It is conceivable that some kernel modules should be loaded in a
|
|
compressed state, so a different module-loading command can be specified
|
|
to avoid uncompressing the modules.
|
|
|
|
@item Access data on any installed device
|
|
Support reading data from any or all floppies or hard disk(s) recognized
|
|
by the BIOS, independent of the setting of the root device.
|
|
|
|
@item Be independent of drive geometry translations
|
|
Unlike many other boot loaders, GRUB makes the particular drive
|
|
translation irrelevant. A drive installed and running with one
|
|
translation may be converted to another translation without any adverse
|
|
effects or changes in GRUB's configuration.
|
|
|
|
@item Detect all installed @sc{ram}
|
|
GRUB can generally find all the installed @sc{ram} on a PC-compatible
|
|
machine. It uses an advanced BIOS query technique for finding all
|
|
memory regions. As described on the Multiboot Specification (@pxref{Top,
|
|
Multiboot Specification, Motivation, multiboot, The Multiboot
|
|
Specification}), not all kernels make use of this information, but GRUB
|
|
provides it for those who do.
|
|
|
|
@item Support Logical Block Address mode
|
|
In traditional disk calls (called @dfn{CHS mode}), there is a geometry
|
|
translation problem, that is, the BIOS cannot access over 1024
|
|
cylinders, so the accessible space is limited to at least 508 MB and to
|
|
at most 8GB. GRUB can't universally solve this problem, as there is no
|
|
standard interface used in all machines. However, several newer machines
|
|
have the new interface, Logical Block Address (@dfn{LBA}) mode. GRUB
|
|
automatically detects if LBA mode is available and uses it if
|
|
available. In LBA mode, GRUB can access the entire disk.
|
|
|
|
@item Support network booting
|
|
GRUB is basically a disk-based boot loader but also has network
|
|
support. You can load OS images from a network by using the @dfn{TFTP}
|
|
protocol.
|
|
|
|
@item Support remote terminals
|
|
To support computers with no console, GRUB provides remote terminal
|
|
support, so that you can control GRUB from a remote host. Only serial
|
|
terminal support is implemented at the moment.
|
|
@end table
|
|
|
|
|
|
@node Role of a boot loader
|
|
@section The role of a boot loader
|
|
|
|
The following is a quotation from Gordon Matzigkeit, a GRUB fanatic:
|
|
|
|
@quotation
|
|
Some people like to acknowledge both the operating system and kernel when
|
|
they talk about their computers, so they might say they use
|
|
``GNU/Linux'' or ``GNU/Hurd''. Other people seem to think that the
|
|
kernel is the most important part of the system, so they like to call
|
|
their GNU operating systems ``Linux systems.''
|
|
|
|
I, personally, believe that this is a grave injustice, because the
|
|
@emph{boot loader} is the most important software of all. I used to
|
|
refer to the above systems as either ``LILO''@footnote{The LInux LOader,
|
|
a boot loader that everybody uses, but nobody likes.} or ``GRUB''
|
|
systems.
|
|
|
|
Unfortunately, nobody ever understood what I was talking about; now I
|
|
just use the word ``GNU'' as a pseudonym for GRUB.
|
|
|
|
So, if you ever hear people talking about their alleged ``GNU'' systems,
|
|
remember that they are actually paying homage to the best boot loader
|
|
around@dots{} GRUB!
|
|
@end quotation
|
|
|
|
We, the GRUB maintainers, do not (usually) encourage Gordon's level of
|
|
fanaticism, but it helps to remember that boot loaders deserve
|
|
recognition. We hope that you enjoy using GNU GRUB as much as we did
|
|
writing it.
|
|
|
|
|
|
@node Naming convention
|
|
@chapter Naming convention
|
|
|
|
The device syntax used in GRUB is a wee bit different from what you may
|
|
have seen before in your operating system(s), and you need to know it so
|
|
that you can specify a drive/partition.
|
|
|
|
Look at the following examples and explanations:
|
|
|
|
@example
|
|
(fd0)
|
|
@end example
|
|
|
|
First of all, GRUB requires that the device name be enclosed with
|
|
@samp{(} and @samp{)}. The @samp{fd} part means that it is a floppy
|
|
disk. The number @samp{0} is the drive number, which is counted from
|
|
@emph{zero}. This expression means that GRUB will use the whole floppy
|
|
disk.
|
|
|
|
@example
|
|
(hd0,2)
|
|
@end example
|
|
|
|
Here, @samp{hd} means it is a hard disk drive. The first integer
|
|
@samp{0} indicates the drive number, that is, the first hard disk, while
|
|
the second integer, @samp{1}, indicates the partition number (or the
|
|
@sc{pc} slice number in the BSD terminology). The partition numbers are
|
|
counted from @emph{one}, not from zero (as was the case in previous
|
|
versions of GRUB). This expression means the second partition of the
|
|
first hard disk drive. In this case, GRUB uses one partition of the
|
|
disk, instead of the whole disk.
|
|
|
|
@example
|
|
(hd0,5)
|
|
@end example
|
|
|
|
This specifies the first @dfn{extended partition} of the first hard disk
|
|
drive. Note that the partition numbers for extended partitions are
|
|
counted from @samp{5}, regardless of the actual number of primary
|
|
partitions on your hard disk.
|
|
|
|
@example
|
|
(hd1,a)
|
|
@end example
|
|
|
|
This means the BSD @samp{a} partition of the second hard disk. If you
|
|
need to specify which @sc{pc} slice number should be used, use something
|
|
like this: @samp{(hd1,1,a)}. If the @sc{pc} slice number is omitted,
|
|
GRUB searches for the first @sc{pc} slice which has a BSD @samp{a}
|
|
partition.
|
|
|
|
Of course, to actually access the disks or partitions with GRUB, you
|
|
need to use the device specification in a command, like @samp{set
|
|
root=(fd0)} or @samp{parttool (hd0,3) hidden-}. To help you find out
|
|
which number specifies a partition you want, the GRUB command-line
|
|
(@pxref{Command-line interface}) options have argument
|
|
completion. This means that, for example, you only need to type
|
|
|
|
@example
|
|
set root=(
|
|
@end example
|
|
|
|
followed by a @key{TAB}, and GRUB will display the list of drives,
|
|
partitions, or file names. So it should be quite easy to determine the
|
|
name of your target partition, even with minimal knowledge of the
|
|
syntax.
|
|
|
|
Note that GRUB does @emph{not} distinguish IDE from SCSI - it simply
|
|
counts the drive numbers from zero, regardless of their type. Normally,
|
|
any IDE drive number is less than any SCSI drive number, although that
|
|
is not true if you change the boot sequence by swapping IDE and SCSI
|
|
drives in your BIOS.
|
|
|
|
Now the question is, how to specify a file? Again, consider an
|
|
example:
|
|
|
|
@example
|
|
(hd0,1)/vmlinuz
|
|
@end example
|
|
|
|
This specifies the file named @samp{vmlinuz}, found on the first
|
|
partition of the first hard disk drive. Note that the argument
|
|
completion works with file names, too.
|
|
|
|
That was easy, admit it. Now read the next chapter, to find out how to
|
|
actually install GRUB on your drive.
|
|
|
|
|
|
@node Installation
|
|
@chapter Installation
|
|
|
|
In order to install GRUB as your boot loader, you need to first
|
|
install the GRUB system and utilities under your UNIX-like operating
|
|
system (@pxref{Obtaining and Building GRUB}). You can do this either
|
|
from the source tarball, or as a package for your OS.
|
|
|
|
After you have done that, you need to install the boot loader on a
|
|
drive (floppy or hard disk). There are two ways of doing that - either
|
|
using the utility @command{grub-install} (@pxref{Invoking
|
|
grub-install}) on a UNIX-like OS, or by running GRUB itself from a
|
|
floppy. These are quite similar, however the utility might probe a
|
|
wrong BIOS drive, so you should be careful.
|
|
|
|
Also, if you install GRUB on a UNIX-like OS, please make sure that you
|
|
have an emergency boot disk ready, so that you can rescue your computer
|
|
if, by any chance, your hard drive becomes unusable (unbootable).
|
|
|
|
GRUB comes with boot images, which are normally put in the directory
|
|
@file{/usr/lib/grub/i386-pc}. Hereafter, the directory where GRUB images are
|
|
initially placed (normally @file{/usr/lib/grub/i386-pc}) will be
|
|
called the @dfn{image directory}, and the directory where the boot
|
|
loader needs to find them (usually @file{/boot/grub}) will be called
|
|
the @dfn{boot directory}.
|
|
|
|
@menu
|
|
* Installing GRUB using grub-install::
|
|
* Making a GRUB bootable CD-ROM::
|
|
* Device map::
|
|
@end menu
|
|
|
|
|
|
@node Installing GRUB using grub-install
|
|
@section Installing GRUB using grub-install
|
|
|
|
@strong{Caution:} This procedure is definitely less safe, because
|
|
there are several ways in which your computer can become
|
|
unbootable. For example, most operating systems don't tell GRUB how to
|
|
map BIOS drives to OS devices correctly---GRUB merely @dfn{guesses}
|
|
the mapping. This will succeed in most cases, but not
|
|
always. Therefore, GRUB provides you with a map file called the
|
|
@dfn{device map}, which you must fix if it is wrong. @xref{Device
|
|
map}, for more details.
|
|
|
|
If you still do want to install GRUB under a UNIX-like OS (such
|
|
as @sc{gnu}), invoke the program @command{grub-install} (@pxref{Invoking
|
|
grub-install}) as the superuser (@dfn{root}).
|
|
|
|
The usage is basically very simple. You only need to specify one
|
|
argument to the program, namely, where to install the boot loader. The
|
|
argument can be either a device file (like @samp{/dev/hda}) or a
|
|
partition specified in GRUB's notation. For example, under Linux the
|
|
following will install GRUB into the MBR of the first IDE disk:
|
|
|
|
@example
|
|
# @kbd{grub-install /dev/hda}
|
|
@end example
|
|
|
|
Likewise, under GNU/Hurd, this has the same effect:
|
|
|
|
@example
|
|
# @kbd{grub-install /dev/hd0}
|
|
@end example
|
|
|
|
If it is the first BIOS drive, this is the same as well:
|
|
|
|
@example
|
|
# @kbd{grub-install '(hd0)'}
|
|
@end example
|
|
|
|
Or you can omit the parentheses:
|
|
|
|
@example
|
|
# @kbd{grub-install hd0}
|
|
@end example
|
|
|
|
But all the above examples assume that GRUB should use images under
|
|
the root directory. If you want GRUB to use images under a directory
|
|
other than the root directory, you need to specify the option
|
|
@option{--root-directory}. The typical usage is that you create a GRUB
|
|
boot floppy with a filesystem. Here is an example:
|
|
|
|
@example
|
|
@group
|
|
# @kbd{mke2fs /dev/fd0}
|
|
# @kbd{mount -t ext2 /dev/fd0 /mnt}
|
|
# @kbd{grub-install --root-directory=/mnt fd0}
|
|
# @kbd{umount /mnt}
|
|
@end group
|
|
@end example
|
|
|
|
Another example is when you have a separate boot partition
|
|
which is mounted at @file{/boot}. Since GRUB is a boot loader, it
|
|
doesn't know anything about mountpoints at all. Thus, you need to run
|
|
@command{grub-install} like this:
|
|
|
|
@example
|
|
# @kbd{grub-install --root-directory=/boot /dev/hda}
|
|
@end example
|
|
|
|
By the way, as noted above, it is quite difficult to guess BIOS drives
|
|
correctly under a UNIX-like OS. Thus, @command{grub-install} will prompt
|
|
you to check if it could really guess the correct mappings, after the
|
|
installation. The format is defined in @ref{Device map}. Please be
|
|
quite careful. If the output is wrong, it is unlikely that your
|
|
computer will be able to boot with no problem.
|
|
|
|
Note that @command{grub-install} is actually just a shell script and the
|
|
real task is done by @command{grub-mkimage} and @command{grub-setup}.
|
|
Therefore, you may run those commands directly to install GRUB, without
|
|
using @command{grub-install}. Don't do that, however, unless you are very
|
|
familiar with the internals of GRUB. Installing a boot loader on a running
|
|
OS may be extremely dangerous.
|
|
|
|
|
|
@node Making a GRUB bootable CD-ROM
|
|
@section Making a GRUB bootable CD-ROM
|
|
|
|
GRUB supports the @dfn{no emulation mode} in the El Torito
|
|
specification@footnote{El Torito is a specification for bootable CD
|
|
using BIOS functions.}. This means that you can use the whole CD-ROM
|
|
from GRUB and you don't have to make a floppy or hard disk image file,
|
|
which can cause compatibility problems.
|
|
|
|
For booting from a CD-ROM, GRUB uses a special Stage 2 called
|
|
@file{stage2_eltorito}. The only GRUB files you need to have in your
|
|
bootable CD-ROM are this @file{stage2_eltorito} and optionally a config file
|
|
@file{grub.cfg}. You don't need to use @file{stage1} or @file{stage2},
|
|
because El Torito is quite different from the standard boot process.
|
|
|
|
Here is an example of procedures to make a bootable CD-ROM
|
|
image. First, make a top directory for the bootable image, say,
|
|
@samp{iso}:
|
|
|
|
@example
|
|
$ @kbd{mkdir iso}
|
|
@end example
|
|
|
|
Make a directory for GRUB:
|
|
|
|
@example
|
|
$ @kbd{mkdir -p iso/boot/grub}
|
|
@end example
|
|
|
|
Copy the file @file{stage2_eltorito}:
|
|
|
|
@example
|
|
$ @kbd{cp /usr/lib/grub/i386-pc/stage2_eltorito iso/boot/grub}
|
|
@end example
|
|
|
|
If desired, make the config file @file{grub.cfg} under @file{iso/boot/grub}
|
|
(@pxref{Configuration}), and copy any files and directories for the disc to the
|
|
directory @file{iso/}.
|
|
|
|
Finally, make a ISO9660 image file like this:
|
|
|
|
@example
|
|
$ @kbd{mkisofs -R -b boot/grub/stage2_eltorito -no-emul-boot \
|
|
-boot-load-size 4 -boot-info-table -o grub.iso iso}
|
|
@end example
|
|
|
|
This produces a file named @file{grub.iso}, which then can be burned
|
|
into a CD (or a DVD). @kbd{mkisofs} has already set up the disc to boot
|
|
from the @kbd{boot/grub/stage2_eltorito} file, so there is no need to
|
|
setup GRUB on the disc. (Note that the @kbd{-boot-load-size 4} bit is
|
|
required for compatibility with the BIOS on many older machines.)
|
|
|
|
You can use the device @samp{(cd)} to access a CD-ROM in your
|
|
config file. This is not required; GRUB automatically sets the root device
|
|
to @samp{(cd)} when booted from a CD-ROM. It is only necessary to refer to
|
|
@samp{(cd)} if you want to access other drives as well.
|
|
|
|
|
|
@node Device map
|
|
@section The map between BIOS drives and OS devices
|
|
|
|
The @command{grub-mkdevicemap} program can be used to create the @dfn{device
|
|
map file}. It is often run automatically by tools such as
|
|
@command{grub-install} if the device map file does not already exist. The
|
|
file name @file{/boot/grub/device.map} is preferred.
|
|
|
|
If the device map file exists, the GRUB utilities (@command{grub-probe},
|
|
@command{grub-setup}, etc.) read it to map BIOS drives to OS devices. This
|
|
file consists of lines like this:
|
|
|
|
@example
|
|
@var{device} @var{file}
|
|
@end example
|
|
|
|
@var{device} is a drive specified in the GRUB syntax (@pxref{Device
|
|
syntax}), and @var{file} is an OS file, which is normally a device file.
|
|
|
|
Historically, the device map file was used because GRUB device names had to
|
|
be used in the configuration file, and they were derived from BIOS drive
|
|
numbers. The map between BIOS drives and OS devices cannot always be
|
|
guessed correctly: for example, GRUB will get the order wrong if you
|
|
exchange the boot sequence between IDE and SCSI in your BIOS.
|
|
|
|
Unfortunately, even OS device names are not always stable. Modern versions
|
|
of the Linux kernel may probe drives in a different order from boot to boot,
|
|
and the prefix (@file{/dev/hd*} versus @file{/dev/sd*}) may change depending
|
|
on the driver subsystem in use. As a result, the device map file required
|
|
frequent editing on some systems.
|
|
|
|
GRUB avoids this problem nowadays by using UUIDs or file system labels when
|
|
generating @file{grub.cfg}, and we advise that you do the same for any
|
|
custom menu entries you write. If the device map file does not exist, then
|
|
the GRUB utilities will assume a temporary device map on the fly. This is
|
|
often good enough, particularly in the common case of single-disk systems.
|
|
|
|
However, the device map file is not entirely obsolete yet, and there are
|
|
still some situations that require it to exist. If necessary, you may edit
|
|
the file if @command{grub-mkdevicemap} makes a mistake. You can put any
|
|
comments in the file if needed, as the GRUB utilities assume that a line is
|
|
just a comment if the first character is @samp{#}.
|
|
|
|
|
|
@node Booting
|
|
@chapter Booting
|
|
|
|
GRUB can load Multiboot-compliant kernels in a consistent way,
|
|
but for some free operating systems you need to use some OS-specific
|
|
magic.
|
|
|
|
@menu
|
|
* General boot methods:: How to boot OSes with GRUB generally
|
|
* OS-specific notes:: Notes on some operating systems
|
|
@end menu
|
|
|
|
|
|
@node General boot methods
|
|
@section How to boot operating systems
|
|
|
|
GRUB has two distinct boot methods. One of the two is to load an
|
|
operating system directly, and the other is to chain-load another boot
|
|
loader which then will load an operating system actually. Generally
|
|
speaking, the former is more desirable, because you don't need to
|
|
install or maintain other boot loaders and GRUB is flexible enough to
|
|
load an operating system from an arbitrary disk/partition. However,
|
|
the latter is sometimes required, since GRUB doesn't support all the
|
|
existing operating systems natively.
|
|
|
|
@menu
|
|
* Loading an operating system directly::
|
|
* Chain-loading::
|
|
@end menu
|
|
|
|
|
|
@node Loading an operating system directly
|
|
@subsection How to boot an OS directly with GRUB
|
|
|
|
Multiboot (@pxref{Top, Multiboot Specification, Motivation, multiboot,
|
|
The Multiboot Specification}) is the native format supported by GRUB.
|
|
For the sake of convenience, there is also support for Linux, FreeBSD,
|
|
NetBSD and OpenBSD. If you want to boot other operating systems, you
|
|
will have to chain-load them (@pxref{Chain-loading}).
|
|
|
|
FIXME: this section is incomplete.
|
|
|
|
@enumerate
|
|
@item
|
|
Run the command @command{boot} (@pxref{boot}).
|
|
@end enumerate
|
|
|
|
However, DOS and Windows have some deficiencies, so you might have to
|
|
use more complicated instructions. @xref{DOS/Windows}, for more
|
|
information.
|
|
|
|
|
|
@node Chain-loading
|
|
@subsection Chain-loading an OS
|
|
|
|
Operating systems that do not support Multiboot and do not have specific
|
|
support in GRUB (specific support is available for Linux, FreeBSD, NetBSD
|
|
and OpenBSD) must be chain-loaded, which involves loading another boot
|
|
loader and jumping to it in real mode.
|
|
|
|
The @command{chainloader} command (@pxref{chainloader}) is used to set this
|
|
up. It is normally also necessary to load some GRUB modules and set the
|
|
appropriate root device. Putting this together, we get something like this,
|
|
for a Windows system on the first partition of the first hard disk:
|
|
|
|
@verbatim
|
|
menuentry "Windows" {
|
|
insmod chain
|
|
insmod ntfs
|
|
set root=(hd0,1)
|
|
chainloader +1
|
|
}
|
|
@end verbatim
|
|
@c FIXME: document UUIDs.
|
|
|
|
On systems with multiple hard disks, an additional workaround may be
|
|
required. @xref{DOS/Windows}.
|
|
|
|
Chain-loading is only supported on PC BIOS and EFI platforms.
|
|
|
|
|
|
@node OS-specific notes
|
|
@section Some caveats on OS-specific issues
|
|
|
|
Here, we describe some caveats on several operating systems.
|
|
|
|
@menu
|
|
* GNU/Hurd::
|
|
* GNU/Linux::
|
|
* DOS/Windows::
|
|
@end menu
|
|
|
|
|
|
@node GNU/Hurd
|
|
@subsection GNU/Hurd
|
|
|
|
Since GNU/Hurd is Multiboot-compliant, it is easy to boot it; there is
|
|
nothing special about it. But do not forget that you have to specify a
|
|
root partition to the kernel.
|
|
|
|
FIXME: this section is incomplete.
|
|
|
|
@enumerate
|
|
@item
|
|
Run the command @command{boot} (@pxref{boot}).
|
|
@end enumerate
|
|
|
|
|
|
@node GNU/Linux
|
|
@subsection GNU/Linux
|
|
|
|
It is relatively easy to boot GNU/Linux from GRUB, because it somewhat
|
|
resembles to boot a Multiboot-compliant OS.
|
|
|
|
FIXME: this section is incomplete.
|
|
|
|
@enumerate
|
|
@item
|
|
Set GRUB's root device to the same drive as GNU/Linux's.
|
|
|
|
@item
|
|
Finally, run the command @command{boot} (@pxref{boot}).
|
|
@end enumerate
|
|
|
|
@strong{Caution:} If you use an initrd and specify the @samp{mem=}
|
|
option to the kernel to let it use less than actual memory size, you
|
|
will also have to specify the same memory size to GRUB. To let GRUB know
|
|
the size, run the command @command{uppermem} @emph{before} loading the
|
|
kernel. @xref{uppermem}, for more information.
|
|
|
|
|
|
@node DOS/Windows
|
|
@subsection DOS/Windows
|
|
|
|
GRUB cannot boot DOS or Windows directly, so you must chain-load them
|
|
(@pxref{Chain-loading}). However, their boot loaders have some critical
|
|
deficiencies, so it may not work to just chain-load them. To overcome
|
|
the problems, GRUB provides you with two helper functions.
|
|
|
|
If you have installed DOS (or Windows) on a non-first hard disk, you
|
|
have to use the disk swapping technique, because that OS cannot boot
|
|
from any disks but the first one. The workaround used in GRUB is the
|
|
command @command{drivemap} (@pxref{drivemap}), like this:
|
|
|
|
@example
|
|
drivemap -s (hd0) (hd1)
|
|
@end example
|
|
|
|
This performs a @dfn{virtual} swap between your first and second hard
|
|
drive.
|
|
|
|
@strong{Caution:} This is effective only if DOS (or Windows) uses BIOS
|
|
to access the swapped disks. If that OS uses a special driver for the
|
|
disks, this probably won't work.
|
|
|
|
Another problem arises if you installed more than one set of DOS/Windows
|
|
onto one disk, because they could be confused if there are more than one
|
|
primary partitions for DOS/Windows. Certainly you should avoid doing
|
|
this, but there is a solution if you do want to do so. Use the partition
|
|
hiding/unhiding technique.
|
|
|
|
If GRUB @dfn{hides} a DOS (or Windows) partition (@pxref{parttool}), DOS (or
|
|
Windows) will ignore the partition. If GRUB @dfn{unhides} a DOS (or Windows)
|
|
partition, DOS (or Windows) will detect the partition. Thus, if you have
|
|
installed DOS (or Windows) on the first and the second partition of the
|
|
first hard disk, and you want to boot the copy on the first partition, do
|
|
the following:
|
|
|
|
@example
|
|
@group
|
|
parttool (hd0,1) hidden-
|
|
parttool (hd0,2) hidden+
|
|
set root=(hd0,1)
|
|
chainloader +1
|
|
parttool @verb{'${root}'} boot+
|
|
boot
|
|
@end group
|
|
@end example
|
|
|
|
|
|
@node Configuration
|
|
@chapter Writing your own configuration file
|
|
|
|
GRUB is configured using @file{grub.cfg}, usually located under
|
|
@file{/boot/grub}. This file is quite flexible, but most users will not
|
|
need to write the whole thing by hand.
|
|
|
|
@menu
|
|
* Simple configuration:: Recommended for most users
|
|
* Shell-like scripting:: For power users and developers
|
|
* Embedded configuration:: Embedding a configuration file into GRUB
|
|
* Themes:: Graphical menu themes
|
|
@end menu
|
|
|
|
|
|
@node Simple configuration
|
|
@section Simple configuration handling
|
|
|
|
The program @command{grub-mkconfig} (@pxref{Invoking grub-mkconfig})
|
|
generates @file{grub.cfg} files suitable for most cases. It is suitable for
|
|
use when upgrading a distribution, and will discover available kernels and
|
|
attempt to generate menu entries for them.
|
|
|
|
The file @file{/etc/default/grub} controls the operation of
|
|
@command{grub-mkconfig}. It is sourced by a shell script, and so must be
|
|
valid POSIX shell input; normally, it will just be a sequence of
|
|
@samp{KEY=value} lines, but if the value contains spaces or other special
|
|
characters then it must be quoted. For example:
|
|
|
|
@example
|
|
GRUB_TERMINAL_INPUT="console serial"
|
|
@end example
|
|
|
|
Valid keys in @file{/etc/default/grub} are as follows:
|
|
|
|
@table @samp
|
|
@item GRUB_DEFAULT
|
|
The default menu entry. This may be a number, in which case it identifies
|
|
the Nth entry in the generated menu counted from zero, or the full name of a
|
|
menu entry, or the special string @samp{saved}. Using the full name may be
|
|
useful if you want to set a menu entry as the default even though there may
|
|
be a variable number of entries before it.
|
|
|
|
If you set this to @samp{saved}, then the default menu entry will be that
|
|
saved by @samp{GRUB_SAVEDEFAULT}, @command{grub-set-default}, or
|
|
@command{grub-reboot}.
|
|
|
|
The default is @samp{0}.
|
|
|
|
@item GRUB_SAVEDEFAULT
|
|
If this option is set to @samp{true}, then, when an entry is selected, save
|
|
it as a new default entry for use by future runs of GRUB. This is only
|
|
useful if @samp{GRUB_DEFAULT=saved}; it is a separate option because
|
|
@samp{GRUB_DEFAULT=saved} is useful without this option, in conjunction with
|
|
@command{grub-set-default} or @command{grub-reboot}. Unset by default.
|
|
|
|
@item GRUB_TIMEOUT
|
|
Boot the default entry this many seconds after the menu is displayed, unless
|
|
a key is pressed. The default is @samp{5}. Set to @samp{0} to boot
|
|
immediately without displaying the menu, or to @samp{-1} to wait
|
|
indefinitely.
|
|
|
|
@item GRUB_HIDDEN_TIMEOUT
|
|
Wait this many seconds for a key to be pressed before displaying the menu.
|
|
If no key is pressed during that time, boot immediately. Unset by default.
|
|
|
|
@item GRUB_HIDDEN_TIMEOUT_QUIET
|
|
In conjunction with @samp{GRUB_HIDDEN_TIMEOUT}, set this to @samp{true} to
|
|
suppress the verbose countdown while waiting for a key to be pressed before
|
|
displaying the menu. Unset by default.
|
|
|
|
@item GRUB_DEFAULT_BUTTON
|
|
@itemx GRUB_TIMEOUT_BUTTON
|
|
@itemx GRUB_HIDDEN_TIMEOUT_BUTTON
|
|
@itemx GRUB_BUTTON_CMOS_ADDRESS
|
|
Variants of the corresponding variables without the @samp{_BUTTON} suffix,
|
|
used to support vendor-specific power buttons. @xref{Vendor power-on keys}.
|
|
|
|
@item GRUB_DISTRIBUTOR
|
|
Set by distributors of GRUB to their identifying name. This is used to
|
|
generate more informative menu entry titles.
|
|
|
|
@item GRUB_TERMINAL_INPUT
|
|
Select the terminal input device. You may select multiple devices here,
|
|
separated by spaces.
|
|
|
|
Valid terminal input names depend on the platform, but may include
|
|
@samp{console} (PC BIOS and EFI consoles), @samp{serial} (serial terminal),
|
|
@samp{ofconsole} (Open Firmware console), @samp{at_keyboard} (PC AT
|
|
keyboard, mainly useful with Coreboot), or @samp{usb_keyboard} (USB keyboard
|
|
using the HID Boot Protocol, for cases where the firmware does not handle
|
|
this).
|
|
|
|
The default is to use the platform's native terminal input.
|
|
|
|
@item GRUB_TERMINAL_OUTPUT
|
|
Select the terminal output device. You may select multiple devices here,
|
|
separated by spaces.
|
|
|
|
Valid terminal output names depend on the platform, but may include
|
|
@samp{console} (PC BIOS and EFI consoles), @samp{serial} (serial terminal),
|
|
@samp{gfxterm} (graphics-mode output), @samp{ofconsole} (Open Firmware
|
|
console), or @samp{vga_text} (VGA text output, mainly useful with Coreboot).
|
|
|
|
The default is to use the platform's native terminal output.
|
|
|
|
@item GRUB_TERMINAL
|
|
If this option is set, it overrides both @samp{GRUB_TERMINAL_INPUT} and
|
|
@samp{GRUB_TERMINAL_OUTPUT} to the same value.
|
|
|
|
@item GRUB_SERIAL_COMMAND
|
|
A command to configure the serial port when using the serial console.
|
|
@xref{serial}. Defaults to @samp{serial}.
|
|
|
|
@item GRUB_CMDLINE_LINUX
|
|
Command-line arguments to add to menu entries for the Linux kernel.
|
|
|
|
@item GRUB_CMDLINE_LINUX_DEFAULT
|
|
Unless @samp{GRUB_DISABLE_LINUX_RECOVERY} is set to @samp{true}, two menu
|
|
entries will be generated for each Linux kernel: one default entry and one
|
|
entry for recovery mode. This option lists command-line arguments to add
|
|
only to the default menu entry, after those listed in
|
|
@samp{GRUB_CMDLINE_LINUX}.
|
|
|
|
@item GRUB_CMDLINE_NETBSD
|
|
@itemx GRUB_CMDLINE_NETBSD_DEFAULT
|
|
As @samp{GRUB_CMDLINE_LINUX} and @samp{GRUB_CMDLINE_LINUX_DEFAULT}, but for
|
|
NetBSD.
|
|
|
|
@item GRUB_DISABLE_LINUX_UUID
|
|
Normally, @command{grub-mkconfig} will generate menu entries that use
|
|
universally-unique identifiers (UUIDs) to identify the root filesystem to
|
|
the Linux kernel, using a @samp{root=UUID=...} kernel parameter. This is
|
|
usually more reliable, but in some cases it may not be appropriate. To
|
|
disable the use of UUIDs, set this option to @samp{true}.
|
|
|
|
@item GRUB_DISABLE_LINUX_RECOVERY
|
|
If this option is set to @samp{true}, disable the generation of recovery
|
|
mode menu entries for Linux.
|
|
|
|
@item GRUB_DISABLE_NETBSD_RECOVERY
|
|
If this option is set to @samp{true}, disable the generation of recovery
|
|
mode menu entries for NetBSD.
|
|
|
|
@item GRUB_VIDEO_BACKEND
|
|
If graphical video support is required, either because the @samp{gfxterm}
|
|
graphical terminal is in use or because @samp{GRUB_GFXPAYLOAD_LINUX} is set,
|
|
then @command{grub-mkconfig} will normally load all available GRUB video
|
|
drivers and use the one most appropriate for your hardware. If you need to
|
|
override this for some reason, then you can set this option.
|
|
|
|
After @command{grub-install} has been run, the available video drivers are
|
|
listed in @file{/boot/grub/video.lst}.
|
|
|
|
@item GRUB_GFXMODE
|
|
Set the resolution used on the @samp{gfxterm} graphical terminal. Note that
|
|
you can only use modes which your graphics card supports via VESA BIOS
|
|
Extensions (VBE), so for example native LCD panel resolutions may not be
|
|
available. The default is @samp{640x480}.
|
|
|
|
@item GRUB_BACKGROUND
|
|
Set a background image for use with the @samp{gfxterm} graphical terminal.
|
|
The value of this option must be a file readable by GRUB at boot time, and
|
|
it must end with @file{.png}, @file{.tga}, @file{.jpg}, or @file{.jpeg}.
|
|
The image will be scaled if necessary to fit the screen.
|
|
|
|
@item GRUB_THEME
|
|
Set a theme for use with the @samp{gfxterm} graphical terminal.
|
|
@xref{Themes}.
|
|
|
|
@item GRUB_GFXPAYLOAD_LINUX
|
|
Set to @samp{text} to force the Linux kernel to boot in normal text mode,
|
|
@samp{keep} to preserve the graphics mode set using @samp{GRUB_GFXMODE},
|
|
@samp{@var{width}x@var{height}}[@samp{x@var{depth}}] to set a particular
|
|
graphics mode, or a sequence of these separated by commas or semicolons to
|
|
try several modes in sequence.
|
|
|
|
Depending on your kernel, your distribution, your graphics card, and the
|
|
phase of the moon, note that using this option may cause GNU/Linux to suffer
|
|
from various display problems, particularly during the early part of the
|
|
boot sequence. If you have problems, simply unset this option and GRUB will
|
|
tell Linux to boot in normal text mode.
|
|
|
|
@item GRUB_DISABLE_OS_PROBER
|
|
Normally, @command{grub-mkconfig} will try to use the external
|
|
@command{os-prober} program, if installed, to discover other operating
|
|
systems installed on the same system and generate appropriate menu entries
|
|
for them. Set this option to @samp{true} to disable this.
|
|
|
|
@item GRUB_INIT_TUNE
|
|
Play a tune on the speaker when GRUB starts. This is particularly useful
|
|
for users unable to see the screen. The value of this option is passed
|
|
directly to @ref{play}.
|
|
|
|
@item GRUB_BADRAM
|
|
If this option is set, GRUB will issue a @ref{badram} command to filter
|
|
out specified regions of RAM.
|
|
|
|
@end table
|
|
|
|
For more detailed customisation of @command{grub-mkconfig}'s output, you may
|
|
edit the scripts in @file{/etc/grub.d} directly.
|
|
@file{/etc/grub.d/40_custom} is particularly useful for adding entire custom
|
|
menu entries; simply type the menu entries you want to add at the end of
|
|
that file, making sure to leave at least the first two lines intact.
|
|
|
|
|
|
@node Shell-like scripting
|
|
@section Writing full configuration files directly
|
|
|
|
|
|
@node Embedded configuration
|
|
@section Embedding a configuration file into GRUB
|
|
|
|
GRUB supports embedding a configuration file directly into the core image,
|
|
so that it is loaded before entering normal mode. This is useful, for
|
|
example, when it is not straightforward to find the real configuration file,
|
|
or when you need to debug problems with loading that file.
|
|
@command{grub-install} uses this feature when it is not using BIOS disk
|
|
functions or when installing to a different disk from the one containing
|
|
@file{/boot/grub}, in which case it needs to use the @command{search}
|
|
command (@pxref{search}) to find @file{/boot/grub}.
|
|
|
|
To embed a configuration file, use the @option{-c} option to
|
|
@command{grub-mkimage}. The file is copied into the core image, so it may
|
|
reside anywhere on the file system, and may be removed after running
|
|
@command{grub-mkimage}.
|
|
|
|
After the embedded configuration file (if any) is executed, GRUB will load
|
|
the @samp{normal} module, which will then read the real configuration file
|
|
from @file{$prefix/grub.cfg}. By this point, the @code{root} variable will
|
|
also have been set to the root device name. For example, @code{prefix}
|
|
might be set to @samp{(hd0,1)/boot/grub}, and @code{root} might be set to
|
|
@samp{hd0,1}. Thus, in most cases, the embedded configuration file only
|
|
needs to set the @code{prefix} and @code{root} variables, and then drop
|
|
through to GRUB's normal processing. A typical example of this might look
|
|
like this:
|
|
|
|
@example
|
|
@group
|
|
search.fs_uuid 01234567-89ab-cdef-0123-456789abcdef root
|
|
set prefix=($root)/boot/grub
|
|
@end group
|
|
@end example
|
|
|
|
(The @samp{search_fs_uuid} module must be included in the core image for this
|
|
example to work.)
|
|
|
|
In more complex cases, it may be useful to read other configuration files
|
|
directly from the embedded configuration file. This allows such things as
|
|
reading files not called @file{grub.cfg}, or reading files from a directory
|
|
other than that where GRUB's loadable modules are installed. To do this,
|
|
include the @samp{configfile} and @samp{normal} modules in the core image,
|
|
and embed a configuration file that uses the @command{configfile} command to
|
|
load another file. The following example of this also requires the
|
|
@command{echo}, @command{search_label}, and @command{test} modules to be
|
|
included in the core image:
|
|
|
|
@example
|
|
@group
|
|
search.fs_label grub root
|
|
if [ -e /boot/grub/example/test1.cfg ]; then
|
|
set prefix=($root)/boot/grub
|
|
configfile /boot/grub/example/test1.cfg
|
|
else
|
|
if [ -e /boot/grub/example/test2.cfg ]; then
|
|
set prefix=($root)/boot/grub
|
|
configfile /boot/grub/example/test2.cfg
|
|
else
|
|
echo "Could not find an example configuration file!"
|
|
fi
|
|
fi
|
|
@end group
|
|
@end example
|
|
|
|
The embedded configuration file may not contain menu entries directly, but
|
|
may only read them from elsewhere using @command{configfile}.
|
|
|
|
|
|
@node Themes
|
|
@section Graphical menu themes
|
|
|
|
|
|
@node Network
|
|
@chapter Booting GRUB from the network
|
|
|
|
The following instructions only work on PC BIOS systems where the Preboot
|
|
eXecution Environment (PXE) is available.
|
|
|
|
To generate a PXE boot image, run:
|
|
|
|
@example
|
|
@group
|
|
grub-mkimage --format=i386-pc --output=core.img --prefix='(pxe)/boot/grub' pxe pxecmd
|
|
cat /boot/grub/pxeboot.img core.img >grub.pxe
|
|
@end group
|
|
@end example
|
|
|
|
Copy @file{grub.pxe}, @file{/boot/grub/*.mod}, and @file{/boot/grub/*.lst}
|
|
to the PXE (TFTP) server, ensuring that @file{*.mod} and @file{*.lst} are
|
|
accessible via the @file{/boot/grub/} path from the TFTP server root. Set
|
|
the DHCP server configuration to offer @file{grub.pxe} as the boot file (the
|
|
@samp{filename} option in ISC dhcpd).
|
|
|
|
After GRUB has started, files on the TFTP server will be accessible via the
|
|
@samp{(pxe)} device.
|
|
|
|
The server and gateway IP address can be controlled by changing the
|
|
@samp{(pxe)} device name to @samp{(pxe:@var{server-ip})} or
|
|
@samp{(pxe:@var{server-ip}:@var{gateway-ip})}. Note that this should be
|
|
changed both in the prefix and in any references to the device name in the
|
|
configuration file.
|
|
|
|
GRUB provides several environment variables which may be used to inspect or
|
|
change the behaviour of the PXE device:
|
|
|
|
@table @samp
|
|
@item net_pxe_ip
|
|
The IP address of this machine. Read-only.
|
|
|
|
@item net_pxe_mac
|
|
The network interface's MAC address. Read-only.
|
|
|
|
@item net_pxe_hostname
|
|
The client host name provided by DHCP. Read-only.
|
|
|
|
@item net_pxe_domain
|
|
The client domain name provided by DHCP. Read-only.
|
|
|
|
@item net_pxe_rootpath
|
|
The path to the client's root disk provided by DHCP. Read-only.
|
|
|
|
@item net_pxe_extensionspath
|
|
The path to additional DHCP vendor extensions provided by DHCP. Read-only.
|
|
|
|
@item net_pxe_boot_file
|
|
The boot file name provided by DHCP. Read-only.
|
|
|
|
@item net_pxe_dhcp_server_name
|
|
The name of the DHCP server responsible for these boot parameters.
|
|
Read-only.
|
|
|
|
@item net_pxe_blksize
|
|
The PXE transfer block size. Read-write, defaults to 512.
|
|
|
|
@item pxe_default_server
|
|
The default PXE server. Read-write, although setting this is only useful
|
|
before opening a PXE device.
|
|
|
|
@item pxe_default_gateway
|
|
The default gateway to use when contacting the PXE server. Read-write,
|
|
although setting this is only useful before opening a PXE device.
|
|
@end table
|
|
|
|
|
|
@node Serial terminal
|
|
@chapter Using GRUB via a serial line
|
|
|
|
This chapter describes how to use the serial terminal support in GRUB.
|
|
|
|
If you have many computers or computers with no display/keyboard, it
|
|
could be very useful to control the computers through serial
|
|
communications. To connect one computer with another via a serial line,
|
|
you need to prepare a null-modem (cross) serial cable, and you may need
|
|
to have multiport serial boards, if your computer doesn't have extra
|
|
serial ports. In addition, a terminal emulator is also required, such as
|
|
minicom. Refer to a manual of your operating system, for more
|
|
information.
|
|
|
|
As for GRUB, the instruction to set up a serial terminal is quite
|
|
simple. First of all, make sure that you haven't specified the option
|
|
@option{--disable-serial} to the configure script when you built your
|
|
GRUB images. If you get them in binary form, probably they have serial
|
|
terminal support already.
|
|
|
|
Then, initialize your serial terminal after GRUB starts up. Here is an
|
|
example:
|
|
|
|
@example
|
|
@group
|
|
grub> @kbd{serial --unit=0 --speed=9600}
|
|
grub> @kbd{terminal serial}
|
|
@end group
|
|
@end example
|
|
|
|
The command @command{serial} initializes the serial unit 0 with the
|
|
speed 9600bps. The serial unit 0 is usually called @samp{COM1}, so, if
|
|
you want to use COM2, you must specify @samp{--unit=1} instead. This
|
|
command accepts many other options, so please refer to @ref{serial},
|
|
for more details.
|
|
|
|
The commands @command{terminal_input} (@pxref{terminal_input}) and
|
|
@command{terminal_output} (@pxref{terminal_output} choose which type of
|
|
terminal you want to use. In the case above, the terminal will be a
|
|
serial terminal, but you can also pass @code{console} to the command,
|
|
as @samp{terminal serial console}. In this case, a terminal in which
|
|
you press any key will be selected as a GRUB terminal.
|
|
|
|
However, note that GRUB assumes that your terminal emulator is
|
|
compatible with VT100 by default. This is true for most terminal
|
|
emulators nowadays, but you should pass the option @option{--dumb} to
|
|
the command if your terminal emulator is not VT100-compatible or
|
|
implements few VT100 escape sequences. If you specify this option then
|
|
GRUB provides you with an alternative menu interface, because the normal
|
|
menu requires several fancy features of your terminal.
|
|
|
|
|
|
@node Vendor power-on keys
|
|
@chapter Using GRUB with vendor power-on keys
|
|
Some laptop vendor provide an additional power-on button which boots another OS.
|
|
GRUB supports such buttons with GRUB_TIMEOUT_BUTTON, GRUB_DEFAULT_BUTTON,
|
|
GRUB_HIDDEN_TIMEOUT_BUTTON and GRUB_BUTTON_CMOS_ADDRESS variables in
|
|
default/grub. GRUB_TIMEOUT_BUTTON, GRUB_DEFAULT_BUTTON and
|
|
GRUB_HIDDEN_TIMEOUT_BUTTON are used instead of corresponding variables without
|
|
_BUTTON suffix when powered using special button.
|
|
GRUB_BUTTON_CMOS_ADDRESS is vendor specific and partially model-specific.
|
|
Values known to GRUB team are:
|
|
|
|
@table @key
|
|
@item Dell XPS M1530
|
|
85:3
|
|
@item Asus EeePC 1005PE
|
|
84:1 (unconfirmed)
|
|
@end table
|
|
|
|
To take full advantage of this function install GRUB into MBR.
|
|
|
|
|
|
@node Images
|
|
@chapter GRUB image files
|
|
|
|
@c FIXME: parts of this section are specific to PC BIOS right now.
|
|
|
|
GRUB consists of several images: a variety of bootstrap images for starting
|
|
GRUB in various ways, a kernel image, and a set of modules which are
|
|
combined with the kernel image to form a core image. Here is a short
|
|
overview of them.
|
|
|
|
@table @file
|
|
@item boot.img
|
|
On PC BIOS systems, this image is the first part of GRUB to start. It is
|
|
written to a master boot record (MBR) or to the boot sector of a partition.
|
|
Because a PC boot sector is 512 bytes, the size of this image is exactly 512
|
|
bytes.
|
|
|
|
The sole function of @file{boot.img} is to read the first sector of the core
|
|
image from a local disk and jump to it. Because of the size restriction,
|
|
@file{boot.img} cannot understand any file system structure, so
|
|
@command{grub-setup} hardcodes the location of the first sector of the core
|
|
image into @file{boot.img} when installing GRUB.
|
|
|
|
@item diskboot.img
|
|
This image is used as the first sector of the core image when booting from a
|
|
hard disk. It reads the rest of the core image into memory and starts the
|
|
kernel. Since file system handling is not yet available, it encodes the
|
|
location of the core image using a block list format.
|
|
|
|
@item cdboot.img
|
|
This image is used as the first sector of the core image when booting from a
|
|
CD-ROM drive. It performs a similar function to @file{diskboot.img}.
|
|
|
|
@item pxeboot.img
|
|
This image is used as the start of the core image when booting from the
|
|
network using PXE. @xref{Network}.
|
|
|
|
@item lnxboot.img
|
|
This image may be placed at the start of the core image in order to make
|
|
GRUB look enough like a Linux kernel that it can be booted by LILO using an
|
|
@samp{image=} section.
|
|
|
|
@item kernel.img
|
|
This image contains GRUB's basic run-time facilities: frameworks for device
|
|
and file handling, environment variables, the rescue mode command-line
|
|
parser, and so on. It is rarely used directly, but is built into all core
|
|
images.
|
|
|
|
@item core.img
|
|
This is the core image of GRUB. It is built dynamically from the kernel
|
|
image and an arbitrary list of modules by the @command{grub-mkimage}
|
|
program. Usually, it contains enough modules to access @file{/boot/grub},
|
|
and loads everything else (including menu handling, the ability to load
|
|
target operating systems, and so on) from the file system at run-time. The
|
|
modular design allows the core image to be kept small, since the areas of
|
|
disk where it must be installed are often as small as 32KB.
|
|
|
|
On PC systems using the traditional MBR partition table format, the core
|
|
image is usually installed in the "MBR gap" between the master boot record
|
|
and the first partition, or sometimes it is installed in a file system and
|
|
read directly from that. The latter is not recommended because GRUB needs
|
|
to encode the location of all the core image sectors in @file{diskboot.img},
|
|
and if the file system ever moves the core image around (as it is entitled
|
|
to do) then GRUB must be reinstalled; it also means that GRUB will not be
|
|
able to reliably find the core image if it resides on a different disk than
|
|
the one to which @file{boot.img} was installed.
|
|
|
|
On PC systems using the more recent GUID Partition Table (GPT) format, the
|
|
core image should be installed to a BIOS Boot Partition. This may be
|
|
created by GNU Parted using a command such as the following:
|
|
|
|
@example
|
|
# @kbd{parted /dev/@var{disk} set @var{partition-number} bios_grub on}
|
|
@end example
|
|
|
|
@strong{Caution:} Be very careful which partition you select! When GRUB
|
|
finds a BIOS Boot Partition during installation, it will automatically
|
|
overwrite part of it. Make sure that the partition does not contain any
|
|
other data.
|
|
|
|
@item *.mod
|
|
Everything else in GRUB resides in dynamically loadable modules. These are
|
|
often loaded automatically, or built into the core image if they are
|
|
essential, but may also be loaded manually using the @command{insmod}
|
|
command (@pxref{insmod}).
|
|
@end table
|
|
|
|
@heading For GRUB Legacy users
|
|
|
|
GRUB 2 has a different design from GRUB Legacy, and so correspondences with
|
|
the images it used cannot be exact. Nevertheless, GRUB Legacy users often
|
|
ask questions in the terms they are familiar with, and so here is a brief
|
|
guide to how GRUB 2's images relate to that.
|
|
|
|
@table @file
|
|
@item stage1
|
|
Stage 1 from GRUB Legacy was very similar to @file{boot.img} in GRUB 2, and
|
|
they serve the same function.
|
|
|
|
@item *_stage1_5
|
|
In GRUB Legacy, Stage 1.5's function was to include enough filesystem code
|
|
to allow the much larger Stage 2 to be read from an ordinary filesystem. In
|
|
this respect, its function was similar to @file{core.img} in GRUB 2.
|
|
However, @file{core.img} is much more capable than Stage 1.5 was; since it
|
|
offers a rescue shell, it is sometimes possible to recover manually in the
|
|
event that it is unable to load any other modules, for example if partition
|
|
numbers have changed. @file{core.img} is built in a more flexible way,
|
|
allowing GRUB 2 to support reading modules from advanced disk types such as
|
|
LVM and RAID.
|
|
|
|
GRUB Legacy could run with only Stage 1 and Stage 2 in some limited
|
|
configurations, while GRUB 2 requires @file{core.img} and cannot work
|
|
without it.
|
|
|
|
@item stage2
|
|
GRUB 2 has no single Stage 2 image. Instead, it loads modules from
|
|
@file{/boot/grub} at run-time.
|
|
|
|
@item stage2_eltorito
|
|
In GRUB 2, images for booting from CD-ROM drives are now constructed using
|
|
@file{cdboot.img} and @file{core.img}, making sure that the core image
|
|
contains the @samp{iso9660} module. It is usually best to use the
|
|
@command{grub-mkrescue} program for this.
|
|
|
|
@item nbgrub
|
|
There is as yet no equivalent for @file{nbgrub} in GRUB 2; it was used by
|
|
Etherboot and some other network boot loaders.
|
|
|
|
@item pxegrub
|
|
In GRUB 2, images for PXE network booting are now constructed using
|
|
@file{pxeboot.img} and @file{core.img}, making sure that the core image
|
|
contains the @samp{pxe} and @samp{pxecmd} modules. @xref{Network}.
|
|
@end table
|
|
|
|
|
|
@node Filesystem
|
|
@chapter Filesystem syntax and semantics
|
|
|
|
GRUB uses a special syntax for specifying disk drives which can be
|
|
accessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish
|
|
between IDE, ESDI, SCSI, or others. You must know yourself which BIOS
|
|
device is equivalent to which OS device. Normally, that will be clear if
|
|
you see the files in a device or use the command @command{search}
|
|
(@pxref{search}).
|
|
|
|
@menu
|
|
* Device syntax:: How to specify devices
|
|
* File name syntax:: How to specify files
|
|
* Block list syntax:: How to specify block lists
|
|
@end menu
|
|
|
|
|
|
@node Device syntax
|
|
@section How to specify devices
|
|
|
|
The device syntax is like this:
|
|
|
|
@example
|
|
@code{(@var{device}[,@var{part-num}][,@var{bsd-subpart-letter}])}
|
|
@end example
|
|
|
|
@samp{[]} means the parameter is optional. @var{device} should be
|
|
either @samp{fd} or @samp{hd} followed by a digit, like @samp{fd0}.
|
|
But you can also set @var{device} to a hexadecimal or a decimal number
|
|
which is a BIOS drive number, so the following are equivalent:
|
|
|
|
@example
|
|
(hd0)
|
|
(0x80)
|
|
(128)
|
|
@end example
|
|
|
|
@var{part-num} represents the partition number of @var{device}, starting
|
|
from one for primary partitions and from five for extended partitions,
|
|
and @var{bsd-subpart-letter} represents the BSD disklabel subpartition,
|
|
such as @samp{a} or @samp{e}.
|
|
|
|
A shortcut for specifying BSD subpartitions is
|
|
@code{(@var{device},@var{bsd-subpart-letter})}, in this case, GRUB
|
|
searches for the first PC partition containing a BSD disklabel, then
|
|
finds the subpartition @var{bsd-subpart-letter}. Here is an example:
|
|
|
|
@example
|
|
(hd0,a)
|
|
@end example
|
|
|
|
The syntax @samp{(hd0)} represents using the entire disk (or the
|
|
MBR when installing GRUB), while the syntax @samp{(hd0,1)}
|
|
represents using the first partition of the disk (or the boot sector
|
|
of the partition when installing GRUB).
|
|
|
|
If you enabled the network support, the special drive @samp{(pxe)} is
|
|
also available. Before using the network drive, you must initialize the
|
|
network. @xref{Network}, for more information.
|
|
|
|
If you boot GRUB from a CD-ROM, @samp{(cd)} is available. @xref{Making
|
|
a GRUB bootable CD-ROM}, for details.
|
|
|
|
|
|
@node File name syntax
|
|
@section How to specify files
|
|
|
|
There are two ways to specify files, by @dfn{absolute file name} and by
|
|
@dfn{block list}.
|
|
|
|
An absolute file name resembles a Unix absolute file name, using
|
|
@samp{/} for the directory separator (not @samp{\} as in DOS). One
|
|
example is @samp{(hd0,1)/boot/grub/grub.cfg}. This means the file
|
|
@file{/boot/grub/grub.cfg} in the first partition of the first hard
|
|
disk. If you omit the device name in an absolute file name, GRUB uses
|
|
GRUB's @dfn{root device} implicitly. So if you set the root device to,
|
|
say, @samp{(hd1,1)} by the command @samp{set root=(hd1,1)} (@pxref{set}),
|
|
then @code{/boot/kernel} is the same as @code{(hd1,1)/boot/kernel}.
|
|
|
|
|
|
@node Block list syntax
|
|
@section How to specify block lists
|
|
|
|
A block list is used for specifying a file that doesn't appear in the
|
|
filesystem, like a chainloader. The syntax is
|
|
@code{[@var{offset}]+@var{length}[,[@var{offset}]+@var{length}]@dots{}}.
|
|
Here is an example:
|
|
|
|
@example
|
|
@code{0+100,200+1,300+300}
|
|
@end example
|
|
|
|
This represents that GRUB should read blocks 0 through 99, block 200,
|
|
and blocks 300 through 599. If you omit an offset, then GRUB assumes
|
|
the offset is zero.
|
|
|
|
Like the file name syntax (@pxref{File name syntax}), if a blocklist
|
|
does not contain a device name, then GRUB uses GRUB's @dfn{root
|
|
device}. So @code{(hd0,2)+1} is the same as @code{+1} when the root
|
|
device is @samp{(hd0,2)}.
|
|
|
|
|
|
@node Interface
|
|
@chapter GRUB's user interface
|
|
|
|
GRUB has both a simple menu interface for choosing preset entries from a
|
|
configuration file, and a highly flexible command-line for performing
|
|
any desired combination of boot commands.
|
|
|
|
GRUB looks for its configuration file as soon as it is loaded. If one
|
|
is found, then the full menu interface is activated using whatever
|
|
entries were found in the file. If you choose the @dfn{command-line} menu
|
|
option, or if the configuration file was not found, then GRUB drops to
|
|
the command-line interface.
|
|
|
|
@menu
|
|
* Command-line interface:: The flexible command-line interface
|
|
* Menu interface:: The simple menu interface
|
|
* Menu entry editor:: Editing a menu entry
|
|
@end menu
|
|
|
|
|
|
@node Command-line interface
|
|
@section The flexible command-line interface
|
|
|
|
The command-line interface provides a prompt and after it an editable
|
|
text area much like a command-line in Unix or DOS. Each command is
|
|
immediately executed after it is entered@footnote{However, this
|
|
behavior will be changed in the future version, in a user-invisible
|
|
way.}. The commands (@pxref{Command-line and menu entry commands}) are a
|
|
subset of those available in the configuration file, used with exactly
|
|
the same syntax.
|
|
|
|
Cursor movement and editing of the text on the line can be done via a
|
|
subset of the functions available in the Bash shell:
|
|
|
|
@table @key
|
|
@item C-f
|
|
@itemx PC right key
|
|
Move forward one character.
|
|
|
|
@item C-b
|
|
@itemx PC left key
|
|
Move back one character.
|
|
|
|
@item C-a
|
|
@itemx HOME
|
|
Move to the start of the line.
|
|
|
|
@item C-e
|
|
@itemx END
|
|
Move the the end of the line.
|
|
|
|
@item C-d
|
|
@itemx DEL
|
|
Delete the character underneath the cursor.
|
|
|
|
@item C-h
|
|
@itemx BS
|
|
Delete the character to the left of the cursor.
|
|
|
|
@item C-k
|
|
Kill the text from the current cursor position to the end of the line.
|
|
|
|
@item C-u
|
|
Kill backward from the cursor to the beginning of the line.
|
|
|
|
@item C-y
|
|
Yank the killed text back into the buffer at the cursor.
|
|
|
|
@item C-p
|
|
@itemx PC up key
|
|
Move up through the history list.
|
|
|
|
@item C-n
|
|
@itemx PC down key
|
|
Move down through the history list.
|
|
@end table
|
|
|
|
When typing commands interactively, if the cursor is within or before
|
|
the first word in the command-line, pressing the @key{TAB} key (or
|
|
@key{C-i}) will display a listing of the available commands, and if the
|
|
cursor is after the first word, the @kbd{@key{TAB}} will provide a
|
|
completion listing of disks, partitions, and file names depending on the
|
|
context. Note that to obtain a list of drives, one must open a
|
|
parenthesis, as @command{root (}.
|
|
|
|
Note that you cannot use the completion functionality in the TFTP
|
|
filesystem. This is because TFTP doesn't support file name listing for
|
|
the security.
|
|
|
|
|
|
@node Menu interface
|
|
@section The simple menu interface
|
|
|
|
The menu interface is quite easy to use. Its commands are both
|
|
reasonably intuitive and described on screen.
|
|
|
|
Basically, the menu interface provides a list of @dfn{boot entries} to
|
|
the user to choose from. Use the arrow keys to select the entry of
|
|
choice, then press @key{RET} to run it. An optional timeout is
|
|
available to boot the default entry (the first one if not set), which is
|
|
aborted by pressing any key.
|
|
|
|
Commands are available to enter a bare command-line by pressing @key{c}
|
|
(which operates exactly like the non-config-file version of GRUB, but
|
|
allows one to return to the menu if desired by pressing @key{ESC}) or to
|
|
edit any of the @dfn{boot entries} by pressing @key{e}.
|
|
|
|
If you protect the menu interface with a password (@pxref{Security}),
|
|
all you can do is choose an entry by pressing @key{RET}, or press
|
|
@key{p} to enter the password.
|
|
|
|
|
|
@node Menu entry editor
|
|
@section Editing a menu entry
|
|
|
|
The menu entry editor looks much like the main menu interface, but the
|
|
lines in the menu are individual commands in the selected entry instead
|
|
of entry names.
|
|
|
|
If an @key{ESC} is pressed in the editor, it aborts all the changes made
|
|
to the configuration entry and returns to the main menu interface.
|
|
|
|
When a particular line is selected, the editor places the user in a
|
|
special version of the GRUB command-line to edit that line. When the
|
|
user hits @key{RET}, GRUB replaces the line in question in the boot
|
|
entry with the changes (unless it was aborted via @key{ESC},
|
|
in which case the changes are thrown away).
|
|
|
|
If you want to add a new line to the menu entry, press @key{o} if adding
|
|
a line after the current line or press @key{O} if before the current
|
|
line.
|
|
|
|
To delete a line, hit the key @key{d}. Although GRUB unfortunately
|
|
does not support @dfn{undo}, you can do almost the same thing by just
|
|
returning to the main menu.
|
|
|
|
|
|
@node Commands
|
|
@chapter The list of available commands
|
|
|
|
In this chapter, we list all commands that are available in GRUB.
|
|
|
|
Commands belong to different groups. A few can only be used in
|
|
the global section of the configuration file (or ``menu''); most
|
|
of them can be entered on the command-line and can be used either
|
|
anywhere in the menu or specifically in the menu entries.
|
|
|
|
In rescue mode, only the @command{insmod} (@pxref{insmod}), @command{ls}
|
|
(@pxref{ls}), @command{set} (@pxref{set}), and @command{unset}
|
|
(@pxref{unset}) commands are normally available.
|
|
|
|
@menu
|
|
* Menu-specific commands::
|
|
* General commands::
|
|
* Command-line and menu entry commands::
|
|
@end menu
|
|
|
|
|
|
@node Menu-specific commands
|
|
@section The list of commands for the menu only
|
|
|
|
The semantics used in parsing the configuration file are the following:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The menu-specific commands have to be used before any others.
|
|
|
|
@item
|
|
The files @emph{must} be in plain-text format.
|
|
|
|
@item
|
|
@samp{#} at the beginning of a line in a configuration file means it is
|
|
only a comment.
|
|
|
|
@item
|
|
Options are separated by spaces.
|
|
|
|
@item
|
|
All numbers can be either decimal or hexadecimal. A hexadecimal number
|
|
must be preceded by @samp{0x}, and is case-insensitive.
|
|
|
|
@item
|
|
Extra options or text at the end of the line are ignored unless otherwise
|
|
specified.
|
|
|
|
@item
|
|
Unrecognized commands are added to the current entry, except before entries
|
|
start, where they are ignored.
|
|
@end itemize
|
|
|
|
These commands can only be used in the menu:
|
|
|
|
@menu
|
|
* menuentry:: Start a menu entry
|
|
@end menu
|
|
|
|
|
|
@node menuentry
|
|
@subsection menuentry
|
|
|
|
@deffn Command title name @dots{}
|
|
Start a new boot entry, and set its name to the contents of the rest of
|
|
the line, starting with the first non-space character.
|
|
@end deffn
|
|
|
|
|
|
@node General commands
|
|
@section The list of general commands
|
|
|
|
Commands usable anywhere in the menu and in the command-line.
|
|
|
|
@menu
|
|
* serial:: Set up a serial device
|
|
* terminal_input:: Manage input terminals
|
|
* terminal_output:: Manage output terminals
|
|
* terminfo:: Define terminal type
|
|
@end menu
|
|
|
|
|
|
@node serial
|
|
@subsection serial
|
|
|
|
@deffn Command serial [@option{--unit=unit}] [@option{--port=port}] [@option{--speed=speed}] [@option{--word=word}] [@option{--parity=parity}] [@option{--stop=stop}]
|
|
Initialize a serial device. @var{unit} is a number in the range 0-3
|
|
specifying which serial port to use; default is 0, which corresponds to
|
|
the port often called COM1. @var{port} is the I/O port where the UART
|
|
is to be found; if specified it takes precedence over @var{unit}.
|
|
@var{speed} is the transmission speed; default is 9600. @var{word} and
|
|
@var{stop} are the number of data bits and stop bits. Data bits must
|
|
be in the range 5-8 and stop bits must be 1 or 2. Default is 8 data
|
|
bits and one stop bit. @var{parity} is one of @samp{no}, @samp{odd},
|
|
@samp{even} and defaults to @samp{no}.
|
|
|
|
The serial port is not used as a communication channel unless the
|
|
@command{terminal_input} or @command{terminal_output} command is used
|
|
(@pxref{terminal_input}, @pxref{terminal_output}).
|
|
|
|
This command is only available if GRUB is compiled with serial
|
|
support. See also @ref{Serial terminal}.
|
|
@end deffn
|
|
|
|
|
|
@node terminal_input
|
|
@subsection terminal_input
|
|
|
|
@deffn Command terminal_input [@option{--append}|@option{--remove}] @
|
|
[terminal1] [terminal2] @dots{}
|
|
List or select an input terminal.
|
|
|
|
With no arguments, list the active and available input terminals.
|
|
|
|
With @option{--append}, add the named terminals to the list of active input
|
|
terminals; any of these may be used to provide input to GRUB.
|
|
|
|
With @option{--remove}, remove the named terminals from the active list.
|
|
|
|
With no options but a list of terminal names, make only the listed terminal
|
|
names active.
|
|
@end deffn
|
|
|
|
|
|
@node terminal_output
|
|
@subsection terminal_output
|
|
|
|
@deffn Command terminal_output [@option{--append}|@option{--remove}] @
|
|
[terminal1] [terminal2] @dots{}
|
|
List or select an output terminal.
|
|
|
|
With no arguments, list the active and available output terminals.
|
|
|
|
With @option{--append}, add the named terminals to the list of active output
|
|
terminals; all of these will receive output from GRUB.
|
|
|
|
With @option{--remove}, remove the named terminals from the active list.
|
|
|
|
With no options but a list of terminal names, make only the listed terminal
|
|
names active.
|
|
@end deffn
|
|
|
|
|
|
@node terminfo
|
|
@subsection terminfo
|
|
|
|
@deffn Command terminfo [term]
|
|
Define the capabilities of your terminal by giving the name of an entry in
|
|
the terminfo database, which should correspond roughly to a @samp{TERM}
|
|
environment variable in Unix.
|
|
|
|
At the moment, only @samp{vt100} is supported in GRUB 2. If you need other
|
|
terminal types, please contact us to discuss the best way to include support
|
|
for these in GRUB.
|
|
|
|
If no option is specified, the current terminal type is printed.
|
|
@end deffn
|
|
|
|
|
|
@node Command-line and menu entry commands
|
|
@section The list of command-line and menu entry commands
|
|
|
|
These commands are usable in the command-line and in menu entries. If
|
|
you forget a command, you can run the command @command{help}
|
|
(@pxref{help}).
|
|
|
|
@menu
|
|
* acpi:: Load ACPI tables
|
|
* badram:: Filter out bad regions of RAM
|
|
* blocklist:: Print a block list
|
|
* boot:: Start up your operating system
|
|
* cat:: Show the contents of a file
|
|
* chainloader:: Chain-load another boot loader
|
|
* cmp:: Compare two files
|
|
* configfile:: Load a configuration file
|
|
* cpuid:: Check for CPU features
|
|
* crc:: Calculate CRC32 checksums
|
|
* date:: Display or set current date and time
|
|
* drivemap:: Map a drive to another
|
|
* echo:: Display a line of text
|
|
* export:: Export an environment variable
|
|
* gettext:: Translate a string
|
|
* gptsync:: Fill an MBR based on GPT entries
|
|
* halt:: Shut down your computer
|
|
* help:: Show help messages
|
|
* insmod:: Insert a module
|
|
* keystatus:: Check key modifier status
|
|
* ls:: List devices or files
|
|
* parttool:: Modify partition table entries
|
|
* password:: Set a clear-text password
|
|
* password_pbkdf2:: Set a hashed password
|
|
* play:: Play a tune
|
|
* pxe_unload:: Unload the PXE environment
|
|
* reboot:: Reboot your computer
|
|
* search:: Search devices by file, label, or UUID
|
|
* set:: Set an environment variable
|
|
* unset:: Unset an environment variable
|
|
* uppermem:: Set the upper memory size
|
|
@end menu
|
|
|
|
|
|
@node acpi
|
|
@subsection acpi
|
|
|
|
@deffn Command acpi [@option{-1}|@option{-2}] @
|
|
[@option{--exclude=table1,@dots{}}|@option{--load-only=table1,@dots{}}] @
|
|
[@option{--oemid=id}] [@option{--oemtable=table}] @
|
|
[@option{--oemtablerev=rev}] [@option{--oemtablecreator=creator}] @
|
|
[@option{--oemtablecreatorrev=rev}] [@option{--no-ebda}] @
|
|
filename @dots{}
|
|
Modern BIOS systems normally implement the Advanced Configuration and Power
|
|
Interface (ACPI), and define various tables that describe the interface
|
|
between an ACPI-compliant operating system and the firmware. In some cases,
|
|
the tables provided by default only work well with certain operating
|
|
systems, and it may be necessary to replace some of them.
|
|
|
|
Normally, this command will replace the Root System Description Pointer
|
|
(RSDP) in the Extended BIOS Data Area to point to the new tables. If the
|
|
@option{--no-ebda} option is used, the new tables will be known only to
|
|
GRUB, but may be used by GRUB's EFI emulation.
|
|
@end deffn
|
|
|
|
@node badram
|
|
@subsection badram
|
|
|
|
@deffn Command badram addr,mask[,addr,mask...]
|
|
Filter out bad RAM.
|
|
@end deffn
|
|
|
|
This command notifies the memory manager that specified regions of
|
|
RAM ought to be filtered out (usually, because they're damaged). This
|
|
remains in effect after a payload kernel has been loaded by GRUB, as
|
|
long as the loaded kernel obtains its memory map from GRUB. Kernels that
|
|
support this include Linux, GNU Mach, the kernel of FreeBSD and Multiboot
|
|
kernels in general.
|
|
|
|
Syntax is the same as provided by the @uref{http://www.memtest.org/,
|
|
Memtest86+ utility}: a list of address/mask pairs. Given a page-aligned
|
|
address and a base address / mask pair, if all the bits of the page-aligned
|
|
address that are enabled by the mask match with the base address, it means
|
|
this page is to be filtered. This syntax makes it easy to represent patterns
|
|
that are often result of memory damage, due to physical distribution of memory
|
|
cells.
|
|
|
|
@node blocklist
|
|
@subsection blocklist
|
|
|
|
@deffn Command blocklist file
|
|
Print a block list (@pxref{Block list syntax}) for @var{file}.
|
|
@end deffn
|
|
|
|
|
|
@node boot
|
|
@subsection boot
|
|
|
|
@deffn Command boot
|
|
Boot the OS or chain-loader which has been loaded. Only necessary if
|
|
running the fully interactive command-line (it is implicit at the end of
|
|
a menu entry).
|
|
@end deffn
|
|
|
|
|
|
@node cat
|
|
@subsection cat
|
|
|
|
@deffn Command cat [@option{--dos}] file
|
|
Display the contents of the file @var{file}. This command may be useful
|
|
to remind you of your OS's root partition:
|
|
|
|
@example
|
|
grub> @kbd{cat /etc/fstab}
|
|
@end example
|
|
|
|
If the @option{--dos} option is used, then carriage return / new line pairs
|
|
will be displayed as a simple new line. Otherwise, the carriage return will
|
|
be displayed as a control character (@samp{<d>}) to make it easier to see
|
|
when boot problems are caused by a file formatted using DOS-style line
|
|
endings.
|
|
@end deffn
|
|
|
|
|
|
@node chainloader
|
|
@subsection chainloader
|
|
|
|
@deffn Command chainloader [@option{--force}] file
|
|
Load @var{file} as a chain-loader. Like any other file loaded by the
|
|
filesystem code, it can use the blocklist notation (@pxref{Block list
|
|
syntax}) to grab the first sector of the current partition with @samp{+1}.
|
|
If you specify the option @option{--force}, then load @var{file} forcibly,
|
|
whether it has a correct signature or not. This is required when you want to
|
|
load a defective boot loader, such as SCO UnixWare 7.1.
|
|
@end deffn
|
|
|
|
|
|
@node cmp
|
|
@subsection cmp
|
|
|
|
@deffn Command cmp file1 file2
|
|
Compare the file @var{file1} with the file @var{file2}. If they differ
|
|
in size, print the sizes like this:
|
|
|
|
@example
|
|
Differ in size: 0x1234 [foo], 0x4321 [bar]
|
|
@end example
|
|
|
|
If the sizes are equal but the bytes at an offset differ, then print the
|
|
bytes like this:
|
|
|
|
@example
|
|
Differ at the offset 777: 0xbe [foo], 0xef [bar]
|
|
@end example
|
|
|
|
If they are completely identical, nothing will be printed.
|
|
@end deffn
|
|
|
|
|
|
@node configfile
|
|
@subsection configfile
|
|
|
|
@deffn Command configfile file
|
|
Load @var{file} as a configuration file. If @var{file} defines any menu
|
|
entries, then show a menu containing them immediately.
|
|
@end deffn
|
|
|
|
|
|
@node cpuid
|
|
@subsection cpuid
|
|
|
|
@deffn Command cpuid [-l]
|
|
Check for CPU features. This command is only available on x86 systems.
|
|
|
|
With the @option{-l} option, return true if the CPU supports long mode
|
|
(64-bit).
|
|
|
|
If invoked without options, this command currently behaves as if it had been
|
|
invoked with @option{-l}. This may change in the future.
|
|
@end deffn
|
|
|
|
|
|
@node crc
|
|
@subsection crc
|
|
|
|
@deffn Command crc file
|
|
Display the CRC32 checksum of @var{file}.
|
|
@end deffn
|
|
|
|
|
|
@node date
|
|
@subsection date
|
|
|
|
@deffn Command date [[year-]month-day] [hour:minute[:second]]
|
|
With no arguments, print the current date and time.
|
|
|
|
Otherwise, take the current date and time, change any elements specified as
|
|
arguments, and set the result as the new date and time. For example, `date
|
|
01-01' will set the current month and day to January 1, but leave the year,
|
|
hour, minute, and second unchanged.
|
|
@end deffn
|
|
|
|
|
|
@node drivemap
|
|
@subsection drivemap
|
|
|
|
@deffn Command drivemap @option{-l}|@option{-r}|[@option{-s}] @
|
|
from_drive to_drive
|
|
Without options, map the drive @var{from_drive} to the drive @var{to_drive}.
|
|
This is necessary when you chain-load some operating systems, such as DOS,
|
|
if such an OS resides at a non-first drive. For convenience, any partition
|
|
suffix on the drive is ignored, so you can safely use @verb{'${root}'} as a
|
|
drive specification.
|
|
|
|
With the @option{-s} option, perform the reverse mapping as well, swapping
|
|
the two drives.
|
|
|
|
With the @option{-l} option, list the current mappings.
|
|
|
|
With the @option{-r} option, reset all mappings to the default values.
|
|
|
|
For example:
|
|
|
|
@example
|
|
drivemap -s (hd0) (hd1)
|
|
@end example
|
|
@end deffn
|
|
|
|
|
|
@node echo
|
|
@subsection echo
|
|
|
|
@deffn Command echo [@option{-n}] [@option{-e}] string @dots{}
|
|
Display the requested text and, unless the @option{-n} option is used, a
|
|
trailing new line. If there is more than one string, they are separated by
|
|
spaces in the output. As usual in GRUB commands, variables may be
|
|
substituted using @samp{$@{var@}}.
|
|
|
|
The @option{-e} option enables interpretation of backslash escapes. The
|
|
following sequences are recognised:
|
|
|
|
@table @code
|
|
@item \\
|
|
backslash
|
|
|
|
@item \a
|
|
alert (BEL)
|
|
|
|
@item \c
|
|
suppress trailing new line
|
|
|
|
@item \f
|
|
form feed
|
|
|
|
@item \n
|
|
new line
|
|
|
|
@item \r
|
|
carriage return
|
|
|
|
@item \t
|
|
horizontal tab
|
|
|
|
@item \v
|
|
vertical tab
|
|
@end table
|
|
|
|
When interpreting backslash escapes, backslash followed by any other
|
|
character will print that character.
|
|
@end deffn
|
|
|
|
|
|
@node export
|
|
@subsection export
|
|
|
|
@deffn Command export envvar
|
|
Export the environment variable @var{envvar}. Exported variables are visible
|
|
to subsidiary configuration files loaded using @command{configfile}.
|
|
@end deffn
|
|
|
|
|
|
@node gettext
|
|
@subsection gettext
|
|
|
|
@deffn Command gettext string
|
|
Translate @var{string} into the current language.
|
|
|
|
The current language code is stored in the @samp{lang} variable in GRUB's
|
|
environment. Translation files in MO format are read from
|
|
@samp{locale_dir}, usually @file{/boot/grub/locale}.
|
|
@end deffn
|
|
|
|
|
|
@node gptsync
|
|
@subsection gptsync
|
|
|
|
@deffn Command gptsync device [partition[+/-[type]]] @dots{}
|
|
Disks using the GUID Partition Table (GPT) also have a legacy Master Boot
|
|
Record (MBR) partition table for compatibility with the BIOS and with older
|
|
operating systems. The legacy MBR can only represent a limited subset of
|
|
GPT partition entries.
|
|
|
|
This command populates the legacy MBR with the specified @var{partition}
|
|
entries on @var{device}. Up to three partitions may be used.
|
|
|
|
@var{type} is an MBR partition type code; prefix with @samp{0x} if you want
|
|
to enter this in hexadecimal. The separator between @var{partition} and
|
|
@var{type} may be @samp{+} to make the partition active, or @samp{-} to make
|
|
it inactive; only one partition may be active. If both the separator and
|
|
type are omitted, then the partition will be inactive.
|
|
@end deffn
|
|
|
|
|
|
@node halt
|
|
@subsection halt
|
|
|
|
@deffn Command halt @option{--no-apm}
|
|
The command halts the computer. If the @option{--no-apm} option
|
|
is specified, no APM BIOS call is performed. Otherwise, the computer
|
|
is shut down using APM.
|
|
@end deffn
|
|
|
|
|
|
@node help
|
|
@subsection help
|
|
|
|
@deffn Command help [pattern @dots{}]
|
|
Display helpful information about builtin commands. If you do not
|
|
specify @var{pattern}, this command shows short descriptions of all
|
|
available commands.
|
|
|
|
If you specify any @var{patterns}, it displays longer information
|
|
about each of the commands whose names begin with those @var{patterns}.
|
|
@end deffn
|
|
|
|
|
|
@node insmod
|
|
@subsection insmod
|
|
|
|
@deffn Command insmod module
|
|
Insert the dynamic GRUB module called @var{module}.
|
|
@end deffn
|
|
|
|
|
|
@node keystatus
|
|
@subsection keystatus
|
|
|
|
@deffn Command keystatus [@option{--shift}] [@option{--ctrl}] [@option{--alt}]
|
|
Return true if the Shift, Control, or Alt modifier keys are held down, as
|
|
requested by options. This is useful in scripting, to allow some user
|
|
control over behaviour without having to wait for a keypress.
|
|
|
|
Checking key modifier status is only supported on some platforms. If invoked
|
|
without any options, the @command{keystatus} command returns true if and
|
|
only if checking key modifier status is supported.
|
|
@end deffn
|
|
|
|
|
|
@node ls
|
|
@subsection ls
|
|
|
|
@deffn Command ls [arg]
|
|
List devices or files.
|
|
|
|
With no arguments, print all devices known to GRUB.
|
|
|
|
If the argument is a device name enclosed in parentheses (@pxref{Device
|
|
syntax}), then list all files at the root directory of that device.
|
|
|
|
If the argument is a directory given as an absolute file name (@pxref{File
|
|
name syntax}), then list the contents of that directory.
|
|
@end deffn
|
|
|
|
|
|
@node parttool
|
|
@subsection parttool
|
|
|
|
@deffn Command parttool partition commands
|
|
Make various modifications to partition table entries.
|
|
|
|
Each @var{command} is either a boolean option, in which case it must be
|
|
followed with @samp{+} or @samp{-} (with no intervening space) to enable or
|
|
disable that option, or else it takes a value in the form
|
|
@samp{@var{command}=@var{value}}.
|
|
|
|
Currently, @command{parttool} is only useful on DOS partition tables (also
|
|
known as Master Boot Record, or MBR). On these partition tables, the
|
|
following commands are available:
|
|
|
|
@table @asis
|
|
@item @samp{boot} (boolean)
|
|
When enabled, this makes the selected partition be the active (bootable)
|
|
partition on its disk, clearing the active flag on all other partitions.
|
|
This command is limited to @emph{primary} partitions.
|
|
|
|
@item @samp{type} (value)
|
|
Change the type of an existing partition. The value must be a number in the
|
|
range 0-0xFF (prefix with @samp{0x} to enter it in hexadecimal).
|
|
|
|
@item @samp{hidden} (boolean)
|
|
When enabled, this hides the selected partition by setting the @dfn{hidden}
|
|
bit in its partition type code; when disabled, unhides the selected
|
|
partition by clearing this bit. This is useful only when booting DOS or
|
|
Wwindows and multiple primary FAT partitions exist in one disk. See also
|
|
@ref{DOS/Windows}.
|
|
@end table
|
|
@end deffn
|
|
|
|
|
|
@node password
|
|
@subsection password
|
|
|
|
@deffn Command password user clear-password
|
|
Define a user named @var{user} with password @var{clear-password}.
|
|
@xref{Security}.
|
|
@end deffn
|
|
|
|
|
|
@node password_pbkdf2
|
|
@subsection password_pbkdf2
|
|
|
|
@deffn Command password_pbkdf2 user hashed-password
|
|
Define a user named @var{user} with password hash @var{hashed-password}.
|
|
Use @command{grub-mkpasswd-pbkdf2} (@pxref{Invoking grub-mkpasswd-pbkdf2})
|
|
to generate password hashes. @xref{Security}.
|
|
@end deffn
|
|
|
|
|
|
@node play
|
|
@subsection play
|
|
|
|
@deffn Command play file | tempo [pitch1 duration1] [pitch2 duration2] ...
|
|
Plays a tune
|
|
|
|
If the argument is a file name (@pxref{File name syntax}), play the tune
|
|
recorded in it. The file format is first the tempo as an unsigned 32bit
|
|
little-endian number, then pairs of unsigned 16bit little-endian numbers for
|
|
pitch and duration pairs.
|
|
|
|
If the arguments are a series of numbers, play the inline tune.
|
|
|
|
The tempo is the base for all note durations. 60 gives a 1-second base, 120
|
|
gives a half-second base, etc. Pitches are Hz. Set pitch to 0 to produce
|
|
a rest.
|
|
@end deffn
|
|
|
|
|
|
@node pxe_unload
|
|
@subsection pxe_unload
|
|
|
|
@deffn Command pxe_unload
|
|
Unload the PXE environment (@pxref{Network}).
|
|
|
|
This command is only available on PC BIOS systems.
|
|
@end deffn
|
|
|
|
|
|
@node reboot
|
|
@subsection reboot
|
|
|
|
@deffn Command reboot
|
|
Reboot the computer.
|
|
@end deffn
|
|
|
|
|
|
@node search
|
|
@subsection search
|
|
|
|
@deffn Command search @
|
|
[@option{--file}|@option{--label}|@option{--fs-uuid}] @
|
|
[@option{--set} var] [@option{--no-floppy}] name
|
|
Search devices by file (@option{-f}, @option{--file}), filesystem label
|
|
(@option{-l}, @option{--label}), or filesystem UUID (@option{-u},
|
|
@option{--fs-uuid}).
|
|
|
|
If the @option{--set} option is used, the first device found is set as the
|
|
value of environment variable @var{var}. The default variable is
|
|
@samp{root}.
|
|
|
|
The @option{--no-floppy} option prevents searching floppy devices, which can
|
|
be slow.
|
|
|
|
The @samp{search.file}, @samp{search.fs_label}, and @samp{search.fs_uuid}
|
|
commands are aliases for @samp{search --file}, @samp{search --label}, and
|
|
@samp{search --fs-uuid} respectively.
|
|
@end deffn
|
|
|
|
|
|
@node set
|
|
@subsection set
|
|
|
|
@deffn Command set [envvar=value]
|
|
Set the environment variable @var{envvar} to @var{value}. If invoked with no
|
|
arguments, print all environment variables with their values.
|
|
@end deffn
|
|
|
|
|
|
@node unset
|
|
@subsection unset
|
|
|
|
@deffn Command unset envvar
|
|
Unset the environment variable @var{envvar}.
|
|
@end deffn
|
|
|
|
|
|
@node uppermem
|
|
@subsection uppermem
|
|
|
|
This command is not yet implemented for GRUB 2, although it is planned.
|
|
|
|
|
|
@node Security
|
|
@chapter Authentication and authorisation
|
|
|
|
By default, the boot loader interface is accessible to anyone with physical
|
|
access to the console: anyone can select and edit any menu entry, and anyone
|
|
can get direct access to a GRUB shell prompt. For most systems, this is
|
|
reasonable since anyone with direct physical access has a variety of other
|
|
ways to gain full access, and requiring authentication at the boot loader
|
|
level would only serve to make it difficult to recover broken systems.
|
|
|
|
However, in some environments, such as kiosks, it may be appropriate to lock
|
|
down the boot loader to require authentication before performing certain
|
|
operations.
|
|
|
|
The @samp{password} (@pxref{password}) and @samp{password_pbkdf2}
|
|
(@pxref{password_pbkdf2}) commands can be used to define users, each of
|
|
which has an associated password. @samp{password} sets the password in
|
|
plain text, requiring @file{grub.cfg} to be secure; @samp{password_pbkdf2}
|
|
sets the password hashed using the Password-Based Key Derivation Function
|
|
(RFC 2898), requiring the use of @command{grub-mkpasswd-pbkdf2}
|
|
(@pxref{Invoking grub-mkpasswd-pbkdf2}) to generate password hashes.
|
|
|
|
In order to enable authentication support, the @samp{superusers} environment
|
|
variable must be set to a list of usernames, separated by any of spaces,
|
|
commas, semicolons, pipes, or ampersands. Superusers are permitted to use
|
|
the GRUB command line, edit menu entries, and execute any menu entry. If
|
|
@samp{superusers} is set, then use of the command line is automatically
|
|
restricted to superusers.
|
|
|
|
Other users may be given access to specific menu entries by giving a list of
|
|
usernames (as above) using the @option{--users} option to the
|
|
@samp{menuentry} command (@pxref{menuentry}). If the @option{--users}
|
|
option is not used for a menu entry, then that entry is unrestricted.
|
|
|
|
Putting this together, a typical @file{grub.cfg} fragment might look like
|
|
this:
|
|
|
|
@example
|
|
@group
|
|
set superusers="root"
|
|
password_pbkdf2 root grub.pbkdf2.sha512.10000.biglongstring
|
|
password user1 insecure
|
|
|
|
menuentry "May be run by any user" @{
|
|
set root=(hd0,1)
|
|
linux /vmlinuz
|
|
@}
|
|
|
|
menuentry "Superusers only" --users "" @{
|
|
set root=(hd0,1)
|
|
linux /vmlinuz single
|
|
@}
|
|
|
|
menuentry "May be run by user1 or a superuser" --users user1 @{
|
|
set root=(hd0,2)
|
|
chainloader +1
|
|
@}
|
|
@end group
|
|
@end example
|
|
|
|
The @command{grub-mkconfig} program does not yet have built-in support for
|
|
generating configuration files with authentication. You can use
|
|
@file{/etc/grub.d/40_custom} to add simple superuser authentication, by
|
|
adding @kbd{set superusers=} and @kbd{password} or @kbd{password_pbkdf2}
|
|
commands.
|
|
|
|
|
|
@node Troubleshooting
|
|
@chapter Error messages produced by GRUB
|
|
|
|
@menu
|
|
* GRUB only offers a rescue shell::
|
|
@end menu
|
|
|
|
|
|
@node GRUB only offers a rescue shell
|
|
@section GRUB only offers a rescue shell
|
|
|
|
GRUB's normal start-up procedure involves setting the @samp{prefix}
|
|
environment variable to a value set in the core image by
|
|
@command{grub-install}, setting the @samp{root} variable to match, loading
|
|
the @samp{normal} module from the prefix, and running the @samp{normal}
|
|
command. This command is responsible for reading
|
|
@file{/boot/grub/grub.cfg}, running the menu, and doing all the useful
|
|
things GRUB is supposed to do.
|
|
|
|
If, instead, you only get a rescue shell, this usually means that GRUB
|
|
failed to load the @samp{normal} module for some reason. It may be possible
|
|
to work around this temporarily: for instance, if the reason for the failure
|
|
is that @samp{prefix} is wrong (perhaps it refers to the wrong device, or
|
|
perhaps the path to @file{/boot/grub} was not correctly made relative to the
|
|
device), then you can correct this and enter normal mode manually:
|
|
|
|
@example
|
|
@group
|
|
# Inspect the current prefix (and other preset variables):
|
|
set
|
|
# Set to the correct value, which might be something like this:
|
|
set prefix=(hd0,1)/grub
|
|
set root=(hd0,1)
|
|
insmod normal
|
|
normal
|
|
@end group
|
|
@end example
|
|
|
|
However, any problem that leaves you in the rescue shell probably means that
|
|
GRUB was not correctly installed. It may be more useful to try to reinstall
|
|
it properly using @kbd{grub-install @var{device}} (@pxref{Invoking
|
|
grub-install}). When doing this, there are a few things to remember:
|
|
|
|
@itemize @bullet{}
|
|
@item
|
|
Drive ordering in your operating system may not be the same as the boot
|
|
drive ordering used by your firmware. Do not assume that your first hard
|
|
drive (e.g. @samp{/dev/sda}) is the one that your firmware will boot from.
|
|
|
|
@item
|
|
At least on BIOS systems, if you tell @command{grub-install} to install GRUB
|
|
to a partition but GRUB has already been installed in the master boot
|
|
record, then the GRUB installation in the partition will be ignored.
|
|
|
|
@item
|
|
If possible, it is generally best to avoid installing GRUB to a partition
|
|
(unless it is a special partition for the use of GRUB alone, such as the
|
|
BIOS Boot Partition used on GPT). Doing this means that GRUB may stop being
|
|
able to read its core image due to a file system moving blocks around, such
|
|
as while defragmenting, running checks, or even during normal operation.
|
|
Installing to the whole disk device is normally more robust.
|
|
|
|
@item
|
|
Check that GRUB actually knows how to read from the device and file system
|
|
containing @file{/boot/grub}. It will not be able to read from encrypted
|
|
devices, nor from file systems for which support has not yet been added to
|
|
GRUB.
|
|
@end itemize
|
|
|
|
|
|
@node Invoking grub-install
|
|
@chapter Invoking grub-install
|
|
|
|
The program @command{grub-install} installs GRUB on your drive using
|
|
@command{grub-mkimage} and (on some platforms) @command{grub-setup}. You
|
|
must specify the device name on which you want to install GRUB, like this:
|
|
|
|
@example
|
|
grub-install @var{install_device}
|
|
@end example
|
|
|
|
The device name @var{install_device} is an OS device name or a GRUB
|
|
device name.
|
|
|
|
@command{grub-install} accepts the following options:
|
|
|
|
@table @option
|
|
@item --help
|
|
Print a summary of the command-line options and exit.
|
|
|
|
@item --version
|
|
Print the version number of GRUB and exit.
|
|
|
|
@item --root-directory=@var{dir}
|
|
Install GRUB images under the directory @var{dir} instead of the root
|
|
directory. This option is useful when you want to install GRUB into a
|
|
separate partition or a removable disk. Here is an example in which
|
|
you have a separate @dfn{boot} partition which is mounted on
|
|
@file{/boot}:
|
|
|
|
@example
|
|
@kbd{grub-install --root-directory=/boot hd0}
|
|
@end example
|
|
|
|
@item --recheck
|
|
Recheck the device map, even if @file{/boot/grub/device.map} already
|
|
exists. You should use this option whenever you add/remove a disk
|
|
into/from your computer.
|
|
@end table
|
|
|
|
|
|
@node Invoking grub-mkconfig
|
|
@chapter Invoking grub-mkconfig
|
|
|
|
The program @command{grub-mkconfig} generates a configuration file for GRUB
|
|
(@pxref{Simple configuration}).
|
|
|
|
@example
|
|
grub-mkconfig -o /boot/grub/grub.cfg
|
|
@end example
|
|
|
|
@command{grub-mkconfig} accepts the following options:
|
|
|
|
@table @option
|
|
@item --help
|
|
Print a summary of the command-line options and exit.
|
|
|
|
@item --version
|
|
Print the version number of GRUB and exit.
|
|
|
|
@item -o @var{file}
|
|
@itemx --output=@var{file}
|
|
Send the generated configuration file to @var{file}. The default is to send
|
|
it to standard output.
|
|
@end table
|
|
|
|
|
|
@node Invoking grub-mkpasswd-pbkdf2
|
|
@chapter Invoking grub-mkpasswd-pbkdf2
|
|
|
|
The program @command{grub-mkpasswd-pbkdf2} generates password hashes for
|
|
GRUB (@pxref{Security}).
|
|
|
|
@example
|
|
grub-mkpasswd-pbkdf2
|
|
@end example
|
|
|
|
@command{grub-mkpasswd-pbkdf2} accepts the following options:
|
|
|
|
@table @option
|
|
@item -c @var{number}
|
|
@itemx --iteration-count=@var{number}
|
|
Number of iterations of the underlying pseudo-random function. Defaults to
|
|
10000.
|
|
|
|
@item -l @var{number}
|
|
@itemx --buflen=@var{number}
|
|
Length of the generated hash. Defaults to 64.
|
|
|
|
@item -s @var{number}
|
|
@itemx --salt=@var{number}
|
|
Length of the salt. Defaults to 64.
|
|
@end table
|
|
|
|
|
|
@node Obtaining and Building GRUB
|
|
@appendix How to obtain and build GRUB
|
|
|
|
@quotation
|
|
@strong{Caution:} GRUB requires binutils-2.9.1.0.23 or later because the
|
|
GNU assembler has been changed so that it can produce real 16bits
|
|
machine code between 2.9.1 and 2.9.1.0.x. See
|
|
@uref{http://sources.redhat.com/binutils/}, to obtain information on
|
|
how to get the latest version.
|
|
@end quotation
|
|
|
|
GRUB is available from the GNU alpha archive site
|
|
@uref{ftp://alpha.gnu.org/gnu/grub} or any of its mirrors. The file
|
|
will be named grub-version.tar.gz. The current version is
|
|
@value{VERSION}, so the file you should grab is:
|
|
|
|
@uref{ftp://alpha.gnu.org/gnu/grub/grub-@value{VERSION}.tar.gz}
|
|
|
|
To unbundle GRUB use the instruction:
|
|
|
|
@example
|
|
@kbd{zcat grub-@value{VERSION}.tar.gz | tar xvf -}
|
|
@end example
|
|
|
|
which will create a directory called @file{grub-@value{VERSION}} with
|
|
all the sources. You can look at the file @file{INSTALL} for detailed
|
|
instructions on how to build and install GRUB, but you should be able to
|
|
just do:
|
|
|
|
@example
|
|
@group
|
|
@kbd{cd grub-@value{VERSION}}
|
|
@kbd{./configure}
|
|
@kbd{make install}
|
|
@end group
|
|
@end example
|
|
|
|
Also, the latest version is available using Bazaar. See
|
|
@uref{http://www.gnu.org/software/grub/grub-download.en.html} for more
|
|
information.
|
|
|
|
@node Reporting bugs
|
|
@appendix Reporting bugs
|
|
|
|
These are the guideline for how to report bugs. Take a look at this
|
|
list below before you submit bugs:
|
|
|
|
@enumerate
|
|
@item
|
|
Before getting unsettled, read this manual through and through. Also,
|
|
see the @uref{http://www.gnu.org/software/grub/grub-faq.html, GNU GRUB FAQ}.
|
|
|
|
@item
|
|
Always mention the information on your GRUB. The version number and the
|
|
configuration are quite important. If you build it yourself, write the
|
|
options specified to the configure script and your operating system,
|
|
including the versions of gcc and binutils.
|
|
|
|
@item
|
|
If you have trouble with the installation, inform us of how you
|
|
installed GRUB. Don't omit error messages, if any. Just @samp{GRUB hangs
|
|
up when it boots} is not enough.
|
|
|
|
The information on your hardware is also essential. These are especially
|
|
important: the geometries and the partition tables of your hard disk
|
|
drives and your BIOS.
|
|
|
|
@item
|
|
If GRUB cannot boot your operating system, write down
|
|
@emph{everything} you see on the screen. Don't paraphrase them, like
|
|
@samp{The foo OS crashes with GRUB, even though it can boot with the
|
|
bar boot loader just fine}. Mention the commands you executed, the
|
|
messages printed by them, and information on your operating system
|
|
including the version number.
|
|
|
|
@item
|
|
Explain what you wanted to do. It is very useful to know your purpose
|
|
and your wish, and how GRUB didn't satisfy you.
|
|
|
|
@item
|
|
If you can investigate the problem yourself, please do. That will give
|
|
you and us much more information on the problem. Attaching a patch is
|
|
even better.
|
|
|
|
When you attach a patch, make the patch in unified diff format, and
|
|
write ChangeLog entries. But, even when you make a patch, don't forget
|
|
to explain the problem, so that we can understand what your patch is
|
|
for.
|
|
|
|
@item
|
|
Write down anything that you think might be related. Please understand
|
|
that we often need to reproduce the same problem you encounterred in our
|
|
environment. So your information should be sufficient for us to do the
|
|
same thing---Don't forget that we cannot see your computer directly. If
|
|
you are not sure whether to state a fact or leave it out, state it!
|
|
Reporting too many things is much better than omitting something
|
|
important.
|
|
@end enumerate
|
|
|
|
If you follow the guideline above, submit a report to the
|
|
@uref{http://savannah.gnu.org/bugs/?group=grub, Bug Tracking System}.
|
|
Alternatively, you can submit a report via electronic mail to
|
|
@email{bug-grub@@gnu.org}, but we strongly recommend that you use the
|
|
Bug Tracking System, because e-mail can be passed over easily.
|
|
|
|
Once we get your report, we will try to fix the bugs.
|
|
|
|
|
|
@node Future
|
|
@appendix Where GRUB will go
|
|
|
|
We started the next generation of GRUB, GRUB 2. GRUB 2 includes
|
|
internationalization, dynamic module loading, real memory management,
|
|
multiple architecture support, a scripting language, and many other
|
|
nice features. If you are interested in the development of GRUB 2, take
|
|
a look at @uref{http://www.gnu.org/software/grub/grub.html, the
|
|
homepage}.
|
|
|
|
|
|
@node Internals
|
|
@appendix Hacking GRUB
|
|
|
|
@menu
|
|
* Getting the source code::
|
|
* Finding your way around::
|
|
@end menu
|
|
|
|
|
|
@node Getting the source code
|
|
@section Getting the source code
|
|
|
|
GRUB is maintained using the @uref{http://bazaar-vcs.org/, Bazaar revision
|
|
control system}. To fetch the primary development branch:
|
|
|
|
@example
|
|
bzr get http://bzr.savannah.gnu.org/r/grub/trunk/grub
|
|
@end example
|
|
|
|
The GRUB developers maintain several other branches with work in progress.
|
|
Of these, the most interesting is the experimental branch, which is a
|
|
staging area for new code which we expect to eventually merge into trunk but
|
|
which is not yet ready:
|
|
|
|
@example
|
|
bzr get http://bzr.savannah.gnu.org/r/grub/branches/experimental
|
|
@end example
|
|
|
|
Once you have used @kbd{bzr get} to fetch an initial copy of a branch, you
|
|
can use @kbd{bzr pull} to keep it up to date. If you have modified your
|
|
local version, you may need to resolve conflicts when pulling.
|
|
|
|
|
|
@node Finding your way around
|
|
@section Finding your way around
|
|
|
|
Here is a brief map of the GRUB code base.
|
|
|
|
GRUB uses Autoconf, but not (yet) Automake. The top-level build rules are
|
|
in @file{configure.ac}, @file{Makefile.in}, and @file{conf/*.rmk}. Each
|
|
@file{conf/*.rmk} file represents a particular target configuration, and is
|
|
processed into GNU Make rules by @file{genmk.rb} (which you only need to
|
|
look at if you are extending the build system). If you are adding a new
|
|
module which follows an existing pattern, such as a new command or a new
|
|
filesystem implementation, it is usually easiest to grep @file{conf/*.rmk}
|
|
for an existing example of that pattern to find out where it should be
|
|
added.
|
|
|
|
Low-level boot code, such as the MBR implementation on PC BIOS systems, is
|
|
in the @file{boot/} directory.
|
|
|
|
The GRUB kernel is in @file{kern/}. This contains core facilities such as
|
|
the device, disk, and file frameworks, environment variable handling, list
|
|
processing, and so on. The kernel should contain enough to get up to a
|
|
rescue prompt. Header files for kernel facilities, among others, are in
|
|
@file{include/}.
|
|
|
|
Terminal implementations are in @file{term/}.
|
|
|
|
Disk access code is spread across @file{disk/} (for accessing the disk
|
|
devices themselves), @file{partmap/} (for interpreting partition table
|
|
data), and @file{fs/} (for accessing filesystems). Note that, with the odd
|
|
specialised exception, GRUB only contains code to @emph{read} from
|
|
filesystems and tries to avoid containing any code to @emph{write} to
|
|
filesystems; this lets us confidently assure users that GRUB cannot be
|
|
responsible for filesystem corruption.
|
|
|
|
PCI and USB bus handling is in @file{bus/}.
|
|
|
|
Video handling code is in @file{video/}. The graphical menu system uses
|
|
this heavily, but is in a separate directory, @file{gfxmenu/}.
|
|
|
|
Most commands are implemented by files in @file{commands/}, with the
|
|
following exceptions:
|
|
|
|
@itemize
|
|
@item
|
|
A few core commands live in @file{kern/corecmd.c}.
|
|
|
|
@item
|
|
Commands related to normal mode live under @file{normal/}.
|
|
|
|
@item
|
|
Commands that load and boot kernels live under @file{loader/}.
|
|
|
|
@item
|
|
The @samp{loopback} command is really a disk device, and so lives in
|
|
@file{disk/loopback.c}.
|
|
|
|
@item
|
|
The @samp{gettext} command lives under @file{gettext/}.
|
|
|
|
@item
|
|
The @samp{loadfont} and @samp{lsfonts} commands live under @file{font/}.
|
|
|
|
@item
|
|
The @samp{serial}, @samp{terminfo}, and @samp{background_image} commands
|
|
live under @file{term/}.
|
|
|
|
@item
|
|
The @samp{efiemu_*} commands live under @file{efiemu/}.
|
|
@end itemize
|
|
|
|
There are a few other special-purpose exceptions; grep for them if they
|
|
matter to you.
|
|
|
|
|
|
|
|
@node Copying This Manual
|
|
@appendix Copying This Manual
|
|
|
|
@menu
|
|
* GNU Free Documentation License:: License for copying this manual.
|
|
@end menu
|
|
|
|
@include fdl.texi
|
|
|
|
|
|
@node Index
|
|
@unnumbered Index
|
|
|
|
@c Currently, we use only the Concept Index.
|
|
@printindex cp
|
|
|
|
|
|
@bye
|
|
|
|
Some notes:
|
|
|
|
This is an attempt to make a manual for GRUB 2. The contents are
|
|
copied from the GRUB manual in GRUB Legacy, so they are not always
|
|
appropriate yet for GRUB 2.
|