194
@node Changes from GRUB Legacy
195
@section Differences from previous versions
197
GRUB 2 is a rewrite of GRUB (@pxref{History}), although it shares many
198
characteristics with the previous version, now known as GRUB Legacy. Users
199
of GRUB Legacy may need some guidance to find their way around this new
204
The configuration file has a new name (@file{grub.cfg} rather than
205
@file{menu.lst} or @file{grub.conf}), new syntax (@pxref{Configuration}) and
206
many new commands (@pxref{Commands}). Configuration cannot be copied over
207
directly, although most GRUB Legacy users should not find the syntax too
211
@file{grub.cfg} is typically automatically generated by
212
@command{grub-mkconfig} (@pxref{Simple configuration}). This makes it
213
easier to handle versioned kernel upgrades.
216
Partition numbers in GRUB device names now start at 1, not 0 (@pxref{Naming
220
The configuration file is now written in something closer to a full
221
scripting language: variables, conditionals, and loops are available.
224
A small amount of persistent storage is available across reboots, using the
225
@command{save_env} and @command{load_env} commands in GRUB and the
226
@command{grub-editenv} utility.
229
GRUB 2 has more reliable ways to find its own files and those of target
230
kernels on multiple-disk systems, and has commands (@pxref{search}) to find
231
devices using file system labels or Universally Unique Identifiers (UUIDs).
234
GRUB 2 is available for several other types of system in addition to the PC
235
BIOS systems supported by GRUB Legacy: PC EFI, PC coreboot, PowerPC, SPARC,
236
and MIPS Lemote Yeeloong are all supported.
239
Many more file systems are supported, including but not limited to ext4,
243
GRUB 2 can read files directly from LVM and RAID devices.
246
A graphical terminal and a graphical menu system are available.
249
GRUB 2's interface can be translated, including menu entry names.
252
The image files (@pxref{Images}) that make up GRUB have been reorganised;
253
Stage 1, Stage 1.5, and Stage 2 are no more.
256
GRUB 2 puts many facilities in dynamically loaded modules, allowing the core
257
image to be smaller, and allowing the core image to be built in more
195
263
@section GRUB features
615
684
@samp{(cd)} if you want to access other drives as well.
688
@section The map between BIOS drives and OS devices
690
The @command{grub-mkdevicemap} program can be used to create the @dfn{device
691
map file}. It is often run automatically by tools such as
692
@command{grub-install} if the device map file does not already exist. The
693
file name @file{/boot/grub/device.map} is preferred.
695
If the device map file exists, the GRUB utilities (@command{grub-probe},
696
@command{grub-setup}, etc.) read it to map BIOS drives to OS devices. This
697
file consists of lines like this:
700
@var{device} @var{file}
703
@var{device} is a drive specified in the GRUB syntax (@pxref{Device
704
syntax}), and @var{file} is an OS file, which is normally a device file.
706
Historically, the device map file was used because GRUB device names had to
707
be used in the configuration file, and they were derived from BIOS drive
708
numbers. The map between BIOS drives and OS devices cannot always be
709
guessed correctly: for example, GRUB will get the order wrong if you
710
exchange the boot sequence between IDE and SCSI in your BIOS.
712
Unfortunately, even OS device names are not always stable. Modern versions
713
of the Linux kernel may probe drives in a different order from boot to boot,
714
and the prefix (@file{/dev/hd*} versus @file{/dev/sd*}) may change depending
715
on the driver subsystem in use. As a result, the device map file required
716
frequent editing on some systems.
718
GRUB avoids this problem nowadays by using UUIDs or file system labels when
719
generating @file{grub.cfg}, and we advise that you do the same for any
720
custom menu entries you write. If the device map file does not exist, then
721
the GRUB utilities will assume a temporary device map on the fly. This is
722
often good enough, particularly in the common case of single-disk systems.
724
However, the device map file is not entirely obsolete yet, and there are
725
still some situations that require it to exist. If necessary, you may edit
726
the file if @command{grub-mkdevicemap} makes a mistake. You can put any
727
comments in the file if needed, as the GRUB utilities assume that a line is
728
just a comment if the first character is @samp{#}.
929
1045
disable the use of UUIDs, set this option to @samp{true}.
931
1047
@item GRUB_DISABLE_LINUX_RECOVERY
932
Disable the generation of recovery mode menu entries for Linux.
1048
If this option is set to @samp{true}, disable the generation of recovery
1049
mode menu entries for Linux.
934
1051
@item GRUB_DISABLE_NETBSD_RECOVERY
935
Disable the generation of recovery mode menu entries for NetBSD.
1052
If this option is set to @samp{true}, disable the generation of recovery
1053
mode menu entries for NetBSD.
1055
@item GRUB_VIDEO_BACKEND
1056
If graphical video support is required, either because the @samp{gfxterm}
1057
graphical terminal is in use or because @samp{GRUB_GFXPAYLOAD_LINUX} is set,
1058
then @command{grub-mkconfig} will normally load all available GRUB video
1059
drivers and use the one most appropriate for your hardware. If you need to
1060
override this for some reason, then you can set this option.
1062
After @command{grub-install} has been run, the available video drivers are
1063
listed in @file{/boot/grub/video.lst}.
937
1065
@item GRUB_GFXMODE
938
1066
Set the resolution used on the @samp{gfxterm} graphical terminal. Note that
986
1119
@section Writing full configuration files directly
1122
@node Embedded configuration
1123
@section Embedding a configuration file into GRUB
1125
GRUB supports embedding a configuration file directly into the core image,
1126
so that it is loaded before entering normal mode. This is useful, for
1127
example, when it is not straightforward to find the real configuration file,
1128
or when you need to debug problems with loading that file.
1129
@command{grub-install} uses this feature when it is not using BIOS disk
1130
functions or when installing to a different disk from the one containing
1131
@file{/boot/grub}, in which case it needs to use the @command{search}
1132
command (@pxref{search}) to find @file{/boot/grub}.
1134
To embed a configuration file, use the @option{-c} option to
1135
@command{grub-mkimage}. The file is copied into the core image, so it may
1136
reside anywhere on the file system, and may be removed after running
1137
@command{grub-mkimage}.
1139
After the embedded configuration file (if any) is executed, GRUB will load
1140
the @samp{normal} module, which will then read the real configuration file
1141
from @file{$prefix/grub.cfg}. By this point, the @code{root} variable will
1142
also have been set to the root device name. For example, @code{prefix}
1143
might be set to @samp{(hd0,1)/boot/grub}, and @code{root} might be set to
1144
@samp{hd0,1}. Thus, in most cases, the embedded configuration file only
1145
needs to set the @code{prefix} and @code{root} variables, and then drop
1146
through to GRUB's normal processing. A typical example of this might look
1151
search.fs_uuid 01234567-89ab-cdef-0123-456789abcdef root
1152
set prefix=($root)/boot/grub
1156
(The @samp{search_fs_uuid} module must be included in the core image for this
1159
In more complex cases, it may be useful to read other configuration files
1160
directly from the embedded configuration file. This allows such things as
1161
reading files not called @file{grub.cfg}, or reading files from a directory
1162
other than that where GRUB's loadable modules are installed. To do this,
1163
include the @samp{configfile} and @samp{normal} modules in the core image,
1164
and embed a configuration file that uses the @command{configfile} command to
1165
load another file. The following example of this also requires the
1166
@command{echo}, @command{search_label}, and @command{test} modules to be
1167
included in the core image:
1171
search.fs_label grub root
1172
if [ -e /boot/grub/example/test1.cfg ]; then
1173
set prefix=($root)/boot/grub
1174
configfile /boot/grub/example/test1.cfg
1176
if [ -e /boot/grub/example/test2.cfg ]; then
1177
set prefix=($root)/boot/grub
1178
configfile /boot/grub/example/test2.cfg
1180
echo "Could not find an example configuration file!"
1186
The embedded configuration file may not contain menu entries directly, but
1187
may only read them from elsewhere using @command{configfile}.
1191
@section Graphical menu themes
990
1195
@chapter Booting GRUB from the network
1130
1336
To take full advantage of this function install GRUB into MBR.
1340
@chapter GRUB image files
1342
@c FIXME: parts of this section are specific to PC BIOS right now.
1344
GRUB consists of several images: a variety of bootstrap images for starting
1345
GRUB in various ways, a kernel image, and a set of modules which are
1346
combined with the kernel image to form a core image. Here is a short
1351
On PC BIOS systems, this image is the first part of GRUB to start. It is
1352
written to a master boot record (MBR) or to the boot sector of a partition.
1353
Because a PC boot sector is 512 bytes, the size of this image is exactly 512
1356
The sole function of @file{boot.img} is to read the first sector of the core
1357
image from a local disk and jump to it. Because of the size restriction,
1358
@file{boot.img} cannot understand any file system structure, so
1359
@command{grub-setup} hardcodes the location of the first sector of the core
1360
image into @file{boot.img} when installing GRUB.
1363
This image is used as the first sector of the core image when booting from a
1364
hard disk. It reads the rest of the core image into memory and starts the
1365
kernel. Since file system handling is not yet available, it encodes the
1366
location of the core image using a block list format.
1369
This image is used as the first sector of the core image when booting from a
1370
CD-ROM drive. It performs a similar function to @file{diskboot.img}.
1373
This image is used as the start of the core image when booting from the
1374
network using PXE. @xref{Network}.
1377
This image may be placed at the start of the core image in order to make
1378
GRUB look enough like a Linux kernel that it can be booted by LILO using an
1379
@samp{image=} section.
1382
This image contains GRUB's basic run-time facilities: frameworks for device
1383
and file handling, environment variables, the rescue mode command-line
1384
parser, and so on. It is rarely used directly, but is built into all core
1388
This is the core image of GRUB. It is built dynamically from the kernel
1389
image and an arbitrary list of modules by the @command{grub-mkimage}
1390
program. Usually, it contains enough modules to access @file{/boot/grub},
1391
and loads everything else (including menu handling, the ability to load
1392
target operating systems, and so on) from the file system at run-time. The
1393
modular design allows the core image to be kept small, since the areas of
1394
disk where it must be installed are often as small as 32KB.
1396
On PC systems using the traditional MBR partition table format, the core
1397
image is usually installed in the "MBR gap" between the master boot record
1398
and the first partition, or sometimes it is installed in a file system and
1399
read directly from that. The latter is not recommended because GRUB needs
1400
to encode the location of all the core image sectors in @file{diskboot.img},
1401
and if the file system ever moves the core image around (as it is entitled
1402
to do) then GRUB must be reinstalled; it also means that GRUB will not be
1403
able to reliably find the core image if it resides on a different disk than
1404
the one to which @file{boot.img} was installed.
1406
On PC systems using the more recent GUID Partition Table (GPT) format, the
1407
core image should be installed to a BIOS Boot Partition. This may be
1408
created by GNU Parted using a command such as the following:
1411
# @kbd{parted /dev/@var{disk} set @var{partition-number} bios_grub on}
1414
@strong{Caution:} Be very careful which partition you select! When GRUB
1415
finds a BIOS Boot Partition during installation, it will automatically
1416
overwrite part of it. Make sure that the partition does not contain any
1420
Everything else in GRUB resides in dynamically loadable modules. These are
1421
often loaded automatically, or built into the core image if they are
1422
essential, but may also be loaded manually using the @command{insmod}
1423
command (@pxref{insmod}).
1426
@heading For GRUB Legacy users
1428
GRUB 2 has a different design from GRUB Legacy, and so correspondences with
1429
the images it used cannot be exact. Nevertheless, GRUB Legacy users often
1430
ask questions in the terms they are familiar with, and so here is a brief
1431
guide to how GRUB 2's images relate to that.
1435
Stage 1 from GRUB Legacy was very similar to @file{boot.img} in GRUB 2, and
1436
they serve the same function.
1439
In GRUB Legacy, Stage 1.5's function was to include enough filesystem code
1440
to allow the much larger Stage 2 to be read from an ordinary filesystem. In
1441
this respect, its function was similar to @file{core.img} in GRUB 2.
1442
However, @file{core.img} is much more capable than Stage 1.5 was; since it
1443
offers a rescue shell, it is sometimes possible to recover manually in the
1444
event that it is unable to load any other modules, for example if partition
1445
numbers have changed. @file{core.img} is built in a more flexible way,
1446
allowing GRUB 2 to support reading modules from advanced disk types such as
1449
GRUB Legacy could run with only Stage 1 and Stage 2 in some limited
1450
configurations, while GRUB 2 requires @file{core.img} and cannot work
1454
GRUB 2 has no single Stage 2 image. Instead, it loads modules from
1455
@file{/boot/grub} at run-time.
1457
@item stage2_eltorito
1458
In GRUB 2, images for booting from CD-ROM drives are now constructed using
1459
@file{cdboot.img} and @file{core.img}, making sure that the core image
1460
contains the @samp{iso9660} module. It is usually best to use the
1461
@command{grub-mkrescue} program for this.
1464
There is as yet no equivalent for @file{nbgrub} in GRUB 2; it was used by
1465
Etherboot and some other network boot loaders.
1468
In GRUB 2, images for PXE network booting are now constructed using
1469
@file{pxeboot.img} and @file{core.img}, making sure that the core image
1470
contains the @samp{pxe} and @samp{pxecmd} modules. @xref{Network}.
1132
1474
@node Filesystem
1133
1475
@chapter Filesystem syntax and semantics
1589
1932
GRUB, but may be used by GRUB's EFI emulation.
1938
@deffn Command badram addr,mask[,addr,mask...]
1942
This command notifies the memory manager that specified regions of
1943
RAM ought to be filtered out (usually, because they're damaged). This
1944
remains in effect after a payload kernel has been loaded by GRUB, as
1945
long as the loaded kernel obtains its memory map from GRUB. Kernels that
1946
support this include Linux, GNU Mach, the kernel of FreeBSD and Multiboot
1949
Syntax is the same as provided by the @uref{http://www.memtest.org/,
1950
Memtest86+ utility}: a list of address/mask pairs. Given a page-aligned
1951
address and a base address / mask pair, if all the bits of the page-aligned
1952
address that are enabled by the mask match with the base address, it means
1953
this page is to be filtered. This syntax makes it easy to represent patterns
1954
that are often result of memory damage, due to physical distribution of memory
1593
1957
@node blocklist
1594
1958
@subsection blocklist
added
removed
docs/grub.texi
