grub.texi 241 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
\input texinfo
@c -*-texinfo-*-
@c %**start of header
@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

This manual is for GNU GRUB (version @value{VERSION},

Copyright @copyright{} 1999,2000,2001,2002,2004,2006,2008,2009,2010,2011,2012,2013 Free Software Foundation, Inc.
24 25 26 27 28 29 30 31 32 33 34 35 36

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
* 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.
* grub-mkrelpath: (grub)Invoking grub-mkrelpath.
* grub-mkrescue: (grub)Invoking grub-mkrescue.  Make a GRUB rescue image
* grub-mount: (grub)Invoking grub-mount.        Mount a file system using GRUB
* grub-probe: (grub)Invoking grub-probe.        Probe device information
* grub-script-check: (grub)Invoking grub-script-check.
44 45 46 47 48 49 50 51 52 53
@end direntry

@setchapternewpage odd

@sp 10
@title the GNU GRUB manual
@subtitle The GRand Unified Bootloader, version @value{VERSION}, @value{UPDATED}.
@author Gordon Matzigkeit
@author Yoshinori K. Okuji
@author Colin Watson
@author Colin D. Bennett
56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83
@c The following two commands start the copyright page.
@vskip 0pt plus 1filll
@end titlepage

@c Output the table of contents at the beginning.

@headings double

@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

This edition documents version @value{VERSION}.

@end ifnottex

* Introduction::                Capturing the spirit of GRUB
* Naming convention::           Names of your drives in GRUB
84 85 86
* OS-specific notes about grub tools:: 
                                Some notes about OS-specific behaviour of GRUB
87 88 89
* Installation::                Installing GRUB on your drive
* Booting::                     How to boot different operating systems
* Configuration::               Writing your own configuration file
* Theme file format::           Format of GRUB theme files
91 92
* 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
* Core image size limitation::  GRUB image files size limitations
96 97
* Filesystem::                  Filesystem syntax and semantics
* Interface::                   The menu and the command-line
* Environment::                 GRUB environment variables
* Commands::                    The list of available builtin commands
* Internationalisation::        Topics relating to language support
* Security::                    Authentication, authorisation, and signatures
102 103
* Platform limitations::        The list of platform-specific limitations
* Platform-specific operations:: Platform-specific operations
* Supported kernels::           The list of supported kernels
105 106
* Troubleshooting::             Error messages produced by GRUB
* Invoking grub-install::       How to use the GRUB installer
* Invoking grub-mkconfig::      Generate a GRUB configuration file
108 109
* Invoking grub-mkpasswd-pbkdf2::
                                Generate GRUB password hashes
* Invoking grub-mkrelpath::     Make system path relative to its root
* Invoking grub-mkrescue::      Make a GRUB rescue image
* Invoking grub-mount::         Mount a file system using GRUB
* Invoking grub-probe::         Probe device information for GRUB
* Invoking grub-script-check::  Check GRUB script file for syntax errors
115 116 117 118 119 120 121 122 123 124 125 126 127 128
* 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
* Copying This Manual::         Copying This Manual
* Index::
@end menu

@node Introduction
@chapter Introduction to GRUB

* Overview::                    What exactly GRUB is and how to use it
* History::                     From maggot to house fly
* Changes from GRUB Legacy::    Differences from previous versions
* Features::                    GRUB features
131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197
* 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.

198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213
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.


215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246
@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

@itemize @bullet
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

@file{grub.cfg} is typically automatically generated by
@command{grub-mkconfig} (@pxref{Simple configuration}).  This makes it
easier to handle versioned kernel upgrades.

Partition numbers in GRUB device names now start at 1, not 0 (@pxref{Naming

The configuration file is now written in something closer to a full
scripting language: variables, conditionals, and loops are available.

A small amount of persistent storage is available across reboots, using the
@command{save_env} and @command{load_env} commands in GRUB and the
247 248
@command{grub-editenv} utility.  This is not available in all configurations
(@pxref{Environment block}).
249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283

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).

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.

Many more file systems are supported, including but not limited to ext4,
HFS+, and NTFS.

GRUB 2 can read files directly from LVM and RAID devices.

A graphical terminal and a graphical menu system are available.

GRUB 2's interface can be translated, including menu entry names.

The image files (@pxref{Images}) that make up GRUB have been reorganised;
Stage 1, Stage 1.5, and Stage 2 are no more.

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

284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323
@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{}
Basic functions must be straightforward for end-users.

Rich functionality to support kernel experts and designers.

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
324 325 326 327
compliance (primarily FreeBSD, NetBSD@footnote{The NetBSD/i386 kernel
is Multiboot-compliant, but lacks support for Multiboot modules.},
OpenBSD, and Linux). Chain-loading of other boot loaders is also
328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358

@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

@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{Amiga
360 361 362 363 364 365 366 367 368 369 370
Fast FileSystem (AFFS)}, @dfn{AtheOS fs}, @dfn{BeFS},
@dfn{BtrFS} (including raid0, raid1, raid10, gzip and lzo),
@dfn{cpio} (little- and big-endian bin, odc and newc variants),
@dfn{Linux ext2/ext3/ext4}, @dfn{DOS FAT12/FAT16/FAT32}, @dfn{exFAT}, @dfn{HFS},
@dfn{HFS+}, @dfn{ISO9660} (including Joliet, Rock-ridge and multi-chunk files),
@dfn{JFS}, @dfn{Minix fs} (versions 1, 2 and 3), @dfn{nilfs2},
@dfn{NTFS} (including compression), @dfn{ReiserFS}, @dfn{ROMFS},
@dfn{Amiga Smart FileSystem (SFS)}, @dfn{Squash4}, @dfn{tar}, @dfn{UDF},
@dfn{BSD UFS/UFS2}, @dfn{XFS}, and @dfn{ZFS} (including lzjb, gzip,
zle, mirror, stripe, raidz1/2/3 and encryption in AES-CCM and AES-GCM).
@xref{Filesystem}, for more information.
371 372

@item Support automatic decompression
373 374 375 376 377
Can decompress files which were compressed by @command{gzip} or
@command{xz}@footnote{Only CRC32 data integrity check is supported (xz default
is CRC64 so one should use --check=crc32 option). LZMA BCJ filters are
supported.}. This function is both automatic and transparent to the user
(i.e. all functions operate upon the uncompressed contents of the specified
378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478
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}

@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:

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''

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:

@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

480 481 482
@end example

Here, @samp{hd} means it is a hard disk drive. The first integer
483 484 485
@samp{0} indicates the drive number, that is, the first hard disk,
the string @samp{msdos} indicates the partition scheme, while
the second integer, @samp{2}, indicates the partition number (or the
486 487 488 489 490
@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.
491 492

494 495 496 497
@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
499 500 501
partitions on your hard disk.

503 504
@end example

505 506
This means the BSD @samp{a} partition on first @sc{pc} slice number
of the second hard disk.
507 508

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,msdos3) hidden-}. To help you find out
which number specifies a partition you want, the GRUB command-line
512 513 514 515
(@pxref{Command-line interface}) options have argument
completion. This means that, for example, you only need to type

set root=(
517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533
@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

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

535 536 537 538 539 540 541 542 543
@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.

544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579
@node OS-specific notes about grub tools
@chapter OS-specific notes about grub tools

On OS which have device nodes similar to Unix-like OS GRUB tools use the
OS name. E.g. for GNU/Linux:

# @kbd{grub-install /dev/sda}
@end example

On AROS we use another syntax. For volumes:

//:<volume name>
@end example


@end example

For disks we use syntax:
//:<driver name>/unit/flags
@end example


# @kbd{grub-install //:ata.device/0/0}
@end example

On Windows we use UNC path. For volumes it's typically

581 582 583 584 585 586
\\?\<drive letter>:
@end example


588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612
@end example

For disks it's

@end example


# @kbd{grub-install \\?\PhysicalDrive0}
@end example

Beware that you may need to further escape the backslashes depending on your

When compiled with cygwin support then cygwin drive names are automatically
when needed. E.g.

# @kbd{grub-install /dev/sda}
@end example
613 614 615 616 617 618 619 620 621 622

@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
623 624
drive (floppy or hard disk) by using the utility
@command{grub-install} (@pxref{Invoking grub-install}) on a UNIX-like OS.
625 626

GRUB comes with boot images, which are normally put in the directory
627 628 629
@file{/usr/lib/grub/<cpu>-<platform>} (for BIOS-based machines
@file{/usr/lib/grub/i386-pc}). Hereafter, the directory where GRUB images are
initially placed (normally @file{/usr/lib/grub/<cpu>-<platform>}) will be
called the @dfn{image directory}, and the directory where the boot
loader needs to find them (usually @file{/boot}) will be called
632 633 634 635
the @dfn{boot directory}.

* Installing GRUB using grub-install::
* Making a GRUB bootable CD-ROM::
* Device map::
* BIOS installation::
639 640 641 642 643 644
@end menu

@node Installing GRUB using grub-install
@section Installing GRUB using grub-install

645 646
For information on where GRUB should be installed on PC BIOS platforms,
@pxref{BIOS installation}.

In order to install GRUB under a UNIX-like OS (such
649 650 651 652 653
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
654 655 656
argument has to be either a device file (like @samp{/dev/hda}).
For example, under Linux the following will install GRUB into the MBR
of the first IDE disk:
657 658

# @kbd{grub-install /dev/sda}
660 661 662 663 664 665 666 667
@end example

Likewise, under GNU/Hurd, this has the same effect:

# @kbd{grub-install /dev/hd0}
@end example

668 669 670 671
But all the above examples assume that GRUB should put images under
the @file{/boot} directory. If you want GRUB to put images under a directory
other than @file{/boot}, you need to specify the option
@option{--boot-directory}. The typical usage is that you create a GRUB
672 673 674 675 676 677
boot floppy with a filesystem. Here is an example:

# @kbd{mke2fs /dev/fd0}
# @kbd{mount -t ext2 /dev/fd0 /mnt}
678 679
# @kbd{mkdir /mnt/boot}
# @kbd{grub-install --boot-directory=/mnt/boot /dev/fd0}
680 681 682 683
# @kbd{umount /mnt}
@end group
@end example

684 685 686
Some BIOSes have a bug of exposing the first partition of a USB drive as a
floppy instead of exposing the USB drive as a hard disk (they call it
``USB-FDD'' boot). In such cases, you need to install like this:
687 688 689 690 691 692 693 694 695 696

# @kbd{losetup /dev/loop0 /dev/sdb1}
# @kbd{mount /dev/loop0 /mnt/usb}
# @kbd{grub-install --boot-directory=/mnt/usb/bugbios --force --allow-floppy /dev/loop0}
@end example

This install doesn't conflict with standard install as long as they are in
separate directories.

Note that @command{grub-install} is actually just a shell script and the
698 699 700 701 702
real task is done by other tools such as @command{grub-mkimage}. 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.

704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723
On EFI systems for fixed disk install you have to mount EFI System Partition.
If you mount it at @file{/boot/efi} then you don't need any special arguments:

# @kbd{grub-install}
@end example

Otherwise you need to specify where your EFI System partition is mounted:

# @kbd{grub-install --efi-directory=/mnt/efi}
@end example

For removable installs you have to use @option{--removable} and specify both
@option{--boot-directory} and @option{--efi-directory}:

# @kbd{grub-install --efi-directory=/mnt/usb --boot-directory=/mnt/usb/boot --removable}
@end example

724 725 726 727 728 729 730 731 732
@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.

733 734 735 736 737 738
For booting from a CD-ROM, GRUB uses a special image called
@file{cdboot.img}, which is concatenated with @file{core.img}. The
@file{core.img} used for this should be built with at least the
@samp{iso9660} and @samp{biosdisk} modules. Your bootable CD-ROM will
usually also need to include a configuration file @file{grub.cfg} and some
other GRUB modules.

To make a simple generic GRUB rescue CD, you can use the
@command{grub-mkrescue} program (@pxref{Invoking grub-mkrescue}):
742 743

$ @kbd{grub-mkrescue -o grub.iso}
745 746
@end example

747 748
You will often need to include other files in your image. To do this, first
make a top directory for the bootable image, say, @samp{iso}:
749 750

$ @kbd{mkdir iso}
752 753
@end example

Make a directory for GRUB:
755 756

$ @kbd{mkdir -p iso/boot/grub}
758 759
@end example

If desired, make the config file @file{grub.cfg} under @file{iso/boot/grub}
761 762 763
(@pxref{Configuration}), and copy any files and directories for the disc to the
directory @file{iso/}.

Finally, make the image:
765 766

$ @kbd{grub-mkrescue -o grub.iso iso}
768 769 770
@end example

This produces a file named @file{grub.iso}, which then can be burned
into a CD (or a DVD), or written to a USB mass storage device.

773 774 775 776 777
The root device will be set up appropriately on entering your
@file{grub.cfg} configuration file, so you can refer to file names on the CD
without needing to use an explicit device name. This makes it easier to
produce rescue images that will work on both optical drives and USB mass
storage devices.
778 779

780 781 782 783
@node Device map
@section The map between BIOS drives and OS devices

If the device map file exists, the GRUB utilities (@command{grub-probe},
784 785
etc.) read it to map BIOS drives to OS devices.  This file consists of lines
like this:
786 787

(@var{device}) @var{file}
789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811
@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.

812 813 814 815 816 817
However, the device map file is not entirely obsolete yet, and it is
used for overriding when current environment is different from the one on boot.
Most common case is if you use a partition or logical volume as a disk for
virtual machine.  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{#}.
818 819

820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885
@node BIOS installation
@section BIOS installation

@heading MBR

The partition table format traditionally used on PC BIOS platforms is called
the Master Boot Record (MBR) format; this is the format that allows up to
four primary partitions and additional logical partitions.  With this
partition table format, there are two ways to install GRUB: it can be
embedded in the area between the MBR and the first partition (called by
various names, such as the "boot track", "MBR gap", or "embedding area", and
which is usually at least 31 KiB), or the core image can be installed in a
file system and a list of the blocks that make it up can be stored in the
first sector of that partition.

Each of these has different problems.  There is no way to reserve space in
the embedding area with complete safety, and some proprietary software is
known to use it to make it difficult for users to work around licensing
restrictions; and systems are sometimes partitioned without leaving enough
space before the first partition.  On the other hand, installing to a
filesystem means that GRUB is vulnerable to its blocks being moved around by
filesystem features such as tail packing, or even by aggressive fsck
implementations, so this approach is quite fragile; and this approach can
only be used if the @file{/boot} filesystem is on the same disk that the
BIOS boots from, so that GRUB does not have to rely on guessing BIOS drive

The GRUB development team generally recommends embedding GRUB before the
first partition, unless you have special requirements.  You must ensure that
the first partition starts at least 31 KiB (63 sectors) from the start of
the disk; on modern disks, it is often a performance advantage to align
partitions on larger boundaries anyway, so the first partition might start 1
MiB from the start of the disk.

@heading GPT

Some newer systems use the GUID Partition Table (GPT) format.  This was
specified as part of the Extensible Firmware Interface (EFI), but it can
also be used on BIOS platforms if system software supports it; for example,
GRUB and GNU/Linux can be used in this configuration.  With this format, it
is possible to reserve a whole partition for GRUB, called the BIOS Boot
Partition.  GRUB can then be embedded into that partition without the risk
of being overwritten by other software and without being contained in a
filesystem which might move its blocks around.

When creating a BIOS Boot Partition on a GPT system, you should make sure
that it is at least 31 KiB in size.  (GPT-formatted disks are not usually
particularly small, so we recommend that you make it larger than the bare
minimum, such as 1 MiB, to allow plenty of room for growth.)  You must also
make sure that it has the proper partition type.  Using GNU Parted, you can
set this using a command such as the following:

# @kbd{parted /dev/@var{disk} set @var{partition-number} bios_grub on}
@end example

If you are using gdisk, set the partition type to @samp{0xEF02}.  With
partitioning programs that require setting the GUID directly, it should be

@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.

886 887 888 889 890 891 892 893 894
@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

* General boot methods::        How to boot OSes with GRUB generally
* Loopback booting::            Notes on booting from loopbacks
896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926
* 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.

* 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.
928 929 930 931 932 933 934 935 936 937 938

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

939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966
@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:

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.

967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991
@node Loopback booting
@section Loopback booting
GRUB is able to read from an image (be it one of CD or HDD) stored on
any of its accessible storages (refer to @pxref{loopback} command).
However the OS itself should be able to find its root. This usually
involves running a userspace program running before the real root
is discovered. This is achieved by GRUB loading a specially made
small image and passing it as ramdisk to the kernel. This is achieved
by commands @command{kfreebsd_module}, @command{knetbsd_module_elf},
@command{kopenbsd_ramdisk}, @command{initrd} (@pxref{initrd}),
@command{initrd16} (@pxref{initrd}), @command{multiboot_module},
@command{multiboot2_module} or @command{xnu_ramdisk}
depending on the loader. Note that for knetbsd the image must be put
inside miniroot.kmod and the whole miniroot.kmod has to be loaded. In
kopenbsd payload this is disabled by default. Aditionally behaviour of
initial ramdisk depends on command line options. Several distributors provide
the image for this purpose or it's integrated in their standard ramdisk and
activated by special option. Consult your kernel and distribution manual for
more details. Other loaders like appleloader, chainloader (BIOS, EFI, coreboot),
freedos, ntldr and plan9 provide no possibility of loading initial ramdisk and
as far as author is aware the payloads in question don't support either initial
ramdisk or discovering loopback boot in other way and as such not bootable this
way. Please consider alternative boot methods like copying all files
from the image to actual partition. Consult your OS documentation for
more details

993 994 995 996 997 998 999 1000
@node OS-specific notes
@section Some caveats on OS-specific issues

Here, we describe some caveats on several operating systems.

* GNU/Hurd::
* GNU/Linux::
* NetBSD::
* DOS/Windows::
1003 1004 1005 1006 1007 1008 1009 1010 1011 1012
@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.

Set GRUB's root device to the same drive as GNU/Hurd's.  The command
@code{search --set=root --file /boot/gnumach.gz} or similar may help you
1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036

Load the kernel and the modules, like this:

grub> @kbd{multiboot /boot/gnumach.gz root=device:hd0s1}
grub> @kbd{module  /hurd/ext2fs.static ext2fs --readonly \
                   --multiboot-command-line='$@{kernel-command-line@}' \
                   --host-priv-port='$@{host-port@}' \
                   --device-master-port='$@{device-port@}' \
                   --exec-server-task='$@{exec-task@}' -T typed '$@{root@}' \
                   '$(task-create)' '$(task-resume)'}
grub> @kbd{module /lib/ exec /hurd/exec '$(exec-task=task-create)'}
@end group
@end example

Finally, run the command @command{boot} (@pxref{boot}).
1037 1038 1039 1040 1041 1042 1043 1044 1045
@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.

Set GRUB's root device to the same drive as GNU/Linux's.  The command
@code{search --set=root --file /vmlinuz} or similar may help you
1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068

Load the kernel using the command @command{linux} (@pxref{linux}):

grub> @kbd{linux /vmlinuz root=/dev/sda1}
@end example

If you need to specify some kernel parameters, just append them to the
command.  For example, to set @option{acpi} to @samp{off}, do this:

grub> @kbd{linux /vmlinuz root=/dev/sda1 acpi=off}
@end example

See the documentation in the Linux source tree for complete information on
the available options.

1069 1070 1071 1072 1073 1074 1075 1076
With @command{linux} GRUB uses 32-bit protocol. Some BIOS services like APM
or EDD aren't available with this protocol. In this case you need to use

grub> @kbd{linux16 /vmlinuz root=/dev/sda1 acpi=off}
@end example 

1077 1078 1079 1080 1081 1082 1083
If you use an initrd, execute the command @command{initrd} (@pxref{initrd})
after @command{linux}:

grub> @kbd{initrd /initrd}
@end example

1085 1086 1087 1088 1089 1090
If you used @command{linux16} you need to use @command{initrd16}:

grub> @kbd{initrd16 /initrd}
@end example

1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101
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.

1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158
@node NetBSD
@subsection NetBSD

Booting a NetBSD kernel from GRUB is also relatively easy: first set
GRUB's root device, then load the kernel and the modules, and finally
run @command{boot}.

Set GRUB's root device to the partition holding the NetBSD root file
system.  For a disk with a NetBSD disk label, this is usually the first
partition (a:).  In that case, and assuming that the partition is on the
first hard disk, set GRUB's root device as follows:

grub> @kbd{insmod part_bsd}
grub> @kbd{set root=(hd0,netbsd1)}
@end example

For a disk with a GUID Partition Table (GPT), and assuming that the
NetBSD root partition is the third GPT partition, do this:

grub> @kbd{insmod part_gpt}
grub> @kbd{set root=(hd0,gpt3)}
@end example

Load the kernel using the command @command{knetbsd}:

grub> @kbd{knetbsd /netbsd}
@end example

Various options may be given to @command{knetbsd}.  These options are,
for the most part, the same as in the NetBSD boot loader.  For instance,
to boot the system in single-user mode and with verbose messages, do

grub> @kbd{knetbsd /netbsd -s -v}
@end example

If needed, load kernel modules with the command
@command{knetbsd_module_elf}.  A typical example is the module for the
root file system:

grub> @kbd{knetbsd_module_elf /stand/amd64/6.0/modules/ffs/ffs.kmod}
@end example

Finally, run the command @command{boot} (@pxref{boot}).
@end enumerate

1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207
@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:

drivemap -s (hd0) (hd1)
@end example

This performs a @dfn{virtual} swap between your first and second hard

@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:

parttool (hd0,1) hidden-
parttool (hd0,2) hidden+
set root=(hd0,1)
chainloader +1
parttool @verb{'${root}'} boot+
@end group
@end example

1208 1209 1210 1211 1212 1213 1214 1215 1216 1217
@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.

* Simple configuration::        Recommended for most users
* Shell-like scripting::        For power users and developers
* Multi-boot manual config::    For non-standard multi-OS scenarios
* Embedded configuration::      Embedding a configuration file into GRUB
1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230
@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.

1231 1232 1233 1234 1235 1236 1237 1238 1239 1240
@command{grub-mkconfig} does have some limitations.  While adding extra
custom menu entries to the end of the list can be done by editing
@file{/etc/grub.d/40_custom} or creating @file{/boot/grub/custom.cfg},
changing the order of menu entries or changing their titles may require
making complex changes to shell scripts stored in @file{/etc/grub.d/}.  This
may be improved in the future.  In the meantime, those who feel that it
would be easier to write @file{grub.cfg} directly are encouraged to do so
(@pxref{Booting}, and @ref{Shell-like scripting}), and to disable any system
provided by their distribution to automatically run @command{grub-mkconfig}.

1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255
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:

GRUB_TERMINAL_INPUT="console serial"
@end example

Valid keys in @file{/etc/default/grub} are as follows:

@table @samp
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 title of a
menu entry, or the special string @samp{saved}.  Using the id may be
1258 1259 1260
useful if you want to set a menu entry as the default even though there may
be a variable number of entries before it.

1261 1262 1263
For example, if you have:

menuentry 'Example GNU/Linux distribution' --class gnu-linux --id example-gnu-linux {
1265 1266 1267 1268 1269 1270 1271
@end verbatim

then you can make this the default using:

1273 1274
@end example

1275 1276 1277 1278
Previously it was documented the way to use entry title. While this still
works it's not recommended since titles often contain unstable device names
and may be translated

If you set this to @samp{saved}, then the default menu entry will be that
1280 1281 1282
saved by @samp{GRUB_SAVEDEFAULT} or @command{grub-set-default}.  This relies on
the environment block, which may not be available in all situations
(@pxref{Environment block}).
1283 1284 1285 1286 1287 1288 1289 1290

The default is @samp{0}.

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}.  Unset by default.
1292 1293
This option relies on the environment block, which may not be available in
all situations (@pxref{Environment block}).
1294 1295 1296 1297 1298 1299 1300

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

1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311
If @samp{GRUB_TIMEOUT_STYLE} is set to @samp{countdown} or @samp{hidden},
the timeout is instead counted before the menu is displayed.

If this option is unset or set to @samp{menu}, then GRUB will display the
menu and then wait for the timeout set by @samp{GRUB_TIMEOUT} to expire
before booting the default entry.  Pressing a key interrupts the timeout.

If this option is set to @samp{countdown} or @samp{hidden}, then, before
displaying the menu, GRUB will wait for the timeout set by
@samp{GRUB_TIMEOUT} to expire.  If @key{ESC} is pressed during that time, it
1312 1313 1314 1315 1316
will display the menu and wait for input.  If a hotkey associated with a
menu entry is pressed, it will boot the associated menu entry immediately.
If the timeout expires before either of these happens, it will boot the
default entry.  In the @samp{countdown} case, it will show a one-line
indication of the remaining time.
1317 1318 1319

1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333
Variants of the corresponding variables without the @samp{_BUTTON} suffix,
used to support vendor-specific power buttons.  @xref{Vendor power-on keys}.

Set by distributors of GRUB to their identifying name.  This is used to
generate more informative menu entry titles.

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
1334 1335 1336
@samp{console} (native platform console), @samp{serial} (serial terminal),
@samp{serial_<port>} (serial terminal with explicit port selection),
@samp{at_keyboard} (PC AT keyboard), or @samp{usb_keyboard} (USB keyboard
1337 1338 1339 1340 1341 1342 1343 1344 1345 1346
using the HID Boot Protocol, for cases where the firmware does not handle

The default is to use the platform's native terminal input.

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
1347 1348 1349 1350 1351 1352 1353 1354
@samp{console} (native platform console), @samp{serial} (serial terminal),
@samp{serial_<port>} (serial terminal with explicit port selection),
@samp{gfxterm} (graphics-mode output), @samp{vga_text} (VGA text output),
@samp{mda_text} (MDA text output), @samp{morse} (Morse-coding using system
beeper) or @samp{spkmodem} (simple data protocol using system speaker).

@samp{spkmodem} is useful when no serial port is available. Connect the output
of sending system (where GRUB is running) to line-in of receiving system
(usually developer machine).
1356 1357 1358 1359 1360 1361
On receiving system compile @samp{spkmodem-recv} from
@samp{util/spkmodem-recv.c} and run:

parecord --channels=1 --rate=48000 --format=s16le | ./spkmodem-recv
@end example

The default is to use the platform's native terminal output.
1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376

If this option is set, it overrides both @samp{GRUB_TERMINAL_INPUT} and
@samp{GRUB_TERMINAL_OUTPUT} to the same value.

A command to configure the serial port when using the serial console.
@xref{serial}.  Defaults to @samp{serial}.

Command-line arguments to add to menu entries for the Linux kernel.

Unless @samp{GRUB_DISABLE_RECOVERY} is set to @samp{true}, two menu
1378 1379 1380 1381
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
1382 1383 1384 1385 1386 1387


1388 1389 1390
As @samp{GRUB_CMDLINE_LINUX}, but for GNU Mach.

1391 1392
1393 1394
The values of these options are passed to Xen hypervisor Xen menu entries,
for all respectively normal entries.
1395 1396 1397 1398 1399

The values of these options replace the values of @samp{GRUB_CMDLINE_LINUX}
and @samp{GRUB_CMDLINE_LINUX_DEFAULT} for Linux and Xen menu entries.

1401 1402 1403 1404 1405 1406 1407
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}.

If this option is set to @samp{true}, disable the generation of recovery
mode menu entries.

1412 1413 1414 1415 1416 1417 1418 1419 1420 1421
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}.

1422 1423 1424 1425
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{auto}, which tries to select a preferred
Colin Watson's avatar
Colin Watson committed
resolution.  @xref{gfxmode}.
1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442

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.

Set a theme for use with the @samp{gfxterm} graphical terminal.

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.  @xref{gfxpayload}.
1444 1445 1446 1447

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
1448 1449
boot sequence.  If you have problems, set this option to @samp{text} and
GRUB will tell Linux to boot in normal text mode.
1450 1451 1452 1453 1454 1455 1456

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.

1457 1458 1459 1460
List of space-separated FS UUIDs of filesystems to be ignored from os-prober
output. For efi chainloaders it's <UUID>@@<EFI FILE>

1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472
Normally, @command{grub-mkconfig} will generate top level menu entry for
the kernel with highest version number and put all other found kernels
or alternative menu entries for recovery mode in submenu. For entries returned
by @command{os-prober} first entry will be put on top level and all others
in submenu. If this option is set to @samp{y}, flat menu with all entries
on top level will be generated instead. Changing this option will require
changing existing values of @samp{GRUB_DEFAULT}, @samp{fallback} (@pxref{fallback})
and @samp{default} (@pxref{default}) environment variables as well as saved
default entry using @command{grub-set-default} and value used with

1473 1474 1475 1476 1477 1478
If set to @samp{y}, @command{grub-mkconfig} and @command{grub-install} will
check for encrypted disks and generate additional commands needed to access
them during boot.  Note that in this case unattended boot is not possible
because GRUB will wait for passphrase to unlock encrypted container.

1479 1480 1481 1482
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}.
1483 1484 1485 1486 1487

If this option is set, GRUB will issue a @ref{badram} command to filter
out specified regions of RAM.

1488 1489 1490 1491 1492
This option may be set to a list of GRUB module names separated by spaces.
Each module will be loaded as early as possible, at the start of

1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506
If this option is set, it overrides the default recordfail setting.  A
setting of -1 causes GRUB to wait for user input indefinitely.  However, a
false positive in the recordfail mechanism may occur if power is lost during
boot before boot success is recorded in userspace.  The default setting is
30, which causes GRUB to wait for user input for thirty seconds before
continuing.  This default allows interactive users the opportunity to switch
to a different, working kernel, while avoiding a false positive causing the
boot to block indefinitely on headless and appliance systems where access to
a console is restricted or limited.

This option is only effective when GRUB was configured with the
@option{--enable-quick-boot} option.

1507 1508 1509 1510 1511
This option sets the English text of the string that will be displayed in
parentheses to indicate that a boot option is provided to help users recover
a broken system.  The default is "recovery mode".

1512 1513
@end table

1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551
The following options are still accepted for compatibility with existing
configurations, but have better replacements:

@table @samp
Wait this many seconds before displaying the menu.  If @key{ESC} is pressed
during that time, display the menu and wait for input according to
@samp{GRUB_TIMEOUT}.  If a hotkey associated with a menu entry is pressed,
boot the associated menu entry immediately.  If the timeout expires before
either of these happens, display the menu for the number of seconds
specified in @samp{GRUB_TIMEOUT} before booting the default entry.

If you set @samp{GRUB_HIDDEN_TIMEOUT}, you should also set
@samp{GRUB_TIMEOUT=0} so that the menu is not displayed at all unless
@key{ESC} is pressed.

This option is unset by default, and is deprecated in favour of the less
confusing @samp{GRUB_TIMEOUT_STYLE=countdown} or

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.

This option is unset by default, and is deprecated in favour of the less
confusing @samp{GRUB_TIMEOUT_STYLE=countdown}.

Variant of @samp{GRUB_HIDDEN_TIMEOUT}, used to support vendor-specific power
buttons.  @xref{Vendor power-on keys}.

This option is unset by default, and is deprecated in favour of the less
confusing @samp{GRUB_TIMEOUT_STYLE=countdown} or

@end table

1552 1553 1554 1555 1556 1557 1558 1559 1560 1561
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

1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619
@c Some of this section is derived from the GNU Bash manual page, also
@c copyrighted by the FSF.

@file{grub.cfg} is written in GRUB's built-in scripting language, which has
a syntax quite similar to that of GNU Bash and other Bourne shell

@heading Words

A @dfn{word} is a sequence of characters considered as a single unit by
GRUB.  Words are separated by @dfn{metacharacters}, which are the following
plus space, tab, and newline:

@{ @} | & $ ; < >
@end example
Quoting may be used to include metacharacters in words; see below.

@heading Reserved words

Reserved words have a special meaning to GRUB.  The following words are
recognised as reserved when unquoted and either the first word of a simple
command or the third word of a @code{for} command:

! [[ ]] @{ @}
case do done elif else esac fi for function
if in menuentry select then time until while
@end example

Not all of these reserved words have a useful purpose yet; some are reserved
for future expansion.

@heading Quoting

Quoting is used to remove the special meaning of certain characters or
words.  It can be used to treat metacharacters as part of a word, to prevent
reserved words from being recognised as such, and to prevent variable

There are three quoting mechanisms: the escape character, single quotes, and
double quotes.

A non-quoted backslash (\) is the @dfn{escape character}.  It preserves the
literal value of the next character that follows, with the exception of

Enclosing characters in single quotes preserves the literal value of each
character within the quotes.  A single quote may not occur between single
quotes, even when preceded by a backslash.

Enclosing characters in double quotes preserves the literal value of all
characters within the quotes, with the exception of @samp{$} and @samp{\}.
The @samp{$} character retains its special meaning within double quotes.
The backslash retains its special meaning only when followed by one of the
following characters: @samp{$}, @samp{"}, @samp{\}, or newline.  A
backslash-newline pair is treated as a line continuation (that is, it is
1620 1621 1622 1623
removed from the input stream and effectively ignored@footnote{Currently a
backslash-newline pair within a variable name is not handled properly, so
use this feature with some care.}).  A double quote may be quoted within
double quotes by preceding it with a backslash.
1624 1625 1626 1627 1628 1629 1630 1631 1632

@heading Variable expansion

The @samp{$} character introduces variable expansion.  The variable name to
be expanded may be enclosed in braces, which are optional but serve to
protect the variable to be expanded from characters immediately following it
which could be interpreted as part of the name.

Normal variable names begin with an alphabetic character, followed by zero
1633 1634
or more alphanumeric characters.  These names refer to entries in the GRUB
environment (@pxref{Environment}).

1636 1637 1638
Positional variable names consist of one or more digits.  They represent
parameters passed to function calls, with @samp{$1} representing the first
parameter, and so on.
1639 1640

The special variable name @samp{?} expands to the exit status of the most
1641 1642 1643 1644
recently executed command.  When positional variable names are active, other
special variable names @samp{@@}, @samp{*} and @samp{#} are defined and they
expand to all positional parameters with necessary quoting, positional
parameters without any quoting, and positional parameter count respectively.
1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657

@heading Comments

A word beginning with @samp{#} causes that word and all remaining characters
on that line to be ignored.

@heading Simple commands

A @dfn{simple command} is a sequence of words separated by spaces or tabs
and terminated by a semicolon or a newline.  The first word specifies the
command to be executed.  The remaining words are passed as arguments to the
invoked command.

1658 1659 1660
The return value of a simple command is its exit status.  If the reserved
word @code{!} precedes the command, then the return value is instead the
logical negation of the command's exit status.
1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702

@heading Compound commands

A @dfn{compound command} is one of the following:

@table @asis
@item for @var{name} in @var{word} @dots{}; do @var{list}; done
The list of words following @code{in} is expanded, generating a list of
items.  The variable @var{name} is set to each element of this list in turn,
and @var{list} is executed each time.  The return value is the exit status
of the last command that executes.  If the expansion of the items following
@code{in} results in an empty list, no commands are executed, and the return
status is 0.

@item if @var{list}; then @var{list}; [elif @var{list}; then @var{list};] @dots{} [else @var{list};] fi
The @code{if} @var{list} is executed.  If its exit status is zero, the
@code{then} @var{list} is executed.  Otherwise, each @code{elif} @var{list}
is executed in turn, and if its exit status is zero, the corresponding
@code{then} @var{list} is executed and the command completes.  Otherwise,
the @code{else} @var{list} is executed, if present.  The exit status is the
exit status of the last command executed, or zero if no condition tested

@item while @var{cond}; do @var{list}; done
@itemx until @var{cond}; do @var{list}; done
The @code{while} command continuously executes the @code{do} @var{list} as
long as the last command in @var{cond} returns an exit status of zero.  The
@code{until} command is identical to the @code{while} command, except that
the test is negated; the @code{do} @var{list} is executed as long as the
last command in @var{cond} returns a non-zero exit status.  The exit status
of the @code{while} and @code{until} commands is the exit status of the last
@code{do} @var{list} command executed, or zero if none was executed.

@item function @var{name} @{ @var{command}; @dots{} @}
This defines a function named @var{name}.  The @dfn{body} of the function is
the list of commands within braces, each of which must be terminated with a
semicolon or a newline.  This list of commands will be executed whenever
@var{name} is specified as the name of a simple command.  Function
definitions do not affect the exit status in @code{$?}.  When executed, the
exit status of a function is the exit status of the last command executed in
the body.

@item menuentry @var{title} [@option{--class=class} @dots{}] [@option{--users=users}] [@option{--unrestricted}] [@option{--hotkey=key}] [@option{--id=id}] @{ @var{command}; @dots{} @}
1704 1705 1706
@end table

1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734
@heading Built-in Commands

Some built-in commands are also provided by GRUB script to help script
writers perform actions that are otherwise not possible.  For example, these
include commands to jump out of a loop without fully completing it, etc.

@table @asis
@item break [@code{n}]
Exit from within a @code{for}, @code{while}, or @code{until} loop.  If
@code{n} is specified, break @code{n} levels.  @code{n} must be greater than
or equal to 1.  If @code{n} is greater than the number of enclosing loops,
all enclosing loops are exited.  The return value is 0 unless @code{n} is
not greater than or equal to 1.

@item continue [@code{n}]
Resume the next iteration of the enclosing @code{for}, @code{while} or
@code{until} loop.  If @code{n} is specified, resume at the @code{n}th
enclosing loop.  @code{n} must be greater than or equal to 1.  If @code{n}
is greater than the number of enclosing loops, the last enclosing loop (the
@dfn{top-level} loop) is resumed.  The return value is 0 unless @code{n} is
not greater than or equal to 1.

@item return [@code{n}]
Causes a function to exit with the return value specified by @code{n}.  If
@code{n} is omitted, the return status is that of the last command executed
in the function body.  If used outside a function the return status is

1735 1736 1737 1738
@item setparams [@code{arg}] @dots{}
Replace positional parameters starting with @code{$1} with arguments to

1739 1740
@item shift [@code{n}]
The positional parameters from @code{n}+1 @dots{} are renamed to
@code{$1}@dots{}.  Parameters represented by the numbers @code{$#} down to
1742 1743 1744 1745 1746 1747 1748 1749
@code{$#}-@code{n}+1 are unset.  @code{n} must be a non-negative number less
than or equal to @code{$#}.  If @code{n} is 0, no parameters are changed.
If @code{n} is not given, it is assumed to be 1.  If @code{n} is greater
than @code{$#}, the positional parameters are not changed.  The return
status is greater than zero if @code{n} is greater than @code{$#} or less
than zero; otherwise 0.

@end table

1751 1752 1753 1754 1755 1756 1757 1758 1759
@node Multi-boot manual config
@section Multi-boot manual config

Currently autogenerating config files for multi-boot environments depends on
os-prober and has several shortcomings. While fixing it is scheduled for the
next release, meanwhile you can make use of the power of GRUB syntax and do it
yourself. A possible configuration is detailed here, feel free to adjust to your

1760 1761 1762 1763 1764 1765
First create a separate GRUB partition, big enough to hold GRUB. Some of the
following entries show how to load OS installer images from this same partition,
for that you obviously need to make the partition large enough to hold those
images as well.
Mount this partition on/mnt/boot and disable GRUB in all OSes and manually
install self-compiled latest GRUB with:
1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776

@code{grub-install --boot-directory=/mnt/boot /dev/sda}

In all the OSes install GRUB tools but disable installing GRUB in bootsector,
so you'll have menu.lst and grub.cfg available for use. Also disable os-prober
use by setting:


in /etc/default/grub

Then write a grub.cfg (/mnt/boot/grub/grub.cfg):
1778 1779 1780 1781 1782


menuentry "OS using grub2" @{
   insmod xfs
   search --set=root --label OS1 --hint hd0,msdos8
1784 1785 1786 1787 1788
   configfile /boot/grub/grub.cfg

menuentry "OS using grub2-legacy" @{
   insmod ext2
   search --set=root --label OS2 --hint hd0,msdos6
1790 1791 1792 1793 1794
   legacy_configfile /boot/grub/menu.lst

menuentry "Windows XP" @{
   insmod ntfs
   search --set=root --label WINDOWS_XP --hint hd0,msdos1
1796 1797 1798 1799 1800
   ntldr /ntldr

menuentry "Windows 7" @{
   insmod ntfs
   search --set=root --label WINDOWS_7 --hint hd0,msdos2
1802 1803 1804 1805 1806
   ntldr /bootmgr

menuentry "FreeBSD" @{
          insmod zfs
          search --set=root --label freepool --hint hd0,msdos7
1808 1809 1810 1811 1812 1813 1814 1815 1816
          kfreebsd /freebsd@@/boot/kernel/kernel
          kfreebsd_module_elf /freebsd@@/boot/kernel/opensolaris.ko
          kfreebsd_module_elf /freebsd@@/boot/kernel/zfs.ko
          kfreebsd_module /freebsd@@/boot/zfs/zpool.cache type=/boot/zfs/zpool.cache
          set kFreeBSD.vfs.root.mountfrom=zfs:freepool/freebsd
          set kFreeBSD.hw.psm.synaptics_support=1

menuentry "experimental GRUB" @{
          search --set=root --label GRUB --hint hd0,msdos5
1818 1819 1820
          multiboot /experimental/grub/i386-pc/core.img

1821 1822
menuentry "Fedora 16 installer" @{
          search --set=root --label GRUB --hint hd0,msdos5
1823 1824 1825 1826
          linux /fedora/vmlinuz lang=en_US keymap=sg resolution=1280x800
          initrd /fedora/initrd.img

1827 1828
menuentry "Fedora rawhide installer" @{
          search --set=root --label GRUB --hint hd0,msdos5
1829 1830 1831 1832
          linux /fedora/vmlinuz repo= lang=en_US keymap=sg resolution=1280x800
          initrd /fedora/initrd.img

1833 1834
menuentry "Debian sid installer" @{
          search --set=root --label GRUB --hint hd0,msdos5
1835 1836 1837 1838 1839 1840 1841 1842
          linux /debian/dists/sid/main/installer-amd64/current/images/hd-media/vmlinuz
          initrd /debian/dists/sid/main/installer-amd64/current/images/hd-media/initrd.gz

@end example

@item Argument to search after --label is FS LABEL. You can also use UUIDs with --fs-uuid UUID instead of --label LABEL. You could also use direct @code{root=hd0,msdosX} but this is not recommended due to device name instability.
1844 1845
@end itemize

1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863
@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

After the embedded configuration file (if any) is executed, GRUB will load
1864 1865 1866 1867 1868 1869 1870 1871
the @samp{normal} module (@pxref{normal}), 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:
1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912

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:

search.fs_label grub root
if [ -e /boot/grub/example/test1.cfg ]; then
    set prefix=($root)/boot/grub
    configfile /boot/grub/example/test1.cfg
    if [ -e /boot/grub/example/test2.cfg ]; then
        set prefix=($root)/boot/grub
        configfile /boot/grub/example/test2.cfg
        echo "Could not find an example configuration file!"
@end group
@end example

The embedded configuration file may not contain menu entries directly, but
may only read them from elsewhere using @command{configfile}.

1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935
@node Theme file format
@chapter Theme file format
@section Introduction
The GRUB graphical menu supports themes that can customize the layout and
appearance of the GRUB boot menu.  The theme is configured through a plain
text file that specifies the layout of the various GUI components (including
the boot menu, timeout progress bar, and text messages) as well as the
appearance using colors, fonts, and images. Example is available in docs/example_theme.txt

@section Theme Elements
@subsection Colors

Colors can be specified in several ways:

@item HTML-style ``#RRGGBB'' or ``#RGB'' format, where *R*, *G*, and *B* are hexadecimal digits (e.g., ``#8899FF'')
@item as comma-separated decimal RGB values (e.g., ``128, 128, 255'')
@item with ``SVG 1.0 color names'' (e.g., ``cornflowerblue'') which must be specified in lowercase.
@end itemize
@subsection Fonts
The fonts GRUB uses ``PFF2 font format'' bitmap fonts.  Fonts are specified
with full font names.  Currently there is no
provision for a preference list of fonts, or deriving one font from another.
1936 1937
Fonts are loaded with the ``loadfont'' command in GRUB (@ref{loadfont}).  To see the list of
loaded fonts, execute the ``lsfonts'' command (@ref{lsfonts}).  If there are too many fonts to
1938 1939 1940 1941 1942 1943
fit on screen, do ``set pager=1'' before executing ``lsfonts''.

@subsection Progress Bar

@float Figure, Pixmap-styled progress bar
@c @image{Theme_progress_bar,,,,png}
1945 1946 1947
@end float

@float Figure, Plain progress bar, drawn with solid color.
@c @image{Theme_progress_bar_filled,,,,png}
1949 1950 1951 1952 1953 1954 1955 1956 1957
@end float

Progress bars are used to display the remaining time before GRUB boots the
default menu entry.  To create a progress bar that will display the remaining
time before automatic boot, simply create a ``progress_bar'' component with
the id ``__timeout__''.  This indicates to GRUB that the progress bar should
be updated as time passes, and it should be made invisible if the countdown to
automatic boot is interrupted by the user.

1958 1959 1960 1961 1962 1963
Progress bars may optionally have text displayed on them.  This text is
controlled by variable ``text'' which contains a printf template with the
only argument %d is the number of seconds remaining. Additionally special
``@@TIMEOUT_NOTIFICATION_LONG@@'' are replaced with standard and translated
1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007

@subsection Circular Progress Indicator

@c @image{Theme_circular_progress,,,,.png}

The circular progress indicator functions similarly to the progress bar.  When
given an id of ``__timeout__'', GRUB updates the circular progress indicator's
value to indicate the time remaining.  For the circular progress indicator,
there are two images used to render it:  the *center* image, and the *tick*
image.  The center image is rendered in the center of the component, while the
tick image is used to render each mark along the circumference of the

@subsection Labels

Text labels can be placed on the boot screen.  The font, color, and horizontal
alignment can be specified for labels.  If a label is given the id
``__timeout__'', then the ``text'' property for that label is also updated
with a message informing the user of the number of seconds remaining until
automatic boot.  This is useful in case you want the text displayed somewhere
else instead of directly on the progress bar.

@subsection Boot Menu

@c @image{Theme_boot_menu,,,,.png}

The boot menu where GRUB displays the menu entries from the ``grub.cfg'' file.
It is a list of items, where each item has a title and an optional icon.  The
icon is selected based on the *classes* specified for the menu entry.  If
there is a PNG file named ``myclass.png'' in the ``grub/themes/icons''
directory, it will be displayed for items which have the class *myclass*.  The
boot menu can be customized in several ways, such as the font and color used
for the menu entry title, and by specifying styled boxes for the menu itself
and for the selected item highlight.

@subsection Styled Boxes

One of the most important features for customizing the layout is the use of
 *styled boxes*.  A styled box is composed of 9 rectangular (and potentially
empty) regions, which are used to seamlessly draw the styled box on screen:

2008 2009 2010 2011 2012
@multitable @columnfractions 0.3 0.3 0.3
@item Northwest (nw) @tab North (n)  @tab Northeast (ne)
@item West (w)       @tab Center (c) @tab East (e)
@item Southwest (sw) @tab South (s)  @tab Southeast (se)
@end multitable
2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076

To support any size of box on screen, the center slice and the slices for the
top, bottom, and sides are all scaled to the correct size for the component on
screen, using the following rules:

@item The edge slices (north, south, east, and west) are scaled in the direction of the edge they are adjacent to.  For instance, the west slice is scaled vertically.
@item The corner slices (northwest, northeast, southeast, and southwest) are not scaled.
@item The center slice is scaled to fill the remaining space in the middle.
@end enumerate

As an example of how an image might be sliced up, consider the styled box
used for a terminal view.

@float Figure, An example of the slices (in red) used for a terminal window. This drawing was created and sliced in Inkscape_, as the next section explains.
@c @image{Box_slice_example_terminal,,,,.png}
@end float
@subsection Creating Styled Box Images

The Inkscape_ scalable vector graphics editor is a very useful tool for
creating styled box images.  One process that works well for slicing a drawing
into the necessary image slices is:

@item Create or open the drawing you'd like use.
@item Create a new layer on the top of the layer stack.  Make it visible.  Select this layer as the current layer.
@item Draw 9 rectangles on your drawing where you'd like the slices to be.  Clear the fill option, and set the stroke to 1 pixel wide solid stroke.  The corners of the slices must meet precisely; if it is off by a single pixel, it will probably be evident when the styled box is rendered in the GRUB menu.  You should probably go to File | Document Properties | Grids and enable a grid or create a guide (click on one of the rulers next to the drawing and drag over the drawing; release the mouse button to place the guide) to help place the rectangles precisely.
@item Right click on the center slice rectangle and choose Object Properties. Change the "Id" to ``slice_c`` and click Set.  Repeat this for the remaining 8 rectangles, giving them Id values of ``slice_n``, ``slice_ne``, ``slice_e``, and so on according to the location.
@item Save the drawing.
@item Select all the slice rectangles.  With the slice layer selected, you can simply press Ctrl+A to select all rectangles.  The status bar should indicate that 9 rectangles are selected.
@item Click the layer hide icon for the slice layer in the layer palette.  The rectangles will remain selected, even though they are hidden.
@item Choose File | Export Bitmap and check the *Batch export 9 selected objects* box.  Make sure that *Hide all except selected* is unchecked. click *Export*.  This will create PNG files in the same directory as the drawing, named after the slices.  These can now be used for a styled box in a GRUB theme.
@end enumerate

@section Theme File Manual

The theme file is a plain text file.  Lines that begin with ``#`` are ignored
and considered comments.  (Note: This may not be the case if the previous line
ended where a value was expected.)

The theme file contains two types of statements:
@item Global properties.
@item Component construction.
@end enumerate

@subsection Global Properties

@subsection Format

Global properties are specified with the simple format:
@item name1: value1
@item name2: "value which may contain spaces"
@item name3: #88F
@end itemize

In this example, name3 is assigned a color value.

@subsection Global Property List

@multitable @columnfractions 0.3 0.6
2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088
@item title-text
   @tab Specifies the text to display at the top center of the screen as a title.
@item title-font
   @tab Defines the font used for the title message at the top of the screen.
@item title-color
   @tab Defines the color of the title message.
@item message-font
   @tab Currently unused. Left for backward compatibility.
@item message-color
   @tab Currently unused. Left for backward compatibility.
@item message-bg-color
   @tab Currently unused. Left for backward compatibility.
2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110
@item desktop-image
   @tab Specifies the image to use as the background.  It will be scaled
   to fit the screen size or proportionally scaled depending on the scale
@item desktop-image-scale-method
   @tab Specifies the scaling method for the *desktop-image*. Options are
   ``stretch``, ``crop``, ``padding``, ``fitwidth``, ``fitheight``.
   ``stretch`` for fitting the screen size. Otherwise it is proportional
   scaling of a part of *desktop-image* to the part of the screen.
   ``crop`` part of the *desktop-image* will be proportionally scaled to
   fit the screen sizes. ``padding`` the entire *desktop-image* will be
   contained on the screen. ``fitwidth`` for fitting the *desktop-image*'s
   width with screen width. ``fitheight`` for fitting the *desktop-image*'s
   height with the screen height. Default is ``stretch``.
@item desktop-image-h-align
   @tab Specifies the horizontal alignment of the *desktop-image* if
   *desktop-image-scale-method* isn't equeal to ``stretch``. Options are
   ``left``, ``center``, ``right``. Default is ``center``.
@item desktop-image-v-align
   @tab Specifies the vertical alignment of the *desktop-image* if
   *desktop-image-scale-method* isn't equeal to ``stretch``. Options are
   ``top``, ``center``, ``bottom``. Default is ``center``.
2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130
@item desktop-color
   @tab Specifies the color for the background if *desktop-image* is not
@item terminal-box
   @tab Specifies the file name pattern for the styled box slices used for the
   command line terminal window.  For example, ``terminal-box: terminal_*.png``
   will use the images ``terminal_c.png`` as the center area, ``terminal_n.png``
   as the north (top) edge, ``terminal_nw.png`` as the northwest (upper left)
   corner, and so on.  If the image for any slice is not found, it will simply
   be left empty.
@item terminal-border
   @tab Specifies the border width of the terminal window.
@item terminal-left
   @tab Specifies the left coordinate of the terminal window.
@item terminal-top
   @tab Specifies the top coordinate of the terminal window.
@item terminal-width
   @tab Specifies the width of the terminal window.
@item terminal-height
   @tab Specifies the height of the terminal window.
2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143
@end multitable

@subsection Component Construction

Greater customizability comes is provided by components.  A tree of components
forms the user interface.  *Containers* are components that can contain other
components, and there is always a single root component which is an instance
of a *canvas* container.

Components are created in the theme file by prefixing the type of component
with a '+' sign:

@code{   + label @{ text="GRUB" font="aqui 11" color="#8FF" @} }
2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163

properties of a component are specified as "name = value" (whitespace
surrounding tokens is optional and is ignored) where *value* may be:
@item a single word (e.g., ``align = center``, ``color = #FF8080``),
@item a quoted string (e.g., ``text = "Hello, World!"``), or
@item a tuple (e.g., ``preferred_size = (120, 80)``).
@end itemize

@subsection Component List

The following is a list of the components and the properties they support.

@item label
   A label displays a line of text.
   @multitable @columnfractions 0.2 0.7
2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180
   @item id
      @tab Set to ``__timeout__`` to display the time elapsed to an automatical
      boot of the default entry.
   @item text
      @tab The text to display. If ``id`` is set to ``__timeout__`` and no
      ``text`` property is set then the amount of seconds will be shown.
      If set to ``@@KEYMAP_SHORT@@``, ``@@KEYMAP_MIDDLE@@`` or
      ``@@KEYMAP_LONG@@`` then predefined hotkey information will be shown.
   @item font
      @tab The font to use for text display.
   @item color
      @tab The color of the text.
   @item align
      @tab The horizontal alignment of the text within the component.
      Options are ``left``, ``center`` and ``right``.
   @item visible
      @tab Set to ``false`` to hide the label.
2181 2182 2183
   @end multitable

@item image
2184 2185
   A component that displays an image.  The image is scaled to fit
   the component.
2186 2187 2188 2189


   @multitable @columnfractions 0.2 0.7
2190 2191
   @item file
      @tab The full path to the image file to load.
2192 2193 2194 2195 2196 2197 2198 2199 2200
   @end multitable

@item progress_bar
   Displays a horizontally oriented progress bar.  It can be rendered using
   simple solid filled rectangles, or using a pair of pixmap styled boxes.


   @multitable @columnfractions 0.2 0.7
2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223
   @item id
      @tab Set to ``__timeout__`` to display the time elapsed to an automatical
      boot of the default entry.
   @item fg_color
      @tab The foreground color for plain solid color rendering.
   @item bg_color
      @tab The background color for plain solid color rendering.
   @item border_color
      @tab The border color for plain solid color rendering.
   @item text_color
      @tab The text color.
   @item bar_style
      @tab The styled box specification for the frame of the progress bar.
      Example: ``progress_frame_*.png``
      If the value is equal to ``highlight_style`` then no styled boxes
      will be shown.
   @item highlight_style
      @tab The styled box specification for the highlighted region of the
      progress bar. This box will be used to paint just the highlighted region
      of the bar, and will be increased in size as the bar nears completion.
      Example: ``progress_hl_*.png``.
      If the value is equal to ``bar_style`` then no styled boxes
      will be shown.
2224 2225 2226 2227 2228 2229 2230 2231
   @item highlight_overlay
      @tab If this option is set to ``true`` then the highlight box
      side slices (every slice except the center slice) will overlay the
      frame box side slices. And the center slice of the highlight box
      can move all the way (from top to bottom), being drawn on the center
      slice of the frame box. That way we can make a progress bar with
      round-shaped edges so there won't be a free space from the highlight to
      the frame in top and bottom scrollbar positions. Default is ``false``.
2232 2233 2234 2235 2236 2237 2238 2239
   @item font
      @tab The font to use for progress bar.
   @item text
      @tab The text to display on the progress bar.  If the progress bar's ID
      is set to ``__timeout__`` and the value of this property is set to
      or ``@@TIMEOUT_NOTIFICATION_LONG@@``, then GRUB will update this
      property with an informative message as the timeout approaches.
2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252
   @end multitable

@item circular_progress
   Displays a circular progress indicator.  The appearance of this component
   is determined by two images:  the *center* image and the *tick* image.  The
   center image is generally larger and will be drawn in the center of the
   component.  Around the circumference of a circle within the component, the
   tick image will be drawn a certain number of times, depending on the
   properties of the component.


   @multitable @columnfractions 0.3 0.6
2253 2254 2255
   @item id
      @tab Set to ``__timeout__`` to display the time elapsed to an automatical
      boot of the default entry.
2256 2257 2258 2259 2260 2261 2262 2263 2264
   @item center_bitmap
      @tab The file name of the image to draw in the center of the component.
   @item tick_bitmap
      @tab The file name of the image to draw for the tick marks.
   @item num_ticks
      @tab The number of ticks that make up a full circle.
   @item ticks_disappear
      @tab Boolean value indicating whether tick marks should progressively appear,
      or progressively disappear as *value* approaches *end*.  Specify
2265 2266 2267 2268 2269
      ``true`` or ``false``. Default is ``false``.
   @item start_angle
      @tab The position of the first tick mark to appear or disappear.
      Measured in "parrots", 1 "parrot" = 1 / 256 of the full circle.
      Use values ``xxx deg`` or ``xxx \xc2\xb0`` to set the angle in degrees.
   @end multitable

2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290